Extracts a set of particles from a (probably large) volume using the
   information in an user provided table.
 
 
   INPUT
 
   tomogram          : * single tomogram
                         As file or Matlab variable.
 
                       * several tomograms
                         As "volume list" (.vll file)
                         doc dVolumeList for more information on these
                         objects.
 
   table             : as file or variable
                       * accepts the special code "reorder" in case the
                         first argument was a volume list (as .vll file)
 
 
   target_directory  :  folder name to store the particles
                       - default: temp_extracted
 
   sidelength        :  length of the box side
 
 
 -------------------------------------------------------------------------
 
   Parameter/values
 
 
    'inmemory'        1: reads the volume only once and keeps it in memory
                      0: Reads the particles sequentially opening the file
                         each time. Useful for big tomograms.
                      - default: 0
 
    'align'           1: applies the geometric transformation coded in the
                         table before saving each box.
                      0: just crops the boxes from the x,y,z coordinates
                         (columns 24 to 26 in the input table)
 
                      - default: 0 (this is probably what you want if you
                                    intend to use the data set as input
                                    for a Dynamo alignemnt experiment)
 
    'ext'             intended extension (without leading point);
                      - default: 'em'
 
    'tag_padding'     number of characters in the tag number of the
                      particle
                      (typically files are named with five
                       numerico positions, i.e. "particle_00012.em")
                      - default: 5
 
    'tags'            to restrict the operations to a subset of tags
                      - default: traverses the whole table
 
    'tomo'            to restrict the operations to a given tomogram number
                      (this is useful if your table includes information
                       adressing particles from several tomograms)
 
                      - default: crops all particles in the table
 
 
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
   Add particles to old data
   -------------------------
 
  'append_tags'      boolean
                     if switched on, the tags in the input table will
                     be modified: Particles will be tagged linearly,
                     starting with the tag number after the last one
                     available in the data.
                     - default: false
 
 
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
   Out of scope
   ------------
 
  'allow_padding'     boolean
                      If switched to "true", the particles close to the
                      boundary that would go out-of-scope when cropped
                      will get "padded" with zeros.
                      Normally they just get excluded from the data
                      extraction.
 
                      - default: false
 
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
   Memory management
   ------------
 
  'memoryMap','mm'    boolean
                      If switched to "true", each tomogram will be mapped
                      to a memory map. This can increase the performance.
 
                      - default: false
 
   'preload_zslice','plz'  preloads full zslices when reading the tomogram
                      This might downgrade performance for tomograms
                      with bigh dimensionality in in x an y.
                      -default: false
 
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
   Averaging
   ---------
 
  'computeAverage','ca'  boolean
                         If switched on, an average of the particles is
                         produced.
                         This is a simple average that just uses the
                         rotations and shifts in the table to transform
                         and normalize the particle. No Fourier
                         compensation is taken into account.
 
 
  -------------------------------------------------------------------------
 
   Output flags
 
   'ws'                to direct the output into a workspace variable.
                       Argument: a string. A variable with this name will
                       be created in the workspace.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
   OUTPUT
 
   Created paticles will be stored in the 
 
   Besides, an output struture is returned to the command line:
 
   .excluded      :   lists particle tags that could not be cropped.
 
 
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
   EXAMPLES of SYNTAX:
 
   dynamo_table_crop(tomogram,table,target,sidelength);
 
  Short example (just to test the syntax);
 
   % creates a random volume
   a = rand(128,128,128);
 
   % creates a random table (with x,y,z positions inside the volume)
   table=dynamo_table_random(20,'rtomo',128);
 
   % you can depict the created 3d positions with dynamo_tableplot:
   dtplot(table,'modus','sketch');
 
   % Now, the actual work: crops subtomograms of sidelength 16
  % and format the result as a Dynamo folder
 
   dynamo_table_crop(a,table,'test_cropping',16,'inmemory',true);
 
 
   String syntax:
 
   You can use it as alternative when your objects (volume and table)
   are contained in files. For instance:
 
   dtcrop  test.em table.tbl test_cropping 16 -inmemory off;
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
  NOTES
 
    1) Tomogram boundaries
       particles whose center are too close to the border will be filled with zeros