Provided by: pktools_2.6.7.6+ds-2build2_amd64 bug

NAME

       pkfilter - program to filter raster images

SYNOPSIS

       pkfilter -i input -o output [-f filter | -srf file [-srf file]...  | -fwhm value [-fwhm
                value]...  ] [options] [advanced options]

DESCRIPTION

       pkfilter 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 -dx and -dy.  A
       circular kernel (disc) is applied if option -circ is set.  An overview  of  the  supported
       filters  (option  -f|--filter)  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 -tap).  In the spectral/temporal domain (Z) you can filter multi-band raster
       inputs.  The kernel filter size can be set with the option -dz (use odd values only).

   FILTERS IN SPATIAL (DX, DY) AND SPECTRAL/TEMPORAL (DZ) DOMAIN
       The number of output bands equals number of input bands

       Filter                Description
       dilate                morphological dilation
       erode                 morphological erosion
       close                 morpholigical            closing
                             (dilate+erode)
       open                  morpholigical            opening
                             (erode+dilate)
       smoothnodata values   smooth   nodata   values    (set
                             --nodata option!)

       Example: "Smooth" (interpolate) nodata in spectral/temporal domain (-dz 1), using a linear
       interpolation

       pkfilter -i input.tif -o smoothed.tif -dz 1 -f smoothnodata -interp linear

       Example: Filter input.tif in spatial domain with morphological dilation filter with kernel
       size 3x3.

       pkfilter -i input.tif -o dilated.tif -dx 3 -dy 3 -f dilate

       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.

       Filter       Description
       nvalid       report   number  of  valid  (not
                    nodata) values in window
       median       perform  a  median   filter   in
                    spatial      (dx,     dy)     or
                    spectral/temporal (dz) domain
       var          calculate variance in window
       min          calculate minimum in window
       max          calculate maximum in window
       sum          calculate sum in window
       mean         calculate mean in window
       stdev        calculate standard deviation  in
                    window

       savgolay     Savitzky-Golay   filter   (check
                    examples page!)
       percentile   calculate  percentile  value  in
                    window
       proportion   calculate proportion in window

       Example: Median filter in spatial domain

       pkfilter -i input.tif -o median.tif -dx 3 -dy 3 -f median

       Example: Calculate statistical variance in spectral/temporal domain (single output band)

       pkfilter -i input.tif -o var.tif -dz 1 -f var

   WAVELET FILTERS
       The number of output bands equals number of input bands

       Filter    Description
       dwt       discrete wavelet transform
       dwti      discrete     inverse     wavelet
                 transform
       dwt_cut   discrete   wavelet   +   inverse
                 transform,    using    threshold
                 option  to  cut  percentile   of
                 coefficients

       Example: Calculate discrete wavelet in spatial domain

       pkfilter -i lena.tif -o lena_dwt.tif -f dwt

       Example: Calculate discrete wavelet in spectral/temporal domain

       pkfilter -i timeseries.tif -o dwt.tif -f dwt -dz 1

       The number of output bands equals number of input bands

       Filter         Description
       dwt_cut_from   discrete   wavelet   +   inverse
                      transform,  setting   all   high
                      frequence  coefficients  to zero
                      (scale >= threshold)

       Example: Calculate low frequency time series based on discrete wavelet + inverse transform
       in spectral/temporal domain, retaining only coefficients until scale 3.

       pkfilter -i timeseries.tif -o lowfrequency.tif -f dwt_cut_from -dz 1 -t 4

   FILTERS IN SPATIAL DOMAIN ONLY (DX, DY > 1 AND ODD).
       The number of output bands equals number of input bands.

       Filter                   Description
       mrf                      Markov random field
       ismin                    pixel is minimum?
       ismax                    pixel is maximum?
       shift                    perform a pixel shift in spatial
                                window
       scramble                 scramble  pixels  in  a  spatial
                                window
       mode (majority voting)   perform  a  majority voring (set
                                --class option)

       sobelx                   horizontal edge detection
       sobely                   vertical edge detection
       sobelxy                  diagonal edge detection (NE-SW)
       sobelyx                  diagonal edge detection (NW-SE)
       countid                  count digital numbers in window
       order                    rank pixels in order
       density                  calculated the density
       homog                    central pixel must be  identical
                                to   all   other  pixels  within
                                window
       heterog                  central pixel must be  different
                                than  all  other  pixels  within
                                window
       sauvola                  Sauvola's thresholding method

       Example: Sobel edge detection in horizontal direction

       pkfilter -i lena.tif -o sobelx.tif -f solbelx -dx 5 -dy 5

