Provided by: pktools_2.6.6-1_amd64 
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 -t 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 -polygon
not set) or extract a pixel on
the surface option (-polygon
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
-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.
-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
-ln layer, --ln layer
Layer name(s) in sample (leave empty to select all)
-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 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. -t 80 -t 60). Use value 100 to select all
pixels for selected class(es)
-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
-polygon, --polygon
Create OGRPolygon as geometry instead of OGRPoint.
-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.
-v level, --verbose level
Verbose mode if > 0
Advanced options
-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
-test testSample, --test testSample
Test sample dataset (use this option in combination with threshold<100 to create a
training (output) and test set
-bn attribute, --bname 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.)
-cn attribute, --cname attribute
Name of the class label in the output vector dataset
-geo value, --geo value
Use geo coordinates (set to 0 to use image coordinates)
-down value, --down value
Down sampling factor (for raster sample datasets only). Can be used to create grid
points
-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)
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).
pkextract -i input.tif -s points.sqlite -o extracted.sqlite
Same example as above, but only extract the points for the layer in points.sqlite named
"valid"
pkextract -i input.tif -s points.sqlite -ln valid -o extracted.sqlite
Extract points and write output in ESRI Shapefile format
pkextract -i input.tif -s points.shp -f "ESRI Shapefile" -o extracted.sqlite
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 -circ to
define a circular buffer.
pkextract -i input.tif -s points.sqlite -o extracted.sqlite -r stdev -buf 3 -polygon
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.
pkextract -i input.tif -s polygons.sqlite -o training.sqlite -r point
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.
pkextract -i input.tif -b 0 -s polygons.sqlite -r centroid -o extracted.sqlite -polygon
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
pkextract -i input.tif -b 1 -s polygons.sqlite -r mean -o extracted.sqlite -polygon
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.
pkextract -i landcover.tif -s polygons.sqlite -r maxvote -o majority.sqlite -polygon -c 1 -c 2 -c 3 -c 4 -c 5
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.
pkextract -i input.tif -o random.sqlite -rand 100 -median -buf 3 -polygon
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.
pkextract -i input.tif -o systematic.sqlite -grid 100 -srcnodata 0
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.
pkextract -i input.tif -s sample.tif -o extracted.sqlite -t 10 -c 1 -c 2 -c 3
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.
pkextract -i input.tif -s sample.tif -o extracted.sqlite -t -5000 -c 1
24 January 2016 pkextract(1)