next up previous 264
Next: AST_OVERLAP - Test if two regions overlap each other
Up: AST Routine Descriptions
Previous: AST_OFFSET2 - Calculate an offset along a geodesic curve in a 2D Frame


AST_OUTLINE$<$X$>$ - Create a new Polygon outling values in a 2D data grid

Description:
This is a set of functions that create a Polygon enclosing a single contiguous set of pixels that have a specified value within a gridded 2-dimensional data array (e.g. an image).

A basic 2-dimensional Frame is used to represent the pixel coordinate system in the returned Polygon. The Domain attribute is set to "PIXEL", the Title attribute is set to "Pixel coordinates", and the Unit attribute for each axis is set to "pixel". All other attributes are left unset. The nature of the pixel coordinate system is determined by parameter STARPIX.

The MAXERR and MAXVERT parameters can be used to control how accurately the returned Polygon represents the required region in the data array. The number of vertices in the returned Polygon will be the minimum needed to achieve the required accuracy.

You should use a function which matches the numerical type of the data you are processing by replacing $<$X$>$ in the generic function name AST_OUTLINE$<$X$>$ are procesing data with type REAL, you should use the function AST_OUTLINER (see the "Data Type Codes" section below for the codes appropriate to other numerical types).

Invocation:
RESULT = AST_OUTLINE$<$X$>$( VALUE, OPER, ARRAY, LBND, UBND, MAXERR, MAXVERT, INSIDE, STARPIX, STATUS )
Arguments:
VALUE = $<$Xtype$>$ (Given)
A data value that specifies the pixels to be outlined.
OPER = INTEGER (Given)
Indicates how the VALUE parameter is used to select the outlined pixels. It can have any of the following values:
  • AST__LT: outline pixels with value less than VALUE.

  • AST__LE: outline pixels with value less than or equal to VALUE.

  • AST__EQ: outline pixels with value equal to VALUE.

  • AST__NE: outline pixels with value not equal to VALUE.

  • AST__GE: outline pixels with value greater than or equal to VALUE.

  • AST__GT: outline pixels with value greater than VALUE.
ARRAY( $*$ ) = $<$Xtype$>$ (Given)
A 2-dimensional array containing the data to be processed. The numerical type of this array should match the 1- or 2-character type code appended to the function name (e.g. if you are using AST_OUTLINER, the type of each array element should be REAL).

The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly and that of the second dimension least rapidly (i.e. normal Fortran array storage order).

LBND( 2 ) = INTEGER (Given)
An array containing the coordinates of the centre of the first pixel in the input grid along each dimension.
UBND( 2) = INTEGER (Given)
An array containing the coordinates of the centre of the last pixel in the input grid along each dimension.

Note that LBND and UBND together define the shape and size of the input grid, its extent along a particular (J'th) dimension being UBND(J)-LBND(J)$+$1. They also define the input grid's coordinate system, each pixel having unit extent along each dimension with integral coordinate values at its centre or upper corner, as selected by parameter STARPIX.

MAXERR = DOUBLE PRECISION (Given)
Together with MAXVERT, this determines how accurately the returned Polygon represents the required region of the data array. It gives the target discrepancy between the returned Polygon and the accurate outline in the data array, expressed as a number of pixels. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals MAXVERT, or the largest discrepancy between the accurate outline and the returned Polygon is greater than MAXERR. If MAXERR is zero or less, its value is ignored and the returned Polygon will have the number of vertices specified by MAXVERT.
MAXVERT = INTEGER (Given)
Together with MAXERR, this determines how accurately the returned Polygon represents the required region of the data array. It gives the maximum allowed number of vertices in the returned Polygon. Insignificant vertices are removed from the accurate outline, one by one, until the number of vertices remaining in the returned Polygon equals MAXVERT, or the largest discrepancy between the accurate outline and the returned Polygon is greater than MAXERR. If MAXVERT is less than 3, its value is ignored and the number of vertices in the returned Polygon will be the minimum needed to ensure that the discrepancy between the accurate outline and the returned Polygon is less than MAXERR.
INSIDE( 2 ) = INTEGER (Given)
An array containing the indices of a pixel known to be inside the required region. This is needed because the supplied data array may contain several disjoint areas of pixels that satisfy the criterion specified by VALUE and OPER. In such cases, the area described by the returned Polygon will be the one that contains the pixel specified by INSIDE. If the specified pixel is outside the bounds given by LBND and UBND, or has a value that does not meet the criterion specified by VALUE and OPER, then this function will search for a suitable pixel. The search starts at the central pixel and proceeds in a spiral manner until a pixel is found that meets the specified crierion.
STARPIX = LOGICAL (Given)
A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If .TRUE., the standard Starlink definition of pixel coordinate is used in which a pixel with integer index I spans a range of pixel coordinate from (I-1) to I (i.e. pixel corners have integral pixel coordinates). If .FALSE., the definition of pixel coordinate used by other AST functions such as AST_RESAMPLE, AST_MASK, etc., is used. In this definition, a pixel with integer index I spans a range of pixel coordinate from (I-0.5) to (I$+$0.5) (i.e. pixel centres have integral pixel coordinates).
BOXSIZE = INTEGER (Given)
The full width in pixels of a smoothing box to be applied to the polygon vertices before downsizing the polygon to a smaller number of vertices. If an even number is supplied, the next larger odd number is used. Values of one or zero result in no smoothing.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_OUTLINE$<$X$>$ = INTEGER
The number of pixels to which a value of BADVAL has been assigned.
Notes:
  • This function proceeds by first finding a very accurate polygon, and then removing insignificant vertices from this fine polygon using AST_DOWNSIZE.

  • The returned Polygon is the outer boundary of the contiguous set of pixels that includes ths specified "inside" point, and satisfy the specified value requirement. This set of pixels may potentially include "holes" where the pixel values fail to meet the specified value requirement. Such holes will be ignored by this function.

  • A value of zero will be returned if this function is invoked with the global error status set, or if it should fail for any reason.
Data Type Codes
To select the appropriate masking function, you should replace $<$X$>$ in the generic function name AST_OUTLINE$<$X$>$ with a 1- or 2-character data type code, so as to match the numerical type $<$Xtype$>$ of the data you are processing, as follows:
  • D: DOUBLE PRECISION

  • R: REAL

  • I: INTEGER

  • UI: INTEGER (treated as unsigned)

  • S: INTEGER$*$2 (short integer)

  • US: INTEGER$*$2 (short integer, treated as unsigned)

  • B: BYTE (treated as signed)

  • UB: BYTE (treated as unsigned)

For example, AST_OUTLINED would be used to process DOUBLE PRECISION data, while AST_OUTLINES would be used to process short integer data (stored in an INTEGER$*$2 array), etc.

For compatibility with other Starlink facilities, the codes W and UW are provided as synonyms for S and US respectively (but only in the Fortran interface to AST).



next up previous 264
Next: AST_OVERLAP - Test if two regions overlap each other
Up: AST Routine Descriptions
Previous: AST_OFFSET2 - Calculate an offset along a geodesic curve in a 2D Frame

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council