PRO convert_pixel_indices_to_image_subscripts, xind, yind, imxsize, subs, nsubs, status, NO_PAR_CHECK = no_par_check
; Description: This module converts a set of x and y pixel indices "xind" and "yind", respectively,
; to a set of subscripts "subs" corresponding to an image array with a size of
; "imxsize" pixels along the x-axis.
;
; N.B: The bottom left hand pixel in the image area has pixel index coordinates of
; "(0,0)", and the right hand column of pixels in the image area has an x-axis
; pixel index coordinate of "imxsize-1".
;
; Input Parameters:
;
; xind - INTEGER/LONG SCALAR/VECTOR/ARRAY - A scalar/vector/array of pixel indices along the
; image x-axis. All pixel indices must correspond to
; image pixels that lie within the image area, and
; therefore all elements in this parameter must have
; values that are non-negative and less than "imxsize".
; yind - INTEGER/LONG SCALAR/VECTOR/ARRAY - A scalar/vector/array of non-negative pixel indices
; along the image y-axis. This parameter must have
; the same number of elements as "xind".
; imxsize - INTEGER/LONG - The image size along the x-axis (pix). This parameter must be
; positive.
;
; Output Parameters:
;
; subs - LONG VECTOR - A one-dimensional vector of subscripts, corresponding to the set of x
; and y pixel indices "xind" and "yind", respectively, for an image array
; with a size of "imxsize" pixels along the x-axis.
; nsubs - LONG - The number of subscripts in the vector of subscripts "subs".
; status - INTEGER - If the module successfully converted 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_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:
;
; 04/01/2011 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "xind" is of the correct number type
;Check that "yind" is of the correct number type, and that it has the same number of elements
;as "xind"
;Check that "imxsize" is a positive number of the correct type
;Check that all the elements of "xind" and "yind" are non-negative, and that all the elements
;of "xind" are less than "imxsize"
;Convert the pixel indices "xind" and "yind" to image subscripts "subs"
;Set "status" to "1"