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
       extra attribute for the extracted pixel value.  For each raster band  in  the  input  image,  a  separate
       attribute  is  created.   For  instance, if the raster dataset contains three bands, three attributes are
       created (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
                         option (-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
                         pixels 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)
                         within  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
                         option  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

                                                10 February 2020                                 pkextractogr(1)