pkextract(1)

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

SYNOPSIS
pkextract
-i input [-s sample | -rand number | -grid size] -o output [options] [advanced options]

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

Instead of a vector dataset, the sample can also be a raster dataset with categorical values. The typical use case is a land cover map that overlaps the input raster dataset. The utility then extracts pixels from the input raster for the respective land cover classes. To select a random subset of the sample raster dataset you can set the threshold option \FC-t\F[] with a percentage value.

A typical usage of pkextract 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 \FC-polygon\F[] not set) or extract a pixel on the surface option (\FC-polygon\F[] set).
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

\FC-i\F[] filename, \FC--input\F[] filename
    Raster input dataset containing band information

\FC-s\F[] sample, \FC--sample\F[] 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.

\FC-rand\F[] number, \FC--random\F[] number
    Create simple random sample of points. Provide number of points to generate

\FC-grid\F[] size, \FC--grid\F[] size
    Create systematic grid of points. Provide cell grid size (in projected units, e.g,. m)

\FC-o\F[] filename, \FC--output\F[] filename
    Output sample dataset Output sample dataset

\FC-ln\F[] layer, \FC--ln\F[] layer
    Layer name(s) in sample (leave empty to select all)

\FC-c\F[] class, \FC--class\F[] 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.

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

\FC-f\F[] format, \FC--f\F[] format
    Output sample dataset format

\FC-ft\F[] fieldType, \FC--ftype\F[] fieldType
    Field type (only Real or Integer)

\FC-lt\F[] labelType, \FC--ltype\F[] labelType
    Label type: In16 or String

\FC-polygon\F[], \FC--polygon\F[]
    Create OGRPolygon as geometry instead of OGRPoint.

\FC-b\F[] band, \FC--band\F[] band
    Band index(es) to extract. Leave empty to use all bands

\FC-sband\F[] band, \FC--startband\F[] band
    Start band sequence number

\FC-eband\F[] band, \FC--endband\F[] band
    End band sequence number

\FC-r\F[] rule, \FC--rule\F[] 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.

\FC-v\F[] level, \FC--verbose\F[] level
    Verbose mode if > 0

Advanced options

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

\FC-srcnodata\F[] value, \FC--srcnodata\F[] value
    Invalid value(s) for input image

\FC-tp\F[] threshold, \FC--thresholdPolygon\F[] threshold
    (absolute) threshold for selecting samples in each polygon

\FC-test\F[] testSample, \FC--test\F[] testSample
    Test sample dataset (use this option in combination with threshold<100 to create a training (output) and test set

\FC-bn\F[] attribute, \FC--bname\F[] attribute
    For single band input data, this extra attribute name will correspond to the raster values. For multi-band input data, multiple attributes with this prefix will be added (e.g. b0, b1, b2, etc.)

\FC-cn\F[] attribute, \FC--cname\F[] attribute
    Name of the class label in the output vector dataset

\FC-geo\F[] value, \FC--geo\F[] value
    Use geo coordinates (set to 0 to use image coordinates)

\FC-down\F[] value, \FC--down\F[] value
    Down sampling factor (for raster sample datasets only). Can be used to create grid points

\FC-buf\F[] value, \FC--buffer\F[] value
    Buffer for calculating statistics for point features

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

EXAMPLE
Using vector samples

Extract all points for all layers read in points.sqlite from input.tif. Create a new point vector dataset named extracted.sqlite, where each point will contain an attribute for the individual input bands in input.tif. Notice that the default vector format is Spatialite (.sqlite).

\FC
pkextract -i input.tif -s points.sqlite -o extracted.sqlite
      \F[]

Same example as above, but only extract the points for the layer in points.sqlite named "valid"

\FC
pkextract -i input.tif -s points.sqlite -ln valid -o extracted.sqlite
      \F[]

Extract points and write output in ESRI Shapefile format

\FC
pkextract -i input.tif -s points.shp -f "ESRI Shapefile" -o extracted.sqlite
      \F[]

Extract the standard deviation for each input band in a 3 by 3 window, centered around the points in the sample vector dataset points.sqlite. The output vector dataset will contain polygon features defined by the buffered points (3x3 window). Use the option \FC-circ\F[] to define a circular buffer.

\FC
pkextract -i input.tif -s points.sqlite -o extracted.sqlite -r stdev -buf 3 -polygon
      \F[]

Extract all pixels from input.tif covered by the polygons in locations.sqlite. Each polygon can thus result in multiple point features with attributes for each input band. Write the extracted points to a point vector dataset training.sqlite.

\FC
pkextract -i input.tif -s polygons.sqlite -o training.sqlite -r point
      \F[]

Extract the first band from input.tif at the centroids of the polygons in vector dataset polygons.sqlite. Assign the extracted point value to a new attribute of the polygon and write to the vector dataset extracted.sqlite.

\FC
pkextract -i input.tif -b 0 -s polygons.sqlite -r centroid -o extracted.sqlite -polygon
      \F[]

Extract the mean values for the second band in input.tif covered by each polygon in polygons.sqlite. The mean values are written to a copy of the polygons in output vector dataset extracted.sqlite

\FC
pkextract -i input.tif -b 1 -s polygons.sqlite -r mean -o extracted.sqlite -polygon
      \F[]

Extract the majority class in each polygon for the input land cover map. The land cover map contains five valid classes, labeled 1-5. Other class values (e.g., labeled as 0) are not taken into account in the voting.

\FC
pkextract -i landcover.tif -s polygons.sqlite -r maxvote -o majority.sqlite -polygon -c 1 -c 2 -c 3 -c 4 -c 5
      \F[]

Using random and grid samples

Extract 100 sample units following a simple random sampling design. For each sample unit, the median value is extracted from the input raster dataset in a window of 3 by 3 pixels and written to an attribute of the output vector dataset. The output vector dataset contains polygon features defined by the windows centered at the random selected sample units.

\FC
pkextract -i input.tif -o random.sqlite -rand 100 -median -buf 3 -polygon
      \F[]

Extract points following a systematic grid with grid cell size of 100 m. Discard pixels that have a value 0 in the input raster dataset.

\FC
pkextract -i input.tif -o systematic.sqlite -grid 100 -srcnodata 0
      \F[]

Using raster samples

Typical use where pixels are extracted based on a land cover map (sample.tif). Extract all bands for a random sample of 10 percent of the pixels in the land cover map sample.tif where the land cover classes are either 1,2 or 3 (class values). Write output to the point vector dataset extracted.sqlite.

\FC
pkextract -i input.tif -s sample.tif -o extracted.sqlite -t 10 -c 1 -c 2 -c 3
      \F[]

Extract all bands for the first 5000 pixels encountered in sample.tif where pixels have a value equal to 1. Write output to point vector dataset extracted.sqlite.

\FC
pkextract -i input.tif -s sample.tif -o extracted.sqlite -t -5000 -c 1
      \F[]