'\" t -*- 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 pkfilter 1 "02 March 2024" "" ""
.SH NAME
pkfilter \- program to filter raster images
.SH SYNOPSIS
'nh
.fi
.ad l
\*(T<\fBpkfilter\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<\fB\-i\fR\*(T> \fIinput\fR \*(T<\fB\-o\fR\*(T> \fIoutput\fR [\*(T<\fB\-f\fR\*(T> \fIfilter\fR | \*(T<\fB\-srf\fR\*(T> \fIfile\fR
[\*(T<\fB\-srf\fR\*(T> \fIfile\fR]\&...
| \*(T<\fB\-fwhm\fR\*(T> \fIvalue\fR
[\*(T<\fB\-fwhm\fR\*(T> \fIvalue\fR]\&...
] [\fIoptions\fR] [\fIadvanced options\fR]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBpkfilter\fR implements spatial and spectral filtering for
raster data.
In the spatial domain (X, Y), the filter typically involves a rectangular
convolution kernel (moving window).
To avoid image shifting, the size of the window should be odd
(3, 5, 7, ...).
You can set the window sizes in X and Y directions separately with the
options \*(T<\fB\-dx\fR\*(T> and \*(T<\fB\-dy\fR\*(T>.
A circular kernel (disc) is applied if option \*(T<\fB\-circ\fR\*(T> is
set.
An overview of the supported filters (option
\*(T<\fB\-f\fR\*(T>|\*(T<\fB\-\-filter\fR\*(T>) is given below.
You can create customized filters by defining your own filter taps
(multiplicative elements of the filter kernel) via an ascii file (option
\*(T<\fB\-tap\fR\*(T>).
In the spectral/temporal domain (Z) you can filter multi-band raster
inputs.
The kernel filter size can be set with the option \*(T<\fB\-dz\fR\*(T>
(use odd values only).
.SS "FILTERS IN SPATIAL (DX, DY) AND SPECTRAL/TEMPORAL (DZ) DOMAIN"
The number of output bands equals number of input bands
.TS
l l.
T{
Filter
T}	T{
Description
T}
.T&
l l.
T{
dilate
T}	T{
morphological dilation
T}
T{
erode
T}	T{
morphological erosion
T}
T{
close
T}	T{
morpholigical closing (dilate+erode)
T}
T{
open
T}	T{
morpholigical opening (erode+dilate)
T}
T{
smoothnodata values
T}	T{
smooth nodata values (set \*(T<\fB\-\-nodata\fR\*(T> option!)
T}
.TE
.PP
Example: "Smooth" (interpolate) nodata in spectral/temporal domain
(\*(T<\fB\-dz\fR\*(T> \fI1\fR), using a linear interpolation

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIsmoothed.tif\fR \fB\-dz\fR \fI1\fR \fB\-f\fR \fIsmoothnodata\fR \fB\-interp\fR \fIlinear\fR
          \*(T>
.fi
.PP
Example: Filter \fIinput.tif\fR in spatial
domain with morphological dilation filter with kernel size 3x3.

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIdilated.tif\fR \fB\-dx\fR \fI3\fR \fB\-dy\fR \fI3\fR \fB\-f\fR \fIdilate\fR
          \*(T>
.fi
.PP
In case of moving window, the number of output bands equals number
of input bands.
In case dz=1, the single output band is calculated as the result of
the statistical function applied to all bands.
.TS
l l.
T{
Filter
T}	T{
Description
T}
.T&
l l.
T{
nvalid
T}	T{
report number of valid (not nodata) values in window
T}
T{
median
T}	T{
perform a median filter in spatial (dx, dy) or spectral/temporal (dz) domain
T}
T{
var
T}	T{
calculate variance in window
T}
T{
min
T}	T{
calculate minimum in window
T}
T{
max
T}	T{
calculate maximum in window
T}
T{
sum
T}	T{
calculate sum in window
T}
T{
mean
T}	T{
calculate mean in window
T}
T{
stdev
T}	T{
calculate standard deviation in window
T}
T{
savgolay
T}	T{
Savitzky-Golay filter (check examples page!)
T}
T{
percentile
T}	T{
calculate percentile value in window
T}
T{
proportion
T}	T{
calculate proportion in window
T}
.TE
.PP
Example: Median filter in spatial domain

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fImedian.tif\fR \fB\-dx\fR \fI3\fR \fB\-dy\fR \fI3\fR \fB\-f\fR \fImedian\fR
          \*(T>
.fi
.PP
Example: Calculate statistical variance in spectral/temporal domain
(single output band)

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIvar.tif\fR \fB\-dz\fR \fI1\fR \fB\-f\fR \fIvar\fR
          \*(T>
.fi
.SS "WAVELET FILTERS"
The number of output bands equals number of input bands
.TS
l l.
T{
Filter
T}	T{
Description
T}
.T&
l l
l l
l l.
T{
dwt
T}	T{
discrete wavelet transform
T}
T{
dwti
T}	T{
discrete inverse wavelet transform
T}
T{
dwt_cut
T}	T{
discrete wavelet + inverse transform, using threshold option to cut percentile of coefficients
T}
.TE
.PP
Example: Calculate discrete wavelet in spatial domain

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIlena.tif\fR \fB\-o\fR \fIlena_dwt.tif\fR \fB\-f\fR \fIdwt\fR
          \*(T>
.fi
.PP
Example: Calculate discrete wavelet in spectral/temporal domain

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fItimeseries.tif\fR \fB\-o\fR \fIdwt.tif\fR \fB\-f\fR \fIdwt\fR \fB\-dz\fR \fI1\fR
          \*(T>
.fi
.PP
The number of output bands equals number of input bands
.TS
l l.
T{
Filter
T}	T{
Description
T}
.T&
l l.
T{
dwt_cut_from
T}	T{
discrete wavelet + inverse transform, setting all high frequence coefficients to zero (scale >= threshold)
T}
.TE
.PP
Example: Calculate low frequency time series based on discrete
wavelet + inverse transform in spectral/temporal domain,
retaining only coefficients until scale 3.

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fItimeseries.tif\fR \fB\-o\fR \fIlowfrequency.tif\fR \fB\-f\fR \fIdwt_cut_from\fR \fB\-dz\fR \fI1\fR \fB\-t\fR \fI4\fR
          \*(T>
.fi
.SS "FILTERS IN SPATIAL DOMAIN ONLY (DX, DY > 1 AND ODD)."
The number of output bands equals number of input bands.
.TS
l l.
T{
Filter
T}	T{
Description
T}
.T&
l l.
T{
mrf
T}	T{
Markov random field
T}
T{
ismin
T}	T{
pixel is minimum?
T}
T{
ismax
T}	T{
pixel is maximum?
T}
T{
shift
T}	T{
perform a pixel shift in spatial window
T}
T{
scramble
T}	T{
scramble pixels in a spatial window
T}
T{
mode (majority voting)
T}	T{
perform a majority voring (set \*(T<\fB\-\-class\fR\*(T> option)
T}
T{
sobelx
T}	T{
horizontal edge detection
T}
T{
sobely
T}	T{
vertical edge detection
T}
T{
sobelxy
T}	T{
diagonal edge detection (NE-SW)
T}
T{
sobelyx
T}	T{
diagonal edge detection (NW-SE)
T}
T{
countid
T}	T{
count digital numbers in window
T}
T{
order
T}	T{
rank pixels in order
T}
T{
density
T}	T{
calculated the density
T}
T{
homog
T}	T{
central pixel must be identical to all other pixels within window
T}
T{
heterog
T}	T{
central pixel must be different than all other pixels within window
T}
T{
sauvola
T}	T{
Sauvola's thresholding method
T}
.TE
.PP
Example: Sobel edge detection in horizontal direction

.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIlena.tif\fR \fB\-o\fR \fIsobelx.tif\fR \fB\-f\fR \fIsolbelx\fR \fB\-dx\fR \fI5\fR \fB\-dy\fR \fI5\fR
        \*(T>
.fi
.SH OPTIONS
.TP 
\*(T<\fB\-i\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-input\fR\*(T> \fIfilename\fR
input image
.TP 
\*(T<\fB\-o\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-output\fR\*(T> \fIfilename\fR
output classification image
.TP 
\*(T<\fB\-f\fR\*(T> \fIfilter\fR, \*(T<\fB\-\-filter\fR\*(T> \fIfilter\fR
filter function (nvalid, median, var, min, max, sum, mean, dilate,
erode, close, open, homog (central pixel must be identical to all
other pixels within window), heterog (central pixel must be
different than all other pixels within window), sobelx (horizontal
edge detection), sobely (vertical edge detection), sobelxy
(diagonal edge detection NE-SW),sobelyx (diagonal edge detection
NW-SE), density, countid, mode (majority voting, only for classes),
smoothnodata (smooth nodata values only) values, ismin, ismax,
order (rank pixels in order), stdev, mrf, dwt, dwti, dwt_cut,
dwt_cut_from, scramble, shift, savgolay, percentile, proportion)
.TP 
\*(T<\fB\-dx\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-dx\fR\*(T> \fIvalue\fR
filter kernel size in x,
use odd values only
.TP 
\*(T<\fB\-dy\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-dy\fR\*(T> \fIvalue\fR
filter kernel size in y,
use odd values only
.TP 
\*(T<\fB\-dz\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-dz\fR\*(T> \fIvalue\fR
filter kernel size in z (band or spectral dimension),
must be odd (example: 3).
Set dz>0 if 1-D filter must be used in band domain
.TP 
\*(T<\fB\-nodata\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-nodata\fR\*(T> \fIvalue\fR
nodata value(s) (used for smoothnodata filter) 
.TP 
\*(T<\fB\-v\fR\*(T> \fIlevel\fR, \*(T<\fB\-\-verbose\fR\*(T> \fIlevel\fR
verbose mode if > 0
.PP
Advanced options
.TP 
\*(T<\fB\-circ\fR\*(T>, \*(T<\fB\-\-circular\fR\*(T>
circular disc kernel for dilation and erosion
.TP 
\*(T<\fB\-r\fR\*(T> \fImethod\fR, \*(T<\fB\-\-resampling\-method\fR\*(T> \fImethod\fR
Resampling method for shifting operation (near: nearest neighbour,
bilinear: bi-linear interpolation).
.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\-wt\fR\*(T> \fItype\fR, \*(T<\fB\-\-wavelet\fR\*(T> \fItype\fR
wavelet type: daubechies,daubechies_centered, haar, haar_centered,
bspline, bspline_centered
.TP 
\*(T<\fB\-wf\fR\*(T> \fIfamily\fR, \*(T<\fB\-\-wf\fR\*(T> \fIfamily\fR
wavelet family (vanishing moment, see also
http://www.gnu.org/software/gsl/manual/html_node/DWT-Initialization.html)
.TP 
\*(T<\fB\-class\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-class\fR\*(T> \fIvalue\fR
class value(s) to use for density, erosion, dilation,
openening and closing, thresholding
.TP 
\*(T<\fB\-t\fR\*(T> \fIthreshold\fR, \*(T<\fB\-\-threshold\fR\*(T> \fIthreshold\fR
threshold value(s) to use for threshold filter (one for each class),
or threshold to cut for dwt_cut (use 0 to keep all) or dwt_cut_from,
or sigma for shift 
.TP 
\*(T<\fB\-tap\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-tap\fR\*(T> \fIfilename\fR
text file containing taps used for spatial filtering
(from ul to lr).
Use dimX and dimY to specify tap dimensions in x and y.
Leave empty for not using taps
.TP 
\*(T<\fB\-tapz\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-tapz\fR\*(T> \fIvalue\fR
taps used for spectral filtering
.TP 
\*(T<\fB\-pad\fR\*(T> \fImethod\fR, \*(T<\fB\-\-pad\fR\*(T> \fImethod\fR
Padding method for filtering (how to handle edge effects).
Choose between: symmetric, replicate, circular, constant
(pad with 0).
.TP 
\*(T<\fB\-fwhm\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-fwhm\fR\*(T> \fIvalue\fR
list of full width half to apply spectral filtering
(\*(T<\fB\-fwhm\fR\*(T> \fIband1\fR
\*(T<\fB\-fwhm\fR\*(T> \fIband2\fR ...)
.TP 
\*(T<\fB\-srf\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-srf\fR\*(T> \fIfilename\fR
list of ASCII files containing spectral response functions
(two columns: wavelength response)
.TP 
\*(T<\fB\-win\fR\*(T> \fIcol\fR, \*(T<\fB\-\-wavelengthIn\fR\*(T> \fIcol\fR
column number of input ASCII file containing wavelengths
.TP 
\*(T<\fB\-wout\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-wavelengthOut\fR\*(T> \fIvalue\fR
list of wavelengths in output spectrum
(\*(T<\fB\-wout\fR\*(T> \fIband1\fR
\*(T<\fB\-wout\fR\*(T> \fIband2\fR ...)
.TP 
\*(T<\fB\-down\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-down\fR\*(T> \fIvalue\fR
down sampling factor.
Use value 1 for no downsampling).
Use value n>1 for downsampling (aggregation)
.TP 
\*(T<\fB\-beta\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-beta\fR\*(T> \fIfilename\fR
ASCII file with beta for each class transition in
Markov Random Field
.TP 
\*(T<\fB\-eps\fR\*(T> \fIvalue\fR, \*(T<\fB\-\-eps\fR\*(T> \fIvalue\fR
error marging for linear feature
.TP 
\*(T<\fB\-l1\fR\*(T>, \*(T<\fB\-\-l1\fR\*(T>
obtain longest object length for linear feature
.TP 
\*(T<\fB\-a1\fR\*(T>, \*(T<\fB\-\-a1\fR\*(T>
obtain angle found for longest object length for linear feature
.TP 
\*(T<\fB\-a2\fR\*(T>, \*(T<\fB\-\-a2\fR\*(T>
obtain angle found for shortest object length for linear feature
.TP 
\*(T<\fB\-interp\fR\*(T> \fItype\fR, \*(T<\fB\-\-interp\fR\*(T> \fItype\fR
type of interpolation for spectral filtering (see
http://www.gnu.org/software/gsl/manual/html_node/Interpolation-Types.html)
.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\-ct\fR\*(T> \fIfilename\fR, \*(T<\fB\-\-ct\fR\*(T> \fIfilename\fR
color table (file with 5 columns:
id R G B ALFA (0: transparent, 255: solid)).
Use none to omit color table 
.SH EXAMPLE
\fBFiltering in spatial domain\fR
.PP
Filter input.tif with morphological dilation filter.
Use a circular kernel (instead of rectangular) of size 3x3.
.PP
.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIfilter.tif\fR \fB\-dx\fR \fI3\fR \fB\-dy\fR \fI3\fR \fB\-f\fR \fIdilate\fR \fB\-circ\fR
      \*(T>
.fi
.PP
Similar to previous example,
but consider only values of 255 for filtering operation.
Typical usage:
dilate cloud values in input image that are flagged as 255
.PP
.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIfilter.tif\fR \fB\-dx\fR \fI3\fR \fB\-dy\fR \fI3\fR \fB\-class\fR \fI255\fR \fB\-f\fR \fIdilate\fR \fB\-circ\fR
      \*(T>
.fi
.PP
\fBFiltering in spectral/temporal domain\fR
.PP
Calculate the median value for each pixel,
calculated on a moving window of width 3
(\*(T<\fB\-dz\fR\*(T> \fI3\fR)
over all input bands.
The output raster dataset will contain as many bands as the input
raster dataset.
.PP
.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIfilter_stdev.tif\fR \fB\-dz\fR \fI3\fR \fB\-f\fR \fImedian\fR
      \*(T>
.fi
.PP
No moving window (\*(T<\fB\-dz\fR\*(T> \fI1\fR).
Calculate the standard deviation for each pixel,
calculated on all input bands.
The output raster dataset will contain a single band only.
.PP
.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIfilter_stdev.tif\fR \fB\-dz\fR \fI1\fR \fB\-f\fR \fIstdev\fR
      \*(T>
.fi
.PP
"Smooth" (interpolate) nodata in spectral/temporal domain
(\*(T<\fB\-dz\fR\*(T> 1), using a linear interpolation.
The following interpolation types are supported:
akima (default), linear, polynomial, cspline, cspline_periodic,
akima_periodic (please check
.URL http://www.gnu.org/software/gsl/manual/html_node/Interpolation-Types.html gsl
page for more information on the interpolation types).
.PP
.nf
\*(T<
\fBpkfilter\fR \fB\-i\fR \fIinput.tif\fR \fB\-o\fR \fIinput_smoothed.tif\fR \fB\-dz\fR \fI1\fR \fB\-f\fR \fIsmoothnodata\fR \fB\-interp\fR \fIlinear\fR
      \*(T>
.fi