#### 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 astOutline <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 astOutlineF (see the `"` Data Type Codes`"` section below for the codes appropriate to other numerical types).

#### Synopsis

AstPolygon ∗astOutline <X >( <Xtype > value, int oper, const <Xtype > array[], const int lbnd[2], const int ubnd[2], double maxerr, int maxvert, const int inside[2], int starpix )

#### Parameters:

##### value

A data value that specifies the pixels to be outlined.

##### oper

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

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 astOutlineF, 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 pixel index of the first pixel in the input grid along each dimension.

##### ubnd

Pointer to an array of two integers 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

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

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

Pointer to an array of two integers 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

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

##### astOutline <X >()

A pointer to the required Polygon.

#### Notes:

- This function proceeds by first finding a very accurate polygon, and then removing insignificant vertices from this fine polygon using astDownsize.

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

- 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 astOutline <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, astOutlineD would be used to process `"` double`"` data, while astOutlineS 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`"` , `"` ubnd`"` and `"` inside`"` 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, astOutline <X > becomes astOutline8 <X >.
Copyright (C) 2021 East Asian Observatory