idlastro / FITS I/O: DIST_ELLIPSE

[Source code]

NAME
DIST_ELLIPSE
PURPOSE
Create a mask array useful for elliptical aperture photemetry
EXPLANATION
Form an array in which the value of each element is equal to the
semi-major axis of the ellipse of specified center, axial ratio, and 
position  angle, which passes through that element.  Useful for 
elliptical aperture photometry.
CALLING SEQUENCE
DIST_ELLIPSE, IM, N, XC, YC, RATIO, POS_ANG, /DOUBLE
INPUTS
N = either  a scalar specifying the size of the N x N square output
        array, or a 2 element vector specifying the size of the
        M x N rectangular output array.
XC,YC - Scalars giving the position of the ellipse center.   This does
        not necessarily have to be within the image
RATIO - Scalar giving the ratio of the major to minor axis.   This 
        should be greater than 1 for position angle to have its 
        standard meaning.
OPTIONAL INPUTS
POS_ANG - Position angle of the major axis, measured counter-clockwise
        from the Y axis.  For an image in standard orientation 
        (North up, East left) this is the astronomical position angle.
OPTIONAL INPUT KEYWORD
/DOUBLE - If this keyword is set and nonzero, the output array will
        be of type DOUBLE rather than floating point.
OUTPUT
IM - REAL*4 elliptical mask array, of size M x N.  THe value of each 
        pixel is equal to the semi-major axis of the ellipse of center
         XC,YC, axial ratio RATIO, and position angle POS_ANG, which 
        passes through the pixel.
EXAMPLE
Total the flux in a elliptical aperture with a major axis of 3', an
axial ratio of 2.3, and a position angle of 25 degrees centered on 
a specified RA and DEC.   The image array, IM is 200 x 200, and has 
an associated FITS header H.
ADXY, H, ra, dec, x, y       ;Get X and Y corresponding to RA and Dec
GETROT, H, rot, cdelt        ;CDELT gives plate scale degrees/pixel
cdelt = abs( cdelt)*3600.    ;CDELT now in arc seconds/pixel
DIST_ELLIPSE, ell, 200, x, y, 2.3, 25  ;Create a elliptical image mask
ell = ell*cdelt(0)           ;Distances now given in arcseconds
good = where( ell lt 180 )   ;Within 3 arc minutes
print,total( im(good) )      ;Total pixel values within 3'
RESTRICTIONS
The speed of DIST_ELLIPSE decreases and the the demands on virtual
increase as the square of the output dimensions.   Users should
dimension the output array as small as possible, and re-use the
array rather than re-calling DIST_ELLIPSE
REVISION HISTORY
Written    W. Landsman             April, 1991
Somewhat faster algorithm          August, 1992
Allow rectangular output array     June, 1994
Converted to IDL V5.0   W. Landsman   September 1997
Added /DOUBLE keyword   W. Landsman   July 2000