OPTIONS

       -i filename, --input filename
              input image

       -o filename, --output filename
              output classification image

       -f filter, --filter filter
              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)

       -dx value, --dx value
              filter kernel size in x, use odd values only

       -dy value, --dy value
              filter kernel size in y, use odd values only

       -dz value, --dz value
              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

       -nodata value, --nodata value
              nodata value(s) (used for smoothnodata filter)

       -v level, --verbose level
              verbose mode if > 0

       Advanced options

       -circ, --circular
              circular disc kernel for dilation and erosion

       -r method, --resampling-method method
              Resampling method for shifting operation (near: nearest  neighbour,  bilinear:  bi-
              linear interpolation).

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

       -wt type, --wavelet type
              wavelet   type:   daubechies,daubechies_centered,   haar,  haar_centered,  bspline,
              bspline_centered

       -wf family, --wf family
              wavelet         family         (vanishing         moment,         see          also
              http://www.gnu.org/software/gsl/manual/html_node/DWT-Initialization.html)

       -class value, --class value
              class  value(s)  to  use  for  density,  erosion,  dilation, openening and closing,
              thresholding

       -t threshold, --threshold threshold
              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

       -tap filename, --tap filename
              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

       -tapz value, --tapz value
              taps used for spectral filtering

       -pad method, --pad method
              Padding method for  filtering  (how  to  handle  edge  effects).   Choose  between:
              symmetric, replicate, circular, constant (pad with 0).

       -fwhm value, --fwhm value
              list of full width half to apply spectral filtering (-fwhm band1 -fwhm band2 ...)

       -srf filename, --srf filename
              list of ASCII files containing spectral response functions (two columns: wavelength
              response)

       -win col, --wavelengthIn col
              column number of input ASCII file containing wavelengths

       -wout value, --wavelengthOut value
              list of wavelengths in output spectrum (-wout band1 -wout band2 ...)

       -down value, --down value
              down sampling factor.  Use value  1  for  no  downsampling).   Use  value  n>1  for
              downsampling (aggregation)

       -beta filename, --beta filename
              ASCII file with beta for each class transition in Markov Random Field

       -eps value, --eps value
              error marging for linear feature

       -l1, --l1
              obtain longest object length for linear feature

       -a1, --a1
              obtain angle found for longest object length for linear feature

       -a2, --a2
              obtain angle found for shortest object length for linear feature

       -interp type, --interp type
              type       of       interpolation       for       spectral      filtering      (see
              http://www.gnu.org/software/gsl/manual/html_node/Interpolation-Types.html)

       -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)).

       -ct filename, --ct filename
              color table (file with 5 columns: id R G B ALFA (0: transparent, 255: solid)).  Use
              none to omit color table

EXAMPLE

       Filtering in spatial domain

       Filter  input.tif  with  morphological dilation filter.  Use a circular kernel (instead of
       rectangular) of size 3x3.

       pkfilter -i input.tif -o filter.tif -dx 3 -dy 3 -f dilate -circ

       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

       pkfilter -i input.tif -o filter.tif -dx 3 -dy 3 -class 255 -f dilate -circ

       Filtering in spectral/temporal domain

       Calculate  the  median value for each pixel, calculated on a moving window of width 3 (-dz
       3) over all input bands.  The output raster dataset will contain  as  many  bands  as  the
       input raster dataset.

       pkfilter -i input.tif -o filter_stdev.tif -dz 3 -f median

       No  moving window (-dz 1).  Calculate the standard deviation for each pixel, calculated on
       all input bands.  The output raster dataset will contain a single band only.

       pkfilter -i input.tif -o filter_stdev.tif -dz 1 -f stdev

       "Smooth" (interpolate)  nodata  in  spectral/temporal  domain  (-dz  1),  using  a  linear
       interpolation.   The following interpolation types are supported: akima (default), linear,
       polynomial, cspline, cspline_periodic, akima_periodic (please check gsl ⟨http://
       www.gnu.org/software/gsl/manual/html_node/Interpolation-Types.html⟩    page    for    more
       information on the interpolation types).

       pkfilter -i input.tif -o input_smoothed.tif -dz 1 -f smoothnodata -interp linear

                                         10 February 2020                             pkfilter(1)