next up previous 264
Next: astOverlap - Test if two regions overlap each other
Up: AST Function Descriptions
Previous: astOffset2 - Calculate an offset along a geodesic curve in a 2D Frame


astOutline$<$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 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, $<$Xtype$>$ array[], int lbnd[2], int ubnd[2], double maxerr, int maxvert, 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 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".

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 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).
boxsize
The full width in pixels of a smoothing box to be applied to the polygon vertices before downsizing the polygon to a smaller number of vertices. If an even number is supplied, the next larger odd number is used. Values of one or zero result in no smoothing.
Returned Value:
astOutline$<$X$>$()
The number of pixels to which a value of "badval" has been assigned.
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.

  • A value of zero 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.


next up previous 264
Next: astOverlap - Test if two regions overlap each other
Up: AST Function Descriptions
Previous: astOffset2 - Calculate an offset along a geodesic curve in a 2D Frame

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council