# doc-cache created by Octave 7.3.0
# name: cache
# type: cell
# rows: 3
# columns: 7
# name: <cell-element>
# type: sq_string
# elements: 1
# length: 15
datapack_to_bmp


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1984

  This function save the images inside of datapack in a set of BMP files.
  The formation rule of the BMP file names is:

  NAME=fullfile(DIRECTORY,sprintf([PRENAME,'.bmp'],II));

  Being II, the number of the saved image.

  After starting the main routine just type the following command at the
  prompt:

  h = datapack_to_bmp(DATA,DIRECTORY,PRENAME);

  %% To filenames: 'seed1.bmp', 'seed2,bmp', ..., 'seed128.bmp'
  h = datapack_to_bmp(DATA,'','seed%d');

  %% To filenames: 'img1coffee.bmp', 'img2coffee,bmp', ..., 'img100coffee.bmp'
  h = datapack_to_bmp(DATA,'','img%dcoffee');

  %% To filenames: 'img0001.bmp', 'img0002,bmp', ..., 'img0123.bmp'
  h = datapack_to_bmp(DATA,'','img%04d');

  
  Input:
  DATA      is the speckle data pack. Where DATA is a 3D matrix created grouping NTIMES 
            intensity matrices with NLIN lines and NCOL columns. When N=size(DATA), then
            N(1,1) represents NLIN and
            N(1,2) represents NCOL and
            N(1,3) represents NTIMES.
  DIRECTORY is the address where the BMP files will be saved.
  PRENAME   is the format filename, example: if you search names as 
            'fig1.bmp', then PRENAME='fig' or PRENAME='fig%d'. If PRENAME not
            contain a format specifiers of family %d, them this format specifiers 
            is added at the final of PRENAME string. The format string is similar
            to the function printf of others programming languages.
            Only are permitted format specifiers of family %d, given that will
            be replaced a decimal number.

  Output:
  h         returns a struct with the fields,
            h.file{i}: The name of i-th bmp file, 
            h.format:  The format filename,
            h.init:    The id of first element,
            h.dir:     The directory where the images will be saved, and
            h.nel:     The numbeer of images.


  For help, bug reports and feature suggestions, please visit:
  http://www.nongnu.org/bsltl




# name: <cell-element>
# type: sq_string
# elements: 1
# length: 74

  This function save the images inside of datapack in a set of BMP files.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 14
get_fir_filter


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 2549

  This function returns a fir filter with an order and  cut-off specified.
  Also can be configured the types of filter as: low pass, high pass, band pass  
  and band stop. The filter also can be weighted by a window. Finally exist
  a parameter that indicates if should be plotted the time and frequency  
  impulse response.
  
  After starting the main routine just type the following command at the
  prompt:

  % By default it is low-pass, hamming window and not display the impulse response.
          h=get_fir_filter(ORDER,Wn);
  [h FTYPE]=get_fir_filter(ORDER,Wn);

  % By default it uses hamming window and not display the impulse response.
          h=get_fir_filter(ORDER,Wn,CTYPE);
  [h FTYPE]=get_fir_filter(ORDER,Wn,CTYPE);

  % By default it don't display the impulse response.
          h=get_fir_filter(ORDER,Wn,CTYPE,WINDOW);
  [h FTYPE]=get_fir_filter(ORDER,Wn,CTYPE,WINDOW);

  % All parameters are configured.
          h=get_fir_filter(ORDER,Wn,CTYPE,WINDOW,GRAPHON);
  [h FTYPE]=get_fir_filter(ORDER,Wn,CTYPE,WINDOW,GRAPHON);


  %% Low pass filter of order ORDER=20, cut-off at frequency to a*Fs/2, Hanning
  %% windows
  h=get_fir_filter(20,a,'low');

  %% High pass filter of order ORDER=20, cut-off at frequency a*Fs/2, Hanning
  %% windows
  h=get_fir_filter(20,a,'high');

  %% Band pass filter of order ORDER=40, cut-off at frequencies at 
  %% [a1*Fs/2 a2*Fs/2], Hanning windows
  h=get_fir_filter(40,[a1 a2],'bandpass');

  %% Reject pass filter of order ORDER=40, cut-off at frequencies at [a1*Fs/2 a2*Fs/2], 
  %% Hanning windows
  h=get_fir_filter(40,[a1 a2],'stop');

  
  Input:
  ORDER     is the a variable that content the order of filter, the length of 
            filter will be equal to ORDER+1.
  Wn        is a scalar variable or vector(1x2) that content the cut-off 
            frequencies.
  CTYPE     [optional] it is the cut-off type of the fir filter, it can be ser
            'low', 'high', 'bandpass' or 'stop'. By default this value is 'low'.
  WINDOW    [optional] it is a vector that represent the weighted values of the
            the filter.
  GRAPHON   [optional] enable or disable the display of the frequency  
            impulse response.

  Output:
  h         it is a vector of length ORDER+1 that represent a fir filter of
            order ORDER.
  FTYPE     [optional] returns the type of the fir filter.
            http://www.mathworks.com/help/signal/ug/fir-filter-design.html

  For help, bug reports and feature suggestions, please visit:
  http://www.nongnu.org/bsltl




