source: TI02-CSML/trunk/services/3rdParty/pywps-1.0.0/doc/install.tex @ 2194

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI02-CSML/trunk/services/3rdParty/pywps-1.0.0/doc/install.tex@2194
Revision 2194, 65.1 KB checked in by lawrence, 13 years ago (diff)

Adding various specs and 3rd party code of interest for the CSML
services development.

Line 
1\documentclass[a4paper,11pt]{article}
2\usepackage{layout}
3\usepackage{lscape}
4\usepackage[utf8]{inputenc}
5\usepackage{indentfirst}
6\usepackage{a4wide}
7\author{Jáchym ČepickÃœ}
8
9\title{Implementation of OGC's WPS standard: PyWPS}
10\usepackage{longtable}
11
12\makeatletter
13%\Lesejk
14\def\Lesejk{{\tt{}Les-e\makebox(2,11)[t]{\rotatebox{35}{j}}\kern-.1667em\lower.5ex\hbox{\rotatebox{315}{k}}\kern-.125em\@}}
15\makeatother
16\pagestyle{plain}
17
18\begin{document}
19\maketitle{}
20
21\bigskip
22\begin{quote}
23    Copyright \copyright  2006 Jáchym ČepickÃœ
24    Permission is granted to copy, distribute and/or modify this document
25    under the terms of the GNU Free Documentation License, Version 1.2
26    or any later version published by the Free Software Foundation;
27    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
28    A copy of the license is included in the section entitled "GNU
29    Free Documentation License".
30\end{quote}
31\bigskip
32   
33
34    In this file, you can found the description of installation and
35    configuration of PyWPS script. At the and, you can learn, how to add
36    your own process to the list of processes.
37
38    PyPWS project has been started on April 2006 with support of DBU -- Deutsche Bundesstiftung Umwelt (\texttt{http://dbu.de}) and with help of GDF-Hannover (\texttt{http://gdf-hannover.de}) and Help Service Remote Sensing (\texttt{http:/bnhelp.cz}) companies.
39     
40    Source code can be found at \texttt{http://}\Lesejk\texttt{?cat=pywps}
41     \tableofcontents
42
43    \newpage
44     
45    %---------------------------------------------------------------------
46    \section{Bugs}
47    Known bugs and limitations to 14.8.2006
48    \begin{itemize}
49    \item  Process Inputs definition is made on very primitive way. But it works.
50    \item Sometimes, when there is e.g. SyntaxError in the process, teporary file \texttt{/tmp/pywps*} is not deleted, which ledts to \texttt{ServerBussy} exception and the files have to be removed by hand.
51    \end{itemize}
52
53    Please report all problems or unexpected handeling.
54
55    %---------------------------------------------------------------------
56    \section{Installation}
57     
58    Required packages:
59     
60    \begin{itemize}
61        \item Web Server (e.g. Apache)
62        \item python
63        \item python-xml
64    \end{itemize}
65     
66    Recommended packages:
67     
68    \begin{itemize}
69        \item GIS GRASS
70        \item PROJ.4
71        \item GDAL/OGR
72    \end{itemize}
73     
74    \subsection{Installation the quick 'n' dirty way}
75    For installing pywps to your server simply unzip the archive to the
76    directory, where cgi programs are allowed to run.
77
78    \subsection{Installation the 'clean' way}
79    Unzip the package
80    \begin{verbatim}
81 $ tar -xzf pywps-VERSION.tar.gz
82    \end{verbatim}
83    and run
84    \begin{verbatim}
85$ python setup.py install
86    \end{verbatim}
87   
88    \subsection{Testing after installation}
89    For test, just run
90    \texttt{wps.py} in your command line:
91     
92    \begin{verbatim}
93\$ ./wps.py
94Content-type: text/xml
95
96<?xml version="1.0" ?>
97<ExceptionReport version="1.0.0" xmlns="http://www.opengis.net/ows"
98        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
99        <Exception exceptionCode="MissingParameterValue" locator="request"/>
100</ExceptionReport>
101    \end{verbatim}
102
103     
104    If you got some other message, like e.g.:
105     
106
107    \begin{verbatim}
108Traceback (most recent call last):
109  File "trunk/index.py", line 53, in ?
110    from Wps import wpsexceptions
111  File "/home/jachym/prog/pywps/trunk/Wps/wpsexceptions.py", line 8, in ?
112    from xml.dom.minidom import Document
113ImportError: No module named xml.dom.minidom
114    \end{verbatim}
115
116     
117    Than something is wrong with your Python installation or with the program.
118    This message means, that the xml.dom.minidom package is not installed in
119    your system.
120     
121
122
123   
124    %---------------------------------------------------------------------
125    \section{Configuration}
126     
127    Before you start to tune your pywps program, you should get your copy of
128    OpenGIS(R) Web Processing Service document (OGC 05-007r4) version 0.4.0
129    from http://www.opengeospatial.org/specs/?page=specs
130     
131
132     
133    NOTE: Note, that the configuration option are CASE SENSITIVE
134     
135
136     
137    Pywps configuration takes places in two files. The files are actually python
138    scripts, so it does not harm, if you have some experience in python
139    programming language. But you should be able to setup the program without
140    any python knowledge.
141     
142
143     
144    The first file is in \texttt{etc\/settings.py} and (optional) the second file is
145    \texttt{etc\/grass.py}. Some special "tuning" can be done in \texttt{processes/\_\_init\_\_.py}
146    file
147     
148
149
150    \subsection{\texttt{etc/settings.py}}
151     
152    This file has got two sections: WPS and serverSettings
153     
154
155     
156    In the \texttt{WPS} section, the main configuration is set, which appears mostly in
157    GetCapabilities request. The \emph{mandatory} parameters, which should be set up
158    are (with default/recommend values):
159     
160
161    \begin{verbatim}
162    'version': "0.4.0",
163    'ServiceIdentification': {
164        'Title':"Jachym's WPS server",
165        'ServiceType':"WPS",
166        'ServiceTypeVersion':"0.1.0",
167        'Abstract':'Abstract to this WPS',
168    },
169    'ServiceProvider': {
170            'ProviderName' : "Your Company",
171            'IndividualName':"Your Name",
172            'PositionName':"Your Position",
173            'Role':"your role",
174            'DeliveryPoint': "Street",
175            'City': "City",
176            'PostalCode':"00000",
177            'Country': "Your country",
178            'ElectronicMailAddress':"your.email@address",
179    },
180
181    'OperationsMetadata': {
182        'ServerAddress' : "http://localhost/cgi-bin/wps/wps.py",
183    },
184    'Keywords' : ['GRASS','GIS','WPS'],
185    \end{verbatim}
186
187     
188    In the \texttt{ServerSettings} section, the variables are set, which have impact on
189    the whole server.
190     
191
192    \begin{verbatim}
193# NOTE: You have to create this directory manually and set rights, so
194#       the program is able to store data in there
195'outputPath': '/var/www/wpsoutputs',
196
197#
198# 'outputUrl' - URL of the directory, where the outputs will be stored
199'outputUrl':  'http://192.168.1.31/wpsoutputs',
200
201#
202# tempPath - path to directory, where temporary data will be stored.
203# NOTE: the pywps has to have rights, to create directories and files
204#       in this directory
205'tempPath': '/tmp',
206
207#
208# maxOperations - maximum number of operations, which is allowed to low
209# on this server at ones
210# default = 1
211'maxOperations':1,
212
213#
214# maxSize: maximum input file size in bytes
215# NOTE: maximum file size is 5MB, no care, if this number is higher
216'maxSize':5242880, # 5 MB
217
218#
219# maxInputParamLength: maximal length of input values
220# NOTE: maximum length of input parameters is 256, no matter, how height
221#       is this number
222'maxInputParamLength':256,
223\end{verbatim}
224
225
226    \subsection{\texttt{etc/grass.py}}
227     
228    This file servers for configuration of GRASS GIS environment (if your
229    processes need one). Everything is stored in \texttt{grassenv} structure.
230     
231
232    \begin{verbatim}
233# PATH in which your modules (processes) should be able the search.
234# Default value:
235'PATH': "/usr/local/grass-6.1.cvs/bin/:/usr/local/grass-6.1.cvs/scripts/:\
236/usr/bin/:/bin/:",
237
238# Add eventually some other path, in which should GRASS search for modules
239'GRASS_ADDON_PATH': "",
240
241# Version of GRASS, you are using
242'GRASS_VERSION': "6.1.cvs",
243
244# GRASS_PERL, where is your PERL bin installed
245'GRASS_PERL': "/usr/bin/perl",
246
247# GRASS_GUI should be always "text" unless you know, what you are doing
248'GRASS_GUI': "text",
249
250# GISBASE is place, where your GRASS installation is
251'GISBASE': "/usr/local/grass-6.1.cvs",
252
253# LD_LIBRARY_PATH
254'LD_LIBRARY_PATH':"/usr/local/grass-6.1.cvs/lib",
255
256# HOME has to be set
257'HOME':"/var/www",
258    \end{verbatim}
259
260   
261    %---------------------------------------------------------------------
262    \section{Add your own processes}
263     
264    All processes are stored in the processes directory. Put your file
265    e.g. myprocess.py in there.
266     
267
268     
269    Process is python class with two functions: \texttt{\_\_init\_\_(self)}
270    and \texttt{execute(self)}.
271    In the \texttt{\_\_init\_\_(self)} function, inputs, outputs and other configuration values are set. The GIS operations
272    are called in \texttt{execute(self)}  function. It is possible also to add as many your functions, as you wish.
273     
274
275    \subsection{Process Configuration}
276     
277    The configuration part belongs to the \texttt{\_\_init\_\_} function of the \texttt{Process} class.
278     
279     
280    Mandatory variables are
281     
282
283    \begin{verbatim}
284# Myprocess name
285self.Identifier = "spearpath"
286
287# Myprocess version
288self.processVersion = "0.1"
289
290# Is it allowed, store the data on the server?
291self.storeSupported = "true"
292
293# Do not wait, till the calculation is done -> return XML with status
294# immediately
295self.statusSupported = "true"
296
297# Myprocess Title
298self.Title="Find the shortest path on the roads map on Spearfish dataset"
299    \end{verbatim}
300
301     
302    Eventually optional attributes can be found in the table 38 - "Parts of
303    ExecuteResponse data structure"
304     
305
306     
307    If your process should happen in existing GRASS-Location, and you just need
308    the input parameters for GRASS modules, you can specify it's name by
309    \texttt{grassLocation} variable:
310     
311
312    \begin{verbatim}
313grassLocation="/var/grassdata/spearfish57/"
314    \end{verbatim}
315
316     
317If this variable is not set, new temporary GRASS Location \&\& mapset will be
318generated and you can work in there. The projection of the location will be
319XY.
320     
321
322
323    \subsubsection{Data Inputs}
324     
325    Data inputs are defined in \texttt{self.Inputs} array. Each input is an dictionary with
326    several (mostly mandatory) parameters. Each input type
327    (\texttt{LiteralValue, ComplexValue, ComplexValueReference,
328    BoundingBoxValue}) \textbf{must} be a Python's dictionary
329    ("\texttt{\{\}}") structure, which \emph{can} be filled with aditional
330    attributes.
331     
332
333    \begin{itemize}
334        \item Example of \texttt{LiteralInput}:
335        \texttt{LiteralValue}s are used for individual text entry. Your
336        process can either support any text entry or the entry must be from
337        list of allowed values. \texttt{LiteralValue}s of types \texttt{AnyValue} and
338        \texttt{AllowedValues} are supported. Range of values is not yet
339        implemented.
340
341        Allowed values are set by array of values. If there is no
342        \texttt{values} arry or it contains \texttt{"*"}
343        in the array, \texttt{AnyValue} is assumed:
344
345    \begin{verbatim}
346    {   # example of "AnyValue" case with centimeters as default unit
347
348        'Identifier': 'my_input_value',
349        'Title': 'This is my input value',
350        'LiteralValue': {'UOMs':["cm"]},
351        # alternative for any value:
352        # 'LiteralValue': {'values':["*"]},
353        'dataType': type(0.0)
354    },
355    {   # example of "AllowedValues case with default units (meters)
356
357        'Identifier': 'my_input_value',
358        'Title': 'This is my input value',
359        'LiteralValue': {values:[250, "300", '40', "a"]},
360        # the default value:
361        'value': 250,
362    },
363
364    \end{verbatim}
365         
366
367        \item Example of \texttt{ComplexValueReference} input:
368        \texttt{ComplexValueReference} is URL to some raster/vector/text
369        file, which can be later imported (e.g. to GRASS) and processed.
370        PyWPS will be dowload the file for you and store it's name to
371        \texttt{self.Inputs[NUMBER]['value']} variable.
372
373    \begin{verbatim}
374    {
375        'Identifier':'input_map_file',
376        'Title': 'Input raster map',
377        'ComplexValueReference': {
378                'Formats': [ "image/tiff" ]
379            },
380    },
381    \end{verbatim}
382         
383
384        \item Example of \texttt{ComplexValue} input:
385        \texttt{ComplexValue} provides possibility to embed input (XML)
386        file (e.g. GML) to input \texttt{ExecuteResponce} XML file. PyWPS
387        will store this input in file on server's harddisk, so you can
388        later handle it just like \texttt{ComplexValueReference}.
389
390    \begin{verbatim}
391    {
392        'Identifier':'vector',
393        'Title': 'Input vector map',
394        'Abstract':
395            "This vector map must be part of the input XML document",
396        'ComplexValue': {
397            'Formats': [ "text/xml" ]
398        },
399    },
400    \end{verbatim}
401
402        \item Example of \texttt{BoundingBoxValue} input:
403        \texttt{BoundingBoxValue} provides possibility define your region
404        borders. You can input this only to your Execute responce XML file.
405
406    \begin{verbatim}
407    {
408        'Identifier':'bbox',
409        'Title': 'Bounding box',
410        'Abstract':
411            "Bounding box",
412        'BoundingBoxValue': {},
413    },
414    \end{verbatim}
415
416    Resulting value in your \texttt{self.Input[NUMBER]['value']} will be
417    array of four values in form \texttt{[Lower East, Lower North, Upper
418    East, Upper North]}.
419         
420    \end{itemize}
421
422
423     
424    Default values can be set like follows: \texttt{'value':"Default value",}
425
426    NOTE: If the 'dataType' attribute is not set, control of the input value
427    will not be possible, which could endanger your system
428     
429    For more details look in the table 33 "Parts of ValueFormChoice data
430    structure"
431
432
433    \subsubsection{Data Outputs}
434     
435    The \texttt{self.Outputs} structure defines the look of the outputs from your process.
436    The definition is not much different from the Input structure:
437     
438
439    \begin{verbatim}
440    {
441        'Identifier': 'output',
442        'Title': 'Resulting output map',
443        'ComplexValue': {
444            'Formats':["text/xml"],
445            }
446    },
447    {
448        'Identifier': 'text',
449        'Title': 'Some text',
450        'Abstract': 'Some informative text',
451        'LiteralValue': {
452             {'UOMs':["none"]},
453        }
454    }
455    \end{verbatim}
456
457    \paragraph{BoundingBox Output}
458    \texttt{BoundingBoxValue} is defined by two coordinates pairs:
459    \texttt{LowerCorner} and \texttt{UpperCorner}. For creating
460    \texttt{BoundingBoxValue}    output, you have to make output array with this
461    values:
462    \begin{verbatim}
463    {
464        'Identifier': 'mybbox',
465        'Title': 'Bounding Box of resulting map',
466        'BoundingBoxValue': {},
467         'value' : [0, 0, 10, 10],
468    },
469    \end{verbatim}
470
471
472    \subsection{Process Programming}
473     
474    The process must be defined in the \texttt{execute(self)} function. To
475    each element in self.Inputs array, \texttt{'value'} option will be added.
476    Input variables are accessible via \texttt{'value'} attribute of each element of the
477    \texttt{self.Inputs} array.
478
479    Another way, how to access input values it to do so via new hash \texttt{self.DataInputs}. This way is
480    more intiutive and less confusing. If order of \texttt{Input}s will change, their identificators in \texttt{DataInputs} structure remain same.
481   
482    Also new variable \texttt{self.grassenv} will be in your process at your service.
483
484    Output values can be stored either directly to \texttt{self.Outputs[index]['value']} variable or to \texttt{self.DataOutputs['identifier']} hash on similar way, how \texttt{DataInputs} are used. This makes the usage again more intuitive.
485
486    \begin{verbatim}
487    def execute(self):
488        if os.system("""g.region -d >&2"""):
489            return "Could not set region to default"
490
491        os.system("r.in.gdal -o in=%s out=my_map >&2" %\
492                                    (self.Inputs[0]['value']))
493        os.system("r.mapcalc my_output=my_map+%d >&2" %\
494                                    (self.DataInputs['value']))
495       
496        if os.system("r.out.gdal type=Float32 out=map.tif in=my_output >&2"):
497            return "Could not export resulting raster map [map.tif]"
498
499        self.Outputs[0]['value'] = "map.tif"
500        self.DataOutputs['location'] = self.grassenv['LOCATION_NAME']
501        return
502    \end{verbatim}
503
504     
505    That is all, folks!
506     
507
508    \subsubsection{Error handling}
509     
510    At the end of the \texttt{execute} function, \texttt{None} value should be returned. Any other
511    value means, that the calculation will be stopped and error report will be returned back to the client.
512     
513
514
515    %---------------------------------------------------------------------
516    \section{Note to grass programming}
517     
518    The simplest way, how to call GRASS's (and other shell) commands is via
519    python's \texttt{os.system()} or \texttt{os.popen()} function.
520    Before you do so, it is important to import
521    the \texttt{os} python package (usually one of the first lines in the file). This
522    approach might not be the best, but it is the simplest one. Feel free to use any other low-end functions.
523     
524     
525    Unfortunately, the GRASS modules are very verbose. Some messages are
526    written to STDOUT, some to STDERR. The STDERR will be stored in the error
527    file of your web server. But you have to "catch" the messages, sent to
528    STDOUT. This can be done e.g. by using "1>\&2" statement (redirecting STDOUT
529    to STDERR in shell):
530     
531
532    \begin{verbatim}
533    os.system("""
534        echo "Rekni jim drazi, tatko, za to nic nedas."  >&2
535    """)
536    \end{verbatim}
537
538   
539    %---------------------------------------------------------------------
540    \section{Testing your new process}
541
542    \begin{itemize}
543        \item GetCapabilities request:
544\begin{verbatim}
545    wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\
546        request=getcapabilities" "http://localhost/cgi-bin/wps.py"
547\end{verbatim}
548         
549        \item DescribeProcess request:
550\begin{verbatim}
551    wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\
552        request=DescribeProcess&Identifier=your_process" \
553        "http://localhost/cgi-bin/wps.py"
554\end{verbatim}
555         
556        \item Execute request:
557\begin{verbatim}
558    wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\
559        request=Execute&Identifier=your_process&\
560        datainputs=input1,value1,input2,value2" \
561        "http://localhost/cgi-bin/wps.py"
562\end{verbatim}
563         
564    \end{itemize}
565
566   
567    %---------------------------------------------------------------------
568    \section{Using the PyWPS}
569    \subsection{Input}
570     
571    To get response from PyWPS you have to formulate appropriate query string first. You can use HTTP GET style or HTTP POST style.
572     
573     
574    HTTP GET style is standard URL, with all parameters in one line. You can not set any \texttt{ComplexValue} data in your process via HTTP GET. Example:
575     
576    \begin{verbatim}
577    wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\
578            request=Execute&Identifier=your_process&\
579            datainputs=input1,value1,input2,value2"\
580            "http://localhost/cgi-bin/wps.py"
581    \end{verbatim}
582     
583    In HTTP POST style, you send one "request" parameter, which contains XML input. The XML file can contain also included ComplexValue data, e.g. GML file. Example:
584     
585    \begin{verbatim}
586    wget --post-file=execute-post.txt \
587            "http://localhost/pywps/wps.py" -O - -nv -q
588    \end{verbatim}
589     
590    The \texttt{execute-post.txt} file can look like follows:
591    \begin{verbatim}
592request=<?xml version="1.0" encoding="utf-8"?>
593<Execute service="WPS" version="0.4.0" store="false" status="false"
594xmlns="http://www.opengeospatial.net/wps"
595xmlns:ows="http://www.opengeospatial.net/ows"
596xmlns:xlink="http://www.w3.org/1999/xlink"
597xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
598xsi:schemaLocation="http://www.opengeospatial.net/wps/wpsDescribeProcess.xsd">
599    <ows:Identifier>searchpath</ows:Identifier>
600    <DataInputs>
601        <Input>
602            <ows:Identifier>streetmap</ows:Identifier>
603            <ows:Title>The map</ows:Title>
604            <ows:ComplexValue>
605                <Value>
606<ogr:FeatureCollection
607     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
608     xsi:schemaLocation="http://ogr.maptools.org/ donut.xsd"
609     xmlns:ogr="http://ogr.maptools.org/"
610     xmlns:gml="http://www.opengis.net/gml">
611  <gml:boundedBy>
612    <gml:Box>
613      <gml:coord><gml:X>4.263256414560601e-14</gml:X>
614        <gml:Y>-70.71067811865474</gml:Y></gml:coord>
615      <gml:coord><gml:X>141.4213562373095</gml:X>
616      <gml:Y>70.71067811865474</gml:Y></gml:coord>
617    </gml:Box>
618  </gml:boundedBy>                     
619  <gml:featureMember>
620    <ogr:donut fid="F0">
621      <ogr:geometryProperty><gml:LineString><gml:coordinates>
622      70.710678118654755,70.710678118654741,0 141.42135623730951,0.0,
623      0 70.710678118654741,-70.710678118654741,0 0.000000000000043,
624      0.000000000000057,0 70.710678118654755,
625      70.710678118654741,0</gml:coordinates>
626      </gml:LineString></ogr:geometryProperty>
627    </ogr:donut>
628  </gml:featureMember>
629  <gml:featureMember>
630    <ogr:donut fid="F0">
631      <ogr:geometryProperty><gml:LineString><gml:coordinates>50.000000000000014,
632      0.000000000000021,0 71.213203435596427,-21.213203435596419,0
633      92.426406871192853,0.0,0 71.213203435596427,21.213203435596423,0
634      50.000000000000014,0.000000000000021,0</gml:coordinates>
635      </gml:LineString></ogr:geometryProperty>
636    </ogr:donut>
637  </gml:featureMember>
638</ogr:FeatureCollection>
639                </Value>
640            </ows:ComplexValue>
641        </Input>
642
643        <Input>
644            <ows:Identifier>x1</ows:Identifier>
645            <ows:LiteralValue>591679.31</ows:LiteralValue>
646        </Input>
647        <Input>
648            <ows:Identifier>y1</ows:Identifier>
649            <ows:LiteralValue>4927205.07</ows:LiteralValue>
650        </Input>
651        <Input>
652            <ows:Identifier>x2</ows:Identifier>
653            <ows:LiteralValue>608642.625</ows:LiteralValue>
654        </Input>
655        <Input>
656            <ows:Identifier>y2</ows:Identifier>
657            <ows:LiteralValue>4915876.31</ows:LiteralValue>
658        </Input>
659    </DataInputs>
660</Execute>
661    \end{verbatim}
662     
663    You can see, that there are 4 inputs in this process:
664     
665    \begin{enumerate}
666            \item ComplexValue GML File
667            \item x1 coordinate
668            \item y1 coordinate
669            \item x2 coordinate
670            \item y2 coordinate
671    \end{enumerate}
672    \subsection{Output}
673     
674    The output from PyWPS can be either XML file or results of processes directly. In default configuration, no files are stored on the server, resulting values (maps) are
675    returned to the client. If you want to return XML file with outputs
676    encoding, you have to enable it in you process configuration with
677    option \texttt{storeSupported}:
678     
679    \begin{verbatim}
680    self.storeSupported = "true"
681    \end{verbatim}
682     
683    And you have to call the PyWPS with "store=true" option:
684     
685    \begin{verbatim}
686    version=0.4.0&service=Wps&request=Execute&Identifier=your_process&\
687                    datainputs=input1,value1,input2,value2&store=true
688    \end{verbatim}
689     
690    Or in XML input:
691     
692    \begin{verbatim}
693request=<?xml version="1.0" encoding="utf-8"?>
694<Execute service="WPS" version="0.4.0" store="true" status="false"
695xmlns="http://www.opengeospatial.net/wps"
696xmlns:ows="http://www.opengeospatial.net/ows"
697xmlns:xlink="http://www.w3.org/1999/xlink"
698xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
699xsi:schemaLocation="http://www.opengeospatial.net/wps/wpsDescribeProcess.xsd">
700
701...
702    \end{verbatim}
703
704    This will cause PyWPS to look after \texttt{self.status} array in your process in form form
705    \begin{verbatim}
706    self.status = ["Message", Percent_Done]
707    \end{verbatim}
708    and generate XML file in statusLocation with this embed message. E.g.
709    \begin{verbatim}
710    self.status = ["Generating raster map", 50]
711    \end{verbatim}
712    will become
713
714    \begin{verbatim}
715    ...
716     <Status>
717                <ProcessStarted message="Generating raster map" percentCompleted="50"/>
718    </Status>
719    ...
720    \end{verbatim}
721
722    \appendix
723    \section{Sample process: \texttt{addvalue}}
724    This sample process describes how to made your own WPS processes. Purpose of this process is:
725    \begin{itemize}
726    \item  Download input raster map from some server
727    \item  Convert it to integer values
728    \item  Add input value to each raster cell
729    \item  Convert raster to vector
730    \item  Export raster to TIFF and vector to GML. Vector file will be embed ot output XML file.
731    \end{itemize}
732    \begin{verbatim}
733"""
734pywps process example:
735
736addvalue: Adds some value to raster map
737"""
738# Author:       Jachym Cepicky
739#               http://les-ejk.cz
740
741import os,time,string,sys
742
743class Process:
744    def __init__(self):
745
746        #
747        # Mandatory parameters
748        #
749
750        # Identifier - name of this process
751        self.Identifier = "addvalue"
752
753        # processVersion - version of this process
754        self.processVersion = "0.1"
755
756        # Title - title for this process
757        self.Title="Add some value to raster map"
758
759        #
760        # Inputs
761        # Inputs = [ {input1},{input2},{...} ]
762        #
763        self.Inputs = [
764                # This module has 2 inputs:
765                # 1) Input raster map
766                # 2) Value to be added
767
768                # 0
769                    {
770                        'Identifier':'input',
771                        'Title': 'Input raster map',
772                        'ComplexValueReference': {
773                            'Formats': [ "image/tiff" ]
774                        },
775                        'value':None
776                    },
777
778                # 1
779                    {
780                        'Identifier': 'value',
781                        'Title': 'Value to be added',
782                        'LiteralValue': {"values":["*"]}, # will cause "AnyValue"
783                        'dataType' : type(0.0),
784                        'value':None
785                    },
786                ]
787
788        #
789        # Output
790        # The structure is not much different from the input structure
791        #
792        self.Outputs = [
793                # 0
794                {
795                    'Identifier': 'vector',
796                    'Title': 'Resulting vector map',
797                    'ComplexValue': {
798                        'Formats':["text/xml"],
799                        },
800                    'value':None
801                },
802                # 1
803                {
804                    'Identifier': 'raster',
805                    'Title': 'Resulting raster map',
806                    'ComplexValueReference': {
807                        'Formats':["image/tiff"],
808                        },
809                    'value':None
810                }
811                # 2
812                {
813                    'Identifier': 'bbox',
814                    'Title': 'Resulting map bbox',
815                    'BoundingBoxValue': {}
816                }
817
818
819            ]
820
821        #
822        # Optional attributes
823        #
824        #
825        # storeSupported = "true" or "false"
826        # should the resulting map be stored on our disk?
827        self.storeSupported = "true"
828
829        #
830        # statusSupported = "true" or "false" - run asynchronous
831        self.statusSupported = "true"
832
833    ##############################################################
834    # Execute part of the process
835    def execute(self):
836        """
837        This function
838            1) Imports the raster map
839            2) runs r.mapcalc out=in+value
840            3) Exports the raster map
841            4) Sets the bounding box of resulting map
842            5) runs r.to.vect
843            6) Exports the vector map
844        """
845
846        # for asynchronous process:
847        self.status=["Importing the raster map", 5]
848
849        # 1) import
850        if os.system("r.in.gdal -o in=%s out=input >&2" %\
851                (self.DataInputs['input'])):
852            return "Could not import raster map
853
854        # check for more than one channel
855        for gdalinfoln in os.popen("gdalinfo %s" % \
856                (self.DataInputs['input'])):
857            if gdalinfoln.split()[0] == "Band" and gdalinfoln.split()[1] == "3":
858                return "This module can work only with ONE channel raster maps"
859
860        # set right region
861        os.system("""g.region rast=input >&2""")
862
863        # for asynchronous process:
864        self.status=["Adding input value to raster map", 30]
865
866        # 2) add the value, convert to int
867        os.system("""r.mapcalc output="int(input+%f)" """ % \
868                (float(self.DataInputs['value'])))
869
870        # for asynchronous process:
871        self.status=["Exporting TIFF image", 50]
872
873        # 3) export the tiff
874        if os.system("r.out.gdal type=Int32 in=output out=%s 1>&2" %\
875            "output.tif"):
876            return "Could not export raster map"
877
878        # for asynchronous process:
879        self.status=["Converting raster to vector", 75]
880
881        # 4) seting the bounding box
882        region = {}
883        for b in os.popen("g.region -g"):
884            b = b.strip()
885            key,val = b.split("=")
886            region[key] = val
887        self.DataOutputs['bbox'] = [region['s'],region['e'],region['n'],region['w']]
888
889        # 5) convert to vector
890        if os.system("r.to.vect in=output out=output feature=area >&2"):
891            return "Could not convert raster to vector"
892
893        # for asynchronous process:
894        self.status=["Exporting GML file", 95]
895
896        # 6) export of vector map to GML
897        if os.system(
898            """v.out.ogr format=GML  in=output dsn=output.gml olayer=output >&2"""):
899            return "Could not export vector to GML"
900
901        # setting output variables
902        self.DataOutputs['vector'] = "output.gml"
903        self.DataOutputs['raster'] = "output.tif"
904
905        # end
906        return
907
908    \end{verbatim}
909
910    \section{KVP request encoding of \texttt{addvalue}}
911    This process can be lunched with URL:\\
912    http://localhost/cgi-bin/wps.py?service=wps\&version=0.4.0\&identifier=addvalue\&request=execute\&$\backslash$\\
913    datainputs=input,http://localhost/data/raster.tif,value,250\&status=true\&store=true
914
915    \section{XML request encoding \texttt{addvalue}}
916\begin{verbatim}
917request=<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
918<Execute service='wps' version='0.4.0' store='true' status='false'
919    xmlns="http://www.opengeospatial.net/wps"
920    xmlns:ows="http://www.opengeospatial.net/ows">
921<ows:Identifier>addvalue</ows:Identifier>
922<DataInputs>
923    <Input>
924        <ows:Identifier>input</ows:Identifier>
925        <ComplexValueReference reference='http://localhost/wps/data/soils.tif' />
926    </Input>
927    <Input>
928        <ows:Identifier>value</ows:Identifier>
929        <LiteralValue>250</LiteralValue>
930    </Input>
931    <!-- Input>
932        <ows:Identifier>bbox</ows:Identifier>
933        <BoundingBoxValue>
934            <BoundingBox>
935                <LowerCorner>-1 -1</LowerCorner>
936                <UpperCorner>10 10</UpperCorner>
937            </BoundingBox>
938        </BoundingBoxValue>
939    </Input -->
940</DataInputs>
941</Execute>
942\end{verbatim}
943
944    \section{Licence of PyWPS}
945
946\begin{center}
947{\Large The GNU General Public License}
948
949{\parindent 0in
950
951Version 2, June 1991
952
953Copyright \copyright\ 1989, 1991 Free Software Foundation, Inc.
954
955\bigskip
956
95751 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
958
959\bigskip
960
961Everyone is permitted to copy and distribute verbatim copies
962of this license document, but changing it is not allowed.
963}
964\end{center}
965
966\renewcommand{\abstractname}{Preamble}
967\begin{abstract}
968The licenses for most software are designed to take away your freedom to
969share and change it.  By contrast, the GNU General Public License is
970intended to guarantee your freedom to share and change free software---to
971make sure the software is free for all its users.  This General Public
972License applies to most of the Free Software Foundation's software and to
973any other program whose authors commit to using it.  (Some other Free
974Software Foundation software is covered by the GNU Library General Public
975License instead.)  You can apply it to your programs, too.
976
977When we speak of free software, we are referring to freedom, not price.
978Our General Public Licenses are designed to make sure that you have the
979freedom to distribute copies of free software (and charge for this service
980if you wish), that you receive source code or can get it if you want it,
981that you can change the software or use pieces of it in new free programs;
982and that you know you can do these things.
983
984To protect your rights, we need to make restrictions that forbid anyone to
985deny you these rights or to ask you to surrender the rights.  These
986restrictions translate to certain responsibilities for you if you
987distribute copies of the software, or if you modify it.
988
989For example, if you distribute copies of such a program, whether gratis or
990for a fee, you must give the recipients all the rights that you have.  You
991must make sure that they, too, receive or can get the source code.  And
992you must show them these terms so they know their rights.
993
994We protect your rights with two steps: (1) copyright the software, and (2)
995offer you this license which gives you legal permission to copy,
996distribute and/or modify the software.
997
998Also, for each author's protection and ours, we want to make certain that
999everyone understands that there is no warranty for this free software.  If
1000the software is modified by someone else and passed on, we want its
1001recipients to know that what they have is not the original, so that any
1002problems introduced by others will not reflect on the original authors'
1003reputations.
1004
1005Finally, any free program is threatened constantly by software patents.
1006We wish to avoid the danger that redistributors of a free program will
1007individually obtain patent licenses, in effect making the program
1008proprietary.  To prevent this, we have made it clear that any patent must
1009be licensed for everyone's free use or not licensed at all.
1010
1011The precise terms and conditions for copying, distribution and
1012modification follow.
1013\end{abstract}
1014
1015\begin{center}
1016{\Large \sc GNU General Public License
1017\\\vspace{3mm}Terms and Conditions For Copying, Distribution and Modification}
1018\end{center}
1019
1020
1021\begin{enumerate}
1022
1023\addtocounter{enumi}{-1}
1024
1025\item 
1026
1027This License applies to any program or other work which contains a notice
1028placed by the copyright holder saying it may be distributed under the
1029terms of this General Public License.  The ``Program'', below, refers to
1030any such program or work, and a ``work based on the Program'' means either
1031the Program or any derivative work under copyright law: that is to say, a
1032work containing the Program or a portion of it, either verbatim or with
1033modifications and/or translated into another language.  (Hereinafter,
1034translation is included without limitation in the term ``modification''.)
1035Each licensee is addressed as ``you''.
1036
1037Activities other than copying, distribution and modification are not
1038covered by this License; they are outside its scope.  The act of
1039running the Program is not restricted, and the output from the Program
1040is covered only if its contents constitute a work based on the
1041Program (independent of having been made by running the Program).
1042Whether that is true depends on what the Program does.
1043
1044\item You may copy and distribute verbatim copies of the Program's source
1045  code as you receive it, in any medium, provided that you conspicuously
1046  and appropriately publish on each copy an appropriate copyright notice
1047  and disclaimer of warranty; keep intact all the notices that refer to
1048  this License and to the absence of any warranty; and give any other
1049  recipients of the Program a copy of this License along with the Program.
1050
1051You may charge a fee for the physical act of transferring a copy, and you
1052may at your option offer warranty protection in exchange for a fee.
1053
1054\item
1055
1056You may modify your copy or copies of the Program or any portion
1057of it, thus forming a work based on the Program, and copy and
1058distribute such modifications or work under the terms of Section 1
1059above, provided that you also meet all of these conditions:
1060
1061\begin{enumerate}
1062
1063\item 
1064
1065You must cause the modified files to carry prominent notices stating that
1066you changed the files and the date of any change.
1067
1068\item
1069
1070You must cause any work that you distribute or publish, that in
1071whole or in part contains or is derived from the Program or any
1072part thereof, to be licensed as a whole at no charge to all third
1073parties under the terms of this License.
1074
1075\item
1076If the modified program normally reads commands interactively
1077when run, you must cause it, when started running for such
1078interactive use in the most ordinary way, to print or display an
1079announcement including an appropriate copyright notice and a
1080notice that there is no warranty (or else, saying that you provide
1081a warranty) and that users may redistribute the program under
1082these conditions, and telling the user how to view a copy of this
1083License.  (Exception: if the Program itself is interactive but
1084does not normally print such an announcement, your work based on
1085the Program is not required to print an announcement.)
1086
1087\end{enumerate}
1088
1089
1090These requirements apply to the modified work as a whole.  If
1091identifiable sections of that work are not derived from the Program,
1092and can be reasonably considered independent and separate works in
1093themselves, then this License, and its terms, do not apply to those
1094sections when you distribute them as separate works.  But when you
1095distribute the same sections as part of a whole which is a work based
1096on the Program, the distribution of the whole must be on the terms of
1097this License, whose permissions for other licensees extend to the
1098entire whole, and thus to each and every part regardless of who wrote it.
1099
1100Thus, it is not the intent of this section to claim rights or contest
1101your rights to work written entirely by you; rather, the intent is to
1102exercise the right to control the distribution of derivative or
1103collective works based on the Program.
1104
1105In addition, mere aggregation of another work not based on the Program
1106with the Program (or with a work based on the Program) on a volume of
1107a storage or distribution medium does not bring the other work under
1108the scope of this License.
1109
1110\item
1111You may copy and distribute the Program (or a work based on it,
1112under Section 2) in object code or executable form under the terms of
1113Sections 1 and 2 above provided that you also do one of the following:
1114
1115\begin{enumerate}
1116
1117\item
1118
1119Accompany it with the complete corresponding machine-readable
1120source code, which must be distributed under the terms of Sections
11211 and 2 above on a medium customarily used for software interchange; or,
1122
1123\item
1124
1125Accompany it with a written offer, valid for at least three
1126years, to give any third party, for a charge no more than your
1127cost of physically performing source distribution, a complete
1128machine-readable copy of the corresponding source code, to be
1129distributed under the terms of Sections 1 and 2 above on a medium
1130customarily used for software interchange; or,
1131
1132\item
1133
1134Accompany it with the information you received as to the offer
1135to distribute corresponding source code.  (This alternative is
1136allowed only for noncommercial distribution and only if you
1137received the program in object code or executable form with such
1138an offer, in accord with Subsection b above.)
1139
1140\end{enumerate}
1141
1142
1143The source code for a work means the preferred form of the work for
1144making modifications to it.  For an executable work, complete source
1145code means all the source code for all modules it contains, plus any
1146associated interface definition files, plus the scripts used to
1147control compilation and installation of the executable.  However, as a
1148special exception, the source code distributed need not include
1149anything that is normally distributed (in either source or binary
1150form) with the major components (compiler, kernel, and so on) of the
1151operating system on which the executable runs, unless that component
1152itself accompanies the executable.
1153
1154If distribution of executable or object code is made by offering
1155access to copy from a designated place, then offering equivalent
1156access to copy the source code from the same place counts as
1157distribution of the source code, even though third parties are not
1158compelled to copy the source along with the object code.
1159
1160\item
1161You may not copy, modify, sublicense, or distribute the Program
1162except as expressly provided under this License.  Any attempt
1163otherwise to copy, modify, sublicense or distribute the Program is
1164void, and will automatically terminate your rights under this License.
1165However, parties who have received copies, or rights, from you under
1166this License will not have their licenses terminated so long as such
1167parties remain in full compliance.
1168
1169\item
1170You are not required to accept this License, since you have not
1171signed it.  However, nothing else grants you permission to modify or
1172distribute the Program or its derivative works.  These actions are
1173prohibited by law if you do not accept this License.  Therefore, by
1174modifying or distributing the Program (or any work based on the
1175Program), you indicate your acceptance of this License to do so, and
1176all its terms and conditions for copying, distributing or modifying
1177the Program or works based on it.
1178
1179\item
1180Each time you redistribute the Program (or any work based on the
1181Program), the recipient automatically receives a license from the
1182original licensor to copy, distribute or modify the Program subject to
1183these terms and conditions.  You may not impose any further
1184restrictions on the recipients' exercise of the rights granted herein.
1185You are not responsible for enforcing compliance by third parties to
1186this License.
1187
1188\item
1189If, as a consequence of a court judgment or allegation of patent
1190infringement or for any other reason (not limited to patent issues),
1191conditions are imposed on you (whether by court order, agreement or
1192otherwise) that contradict the conditions of this License, they do not
1193excuse you from the conditions of this License.  If you cannot
1194distribute so as to satisfy simultaneously your obligations under this
1195License and any other pertinent obligations, then as a consequence you
1196may not distribute the Program at all.  For example, if a patent
1197license would not permit royalty-free redistribution of the Program by
1198all those who receive copies directly or indirectly through you, then
1199the only way you could satisfy both it and this License would be to
1200refrain entirely from distribution of the Program.
1201
1202If any portion of this section is held invalid or unenforceable under
1203any particular circumstance, the balance of the section is intended to
1204apply and the section as a whole is intended to apply in other
1205circumstances.
1206
1207It is not the purpose of this section to induce you to infringe any
1208patents or other property right claims or to contest validity of any
1209such claims; this section has the sole purpose of protecting the
1210integrity of the free software distribution system, which is
1211implemented by public license practices.  Many people have made
1212generous contributions to the wide range of software distributed
1213through that system in reliance on consistent application of that
1214system; it is up to the author/donor to decide if he or she is willing
1215to distribute software through any other system and a licensee cannot
1216impose that choice.
1217
1218This section is intended to make thoroughly clear what is believed to
1219be a consequence of the rest of this License.
1220
1221\item
1222If the distribution and/or use of the Program is restricted in
1223certain countries either by patents or by copyrighted interfaces, the
1224original copyright holder who places the Program under this License
1225may add an explicit geographical distribution limitation excluding
1226those countries, so that distribution is permitted only in or among
1227countries not thus excluded.  In such case, this License incorporates
1228the limitation as if written in the body of this License.
1229
1230\item
1231The Free Software Foundation may publish revised and/or new versions
1232of the General Public License from time to time.  Such new versions will
1233be similar in spirit to the present version, but may differ in detail to
1234address new problems or concerns.
1235
1236Each version is given a distinguishing version number.  If the Program
1237specifies a version number of this License which applies to it and ``any
1238later version'', you have the option of following the terms and conditions
1239either of that version or of any later version published by the Free
1240Software Foundation.  If the Program does not specify a version number of
1241this License, you may choose any version ever published by the Free Software
1242Foundation.
1243
1244\item
1245If you wish to incorporate parts of the Program into other free
1246programs whose distribution conditions are different, write to the author
1247to ask for permission.  For software which is copyrighted by the Free
1248Software Foundation, write to the Free Software Foundation; we sometimes
1249make exceptions for this.  Our decision will be guided by the two goals
1250of preserving the free status of all derivatives of our free software and
1251of promoting the sharing and reuse of software generally.
1252
1253\begin{center}
1254{\Large\sc
1255No Warranty
1256}
1257\end{center}
1258
1259\item
1260{\sc Because the program is licensed free of charge, there is no warranty
1261for the program, to the extent permitted by applicable law.  Except when
1262otherwise stated in writing the copyright holders and/or other parties
1263provide the program ``as is'' without warranty of any kind, either expressed
1264or implied, including, but not limited to, the implied warranties of
1265merchantability and fitness for a particular purpose.  The entire risk as
1266to the quality and performance of the program is with you.  Should the
1267program prove defective, you assume the cost of all necessary servicing,
1268repair or correction.}
1269
1270\item
1271{\sc In no event unless required by applicable law or agreed to in writing
1272will any copyright holder, or any other party who may modify and/or
1273redistribute the program as permitted above, be liable to you for damages,
1274including any general, special, incidental or consequential damages arising
1275out of the use or inability to use the program (including but not limited
1276to loss of data or data being rendered inaccurate or losses sustained by
1277you or third parties or a failure of the program to operate with any other
1278programs), even if such holder or other party has been advised of the
1279possibility of such damages.}
1280
1281\end{enumerate}
1282
1283
1284\begin{center}
1285{\Large\sc End of Terms and Conditions}
1286\end{center}
1287
1288    \section{Licence of this document}
1289
1290 \begin{center}
1291
1292
1293{\Large GNU Free Documentation License}
1294
1295       Version 1.2, November 2002
1296
1297 Copyright \copyright 2000,2001,2002  Free Software Foundation, Inc.
1298 
1299 \bigskip
1300 
1301     51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
1302 
1303 \bigskip
1304 
1305 Everyone is permitted to copy and distribute verbatim copies
1306 of this license document, but changing it is not allowed.
1307\end{center}
1308
1309
1310\begin{center}
1311{\bf\large Preamble}
1312\end{center}
1313
1314The purpose of this License is to make a manual, textbook, or other
1315functional and useful document "free" in the sense of freedom: to
1316assure everyone the effective freedom to copy and redistribute it,
1317with or without modifying it, either commercially or noncommercially.
1318Secondarily, this License preserves for the author and publisher a way
1319to get credit for their work, while not being considered responsible
1320for modifications made by others.
1321
1322This License is a kind of "copyleft", which means that derivative
1323works of the document must themselves be free in the same sense.  It
1324complements the GNU General Public License, which is a copyleft
1325license designed for free software.
1326
1327We have designed this License in order to use it for manuals for free
1328software, because free software needs free documentation: a free
1329program should come with manuals providing the same freedoms that the
1330software does.  But this License is not limited to software manuals;
1331it can be used for any textual work, regardless of subject matter or
1332whether it is published as a printed book.  We recommend this License
1333principally for works whose purpose is instruction or reference.
1334
1335
1336\begin{center}
1337{\Large\bf 1. APPLICABILITY AND DEFINITIONS}
1338\end{center}
1339
1340This License applies to any manual or other work, in any medium, that
1341contains a notice placed by the copyright holder saying it can be
1342distributed under the terms of this License.  Such a notice grants a
1343world-wide, royalty-free license, unlimited in duration, to use that
1344work under the conditions stated herein.  The \textbf{"Document"}, below,
1345refers to any such manual or work.  Any member of the public is a
1346licensee, and is addressed as \textbf{"you"}.  You accept the license if you
1347copy, modify or distribute the work in a way requiring permission
1348under copyright law.
1349
1350A \textbf{"Modified Version"} of the Document means any work containing the
1351Document or a portion of it, either copied verbatim, or with
1352modifications and/or translated into another language.
1353
1354A \textbf{"Secondary Section"} is a named appendix or a front-matter section of
1355the Document that deals exclusively with the relationship of the
1356publishers or authors of the Document to the Document's overall subject
1357(or to related matters) and contains nothing that could fall directly
1358within that overall subject.  (Thus, if the Document is in part a
1359textbook of mathematics, a Secondary Section may not explain any
1360mathematics.)  The relationship could be a matter of historical
1361connection with the subject or with related matters, or of legal,
1362commercial, philosophical, ethical or political position regarding
1363them.
1364
1365The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles
1366are designated, as being those of Invariant Sections, in the notice
1367that says that the Document is released under this License.  If a
1368section does not fit the above definition of Secondary then it is not
1369allowed to be designated as Invariant.  The Document may contain zero
1370Invariant Sections.  If the Document does not identify any Invariant
1371Sections then there are none.
1372
1373The \textbf{"Cover Texts"} are certain short passages of text that are listed,
1374as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1375the Document is released under this License.  A Front-Cover Text may
1376be at most 5 words, and a Back-Cover Text may be at most 25 words.
1377
1378A \textbf{"Transparent"} copy of the Document means a machine-readable copy,
1379represented in a format whose specification is available to the
1380general public, that is suitable for revising the document
1381straightforwardly with generic text editors or (for images composed of
1382pixels) generic paint programs or (for drawings) some widely available
1383drawing editor, and that is suitable for input to text formatters or
1384for automatic translation to a variety of formats suitable for input
1385to text formatters.  A copy made in an otherwise Transparent file
1386format whose markup, or absence of markup, has been arranged to thwart
1387or discourage subsequent modification by readers is not Transparent.
1388An image format is not Transparent if used for any substantial amount
1389of text.  A copy that is not "Transparent" is called \textbf{"Opaque"}.
1390
1391Examples of suitable formats for Transparent copies include plain
1392ASCII without markup, Texinfo input format, LaTeX input format, SGML
1393or XML using a publicly available DTD, and standard-conforming simple
1394HTML, PostScript or PDF designed for human modification.  Examples of
1395transparent image formats include PNG, XCF and JPG.  Opaque formats
1396include proprietary formats that can be read and edited only by
1397proprietary word processors, SGML or XML for which the DTD and/or
1398processing tools are not generally available, and the
1399machine-generated HTML, PostScript or PDF produced by some word
1400processors for output purposes only.
1401
1402The \textbf{"Title Page"} means, for a printed book, the title page itself,
1403plus such following pages as are needed to hold, legibly, the material
1404this License requires to appear in the title page.  For works in
1405formats which do not have any title page as such, "Title Page" means
1406the text near the most prominent appearance of the work's title,
1407preceding the beginning of the body of the text.
1408
1409A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose
1410title either is precisely XYZ or contains XYZ in parentheses following
1411text that translates XYZ in another language.  (Here XYZ stands for a
1412specific section name mentioned below, such as \textbf{"Acknowledgements"},
1413\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.) 
1414To \textbf{"Preserve the Title"}
1415of such a section when you modify the Document means that it remains a
1416section "Entitled XYZ" according to this definition.
1417
1418The Document may include Warranty Disclaimers next to the notice which
1419states that this License applies to the Document.  These Warranty
1420Disclaimers are considered to be included by reference in this
1421License, but only as regards disclaiming warranties: any other
1422implication that these Warranty Disclaimers may have is void and has
1423no effect on the meaning of this License.
1424
1425
1426\begin{center}
1427{\Large\bf 2. VERBATIM COPYING}
1428\end{center}
1429
1430You may copy and distribute the Document in any medium, either
1431commercially or noncommercially, provided that this License, the
1432copyright notices, and the license notice saying this License applies
1433to the Document are reproduced in all copies, and that you add no other
1434conditions whatsoever to those of this License.  You may not use
1435technical measures to obstruct or control the reading or further
1436copying of the copies you make or distribute.  However, you may accept
1437compensation in exchange for copies.  If you distribute a large enough
1438number of copies you must also follow the conditions in section 3.
1439
1440You may also lend copies, under the same conditions stated above, and
1441you may publicly display copies.
1442
1443
1444\begin{center}
1445{\Large\bf 3. COPYING IN QUANTITY}
1446\end{center}
1447
1448
1449If you publish printed copies (or copies in media that commonly have
1450printed covers) of the Document, numbering more than 100, and the
1451Document's license notice requires Cover Texts, you must enclose the
1452copies in covers that carry, clearly and legibly, all these Cover
1453Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1454the back cover.  Both covers must also clearly and legibly identify
1455you as the publisher of these copies.  The front cover must present
1456the full title with all words of the title equally prominent and
1457visible.  You may add other material on the covers in addition.
1458Copying with changes limited to the covers, as long as they preserve
1459the title of the Document and satisfy these conditions, can be treated
1460as verbatim copying in other respects.
1461
1462If the required texts for either cover are too voluminous to fit
1463legibly, you should put the first ones listed (as many as fit
1464reasonably) on the actual cover, and continue the rest onto adjacent
1465pages.
1466
1467If you publish or distribute Opaque copies of the Document numbering
1468more than 100, you must either include a machine-readable Transparent
1469copy along with each Opaque copy, or state in or with each Opaque copy
1470a computer-network location from which the general network-using
1471public has access to download using public-standard network protocols
1472a complete Transparent copy of the Document, free of added material.
1473If you use the latter option, you must take reasonably prudent steps,
1474when you begin distribution of Opaque copies in quantity, to ensure
1475that this Transparent copy will remain thus accessible at the stated
1476location until at least one year after the last time you distribute an
1477Opaque copy (directly or through your agents or retailers) of that
1478edition to the public.
1479
1480It is requested, but not required, that you contact the authors of the
1481Document well before redistributing any large number of copies, to give
1482them a chance to provide you with an updated version of the Document.
1483
1484
1485\begin{center}
1486{\Large\bf 4. MODIFICATIONS}
1487\end{center}
1488
1489You may copy and distribute a Modified Version of the Document under
1490the conditions of sections 2 and 3 above, provided that you release
1491the Modified Version under precisely this License, with the Modified
1492Version filling the role of the Document, thus licensing distribution
1493and modification of the Modified Version to whoever possesses a copy
1494of it.  In addition, you must do these things in the Modified Version:
1495
1496\begin{itemize}
1497\item[A.] 
1498   Use in the Title Page (and on the covers, if any) a title distinct
1499   from that of the Document, and from those of previous versions
1500   (which should, if there were any, be listed in the History section
1501   of the Document).  You may use the same title as a previous version
1502   if the original publisher of that version gives permission.
1503   
1504\item[B.]
1505   List on the Title Page, as authors, one or more persons or entities
1506   responsible for authorship of the modifications in the Modified
1507   Version, together with at least five of the principal authors of the
1508   Document (all of its principal authors, if it has fewer than five),
1509   unless they release you from this requirement.
1510   
1511\item[C.]
1512   State on the Title page the name of the publisher of the
1513   Modified Version, as the publisher.
1514   
1515\item[D.]
1516   Preserve all the copyright notices of the Document.
1517   
1518\item[E.]
1519   Add an appropriate copyright notice for your modifications
1520   adjacent to the other copyright notices.
1521   
1522\item[F.]
1523   Include, immediately after the copyright notices, a license notice
1524   giving the public permission to use the Modified Version under the
1525   terms of this License, in the form shown in the Addendum below.
1526   
1527\item[G.]
1528   Preserve in that license notice the full lists of Invariant Sections
1529   and required Cover Texts given in the Document's license notice.
1530   
1531\item[H.]
1532   Include an unaltered copy of this License.
1533   
1534\item[I.]
1535   Preserve the section Entitled "History", Preserve its Title, and add
1536   to it an item stating at least the title, year, new authors, and
1537   publisher of the Modified Version as given on the Title Page.  If
1538   there is no section Entitled "History" in the Document, create one
1539   stating the title, year, authors, and publisher of the Document as
1540   given on its Title Page, then add an item describing the Modified
1541   Version as stated in the previous sentence.
1542   
1543\item[J.]
1544   Preserve the network location, if any, given in the Document for
1545   public access to a Transparent copy of the Document, and likewise
1546   the network locations given in the Document for previous versions
1547   it was based on.  These may be placed in the "History" section.
1548   You may omit a network location for a work that was published at
1549   least four years before the Document itself, or if the original
1550   publisher of the version it refers to gives permission.
1551   
1552\item[K.]
1553   For any section Entitled "Acknowledgements" or "Dedications",
1554   Preserve the Title of the section, and preserve in the section all
1555   the substance and tone of each of the contributor acknowledgements
1556   and/or dedications given therein.
1557   
1558\item[L.]
1559   Preserve all the Invariant Sections of the Document,
1560   unaltered in their text and in their titles.  Section numbers
1561   or the equivalent are not considered part of the section titles.
1562   
1563\item[M.]
1564   Delete any section Entitled "Endorsements".  Such a section
1565   may not be included in the Modified Version.
1566   
1567\item[N.]
1568   Do not retitle any existing section to be Entitled "Endorsements"
1569   or to conflict in title with any Invariant Section.
1570   
1571\item[O.]
1572   Preserve any Warranty Disclaimers.
1573\end{itemize}
1574
1575If the Modified Version includes new front-matter sections or
1576appendices that qualify as Secondary Sections and contain no material
1577copied from the Document, you may at your option designate some or all
1578of these sections as invariant.  To do this, add their titles to the
1579list of Invariant Sections in the Modified Version's license notice.
1580These titles must be distinct from any other section titles.
1581
1582You may add a section Entitled "Endorsements", provided it contains
1583nothing but endorsements of your Modified Version by various
1584parties--for example, statements of peer review or that the text has
1585been approved by an organization as the authoritative definition of a
1586standard.
1587
1588You may add a passage of up to five words as a Front-Cover Text, and a
1589passage of up to 25 words as a Back-Cover Text, to the end of the list
1590of Cover Texts in the Modified Version.  Only one passage of
1591Front-Cover Text and one of Back-Cover Text may be added by (or
1592through arrangements made by) any one entity.  If the Document already
1593includes a cover text for the same cover, previously added by you or
1594by arrangement made by the same entity you are acting on behalf of,
1595you may not add another; but you may replace the old one, on explicit
1596permission from the previous publisher that added the old one.
1597
1598The author(s) and publisher(s) of the Document do not by this License
1599give permission to use their names for publicity for or to assert or
1600imply endorsement of any Modified Version.
1601
1602
1603\begin{center}
1604{\Large\bf 5. COMBINING DOCUMENTS}
1605\end{center}
1606
1607
1608You may combine the Document with other documents released under this
1609License, under the terms defined in section 4 above for modified
1610versions, provided that you include in the combination all of the
1611Invariant Sections of all of the original documents, unmodified, and
1612list them all as Invariant Sections of your combined work in its
1613license notice, and that you preserve all their Warranty Disclaimers.
1614
1615The combined work need only contain one copy of this License, and
1616multiple identical Invariant Sections may be replaced with a single
1617copy.  If there are multiple Invariant Sections with the same name but
1618different contents, make the title of each such section unique by
1619adding at the end of it, in parentheses, the name of the original
1620author or publisher of that section if known, or else a unique number.
1621Make the same adjustment to the section titles in the list of
1622Invariant Sections in the license notice of the combined work.
1623
1624In the combination, you must combine any sections Entitled "History"
1625in the various original documents, forming one section Entitled
1626"History"; likewise combine any sections Entitled "Acknowledgements",
1627and any sections Entitled "Dedications".  You must delete all sections
1628Entitled "Endorsements".
1629
1630\begin{center}
1631{\Large\bf 6. COLLECTIONS OF DOCUMENTS}
1632\end{center}
1633
1634You may make a collection consisting of the Document and other documents
1635released under this License, and replace the individual copies of this
1636License in the various documents with a single copy that is included in
1637the collection, provided that you follow the rules of this License for
1638verbatim copying of each of the documents in all other respects.
1639
1640You may extract a single document from such a collection, and distribute
1641it individually under this License, provided you insert a copy of this
1642License into the extracted document, and follow this License in all
1643other respects regarding verbatim copying of that document.
1644
1645
1646\begin{center}
1647{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS}
1648\end{center}
1649
1650
1651A compilation of the Document or its derivatives with other separate
1652and independent documents or works, in or on a volume of a storage or
1653distribution medium, is called an "aggregate" if the copyright
1654resulting from the compilation is not used to limit the legal rights
1655of the compilation's users beyond what the individual works permit.
1656When the Document is included in an aggregate, this License does not
1657apply to the other works in the aggregate which are not themselves
1658derivative works of the Document.
1659
1660If the Cover Text requirement of section 3 is applicable to these
1661copies of the Document, then if the Document is less than one half of
1662the entire aggregate, the Document's Cover Texts may be placed on
1663covers that bracket the Document within the aggregate, or the
1664electronic equivalent of covers if the Document is in electronic form.
1665Otherwise they must appear on printed covers that bracket the whole
1666aggregate.
1667
1668
1669\begin{center}
1670{\Large\bf 8. TRANSLATION}
1671\end{center}
1672
1673
1674Translation is considered a kind of modification, so you may
1675distribute translations of the Document under the terms of section 4.
1676Replacing Invariant Sections with translations requires special
1677permission from their copyright holders, but you may include
1678translations of some or all Invariant Sections in addition to the
1679original versions of these Invariant Sections.  You may include a
1680translation of this License, and all the license notices in the
1681Document, and any Warranty Disclaimers, provided that you also include
1682the original English version of this License and the original versions
1683of those notices and disclaimers.  In case of a disagreement between
1684the translation and the original version of this License or a notice
1685or disclaimer, the original version will prevail.
1686
1687If a section in the Document is Entitled "Acknowledgements",
1688"Dedications", or "History", the requirement (section 4) to Preserve
1689its Title (section 1) will typically require changing the actual
1690title.
1691
1692
1693\begin{center}
1694{\Large\bf 9. TERMINATION}
1695\end{center}
1696
1697
1698You may not copy, modify, sublicense, or distribute the Document except
1699as expressly provided for under this License.  Any other attempt to
1700copy, modify, sublicense or distribute the Document is void, and will
1701automatically terminate your rights under this License.  However,
1702parties who have received copies, or rights, from you under this
1703License will not have their licenses terminated so long as such
1704parties remain in full compliance.
1705
1706
1707\begin{center}
1708{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE}
1709\end{center}
1710
1711
1712The Free Software Foundation may publish new, revised versions
1713of the GNU Free Documentation License from time to time.  Such new
1714versions will be similar in spirit to the present version, but may
1715differ in detail to address new problems or concerns.  See
1716http://www.gnu.org/copyleft/.
1717
1718Each version of the License is given a distinguishing version number.
1719If the Document specifies that a particular numbered version of this
1720License "or any later version" applies to it, you have the option of
1721following the terms and conditions either of that specified version or
1722of any later version that has been published (not as a draft) by the
1723Free Software Foundation.  If the Document does not specify a version
1724number of this License, you may choose any version ever published (not
1725as a draft) by the Free Software Foundation.
1726
1727
1728%---------------------------------------------------------------------
1729\end{document}
1730
1731\end{document}
Note: See TracBrowser for help on using the repository browser.