[pktools] 06/06: Add man page for pkextract.
Bas Couwenberg
sebastic at xs4all.nl
Sat Dec 6 19:57:50 UTC 2014
This is an automated email from the git hooks/post-receive script.
sebastic-guest pushed a commit to branch master
in repository pktools.
commit f79fa2f2666a11ded36b0789695f1c8425547129
Author: Bas Couwenberg <sebastic at xs4all.nl>
Date: Sat Dec 6 20:55:21 2014 +0100
Add man page for pkextract.
---
debian/changelog | 2 +-
debian/man/pkextract.1.xml | 498 +++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 499 insertions(+), 1 deletion(-)
diff --git a/debian/changelog b/debian/changelog
index 1a4a5dd..a2e106e 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -4,7 +4,7 @@ pktools (2.6.1-1) UNRELEASED; urgency=medium
* Refresh patches.
* Remove libbase package, library no longer installed.
* Add man page for pkann, pkascii2img, pkascii2ogr, pkcomposite, pkcreatect,
- pkcrop, pkdiff, pkdsm2shadow, pkdumpimg, pkdumpogr, pkegcs.
+ pkcrop, pkdiff, pkdsm2shadow, pkdumpimg, pkdumpogr, pkegcs, pkextract.
-- Bas Couwenberg <sebastic at xs4all.nl> Wed, 03 Dec 2014 21:16:31 +0100
diff --git a/debian/man/pkextract.1.xml b/debian/man/pkextract.1.xml
new file mode 100644
index 0000000..a70bf6f
--- /dev/null
+++ b/debian/man/pkextract.1.xml
@@ -0,0 +1,498 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<refentry id='pkextract'>
+
+ <refmeta>
+ <refentrytitle>pkextract</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pkextract</refname>
+ <refpurpose>extract pixel values from raster image from a (vector or raster) sample</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv id='synopsis'>
+ <cmdsynopsis>
+ <command>pkextract</command>
+ <arg choice='plain'><option>-i</option> <replaceable>input</replaceable></arg>
+ <group>
+ <arg choice='opt'><option>-s</option> <replaceable>sample</replaceable></arg>
+ <arg choice='opt'><option>-rand</option> <replaceable>number</replaceable></arg>
+ <arg choice='opt'><option>-grid</option> <replaceable>size</replaceable></arg>
+ </group>
+ <arg choice='plain'><option>-o</option> <replaceable>output</replaceable></arg>
+ <arg choice='opt'><replaceable>options</replaceable></arg>
+ <arg choice='opt'><replaceable>advanced options</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id='description'>
+ <title>DESCRIPTION</title>
+ <para>
+ <command>pkextract</command> 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).
+ </para>
+ <para>
+ 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 <option>-t</option> with a percentage value.
+ </para>
+ <para>
+ A typical usage of <command>pkextract</command> is to prepare a training
+ sample for one of the classifiers implemented in pktools.
+ </para>
+ </refsect1>
+
+ <refsect1 id='options'>
+ <title>OPTIONS</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-i</option> <replaceable>filename</replaceable></term>
+ <term><option>--input</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ Raster input dataset containing band information
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s</option> <replaceable>sample</replaceable></term>
+ <term><option>--sample</option> <replaceable>sample</replaceable></term>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-rand</option> <replaceable>number</replaceable></term>
+ <term><option>--random</option> <replaceable>number</replaceable></term>
+ <listitem>
+ <para>
+ Create simple random sample of points.
+ Provide number of points to generate
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-grid</option> <replaceable>size</replaceable></term>
+ <term><option>--grid</option> <replaceable>size</replaceable></term>
+ <listitem>
+ <para>
+ Create systematic grid of points.
+ Provide cell grid size (in projected units, e.g,. m)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-o</option> <replaceable>filename</replaceable></term>
+ <term><option>--output</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ Output sample dataset Output sample dataset
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ln</option> <replaceable>layer</replaceable></term>
+ <term><option>--ln</option> <replaceable>layer</replaceable></term>
+ <listitem>
+ <para>
+ Layer name(s) in sample (leave empty to select all)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-c</option> <replaceable>class</replaceable></term>
+ <term><option>--class</option> <replaceable>class</replaceable></term>
+ <listitem>
+ <para>
+ 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 or proportion
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-t</option> <replaceable>threshold</replaceable></term>
+ <term><option>--threshold</option> <replaceable>threshold</replaceable></term>
+ <listitem>
+ <para>
+ 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. <option>-t</option> <replaceable>80</replaceable>
+ <option>-t</option> <replaceable>60</replaceable>).
+ Use value 100 to select all pixels for selected class(es)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-f</option> <replaceable>format</replaceable></term>
+ <term><option>--f</option> <replaceable>format</replaceable></term>
+ <listitem>
+ <para>
+ Output sample dataset format
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ft</option> <replaceable>fieldType</replaceable></term>
+ <term><option>--ftype</option> <replaceable>fieldType</replaceable></term>
+ <listitem>
+ <para>
+ Field type (only Real or Integer)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-lt</option> <replaceable>labelType</replaceable></term>
+ <term><option>--ltype</option> <replaceable>labelType</replaceable></term>
+ <listitem>
+ <para>
+ Label type: In16 or String
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-polygon</option></term>
+ <term><option>--polygon</option></term>
+ <listitem>
+ <para>
+ Create OGRPolygon as geometry instead of OGRPoint.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-b</option> <replaceable>band</replaceable></term>
+ <term><option>--band</option> <replaceable>band</replaceable></term>
+ <listitem>
+ <para>
+ Band index(es) to extract.
+ Leave empty to use all bands
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-r</option> <replaceable>rule</replaceable></term>
+ <term><option>--rule</option> <replaceable>rule</replaceable></term>
+ <listitem>
+ <para>
+ 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, min, max, mode, sum.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-v</option> <replaceable>level</replaceable></term>
+ <term><option>--verbose</option> <replaceable>level</replaceable></term>
+ <listitem>
+ <para>
+ Verbose mode if > 0
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>Advanced options</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-bndnodata</option> <replaceable>band</replaceable></term>
+ <term><option>--bndnodata</option> <replaceable>band</replaceable></term>
+ <listitem>
+ <para>
+ Band(s) in input image to check if pixel is valid
+ (used for srcnodata)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-srcnodata</option> <replaceable>value</replaceable></term>
+ <term><option>--srcnodata</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Invalid value(s) for input image
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-tp</option> <replaceable>threshold</replaceable></term>
+ <term><option>--thresholdPolygon</option> <replaceable>threshold</replaceable></term>
+ <listitem>
+ <para>
+ (absolute) threshold for selecting samples in each polygon
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-test</option> <replaceable>testSample</replaceable></term>
+ <term><option>--test</option> <replaceable>testSample</replaceable></term>
+ <listitem>
+ <para>
+ Test sample dataset (use this option in combination with
+ threshold<100 to create a training (output) and test set
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-bn</option> <replaceable>attribute</replaceable></term>
+ <term><option>--bname</option> <replaceable>attribute</replaceable></term>
+ <listitem>
+ <para>
+ 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.)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-cn</option> <replaceable>attribute</replaceable></term>
+ <term><option>--cname</option> <replaceable>attribute</replaceable></term>
+ <listitem>
+ <para>
+ Name of the class label in the output vector dataset
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-geo</option> <replaceable>value</replaceable></term>
+ <term><option>--geo</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Use geo coordinates (set to 0 to use image coordinates)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-down</option> <replaceable>value</replaceable></term>
+ <term><option>--down</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Down sampling factor (for raster sample datasets only).
+ Can be used to create grid points
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-buf</option> <replaceable>value</replaceable></term>
+ <term><option>--buffer</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Buffer for calculating statistics for point features
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-circ</option></term>
+ <term><option>--circular</option></term>
+ <listitem>
+ <para>
+ Use a circular disc kernel buffer
+ (for vector point sample datasets only,
+ use in combination with buffer option)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+ <refsect1 id='example'>
+ <title>EXAMPLE</title>
+
+ <example>
+ <title>Using vector samples</title>
+
+ <para>
+ Extract all points for all layers read in
+ <replaceable>points.sqlite</replaceable> from
+ <replaceable>input.tif</replaceable>.
+ Create a new point vector dataset named
+ <replaceable>extracted.sqlite</replaceable>,
+ where each point will contain an attribute for the individual input bands
+ in <replaceable>input.tif</replaceable>.
+ Notice that the default vector format is Spatialite (.sqlite).
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-s</option> <replaceable>points.sqlite</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable>
+ </screen>
+
+ <para>
+ Same example as above, but only extract the points for the layer in
+ <replaceable>points.sqlite</replaceable> named "valid"
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-s</option> <replaceable>points.sqlite</replaceable> <option>-ln</option> <replaceable>valid</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable>
+ </screen>
+
+ <para>
+ Extract points and write output in ESRI Shapefile format
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-s</option> <replaceable>points.shp</replaceable> <option>-f</option> <replaceable>"ESRI Shapefile"</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable>
+ </screen>
+
+ <para>
+ Extract the standard deviation for each input band in a 3 by 3 window,
+ centered around the points in the sample vector dataset
+ <replaceable> points.sqlite</replaceable>.
+ The output vector dataset will contain polygon features defined by the
+ buffered points (3x3 window).
+ Use the option <option>-circ</option> to define a circular buffer.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-s</option> <replaceable>points.sqlite</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable> <option>-r</option> <replaceable>stdev</replaceable> <option>-buf</option> <replaceable>3</replaceable> <option>-polygon</option>
+ </screen>
+
+ <para>
+ Extract all pixels from <replaceable>input.tif</replaceable> covered by
+ the polygons in <replaceable>locations.sqlite</replaceable>.
+ Each polygon can thus result in multiple point features with attributes
+ for each input band.
+ Write the extracted points to a point vector dataset
+ <replaceable>training.sqlite</replaceable>.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-s</option> <replaceable>polygons.sqlite</replaceable> <option>-o</option> <replaceable>training.sqlite</replaceable> <option>-r</option> <replaceable>point</replaceable>
+ </screen>
+
+ <para>
+ Extract the first band from <replaceable>input.tif</replaceable> at the
+ centroids of the polygons in vector dataset
+ <replaceable>polygons.sqlite</replaceable>.
+ Assign the extracted point value to a new attribute of the polygon and
+ write to the vector dataset <replaceable>extracted.sqlite</replaceable>.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-b</option> <replaceable>0</replaceable> <option>-s</option> <replaceable>polygons.sqlite</replaceable> <option>-r</option> <replaceable>centroid</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable> <option>-polygon</option>
+ </screen>
+
+ <para>
+ Extract the mean values for the second band in
+ <replaceable>input.tif</replaceable> covered by each polygon in
+ <replaceable>polygons.sqlite</replaceable>.
+ The mean values are written to a copy of the polygons in output vector
+ dataset <replaceable>extracted.sqlite</replaceable>
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-b</option> <replaceable>1</replaceable> <option>-s</option> <replaceable>polygons.sqlite</replaceable> <option>-r</option> <replaceable>mean</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable> <option>-polygon</option>
+ </screen>
+
+ <para>
+ 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.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>landcover.tif</replaceable> <option>-s</option> <replaceable>polygons.sqlite</replaceable> <option>-r</option> <replaceable>maxvote</replaceable> <option>-o</option> <replaceable>majority.sqlite</replaceable> <option>-polygon</option> <option>-c</option> <replaceable>1</replaceable> <option>-c</option> <replaceable>2</replaceable> <option>-c</option> <replaceable>3</replaceable> <option>-c</option> <replaceable>4</replaceable> [...]
+ </screen>
+ </example>
+
+ <example>
+ <title>Using random and grid samples</title>
+
+ <para>
+ 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.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-o</option> <replaceable>random.sqlite</replaceable> <option>-rand</option> <replaceable>100</replaceable> <option>-median</option> <option>-buf</option> <replaceable>3</replaceable> <option>-polygon</option>
+ </screen>
+
+ <para>
+ 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.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-o</option> <replaceable>systematic.sqlite</replaceable> <option>-grid</option> <replaceable>100</replaceable> <option>-srcnodata</option> <replaceable>0</replaceable>
+ </screen>
+ </example>
+
+ <example>
+ <title>Using raster samples</title>
+
+ <para>
+ Typical use where pixels are extracted based on a land cover map
+ (<replaceable>sample.tif</replaceable>).
+ Extract all bands for a random sample of 10 percent of the pixels in
+ the land cover map <replaceable>sample.tif</replaceable> where the
+ land cover classes are either 1,2 or 3 (class values).
+ Write output to the point vector dataset
+ <replaceable>extracted.sqlite</replaceable>.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-s</option> <replaceable>sample.tif</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable> <option>-t</option> <replaceable>10</replaceable> <option>-c</option> <replaceable>1</replaceable> <option>-c</option> <replaceable>2</replaceable> <option>-c</option> <replaceable>3</replaceable>
+ </screen>
+
+ <para>
+ Extract all bands for the first 5000 pixels encountered in
+ <replaceable>sample.tif</replaceable> where pixels have a
+ value equal to 1.
+ Write output to point vector dataset
+ <replaceable>extracted.sqlite</replaceable>.
+ </para>
+ <screen>
+<command>pkextract</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-s</option> <replaceable>sample.tif</replaceable> <option>-o</option> <replaceable>extracted.sqlite</replaceable> <option>-t</option> <replaceable>-5000</replaceable> <option>-c</option> <replaceable>1</replaceable>
+ </screen>
+ </example>
+
+ </refsect1>
+
+</refentry>
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-grass/pktools.git
More information about the Pkg-grass-devel
mailing list