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 <[email protected]> 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 <[email protected]> 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 _______________________________________________ Pkg-grass-devel mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-grass-devel
