PRO image_partition, nx, ny, imxsize, imysize, grow, regions, nregions, xrsize, yrsize, status

; Description: This module determines the set of rectangular image regions "regions" created by partitioning 
;              an image of dimensions "imxsize" by "imysize" pixels into a grid of "nx" by "ny" equal size 
;              regions of dimensions "xrsize" by "yrsize" pixels. In deciding the coordinates of the image
;              regions to return, the algorithm will also take into account the amount of overlap between
;              regions "grow" requested by the user. 
;
; Input Parameters:
;
;   nx - INTEGER/LONG - The number of grid subdivisions in the x direction (Default value = 1). If the value
;                       of "nx" is greater than "imxsize", then it will be reset to the value of "imxsize".
;                       If the value of "nx" is zero or negative, then it will be reset to "1".
;   ny - INTEGER/LONG - The number of grid subdivisions in the y direction (Default value = 1). If the value
;                       of "ny" is greater than "imysize", then it will be reset to the value of "imysize".
;                       If the value of "ny" is zero or negative, then it will be reset to "1".
;   imxsize - INTEGER/LONG - The image size along the x-axis (pix).
;   imysize - INTEGER/LONG - The image size along the y-axis (pix).
;   grow - FLOAT/DOUBLE - This parameter controls the amount of overlap between the image regions and it is 
;                         specified as a fraction of the size of an image region before expansion (Default 
;                         value = 0.0). After expansion, the final size of an image region in any one 
;                         direction is given by "(2*grow + 1)*floor(S/M)" where S is the image size along 
;                         the relevant axis (pix) and M is the number of grid subdivisions along the same 
;                         axis. If the value of "grow" is negative, then it will be reset to "0.0".
;
; Output Parameters:
;
;   regions - IDL STRUCTURE - This parameter is an IDL structure with the following tags specifing the 
;                             image regions:
;
;                             lx - LONG - The x-axis pixel index of the lower left-hand corner of the
;                                         rectangular image region.
;                             ux - LONG - The x-axis pixel index of the upper right-hand corner of the
;                                         rectangular image region.
;                             ly - LONG - The y-axis pixel index of the lower left-hand corner of the
;                                         rectangular image region.
;                             uy - LONG - The y-axis pixel index of the upper right-hand corner of the
;                                         rectangular image region.
;
;   xrsize - LONG - The image region size along the x-axis (pix). All image regions have the same dimensions.
;   yrsize - LONG - The image region size along the y-axis (pix). All image regions have the same dimensions.
;   nregions - LONG - The number of image regions specified by the IDL structure "regions".
;   status - INTEGER - This parameter is returned with a value of "1" if the partitioning of the image was
;                      successful, and it is returned with a value of "0" if the partitioning of the image
;                      was unsuccessful.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   19/04/2009 - Module modified such that the image region index increases along rows and then columns,
;                rather than increasing along columns and then rows (dmb).
;   02/09/2008 - Module created (dmb).

;Check the values of "imxsize" and "imysize"

;Check the values of "nx" and "ny", forcing the values to be at least "1", and no greater than "imxsize" and 
;"imysize" respectively

;Check the value of "grow", forcing the value to be at least "0.0"

;Determine the number of required image regions

;Calculate the size of each region

;Create the output structure to contain the image region specifications

  ;Determine the current region limits in the y direction

  ;Extend the current region limits in the y direction to create the required overlap

    ;Determine the current region limits in the x direction

    ;Extend the current region limits in the x direction to create the required overlap

    ;Save the current region limits in the output structure

;Update the image region size