AST_MASK <X >

Mask a region of a data grid

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 .FALSE.) 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 AST_MASK <X > by an appropriate 1- or 2-character type code. For example, if you are masking data with type REAL, you should use the function AST_MASKR (see the " Data Type Codes" section below for the codes appropriate to other numerical types).

Invocation

RESULT = AST_MASK <X >( THIS, MAP, INSIDE, NDIM, LBND, UBND, IN, VAL, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to a Region.
MAP = INTEGER (Given)
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 arguments. A value of AST__NULL 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 = INTEGER (Given)
A boolean value which indicates which pixel are to be masked. If .TRUE. 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 .FALSE. 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 = INTEGER (Given)
The number of dimensions in the input grid. This should be at least one.
LBND( NDIM ) = INTEGER (Given)
An array containing the coordinates of the centre of the first pixel in the input grid along each dimension.
UBND( NDIM ) = INTEGER (Given)
An array 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. 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( ∗ ) = <Xtype > (Given and Returned)
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 AST_MASKR, the type of each array element should be REAL).

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. normal Fortran array storage order).

On exit, the samples specified by INSIDE are set to the value of VAL. All other samples are left unchanged.

VAL = <Xtype > (Given)
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).
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value

AST_MASK <X > = INTEGER
The number of pixels to which a value of BADVAL has been assigned.

Notes:

Data Type Codes

To select the appropriate masking function, you should replace <X > in the generic function name AST_MASK <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:

For example, AST_MASKD would be used to process DOUBLE PRECISION data, while AST_MASKS 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).

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, UBND are changed from type INTEGER to type INTEGER∗8. The function return type is similarly changed to type INTEGER∗8. The function name is changed by inserting the digit " 8" before the trailing data type code. Thus, AST_MASK <X > becomes AST_MASK8 <X >.
Copyright (C) 2021 East Asian Observatory