#### Description:

This is a set of functions that modifies a Moc by combining it with a subset of the pixel positions contained within a supplied 2-dimensional array. A FrameSet must be supplied describing the World Coordinate Systems associated with the array. The current Frame of this FrameSet must be a SkyFrame or a CmpFrame containing a SkyFrame.

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

#### Synopsis

void astAddPixelMask <X >( AstMoc ∗this, int cmode, AstFrameSet ∗wcs, <Xtype > value, int oper, int flags, <Xtype > badval, const <Xtype > array[], const int dims[2] )

#### Parameters:

##### this

Pointer to the Moc to be modified.

##### cmode

Indicates how the Moc and select pixels are to be combined. Any of the following values may be supplied:

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

##### wcs

Pointer to a FrameSet defining the World Coordinate Systems associated with the image. The current Frame should be a SkyFrame or a CmpFrame containing a SkyFrame. The base Frame should have the same number of axes as the current Frame and should represent `"` 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.

##### value

A data value that specifies the selected pixels. See parameter `"` oper`"` .

##### oper

Indicates how the `"` value`"` parameter is used to select the required pixels. It can have any of the following values:

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

##### flags

The bitwise OR of a set of flag values which may be used to provide additional control over the operation. See the `"` 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.

##### badval

This parameter should have the same type as the elements of the data array. It specifies the value used to flag missing data (bad pixels). Such pixels are never included in the Moc.

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.

##### array

Pointer to the 2-dimensional data array. 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 astAddPixelMaskF, 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 (i.e. Fortran array indexing is used).

##### dims

Pointer to an array containing the length of each pixel axis, in pixels.

#### Control Flags

The following flags are defined in the `"` ast.h`"` header file and may be used to provide additional control over the process. Having selected a set of flags, you should supply the bitwise OR of their values via the `"` flags`"` parameter:

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

#### Data Type Codes

To select the appropriate masking function, you should replace <X > in the generic function name astAddPixelMask <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, astAddPixelMaskD would be used to process `"` double`"` data, while astAddPixelMaskS 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 argument `"` dims`"` is 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, astAddPixelMask <X > becomes astAddPixelMask8 <X >.
Copyright (C) 2021 East Asian Observatory