AST_CONVEX <X >

Create a new Polygon representing the convex hull of a 2D data grid

Description:

This is a set of functions that create the shortest Polygon that encloses all pixels with 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.

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_CONVEX <X > are procesing data with type REAL, you should use the function AST_CONVEXR (see the " Data Type Codes" section below for the codes appropriate to other numerical types).

Invocation

RESULT = AST_CONVEX <X >( VALUE, OPER, ARRAY, LBND, UBND, STARPIX, STATUS )

Arguments

VALUE = <Xtype > (Given)
A data value that specifies the pixels to be included within the convex hull.
OPER = INTEGER (Given)
Indicates how the VALUE parameter is used to select the required pixels. It can have any of the following values:

  • AST__LT: include pixels with value less than VALUE.

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

  • AST__EQ: include pixels with value equal to VALUE.

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

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

  • AST__GT: include 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_CONVEXR, 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.

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_CONVEX <X > = INTEGER
A pointer to the required Polygon. AST__NULL is returned without error if the array contains no pixels that satisfy the criterion specified by VALUE and OPER.

Notes:

Data Type Codes

To select the appropriate masking function, you should replace <X > in the generic function name AST_CONVEX <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_CONVEXD would be used to process DOUBLE PRECISION data, while AST_CONVEXS 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 and UBND 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_CONVEX <X > becomes AST_CONVEX8 <X >.
Copyright (C) 2021 East Asian Observatory