# name: <cell-element>
# type: sq_string
# elements: 1
# length: 75

  This function returns a fir filter with an order and  cut-off specified.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 13
get_lux_level


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 2188

  This function creates an analysis in time of illumination level in some points 
  in the datpack. 
  A set of M points (pixels) randomly are selected in the datapack, 
  and through DATA(:,:,k) for all k value. These points can be selected with
  uniform distribution or a gaussian distribution.

  [YMEAN YSTD POINTS]=get_lux_level(DATA,M);
  [YMEAN YSTD POINTS]=get_lux_level(DATA,M,'on');
  [YMEAN YSTD POINTS]=get_lux_level(DATA,M,Sigma);
  [YMEAN YSTD POINTS]=get_lux_level(DATA,M,Sigma,'on');
  
  Input:
  DATA    is the speckle data pack. Where DATA is a 3D matrix created grouping NTIMES 
          intensity matrices with NLIN lines and NCOL columns. When N=size(DATA), then
          N(1,1) represents NLIN and
          N(1,2) represents NCOL and
          N(1,3) represents NTIMES.
  M       is the number of points in analysis.
  Sigma   [Optional]is the standard deviation in pixels. If this variable is used
          then the points are selected using a gaussian distribution. 
  Show    [Optional] can be used in the last position of input, and its function 
          is used to enable a graphic output of the selected points that formed the
          THSP. Show='on', Show='on-red', Show='on-red-filled', Show='on-green', 
          Show='on-green-filled', Show='on-blue' , Show='on-blue-filled'
          Show='on-cyan', Show='on-cyan-filled', Show='on-magenta', 
          Show='on-magenta-filled', Show='on-yellow', Show='on-yellow-filled',
          Show='on-black', Show='on-black-filled', Show='on-gray' or  
          Show='on-gray-filled', Show='on-white' or  
          Show='on-white-filled' to enable. 
          It is disabled in other cases, by default Show='off'.
          Show='on' plot the points in the color red, in other cases are used the
          specified colors.

  Output:
  YMEAN  is the mean illumination level in M points.
  YSTD   is the standard deviation value (arround) of illumination level in M points.
  POINTS [Optional] is a matrix with two columns and 
         M lines. Thus, each line represents one point in study, (line,column).


  For help, bug reports and feature suggestions, please visit:
  http://nongnu.org/bsltl/




# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80

  This function creates an analysis in time of illumination level in some po...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 19
imagesc_with_points


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 780

  This function is similar to imagesc, with the difference that this also draw 
  the points contained in the variable POINTS. Additionally can be selected the
  color of the points.

  imagesc_with_points(MAT, POINTS);
  hf=imagesc_with_points(MAT, POINTS);
  hf=imagesc_with_points(MAT, POINTS,'w');

  
  Input:
  MAT       is a matrix that will be used like the canvas to draw the points. 
  POINTS    is a matrix with two columns and M lines. Thus, each line represent 
            one point in study.(line,column).
  OPTION    is the color of the points, by default OPTION='r', you can try 'r',
            'g', 'b', 'w','k'.

  Output:
  hf        returns the figure handler.


  For help, bug reports and feature suggestions, please visit:
  http://www.nongnu.org/bsltl




# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80

  This function is similar to imagesc, with the difference that this also dr...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 11
mwnumbering


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1556

  This function divides the MAT matrix in windows of WLines lines and WColumns 
  columns, then in each one of these windows it is calculated the mean value of all 
  elements. 

  With theirs information is created a new matrix MATW with the same 
  size and windows of MAT, and the mean values in the MAT matrix are replaced 
  in all elements, for each window, in the MATW matrix.
  
  In the middle of each window is write the representative value of a window,
  following the matrix MATW. 
  
  After starting the main routine just type the following command at the
  prompt:
  MATW = mwnumbering(MAT,WLines,WColumns);
  MATW = mwnumbering(MAT,WLines,WColumns,FontSize);

  Mean values, of the elements in the window of 8x10 pixels, in the MAT matrix.
  In each windows is write the value of MATW in the window. 
  The used font size is 10. 
  MATW = mwnumbering(MAT,8,10);

  Mean values, of the elements in the window of 8x10 pixels, in the MAT matrix.
  In each windows is write the value of MATW in the window.
  The used font size is 16. 
  MATW = mwnumbering(MAT,8,10,16);
  
  Input:
  MAT      is a matrix with NLIN lines and NCOL columns.
  WLines   is the number of lines in each analysis window.
  WColumns is the number of columns in each analysis window.
  FontSize [Optional] The font size of text.

  Output:
  MATW     is a matrix with the mean values, of the elements in 
           the window of WLinesxWColumns pixels, in the MAT matrix.


  For help, bug reports and feature suggestions, please visit:
  http://nongnu.org/bsltl/




# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80

  This function divides the MAT matrix in windows of WLines lines and WColum...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 13
select_points


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 2947

  This function select a set of M points, selected according to Type, 
  in DATA(:,:,1), and through DATA(:,:,k) 

  After starting the main routine just type the following command at the
  prompt:
  P1 = select_points(DATA,Type,M);

  [P1 P2] = select_points(DATA,'gaussian',M,2);
  P1      = select_points(DATA,'gaussian',M);

  [P1 P2] = select_points(DATA,'random',M,2);
  P1      = select_points(DATA,'random',M);

  [P1 P2] = select_points(DATA,'region',2);
  P1      = select_points(DATA,'region');

  [P1 P2 P3]= select_points(DATA,'line',3);
  P1        = select_points(DATA,'line');

  
  Input:
  DATA    is the speckle data pack. Where DATA is a 3D matrix created grouping NTIMES 
          intensity matrices with NLIN lines and NCOL columns. When N=size(DATA), then
          N(1,1) represent NLIN and
          N(1,2) represent NCOL and
          N(1,3) represent NTIMES.
          Or a image where if N=size(DATA), then
          N(1,1) represent NLIN and
          N(1,2) represent NCOL
  Type    is the type of selecting points method. These can be:
          'gaussian' - Need selecting two points; center and deviation radius.
                       This type select M points chosen randomly (Gaussian)
                       around one central point. Also is needed add an additional 
                       input parameter M, with the number of points.
          'random'   - Need selecting two points; two opposite corners.
                       This type select M points chosen uniformly random
                       between two corner points. Also is needed add an additional 
                       input parameter M, with the number of points
          'region'   - Need selecting two points; two opposite corners.
                       This type select all the pixels between two corner points.
          'line'     - Need selecting two points; begin and end.
                       This type select all the pixels in a line between two 
                       corner points.
  M        [Optional] is the number of points randomly selected.
           if Type is 'gaussian' or 'random', then M is mandatory and M will be
           the third input parameter; in other case M is not necessary and the 
           third input parameter will be Groups.
  Groups   [Optional] is the number of groups of points to be selected.
           if Type is 'gaussian' or 'random', Groups is the fourth input parameter
           in other case, Groups is the third parameter.
           the groups of points are returned as additional output parameters.
           by default Groups is 1.

  Output:
  P1      is a matrix with two columns and M lines. Thus, each line represent 
          one point in study.(line,column).
  Pi      is a matrix with two columns and M lines. Thus, each line represent 
          one point in study.(line,column). the existence of this group of points
          depend of input parameter Groups.




# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80

  This function select a set of M points, selected according to Type, 
  in ...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 11
thsp_points


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1587

  This function evaluates the THSP (Time History Speckle Patterns) of a set
  points selected in DATA(:,:,1), and through DATA(:,:,k) 
  for all k value. Similarly to [1][2] the THSP is calculated.

  References:
  [1]  OULOMARA, G.; TRIBILLON, J.; DUVERNOY, J. Biological activity measurements 
       on botanical specimen surfaces using a temporal decorrelation effect of 
       laser speckle. Journal of Moderns Optics, London, v. 36, n. 2, p. 136-179, 
       Feb. 1989.

  [2]  XU, Z.; JOENATHAN, C.; KHORANA, B. M. Temporal and spatial properties of 
       the time-varying speckles of botanical specimens. Optical Engineering, Virginia, 
       v. 34, n. 5, p. 1487-1502, May 1995.


  After starting the main routine just type the following command at the
  prompt:
  Y = thsp_points(DATA, POINTS);
  
  Input:
  DATA    is the speckle data pack. Where DATA is a 3D matrix created grouping NTIMES 
          intensity matrices with NLIN lines and NCOL columns. When N=size(DATA), then
          N(1,1) represent NLIN and
          N(1,2) represent NCOL and
          N(1,3) represent NTIMES.
  POINTS  is a matrix with two columns and M lines,
          where each line represent one point in study as (line,column).
          Or a column vector with M lines,
          where each line represent one point in study as a linear index.
          A matrix is linearly indexed moving from one column to next, 
          filling up all rows in each column.

  Output:
  Y      is the time history speckle patterns. Where Y is a 2D matrix with
         M lines and NTIMES columns.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80

  This function evaluates the THSP (Time History Speckle Patterns) of a set
...





