next up previous 264
Next: astMatchAxes - Find any corresponding axes in two Frames
Up: AST Function Descriptions
Previous: astMark - Draw a set of markers for a Plot


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


next up previous 264
Next: astMatchAxes - Find any corresponding axes in two Frames
Up: AST Function Descriptions
Previous: astMark - Draw a set of markers for a Plot

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
7th December 2012
E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2012 Science \& Technology Facilities Council