Add a set of pixels to a Moc
The subset of pixels to be combined with the Moc are selected using the VALUE and OPER parameters. The way in which the existing Moc and the selected pixels are combined together is determined by the CMODE parameter.
An adaptive alogorithm is used to find the HEALPix cells that are inside the selected area
in the pixel array. An initial grid, corresponding to the HEALPix cells at the order given
by the Moc’
s "
MinOrder"
attribute, is placed over the pixel array. Each of these cells is
tested at 9 positions (corners, edge-centres and cell-centre). If all 9 positions are inside
the selected area of pixels, then the whole cell is assumed to be inside. If no positions are
inside the selected area, then the whole cell is assumed to be outside. If there is a mix of
inside and outside positions, the cell is divided into four sub-cells at HEALPix order "
MinOrder+1"
,
and the same test is applied to each sub-cell in turn. When the HEALPix order reaches the value of the
Moc’
s "
MaxOrder"
attribute, each cell is tested only at the cell centre, and is assumed to be inside
the selected area if the cell centre is inside the selected area.
This process means that contiguous "
islands"
or "
holes"
in the supplied pixel mask may be
missed if they are smaller than the cell size associated with HEALPix order "
MinOrder"
.
If no value has yet been set for the MaxOrder attribute, then this function will automatically set it to the smallest value that results in the cells in the Moc being no larger than half the size of the pixels in the centre of the array. Note, if the value set for attribute MinOrder is greater than or equal to MaxOrder, a value of (MaxOrder-1) will be used in place of MinOrder.
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_ADDPIXELMASK<X>
are procesing data with type REAL, you should use the function AST_ADDPIXELMASKR (see the "
Data
Type Codes"
section below for the codes appropriate to other numerical types).
AST__AND: The modified Moc is the intersection of the original Moc and the selected pixels.
AST__OR: The modified Moc is the union of the original Moc and the selected pixels.
AST__XOR: The modified Moc is the exclusive disjunction of the original Moc and the selected pixels.
"
grid"
coordinates within a
pixel array (i.e. the first pixel is centred at (1.0,1.0,...) and the distance between pixel centres is 1.0 on
both axes). The array supplied for parameter ARRAY is assumed to be a 2-dimensional slice
from this array, spanned by the grid axes corresponding to the SkyFrame axes. AST__LT: select pixels with value less than VALUE.
AST__LE: select pixels with value less than or equal to VALUE.
AST__EQ: select pixels with value equal to VALUE.
AST__NE: select pixels with value not equal to VALUE.
AST__GE: select pixels with value greater than or equal to VALUE.
AST__GT: select pixels with value greater than VALUE.
"
Control Flags"
section below for a description of the options
available. If no flag values are to be set, a value of zero should be given. If the AST__USEBAD flag is set via the FLAGS parameter, then this value is used to test for bad pixels in the supplied data array.
The storage order of data within this array should be such that the index of the first grid dimension varies most rapidly (i.e. normal Fortran array storage order).
AST__USEBAD: Indicates that there may be bad pixels in the input array which must be recognised by comparing with the value given for BADVAL. If this flag is not set, all input values are treated literally.
D: DOUBLE PRECISION
R: REAL
I: INTEGER
UI: INTEGER (treated as unsigned)
S: INTEGER∗2 (short integer)
US: INTEGER∗2 (short integer, treated as unsigned)
B: BYTE (treated as signed)
UB: BYTE (treated as unsigned)
For example, AST_ADDPIXELMASKD would be used to process DOUBLE PRECISION data, while AST_ADDPIXELMASKS 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).
"
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 argument DIMS is 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_ADDPIXELMASK<X>
becomes AST_ADDPIXELMASK8<X>.