'\" -*- coding: UTF-8 -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH pksetmask 1 "06 December 2020" "" ""
.SH NAME
pksetmask \- program to apply mask image (set invalid values) to raster image
.SH SYNOPSIS
'nh
.fi
.ad l
\fBpksetmask\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\fB-i\fR \fIinput\fR \fB-m\fR \fImask\fR [\fB-msknodata\fR \fIvalue\fR] \fB-o\fR \fIoutput\fR [\fIoptions\fR] [\fIadvanced options\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBpksetmask\fR sets a mask provided with option
\*(T<\fB\-m\fR\*(T> 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 \*(T<\fB\-msknodata\fR\*(T>) will then be set
to nodata (set with \*(T<\fB\-nodata\fR\*(T>).
Other operators are less than (\*(T<\fB\-\-operator\fR\*(T> '<') and
larger than (\*(T<\fB\-\-operator\fR\*(T> '<').
.SH OPTIONS
.TP 
\*(T<\fB\-i\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-input\fR\*(T> \fIfilename\fR
Input image
.TP 
\*(T<\fB\-m\fR\*(T> \fImask\fR, \*(T<\fB\-\-mask\fR\*(T> \fImask\fR
Mask image(s)
.TP 
\*(T<\fB\-msknodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-msknodata\fR\*(T> \fIvalue\fR
Mask value(s) where image has nodata.
Use one value for each mask, or multiple values for a single mask.
.TP 
\*(T<\fB\-o\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-output\fR\*(T> \fIfilename\fR
Output mask file
.TP 
\*(T<\fB\-nodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-nodata\fR\*(T> \fIvalue\fR
nodata value to put in image if not valid
.TP 
\*(T<\fB\-v\fR\*(T> \fIlevel\fR, \*(T<\fB\-\-verbose\fR\*(T> \fIlevel\fR
verbose
.PP
Advanced options
.TP 
\*(T<\fB\-p\fR\*(T> \fI'<'|'='|'>'\fR, \*(T<\fB\-\-operator\fR\*(T> \fI'<'|'='|'>'\fR
Operator: < = > !.
Use operator for each \*(T<\fB\-msknodata\fR\*(T> option
.TP 
\*(T<\fB\-ot\fR\*(T> \fItype\fR, \*(T<\fB\-\-otype\fR\*(T> \fItype\fR
Data type for output image
({Byte / Int16 / UInt16 / UInt32 / Int32 / Float32 / Float64 / CInt16 / CInt32 / CFloat32 / CFloat64}).
Empty string: inherit type from input image
.TP 
\*(T<\fB\-of\fR\*(T> \fIGDALformat\fR, \*(T<\fB\-\-oformat\fR\*(T> \fIGDALformat\fR
Output image format (see also
\fBgdal_translate\fR(1)).
.TP 
\*(T<\fB\-co\fR\*(T> \fIoption\fR, \*(T<\fB\-\-co\fR\*(T> \fIoption\fR
Creation option for output file.
Multiple options can be specified.
.TP 
\*(T<\fB\-ct\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-ct\fR\*(T> \fIfilename\fR
colour table in ASCII format having 5 columns: id R G B ALFA
(0: transparent, 255: solid)
.SH EXAMPLE
\fBUsing a single mask\fR
.PP
With a single mask you can provide as many triples
(\*(T<\fB\-\-operator\fR\*(T>, \*(T<\fB\-\-msknodata\fR\*(T>,
\*(T<\fB\-\-nodata\fR\*(T>) 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:
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask.tif\fR \fB\-\-operator\fR='>' \fB\-\-msknodata\fR \fI0\fR \fB\-\-nodata\fR \fI0\fR \fB\-\-operator\fR='>' \fB\-\-msknodata\fR \fI10\fR \fB\-\-nodata\fR \fI10\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
Warning: second operator will never test true as first will supersede! 
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask.tif\fR \fB\-\-operator\fR='>' \fB\-\-msknodata\fR \fI10\fR \fB\-\-nodata\fR \fI10\fR \fB\-\-operator\fR='>' \fB\-\-msknodata\fR \fI0\fR \fB\-\-nodata\fR \fI1\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
OK: values above 10 will be 10, values between 0 and 10 will be 1
.PP
\fBUsing multiple masks\fR
.PP
With multiple masks, you can use one triple
(\*(T<\fB\-\-operator\fR\*(T>, \*(T<\fB\-\-msknodata\fR\*(T>,
\*(T<\fB\-\-nodata\fR\*(T>) 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
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask1.tif\fR \fB\-\-operator\fR '>' \fB\-\-msknodata\fR \fI250\fR \fB\-\-nodata\fR \fI1\fR \fB\-m\fR \fImask2.tif\fR \fB\-\-operator\fR '>' \fB\-\-msknodata\fR \fI100\fR \fB\-\-nodata\fR \fI2\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
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)
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask1.tif\fR \fB\-m\fR \fImask2.tif\fR \fB\-\-operator\fR '>' \fB\-\-msknodata\fR \fI250\fR \fB\-\-nodata\fR \fI1\fR \fB\-o\fR \fIoutput.tif\fR
      \*(T>
.fi
.PP
If either mask1.tif or mask2.tif is above 250, the output will be 1
.PP
\fBMore examples\fR
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-ot\fR \fIByte\fR \fB\-\-msknodata\fR \fI0\fR \fB\-nodata\fR \fI255\fR
      \*(T>
.fi
.PP
copy pixel values from input.tif to output.tif, applying mask.tif,
setting all values to 255 where mask is 0.
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-ot\fR \fIByte\fR \fB\-\-msknodata\fR \fI1\fR \fB\-nodata\fR \fI255\fR \fB\-\-operator\fR '!'
      \*(T>
.fi
.PP
copy values from input.tif to output.tif,
but set all values to 255 if mask is not 1
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask1.tif\fR \fB\-m\fR \fImask2.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-ot\fR \fIByte\fR \fB\-\-msknodata\fR \fI0\fR \fB\-nodata\fR \fI255\fR
      \*(T>
.fi
.PP
Application of two masks.
Copy pixel values from input.tif to output.tif,
setting all values to 255 where either mask is 0.
.PP
.nf
\*(T<
\fBpksetmask\fR \fB\-i\fR \fIinput.tif\fR \fB\-m\fR \fImask.tif\fR \fB\-o\fR \fIoutput.tif\fR \fB\-ot\fR \fIByte\fR \fB\-\-msknodata\fR \fI0\fR \fB\-\-msknodata\fR \fI1\fR \fB\-nodata\fR \fI255\fR \fB\-nodata\fR \fI255\fR
      \*(T>
.fi
.PP
copy pixel values from input.tif to output.tif, applying single masks, setting all values to 255 where mask is either 0 or 1.
.SH 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.
.PP
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).