PRO generate_pixel_indices_for_rectangle_in_image, imxsize, imysize, xlo, xhi, ylo, yhi, xind, yind, subs, nind, status, danidl_cppcode, NO_SUBS = no_subs, $
; Description: This module generates a set of x and y pixel indices "xind" and "yind", respectively,
; for a rectangular region in an image array of size "imxsize" by "imysize" pixels.
; The rectangular region is defined by the pixel index coordinates "(xlo,ylo)" of the
; bottom left hand pixel in the rectangle, and the pixel index coordinates "(xhi,yhi)"
; of the top right hand pixel in the rectangle. If either (or both) of these index
; coordinates lie outside of the image area, then the rectangular region is truncated
; to the overlap region with the image area before generating the pixel indices, which
; may of course be empty. The module also returns the image subscripts "subs"
; corresponding to the set of x and y pixel indices.
; This module will use C++ code if possible to achieve a faster execution than the
; default IDL code. The C++ code can be up to a factor of ~1.75 times faster than the
; IDL code in this case.
;
; N.B: The bottom left hand pixel in the image area has pixel index coordinates of
; "(0,0)", and the top right hand pixel in the image area has pixel index
; coordinates of "(imxsize-1,imysize-1)".
;
; Input Parameters:
;
; imxsize - INTEGER/LONG - The image size along the x-axis (pix). This parameter must be positive.
; imysize - INTEGER/LONG - The image size along the y-axis (pix). This parameter must be positive.
; xlo - INTEGER/LONG - The x index of the bottom left hand corner of the rectangular region.
; xhi - INTEGER/LONG - The x index of the top right hand corner of the rectangular region. This
; parameter must have a value that is greater than or equal to the value of
; the parameter "xlo".
; ylo - INTEGER/LONG - The y index of the bottom left hand corner of the rectangular region.
; yhi - INTEGER/LONG - The y index of the top right hand corner of the rectangular region. This
; parameter must have a value that is greater than or equal to the value of
; the parameter "ylo".
; danidl_cppcode - STRING - The full directory path indicating where the DanIDL C++ code is
; installed. The shared library of DanIDL C++ routines should exist as
; "/dist/libDanIDL.so" within the installation.
;
; Output Parameters:
;
; xind - LONG VECTOR - A one-dimensional vector with "nind" elements representing the pixel
; indices along the image x-axis for the required rectangular region in an
; image array of size "imxsize" by "imysize" pixels. All elements in this
; parameter are non-negative and less than "imxsize". If the overlap region
; between the rectangular region and the image area is empty, then this
; parameter is set to the single element vector "[-1]".
; yind - LONG VECTOR - A one-dimensional vector with "nind" elements representing the pixel
; indices along the image y-axis for the required rectangular region in an
; image array of size "imxsize" by "imysize" pixels. All elements in this
; parameter are non-negative and less than "imysize". If the overlap region
; between the rectangular region and the image area is empty, then this
; parameter is set to the single element vector "[-1]".
; subs - LONG VECTOR - A one-dimensional vector with "nind" elements representing the image
; subscripts for the required rectangular region in an image array of size
; "imxsize" by "imysize" pixels. All elements in this parameter are
; non-negative. If the overlap region between the rectangular region and
; the image area is empty, or if the keyword NO_SUBS is set (as "/NO_SUBS"),
; then this parameter is set to the single element vector "[-1]".
; nind - LONG - The number of elements in each of the output parameters "xind", "yind", and
; "subs". If the overlap region between the rectangular region and the image area
; is empty, then this parameter is set to "0".
; status - INTEGER - If the module successfully generated the set of x and y pixel indices, then
; "status" is returned with a value of "1", otherwise it is returned with a
; value of "0".
;
; Keywords:
;
; If the keyword NO_SUBS is set (as "/NO_SUBS"), then the module will not generate the image
; subscripts "subs", and this parameter will be returned as the single element vector "[-1]".
; Set this keyword if the image subscripts are not required in order to obtain a faster
; execution of this module.
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the module will not perform
; parameter checking on the input parameters, reducing module overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 03/01/2011 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "imxsize" and "imysize" are positive numbers of the correct type
;Check that "xlo", "xhi", "ylo", and "yhi" are of the correct number type and that they all
;have sensible values
;Set "status" to "1"
;Determine the overlap region between the rectangular region and the image area
;If the overlap region between the rectangular region and the image area is empty, then return
;an empty set of pixel indices
;Generate the x and y pixel indices for the rectangular region
;If required, generate the image subscripts for the rectangular region