#### 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 astConvex <X > by an appropriate 1- or 2-character type code. For example, if you are procesing data with type `"` float`"` , you should use the function astConvexF (see the `"` Data Type Codes`"` section below for the codes appropriate to other numerical types).

#### Synopsis

AstPolygon ∗astConvex <X >( <Xtype > value, int oper, const <Xtype > array[], const int lbnd[2], const int ubnd[2], int starpix )

#### Parameters:

##### value

A data value that specifies the pixels to be included within the convex hull.

##### oper

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

Pointer to 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 astConvexF, the type of each array element should be `"` float`"` ).

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. Fortran array indexing is used).

##### lbnd

Pointer to an array of two integers containing the coordinates of the centre of the first pixel in the input grid along each dimension.

##### ubnd

Pointer to an array of two integers 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 (assuming the index `"` j`"` to be zero-based). 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

A flag indicating the nature of the pixel coordinate system used to describe the vertex positions in the returned Polygon. If non-zero, 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 zero, the definition of pixel coordinate used by other AST functions such as astResample, astMask, 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).

#### Returned Value

##### astConvex <X >()

A pointer to the required Polygon. NULL is returned without error if the array contains no pixels that satisfy the criterion specified by `"` value`"` and `"` oper`"` .

#### Notes:

- NULL 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 astConvex <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

- F: float

- L: long int

- UL: unsigned long int

- I: int

- UI: unsigned int

- S: short int

- US: unsigned short int

- B: byte (signed char)

- UB: unsigned byte (unsigned char)

For example, astConvexD would be used to process `"` double`"` data, while astConvexS would be used to process `"` short int`"` data, etc.

#### 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 `"` int`"` to type `"` int64_t`"` (defined in header file stdint.h). The function name is changed by inserting the digit `"` 8`"` before the trailing data type code. Thus, astConvex <X > becomes astConvex8 <X >.
Copyright (C) 2021 East Asian Observatory