NAME

       pksetmask - program to apply mask image (set invalid values) to raster image

SYNOPSIS

       pksetmask -i input -m mask [-msknodata value] -o output [options] [advanced options]

DESCRIPTION

       pksetmask  sets  a  mask  provided with option -m to an input raster dataset.  The default
       operator is '='.  Values in the input raster data where the mask has a nodata  value  (set
       with  the  option  -msknodata)  will  then  be  set  to  nodata (set with -nodata).  Other
       operators are less than (--operator '<') and larger than (--operator '<').

OPTIONS

       -i filename, --input filename
              Input image

       -m mask, --mask mask
              Mask image(s)

       -msknodata value, --msknodata value
              Mask value(s) where image has nodata.  Use one value for  each  mask,  or  multiple
              values for a single mask.

       -o filename, --output filename
              Output mask file

       -nodata value, --nodata value
              nodata value to put in image if not valid

       -v level, --verbose level
              verbose

       Advanced options

       -p '<'|'='|'>', --operator '<'|'='|'>'
              Operator: < = > !.  Use operator for each -msknodata option

       -ot type, --otype type
              Data  type  for  output  image ({Byte / Int16 / UInt16 / UInt32 / Int32 / Float32 /
              Float64 / CInt16 / CInt32 / CFloat32 / CFloat64}).  Empty string: inherit type from
              input image

       -of GDALformat, --oformat GDALformat
              Output image format (see also gdal_translate(1)).

       -co option, --co option
              Creation option for output file.  Multiple options can be specified.

       -ct filename, --ct filename
              colour  table in ASCII format having 5 columns: id R G B ALFA (0: transparent, 255:
              solid)

EXAMPLE

       Using a single mask

       With a single mask you can provide as many triples (--operator, --msknodata, --nodata)  as
       you  wish.   All  operators work simultaneously on that mask.  Caution: the first operator
       that tests true will be selected.  This is explained in the next example:

       pksetmask -i input.tif -m mask.tif --operator='>' --msknodata 0 --nodata 0 --operator='>' --msknodata 10 --nodata 10 -o output.tif

       Warning: second operator will never test true as first will supersede!

       pksetmask -i input.tif -m mask.tif --operator='>' --msknodata 10 --nodata 10 --operator='>' --msknodata 0 --nodata 1 -o output.tif

       OK: values above 10 will be 10, values between 0 and 10 will be 1

       Using multiple masks

       With multiple masks, you can use one triple (--operator, --msknodata, --nodata)  for  each
       corresponding  mask  (following the same order of input).  If the number of triples is not
       equal to the number  of  masks,  then  only  the  first  triple  is  used  for  all  masks
       simultaneously

       pksetmask -i input.tif -m mask1.tif --operator '>' --msknodata 250 --nodata 1 -m mask2.tif --operator '>' --msknodata 100 --nodata 2 -o output.tif

       If  mask1.tif  is above 250, the output will be 1.  If mask2 is above 100, the output will
       be 2.  If both operators test true, the first will supersede (output will be 1)

       pksetmask -i input.tif -m mask1.tif -m mask2.tif --operator '>' --msknodata 250 --nodata 1 -o output.tif

       If either mask1.tif or mask2.tif is above 250, the output will be 1

       More examples

       pksetmask -i input.tif -m mask.tif -o output.tif -ot Byte --msknodata 0 -nodata 255

       copy pixel values from input.tif to output.tif, applying mask.tif, setting all  values  to
       255 where mask is 0.

       pksetmask -i input.tif -m mask.tif -o output.tif -ot Byte --msknodata 1 -nodata 255 --operator '!'

       copy values from input.tif to output.tif, but set all values to 255 if mask is not 1

       pksetmask -i input.tif -m mask1.tif -m mask2.tif -o output.tif -ot Byte --msknodata 0 -nodata 255

       Application  of  two  masks.   Copy pixel values from input.tif to output.tif, setting all
       values to 255 where either mask is 0.

       pksetmask -i input.tif -m mask.tif -o output.tif -ot Byte --msknodata 0 --msknodata 1 -nodata 255 -nodata 255

       copy pixel values from input.tif to output.tif, applying single masks, setting all  values
       to 255 where mask is either 0 or 1.

FAQ

       Q1. I want to mask my input image (a byte image with values between 0 and 254) with a mask
       that only covers a spatial subset of the input image.  Within the spatial  subset  of  the
       primary  mask,  all  pixels must be set to 0 where the primary mask equals 1.  Outside the
       spatial subset I want to set all pixel values to 255.

       A1. This can be done using two masks, selecting the input image  as  the  secondary  mask.
       Choose  the  secondary  operator  acting  on the secondary mask such that the condition is
       always true (e.g, < 255).

                                           30 July 2024                              pksetmask(1)