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 <sebas...@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 <sebas...@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 (&gt;0) or absolute (&lt;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 &gt; 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&lt;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

_______________________________________________
Pkg-grass-devel mailing list
Pkg-grass-devel@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-grass-devel

Reply via email to