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 <sebas...@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 <sebas...@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

_______________________________________________
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