# fevalImages

## PURPOSE

Used to apply the same operation to all images in given directory.

## SYNOPSIS

function X = fevalImages( fHandle, prms, srcDir, name, ext,nStr, nEnd, nDigits )

## DESCRIPTION

     Used to apply the same operation to all images in given directory.

     For each image in  srcDir, loads the image, applies the function in
     fHandle and stores the result.  The result x=fHandle(I,prms{:}) on the
     ith image is stored in X(:,...:,i).  If the size of x depends on the size
     of I, then all images in the directory must have the same size.  Also I
     may have a different format depending on how it is stored on disk -
     example: MxN for grayscale, MxNx3 for RGB, MxNx4 for CMYK. This function
     is similar to fevalArrays, except instead of operating on images in
     memory it operates on images on disk.  For long operations shows progress
     info.

     The srcDir must contain nothing but images.  Either the images follow no
     naming convention, or they follow a very rigid naming convention that
     consists of a string followed by an nDigits number specifying the image
     number, followed by an extension.  The advantage of the more rigid naming
     convention is that it allows a certain range of images to be operated on,
     specified by [nStr,nEnd]. For example, to operate on images
     "rats0003.tif ... rats0113.tif" in directory '../rats/' use:
      fevalImages( fHandle, prms, '../rats/', 'rats' , 'tif', 3, 113, 4 );
     If the parameter name is specified ('rats' in the example above), the
     rigid naming convention is assumed.  All further input arguments are
     optional. imwrite2 writes images in the format described above.

     A limitation of fevalImages is that it does not pass state information
     to fHandle.  For example, fHandle may want to know how many times it's
     been  called. This can be overcome by saving state information inside
     fHandle using 'persistent' variables.  For an example see imwrite2 (which
     uses persistent variables with fevalArrays).

     USAGE
      X = fevalImages( fHandle, prms, srcDir, [name], [ext],
                        [nStr], [nEnd], [nDigits] )

     INPUTS
      fHandle   - function to apply to each image [see above]
      prms      - cell array of additional parameters to fHandle (may be {} )
      srcDir    - directory containing images
      name      - [] base name of images
      ext       - [] extension of image
      nStr      - [] image number on which to start
      nEnd      - [] image number on which to end
      nDigits   - [] number of digits for filename index

     OUTPUTS
      X        - output array [see above]

     EXAMPLE
      % reads in all images in directory (note that fHandle is identity):
      X = fevalImages( @(x) x, {}, srcDir );
      % reads in different sized images into cell array:
      X = fevalImages( @(x) {x}, {}, srcDir );
      % reads in all images converting to grayscale:
      X = fevalImages( @(x) rgb2gray(x), {}, srcDir );

     See also FEVALARRAYS, IMWRITE2, PERSISTENT, TICSTATUS

     Piotr's Image&Video Toolbox      Version 2.40
     Copyright 2009 Piotr Dollar.  [pdollar-at-caltech.edu]
     Please email me if you find bugs, or have suggestions or questions!
     Licensed under the Lesser GPL [see external/lgpl.txt]

## CROSS-REFERENCE INFORMATION

This function calls:

- int2str2 Convert integer to string of given length; improved version of int2str.
- ticStatus Used to display the progress of a long process.
- tocStatus Used to display the progress of a long process.

This function is called by:

- imwrite2 Similar to imwrite, except follows a strict naming convention.