Mask a region of a data grid astMaskX
"
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 astMaskX
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).
"
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.
"
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"
elements, containing the coordinates
of the centre of the first pixel in the input grid along each dimension. "
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.
"
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.
"
in"
array. It specifies the
value used to flag the masked data (see "
inside"
). "
badval"
has been assigned. 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.
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.
"
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,
astMaskX
becomes astMask8X.