[pktools] 01/06: Add man page for pkann.
Bas Couwenberg
sebastic at xs4all.nl
Fri Dec 5 23:19:32 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 2ab4d81a317edab692c17d20cb4adae1ab9f7894
Author: Bas Couwenberg <sebastic at xs4all.nl>
Date: Fri Dec 5 16:09:02 2014 +0100
Add man page for pkann.
---
debian/changelog | 1 +
debian/control | 6 +-
debian/man/pkann.1.xml | 523 ++++++++++++++++++++++++++++++++++++++++++++++++
debian/pktools.manpages | 1 +
debian/rules | 13 +-
5 files changed, 542 insertions(+), 2 deletions(-)
diff --git a/debian/changelog b/debian/changelog
index c82f712..28c9889 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -3,6 +3,7 @@ pktools (2.6.1-1) UNRELEASED; urgency=medium
* New upstream release.
* Refresh patches.
* Remove libbase package, library no longer installed.
+ * Add man page for pkann.
-- Bas Couwenberg <sebastic at xs4all.nl> Wed, 03 Dec 2014 21:16:31 +0100
diff --git a/debian/control b/debian/control
index 62d2d00..c2967ca 100644
--- a/debian/control
+++ b/debian/control
@@ -15,7 +15,11 @@ Build-Depends: debhelper (>= 9),
liblas-c-dev,
libsvm-dev,
libnlopt-dev,
- pkg-kde-tools
+ pkg-kde-tools,
+ docbook2x,
+ docbook-xsl,
+ docbook-xml,
+ xsltproc
Standards-Version: 3.9.6
Vcs-Browser: http://anonscm.debian.org/gitweb/?p=pkg-grass/pktools.git
Vcs-Git: git://anonscm.debian.org/pkg-grass/pktools.git
diff --git a/debian/man/pkann.1.xml b/debian/man/pkann.1.xml
new file mode 100644
index 0000000..9f9d9c5
--- /dev/null
+++ b/debian/man/pkann.1.xml
@@ -0,0 +1,523 @@
+<?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='pkann'>
+
+ <refmeta>
+ <refentrytitle>pkann</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pkann</refname>
+ <refpurpose>classify raster image using Artificial Neural Network</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv id='synopsis'>
+ <cmdsynopsis>
+ <command>pkann</command>
+ <arg choice='plain'><option>-t</option> <replaceable>training</replaceable></arg>
+ <arg choice='opt'><option>-i</option> <replaceable>input</replaceable></arg>
+ <arg choice='opt'><option>-cv</option> <replaceable>value</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>pkann</command> implements an artificial neural network (ANN) to
+ solve a supervised classification problem.
+ The implementation is based on the open source C++ library
+ (<ulink url="http://leenissen.dk/fann/wp/">fann</ulink>).
+ Both raster and vector files are supported as input.
+ The output will contain the classification result, either in raster or
+ vector format, corresponding to the format of the input.
+ A training sample must be provided as an OGR vector dataset that contains
+ the class labels and the features for each training point.
+ The point locations are not considered in the training step.
+ You can use the same training sample for classifying different images,
+ provided the number of bands of the images are identical.
+ Use the utility
+ <citerefentry>
+ <refentrytitle>pkextract</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ to create a suitable training sample, based on a sample of points or
+ polygons.
+ For raster output maps you can attach a color table using the option
+ <option>-ct</option>.
+ </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>
+ input image
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-t</option> <replaceable>filename</replaceable></term>
+ <term><option>--training</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ training vector file.
+ A single vector file contains all training features (must be set
+ as: B0, B1, B2,...) for all classes (class numbers identified by
+ label option).
+ Use multiple training files for bootstrap aggregation (alternative
+ to the <option>--bag</option> and <option>--bsize</option> options,
+ where a random subset is taken from a single training file)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-tln</option> <replaceable>layer</replaceable></term>
+ <term><option>--tln</option> <replaceable>layer</replaceable></term>
+ <listitem>
+ <para>
+ training layer name(s)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-label</option> <replaceable>attribute</replaceable></term>
+ <term><option>--label</option> <replaceable>attribute</replaceable></term>
+ <listitem>
+ <para>
+ identifier for class label in training vector file.
+ (default: label)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-prior</option> <replaceable>value</replaceable></term>
+ <term><option>--prior</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ prior probabilities for each class (e.g., <option>-prior</option>
+ 0.3 <option>-prior</option> 0.3 <option>-prior</option> 0.2 )
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-cv</option> <replaceable>value</replaceable></term>
+ <term><option>--cv</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ n-fold cross validation mode (default: 0)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-nn</option> <replaceable>number</replaceable></term>
+ <term><option>--nneuron</option> <replaceable>number</replaceable></term>
+ <listitem>
+ <para>
+ number of neurons in hidden layers in neural network (multiple
+ hidden layers are set by defining multiple number of neurons:
+ <option>-nn</option> 15 <option>-nn</option> 1, default is one
+ hidden layer with 5 neurons)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-m</option> <replaceable>filename</replaceable></term>
+ <term><option>--mask</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ Use the first band of the specified file as a validity mask.
+ Nodata values can be set with the option
+ <option>--msknodata</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-msknodata</option> <replaceable>value</replaceable></term>
+ <term><option>--msknodata</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ mask value(s) not to consider for classification (use negative
+ values if only these values should be taken into account).
+ Values will be taken over in classification image.
+ Default is 0.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-nodata</option> <replaceable>value</replaceable></term>
+ <term><option>--nodata</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ nodata value to put where image is masked as nodata
+ (default: 0)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-o</option> <replaceable>filename</replaceable></term>
+ <term><option>--output</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ output classification image
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ot</option> <replaceable>type</replaceable></term>
+ <term><option>--otype</option> <replaceable>type</replaceable></term>
+ <listitem>
+ <para>
+ Data type for output image
+ ({Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/CInt16/CInt32/CFloat32/CFloat64}).
+ Empty string: inherit type from input image
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-of</option> <replaceable>GDALformat</replaceable></term>
+ <term><option>--oformat</option> <replaceable>GDALformat</replaceable></term>
+ <listitem>
+ <para>
+ Output image format (see also
+ <citerefentry>
+ <refentrytitle>gdal_translate</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>).
+ Empty string: inherit from input image
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-f</option> <replaceable>OGRformat</replaceable></term>
+ <term><option>--f</option> <replaceable>OGRformat</replaceable></term>
+ <listitem>
+ <para>
+ Output ogr format for active training sample
+ (default: SQLite)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-ct</option> <replaceable>filename</replaceable></term>
+ <term><option>--ct</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ colour table in ASCII format having 5 columns: id R G B ALFA
+ (0: transparent, 255: solid)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-co</option> <replaceable>NAME=VALUE</replaceable></term>
+ <term><option>--co</option> <replaceable>NAME=VALUE</replaceable></term>
+ <listitem>
+ <para>
+ Creation option for output file.
+ Multiple options can be specified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-c</option> <replaceable>name</replaceable></term>
+ <term><option>--class</option> <replaceable>name</replaceable></term>
+ <listitem>
+ <para>
+ list of class names.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-r</option> <replaceable>value</replaceable></term>
+ <term><option>--reclass</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ list of class values (use same order as in
+ <option>--class</option> option).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-v</option> <replaceable>0|1|2</replaceable></term>
+ <term><option>--verbose</option> <replaceable>0|1|2</replaceable></term>
+ <listitem>
+ <para>
+ set to: 0 (results only), 1 (confusion matrix), 2 (debug)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>Advanced options</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-bal</option> <replaceable>size</replaceable></term>
+ <term><option>--balance</option> <replaceable>size</replaceable></term>
+ <listitem>
+ <para>
+ balance the input data to this number of samples for each class
+ (default: 0)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-min</option> <replaceable>number</replaceable></term>
+ <term><option>--min</option> <replaceable>number</replaceable></term>
+ <listitem>
+ <para>
+ if number of training pixels is less then min, do not take this
+ class into account (0: consider all classes)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-b</option> <replaceable>band</replaceable></term>
+ <term><option>--band</option> <replaceable>band</replaceable></term>
+ <listitem>
+ <para>
+ band index (starting from 0, either use <option>--band</option>
+ option or use <option>--start</option> to <option>--end</option>)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s</option> <replaceable>band</replaceable></term>
+ <term><option>--start</option> <replaceable>band</replaceable></term>
+ <listitem>
+ <para>
+ start band sequence number
+ (default: 0)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-e</option> <replaceable>band</replaceable></term>
+ <term><option>--end</option> <replaceable>band</replaceable></term>
+ <listitem>
+ <para>
+ end band sequence number (set to 0 to include bands)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--offset</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ offset value for each spectral band input features:
+ refl[band]=(DN[band]-offset[band])/scale[band]
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--scale</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ scale value for each spectral band input features:
+ refl=(DN[band]-offset[band])/scaleband
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-a</option> <replaceable>1|2</replaceable></term>
+ <term><option>--aggreg</option> <replaceable>1|2</replaceable></term>
+ <listitem>
+ <para>
+ how to combine aggregated classifiers, see also
+ <option>--rc</option> option (1: sum rule, 2: max rule).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--connection</option> <replaceable>0|1</replaceable></term>
+ <listitem>
+ <para>
+ connection rate (default: 1.0 for a fully connected network)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-w</option> <replaceable>weights</replaceable></term>
+ <term><option>--weights</option> <replaceable>weights</replaceable></term>
+ <listitem>
+ <para>
+ weights for neural network.
+ Apply to fully connected network only, starting from first input
+ neuron to last output neuron, including the bias neurons (last
+ neuron in each but last layer)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-l</option> <replaceable>rate</replaceable></term>
+ <term><option>--learning</option> <replaceable>rate</replaceable></term>
+ <listitem>
+ <para>
+ learning rate (default: 0.7)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--maxit</option> <replaceable>number</replaceable></term>
+ <listitem>
+ <para>
+ number of maximum iterations (epoch) (default: 500)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-comb</option> <replaceable>rule</replaceable></term>
+ <term><option>--comb</option> <replaceable>rule</replaceable></term>
+ <listitem>
+ <para>
+ how to combine bootstrap aggregation classifiers
+ (0: sum rule, 1: product rule, 2: max rule).
+ Also used to aggregate classes with <option>--rc</option> option.
+ Default is sum rule (0)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-bag</option> <replaceable>value</replaceable></term>
+ <term><option>--bag</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Number of bootstrap aggregations (default is no bagging: 1)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-bs</option> <replaceable>value</replaceable></term>
+ <term><option>--bsize</option> <replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Percentage of features used from available training features for
+ each bootstrap aggregation (one size for all classes, or a
+ different size for each class respectively. default: 100)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-cb</option> <replaceable>filename</replaceable></term>
+ <term><option>--classbag</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ output for each individual bootstrap aggregation (default is blank)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--prob</option> <replaceable>filename</replaceable></term>
+ <listitem>
+ <para>
+ probability image.
+ Default is no probability image
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-na</option> <replaceable>number</replaceable></term>
+ <term><option>--na</option> <replaceable>number</replaceable></term>
+ <listitem>
+ <para>
+ number of active training points
+ (default: 1)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+ <refsect1 id='example'>
+ <title>EXAMPLE</title>
+
+ <example>
+ <para>
+ Classify input image <filename>input.tif</filename> with an
+ Artificial Neural Network using one hidden layer with 5 neurons.
+ A training sample that is provided as an OGR vector dataset.
+ It contains all features (same dimensionality as
+ <filename>input.tif</filename>) in its fields (please check
+ <citerefentry>
+ <refentrytitle>pkextract</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ on how to obtain such a file from a "clean" vector file containing
+ locations only).
+ A two-fold cross validation (cv) is performed (output on screen).
+ </para>
+
+ <screen>
+<command>pkann</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-t</option> <replaceable>training.sqlite</replaceable> <option>-o</option> <replaceable>output.tif</replaceable> <option>--nneuron</option> <replaceable>5</replaceable> <option>-cv</option> <replaceable>2</replaceable>
+ </screen>
+ </example>
+
+ <example>
+ <para>
+ Same example as above, but use two hidden layers with 15 and 5 neurons
+ respectively.
+ </para>
+
+ <screen>
+<command>pkann</command> <option>-i</option> <replaceable>input.tif</replaceable> <option>-t</option> <replaceable>training.sqlite</replaceable> <option>-o</option> <replaceable>output.tif</replaceable> <option>--nneuron</option> <replaceable>15</replaceable> <option>--neuron</option> <replaceable>5</replaceable> <option>-cv</option> <replaceable>2</replaceable>
+ </screen>
+ </example>
+
+ </refsect1>
+
+ <refsect1 id='see-also'>
+ <title>SEE ALSO</title>
+
+ <citerefentry>
+ <refentrytitle>pkextract</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+
+ </refsect1>
+
+</refentry>
diff --git a/debian/pktools.manpages b/debian/pktools.manpages
new file mode 100644
index 0000000..13cdaf4
--- /dev/null
+++ b/debian/pktools.manpages
@@ -0,0 +1 @@
+debian/man/*.1
diff --git a/debian/rules b/debian/rules
index 344135f..7582b16 100755
--- a/debian/rules
+++ b/debian/rules
@@ -10,6 +10,8 @@ ifneq ($(wildcard /usr/lib/$(DEB_HOST_MULTIARCH)/hdf5/serial/libhdf5.so),)
export DEB_CXXFLAGS_MAINT_APPEND := -I/usr/include/hdf5/serial
endif
+MANPAGES:=$(wildcard debian/man/*.*.xml)
+
%:
dh $@ --buildsystem autoconf \
--with autoreconf \
@@ -20,11 +22,20 @@ override_dh_auto_configure:
dh_auto_configure -- --enable-fann --enable-las --enable-nlopt
override_dh_clean:
- dh_clean
+ dh_clean debian/man/*.1
find $(CURDIR) -name '*.o' -delete
find $(CURDIR) -name '*.so*' -delete
find $(CURDIR) -name '*.a' -delete
+override_dh_auto_build:
+ # Create man pages from DocBook XML
+ for x in $(MANPAGES) ; do \
+ docbook2x-man $$x ; \
+ mv `basename $$x | sed 's/.xml$$//'` `dirname $$x` ; \
+ done
+
+ dh_auto_build
+
override_dh_install:
find debian/tmp/usr/lib -name '*.la' -delete
dh_install --list-missing
--
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