A simple estimation of symmetry based on the behaviour of the correlation
  of an object with a series of symmetrized versions of itself.
 
  
 
  INPUT
 
    object:      a volume (as file or matlab object), or a set of volumes
 
    symtype:    'c' or 'h' (helical)
                't': experimental option ('torsion')
                'i','ico': option to find a rotation angle that brings
                           the particle to icosahedral symmetry as defined
                           inside the Dynamo angular convention.
 
 
  PARAMETER/VALUE
 
  'mask'           : a binary mask (as file or variable)
                     Computations will be restricted to the interior of
                     this mask.
 
  * specific for type 'c'
 
    'order'        : order of rotational symmetry
 
  * specific for type 'h'
 
     'dphi'        : angular distance between subunits
 
     'dz'          : axias rise
 
     'rep'         : number of repetitions
                     - default: maximally allowed number of repetitions
 
 
     'hmethod'     : allows to switch to different interpolation
                     methods. The current version provides only
                     the values 'normal' and 'splines'
                     - default: 'splines'
 
   * specific for type 't' ("torsion")
 
     'crop'        : scalar
 
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  -
 
     Cross-correlation
     -----------------
  
 
     'mask'          :  defined in direct space
 
     'type'          : 'pearson' | 'cc' |  'fsc'
 
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  -
 
   Symmetry axis orientation
   -------------------------
  
   If you suspect the symmetry of a particle but don't know where 
   the axis is oriented you can use the 'triplets' option
 
   'triplets'    : an array Nx3 of Dynamo euler angels
                   Dynamo will put the axis along each one of the angles
                   and test the symmetry there.
 
   'cone_range','cr'      : To generate automatically a list of triplets.
   'cone_sampling','cs'   : idem.
                 
  
      EXAMPLE
    
      dread thermo1.em v; % reads the template
   
      vr = drot(v,[56,78,34]); % creates a random rotation
  
     % creates a distribution of angles
      angles = dynamo_angleincrement2list(180,5);
     % We only create a grid of orientations: azymutal scan is not required 
     % for c8
 
     % makes the symmetry scan to find the axis of symmetrey of vr
       o = dynamo_symmetry_scan(vr,'c8','triplets',u,'type','pearson');
 
     % equivalent notation that generates automatically the scanned
     % list of angles
      o = dynamo_symmetry_scan(vr,'c8','cr',180,'cs',5,'type','pearson');
 
      dview(drot(vr,o.anglesOnVolume));
   
     % note that the produced output anglesOnVolume can be applied dirctly 
     % onto the input volume to produce a symmetry-aligned version.
 
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -  -
 
   Depiction
   ---------
 
      'bar'            :  boolean: depicts a waiting bar to scan task
                          progress
 
      'show'           :  boolean
                          - default: true (produces a depiction)  
  
      'nfig'           :  boolean
                          - default: 1   (if a depiction is produced, it is sent to figure 1) 
  
      'subplot'        :  boolean
                          if switched on, the depiction for several volumes
                          will be arranged into the same plot
                          - default: off
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
   EXAMPLE:
 
   1 - C symmetry estimation
 
   % Locates the c8 symmetry on the thermosome particle
 
   v=dynamo_read('template.em');
 
   output = dynamo_symmetry_scan(v,'c','order',1:16,'type','cc');
 
   % or
 
   dynamo_symmetry_scan template.em c -order 1:16 -type cc -ws output;
 
 
   2 - H symmetry estimation
 
   If you suspect the symmetry of template.em to lay in the range 50-70
   degrees,  for the angle between subunits and 3 and 5 (pixels)
   this could be a reasonable discretization for the scan
 
   dsymmetry_scan template.em h -dphi 50:2:70  -dz 3:0.5:5 -type cc -ws output;
 
 
   3 - Experimental: torsion along one axis in the z direction
 
   dsymmetry_scan template.em t  -dz 1 -reps 8 -type pearson -mask my_mask.em -ws output;
    dpanel(output.similarity);