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)