BURNMASK

Description

Parameters

burnmask(fili, dbic, mask, maskfile, burnval, inclus, filo, dboc, ftype, foptions)

Parameter descriptions

FILI

Specifies the name of the file containing the input channels (DBIC) to be processed.

DBIC

Optionally specifies the input channels to be processed. If no channels are provided explicitly, all channels will be processed automatically.

MASK

Specifies the areas of the data to be processed. Only pixels within the mask area are altered and unmasked pixels are left unchanged.

You can define these areas using three types of mask boundaries: window, bitmap, or polygon vectors.

            MASK=Xoffset, Yoffset, Xsize, Ysize 
          

Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

For a bitmap mask, specify the number of the bitmap segment that you want to use. All the pixels within the specified segment having a pixel value of 1 define the area where input data must exist to be processed.

For a vector mask, specify the number of the polygon segment that you want to use as a mask. The masked pixels will be the ones within the provided polygons.

If you specify a MASK but not a MASKFILE, the MASK is obtained from the input file.

MASKFILE

BURNVAL

Specifies numbers to burn to the input channels. Regardless of the type of mask you are using, you can always specify a single value to update all of the pixels under the provided mask to this number. You can provide the burn values as a single number (applied to all input channels) or as a pixel "stack". If you provide a pixel stack, but the number of values does not equal the number of input channels, the list will be truncated or the last value will be repeated as necessary. With complex data, you must specify a pair of values for each channel as real and imaginary parts; otherwise, the last value will be repeated for the remaining parts of each channel.

INCLUS

Whether or not the mask is inclusive.

By default, only pixels inside of the mask will be burned, but if this parameter is set to "No" then mask is inverted automatically.

FILO

Specifies the name of the file to receive the processed raster data. If FILO does not exist, a new file will be created using FTYPE and FOPTIONS. In such a case, the file will have the same number of channels as specified in DBIC and have the same geocoding information and metadata as FILI. If FILO already exists, the output file specified must be in a format that can be updated. Furthermore, the updatable file must already contain suitable channels for the result data to be written to and those must be specified using DBOC. When writing to an existing file, FTYPE and FOPTIONS should not be specified. If they are specified, BURNMASK will error unless they agree with the existing file. FILO can equal FILI, as long as FILI meets the above criteria.

DBOC

Optionally specifies the output channels to receive the burned raster.

If FILO specifies a new file, DBOC should be left blank (defaulted) and the results will be written to the channels in the new file.

If FILO points to an existing file, DBOC must specify existing channels to be updated/overwritten. If FILO equals FILI, and output channels (DBOC) equal the input channels (DBIC), then those channels will be modified in place.

FTYPE

Optionally specifies the output file format type, represented by a three- or four-letter code. The format type must be a GDB-recognized file type. If FILO specified an existing file, FTYPE should not be specified since that existing file will be updated and its type won't be changed.

For a complete list of GDB-recognized file types and their codes, see GDB file formats in the Technical Reference section of the CATALYST Professional online Help.

FOPTIONS

Optionally specifies the file creation options to be applied when creating the output file. These are specific to the file format; in each case, the default of no options is allowed. FOPTIONS can be used to specify the compression schemes, file format subtypes, and other information.

Different options are available for different file types (see the FTYPE parameter). The options are described in GDB file formats in the Technical Reference section of the CATALYST Professional online Help.

Details

BURNMASK will alter pixels in a raster that are covered by the provided mask (that is, it burns a mask into a raster). The mask, which can be one of three types, will spatially dictate which pixels are to be affected. All pixels that are outside of the mask will be present in the output, unchanged. Any number of channels in the input raster can be processed.

When the mask is a bitmap or polygon layer it can be in a different projection than the input raster data and the mask will be reprojected on-the-fly to determine the pixels to alter.

In the simplest case, a single value specified using the BURNVAL (Burn Values) parameter will be written to the raster under the entire mask. If the value being burned is outside of the values of the raster's bit depth, an error will be generated. For example, if trying to burn a value of 500 into an 8U channel, BURNMASK will error and not create any output.

BURNMASK is aware of NoData values in the input raster. If a pixel is defined to be NoData via the NO_DATA_VALUE metadata tag, that pixel will not be adjusted even if it is covered by the provided mask (that is, any pixel that is NoData in the input will be in the output).

Examples

Set all of the pixels in the DEM to 0 for all pixels in the ocean.

from pci.burnmask import burnmask

fili = "dem.pix"         # input raster
dbic = []                # default, process all channels
mask = [1]               # use first segment as the mask
maskfile = "oceans.shp"  # mask file
burnval = [0]            # set masked pixels to 0
inclus = "yes"           # inclusive mask
filo = "dem_0.pix"       # output file to be created
dboc =  []               # default, creating output file
ftype = ''               # default, use PIX
foptions = ''            # default, no options

burnmask( fili, dbic, mask, maskfile, burnval, inclus, filo, dboc, ftype, foptions )
      

Set all of the water pixels in the input image to have artificially dark blue water, when viewed as natural color image.

from pci.burnmask import burnmask

fili = "L7_fuse.pix"      # input raster
dbic = [3,2,1]            # use R,G and B channels
mask = [2]                # use first segment as the mask
maskfile = "L7_water.pix" # mask file
burnval = [0,0,140]       # RGB values for dark blue
inclus = "yes"            # inclusive mask
filo = "L7_fuse.pix"      # write to input file
dboc =  [3,2,1]           # update input channels
ftype = ''                # unnecessary
foptions = ''             # unnecessary

burnmask( fili, dbic, mask, maskfile, burnval, inclus, filo, dboc, ftype, foptions )