Create a new Polygon outling values in a 2D data grid
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).
"
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"
.
"
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).
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"
.
"
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"
. "
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"
. "
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. 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.
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.
"
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$>$.