#### Description:

This is a set of functions for masking out regions within gridded data (e.g. an image). The functions modifies a given data grid by assigning a specified value to all samples which are inside (or outside if `"` inside`"` is zero) the specified Region.

You should use a masking function which matches the numerical type of the data you are processing by replacing <X > in the generic function name astMask <X > by an appropriate 1- or 2-character type code. For example, if you are masking data with type `"` float`"` , you should use the function astMaskF (see the `"` Data Type Codes`"` section below for the codes appropriate to other numerical types).

#### Synopsis

int astMask <X >( AstRegion ∗this, AstMapping ∗map, int inside, int ndim, const int lbnd[], const int ubnd[], <Xtype > in[], <Xtype > val )

#### Parameters:

##### this

Pointer to a Region.

##### map

Pointer to a Mapping. The forward transformation should map positions in the coordinate system of the supplied Region into pixel coordinates as defined by the `"` lbnd`"` and `"` ubnd`"` parameters. A NULL pointer can be supplied if the coordinate system of the supplied Region corresponds to pixel coordinates. This is equivalent to supplying a UnitMap.

The number of inputs for this Mapping (as given by its Nin attribute) should match the number of axes in the supplied Region (as given by the Naxes attribute of the Region). The number of outputs for the Mapping (as given by its Nout attribute) should match the number of grid dimensions given by the value of `"` ndim`"` below.

##### inside

A boolean value which indicates which pixel are to be masked. If a non-zero value is supplied, then all grid pixels with centres inside the supplied Region are assigned the value given by `"` val`"` , and all other pixels are left unchanged. If zero is supplied, then all grid pixels with centres not inside the supplied Region are assigned the value given by `"` val`"` , and all other pixels are left unchanged. Note, the Negated attribute of the Region is used to determine which pixel are inside the Region and which are outside. So the inside of a Region which has not been negated is the same as the outside of the corresponding negated Region.

For types of Region such as PointList which have zero volume, pixel centres will rarely fall exactly within the Region. For this reason, the inclusion criterion is changed for zero-volume Regions so that pixels are included (or excluded) if any part of the Region passes through the pixel. For a PointList, this means that pixels are included (or excluded) if they contain at least one of the points listed in the PointList.

##### ndim

The number of dimensions in the input grid. This should be at least one.

##### lbnd

Pointer to an array of integers, with `"` ndim`"` elements, containing the coordinates of the centre of the first pixel in the input grid along each dimension.

##### ubnd

Pointer to an array of integers, with `"` ndim`"` elements, 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.

##### in

Pointer to an array, with one element for each pixel in the input grid, containing the data to be masked. 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 astMaskF, 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 final dimension least rapidly (i.e. Fortran array indexing is used).

On exit, the samples specified by `"` inside`"` are set to the value of `"` val`"` . All other samples are left unchanged.

##### val

This argument should have the same type as the elements of the `"` in`"` array. It specifies the value used to flag the masked data (see `"` inside`"` ).

#### Returned Value

##### astMask <X >()

The number of pixels to which a value of `"` badval`"` has been assigned.

#### Notes:

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

- An error will be reported if the overlap of the Region and the array cannot be determined.

#### Data Type Codes

To select the appropriate masking function, you should replace <X > in the generic function name astMask <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, astMaskD would be used to process `"` double`"` data, while astMaskS 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`"` and `"` ubnd`"` are changed from type `"` int`"` to type `"` int64_t`"` (defined in header file stdint.h). The function return type is similarly changed to type int64_t. The function name is changed by inserting the digit `"` 8`"` before the trailing data type code. Thus, astMask <X > becomes astMask8 <X >.
Copyright (C) 2021 East Asian Observatory