pktools 2.6.7
Processing Kernel for geospatial data
pkextractogr

extract pixel values from raster image using a vector dataset sample

SYNOPSIS

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

Options: [-ln layer]* [-c class]* [-t threshold]* [-f format] [-ft fieldType] [-b band]* [-r rule]*

Advanced options: [-sband band -eband band]* [-bndnodata band -srcnodata value]* [-tp threshold] [-buf value [-circ]]

Description

The utility 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:

pkextractogr_rules

extraction rule output features
point extract a single pixel within the polygon or on each point feature
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

  • use either -short or --long options (both --long=value and --long value are supported)
  • short option -h shows basic options only, long option --help shows all options
    short long type default description
    i input std::string Raster input dataset containing band information
    s sample std::string OGR vector dataset with features to be extracted from input data. Output will contain features with input band information included
    ln ln std::string Layer name(s) in sample (leave empty to select all)
    rand random unsigned int Create simple random sample of points. Provide number of points to generate
    grid grid double Create systematic grid of points. Provide cell grid size (in projected units, e.g,. m)
    o output std::string Output sample dataset
    c class int 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 float 100 Probability threshold for selecting samples (randomly). Provide probability in percentage (>0) or absolute (<0). Use a single threshold per vector sample layer
    perc perc double 95 Percentile value used for rule percentile
    f f std::string SQLite Output sample dataset format
    ft ftype std::string Real Field type (only Real or Integer)
    b band int Band index(es) to extract (0 based). Leave empty to use all bands
    sband startband unsigned short Start band sequence number
    eband endband unsigned short End band sequence number
    r rule std::string centroid Rule how to report image information per feature (only for vector sample). point (single point or at centroid if polygon), allpoints (within polygon), centroid, mean, stdev, median, proportion, count, min, max, mode, sum, percentile.
    bndnodata bndnodata int 0 Band(s) in input image to check if pixel is valid (used for srcnodata)
    srcnodata srcnodata double Invalid value(s) for input image
    tp thresholdPolygon float (absolute) threshold for selecting samples in each polygon
    buf buffer short 0 Buffer for calculating statistics for point features (in number of pixels)
    circ circular bool false Use a circular disc kernel buffer (for vector point sample datasets only, use in combination with buffer option)

Usage: pkextractogr -i input [-s sample | -rand number | -grid size] -o output -r rule

Examples

Some examples how to use pkextractogr can be found here