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