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 pixel index of the first pixel in the input grid along each dimension.
UBND( 2) = INTEGER (Given)
An array containing the pixel index 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 pixel grid, its extent along a particular (J’ th) dimension being UBND(J)-LBND(J)+1 pixels. For FITS images, the LBND values will be 1 and the UBND values will be equal to the NAXISi header values. Other data systems, such as the Starlink NDF system, allow an arbitrary pixel origin to be used (i.e. LBND is not necessarily 1).

These bounds also define the input grid’ s floating point 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 pixel 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).
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value

AST_OUTLINE <X > = INTEGER
A pointer to the required Polygon.

Notes:

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:

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).

Handling of Huge Pixel Arrays

If the input grid is so large that an integer pixel index, (or a count of pixels) could exceed the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte) to hold pixel indices and pixel counts. Specifically, the arguments LBND, UBND and INSIDE are changed from type INTEGER to type INTEGER∗8. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, AST_OUTLINE <X > becomes AST_OUTLINE8 <X >.
Copyright (C) 2021 East Asian Observatory