NAME

       pkextractogr - extract pixel values from raster image from a (vector or raster) sample

SYNOPSIS

       pkextractogr -i input [-s sample | -rand number | -grid size] -o output [options]

DESCRIPTION

       pkextractogr extracts pixel values from an input raster dataset, based on the locations you provide via a
       sample  file.   Alternatively,  a  random sample or systematic grid of points can also be extracted.  The
       sample can be a vector file with points or polygons.  In the case of polygons, you can either extract the
       values for all raster pixels that are covered by the polygons, or extract a single value for each polygon
       such as the centroid, mean, median, etc.  As output, a new copy of the vector file is created with an ex‐
       tra attribute for the extracted pixel value.  For each raster band in the input  image,  a  separate  at‐
       tribute  is created.  For instance, if the raster dataset contains three bands, three attributes are cre‐
       ated (b0, b1 and b2).

       A typical usage of pkextractogr is to prepare a training sample for one of the classifiers implemented in
       pktools.

       Overview of the possible extraction rules:
       Extraction rule   Output features
       point             Extract all pixel values  covered  by
                         the polygon (option -polygon not set)
                         or extract a pixel on the surface op‐
                         tion (-polygon set).
       allpoints         Extract  all  pixel values covered by
                         the polygon.
       centroid          Extract pixel value at  the  centroid
                         of the polygon.
       mean              Extract  average  of all pixel values
                         within the polygon.
       stdev             Extract  standard  deviation  of  all
                         pixel values within the polygon.
       median            Extract  median  of  all pixel values
                         within the polygon.
       min               Extract minimum value of  all  pixels
                         within the polygon.
       max               Extract  maximum  value of all pixels
                         within the polygon.
       sum               Extract sum of the values of all pix‐
                         els within the polygon.
       mode              Extract the mode  of  classes  within
                         the polygon (classes must be set with
                         the option class).
       proportion        Extract proportion of class(es) with‐
                         in  the  polygon (classes must be set
                         with the option class).
       count             Extract count of class(es) within the
                         polygon (classes must be set with the
                         option class).
       percentile        Extract percentile as defined by  op‐
                         tion  perc  (e.g,  95th percentile of
                         values covered by polygon).

OPTIONS

       -i filename, --input filename
              Raster input dataset containing band information

       -s sample, --sample sample
              OGR vector dataset with features to be extracted from input data.  Output  will  contain  features
              with input band information included.  Sample image can also be GDAL raster dataset.

       -ln layer, --ln layer
              Layer name(s) in sample (leave empty to select all)

       -rand number, --random number
              Create simple random sample of points.  Provide number of points to generate

       -grid size, --grid size
              Create systematic grid of points.  Provide cell grid size (in projected units, e.g,. m)

       -o filename, --output filename
              Output sample dataset Output sample dataset

       -c class, --class class
              Class(es)  to  extract from input sample image.  Leave empty to extract all valid data pixels from
              sample dataset.  Make sure to set classes if rule is set to mode, proportion or count.

       -t threshold, --threshold threshold
              Probability threshold for selecting samples (randomly).  Provide probability in percentage (>0) or
              absolute (<0).  Use a single threshold per vector sample layer.  If using raster land  cover  maps
              as  a  sample  dataset,  you can provide a threshold value for each class (e.g. -t 80 -t 60).  Use
              value 100 to select all pixels for selected class(es)

       -perc percentile, --perc percentile
              Percentile value used for rule percentile

       -f format, --f format
              Output sample dataset format

       -ft fieldType, --ftype fieldType
              Field type (only Real or Integer)

       -lt labelType, --ltype labelType
              Label type: In16 or String

       -b band, --band band
              Band index(es) to extract.  Leave empty to use all bands

       -sband band, --startband band
              Start band sequence number

       -eband band, --endband band
              End band sequence number

       -r rule, --rule rule
              Rule how to report image information per feature (only for vector sample).  point (value  at  each
              point  or  at  centroid  if  polygon), centroid, mean, stdev, median, proportion, count, min, max,
              mode, sum, percentile.

       -bndnodata band, --bndnodata band
              Band(s) in input image to check if pixel is valid (used for srcnodata)

       -srcnodata value, --srcnodata value
              Invalid value(s) for input image

       -tp threshold, --thresholdPolygon threshold
              (absolute) threshold for selecting samples in each polygon

       -buf value, --buffer value
              Buffer for calculating statistics for point features

       -circ, --circular
              Use a circular disc kernel buffer (for vector point sample datasets only, use in combination  with
              buffer option)

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

                                                  01 April 2024                                  pkextractogr(1)