GRASS-Wiki - User contributions [en]

GRASS and Python

2009-12-17T22:42:20Z

⚠️Glynn: /* Example */ Fix typo

''(for discussions on the new GRASS GUI, see [[GRASS GUI|here]])''

==Python SIGs==
Python Special Interest Groups are focused collaborative efforts to develop, improve, or maintain specific Python resources. Each SIG has a charter, a coordinator, a mailing list, and a directory on the Python website. SIG membership is informal, defined by subscription to the SIG's mailing list. Anyone can join a SIG, and participate in the development discussions via the SIG's mailing list. Below is the list of currently active Python SIGs, with links to their resources.

See more at http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with {{cmd|g.parser}}, as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system.
For code which needs access to the power of C, you can access the GRASS C library functions via the SWIG interface.

* GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/
* GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html

Code style: Have a look at [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_PYTHON SUBMITTING_PYTHON].

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Example ===

Example of Python script, which is processed by g.parser:

<source lang="python">
#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008,2009 by the GRASS Development Team
#
# This program is free software under the GNU General Public
# License (>=v2). Read the file COPYING that comes with GRASS
# for details.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
from grass.script import core as grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drape_map, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()
</source>

==Python extensions for GRASS GIS==
=== wxPython GUI development for GRASS ===

* See the [[GRASS GUI]] wiki page

=== GRASS Python library ===

See [http://download.osgeo.org/grass/grass6_progman/pythonlib.html GRASS Python library]

=== Python-SWIG-GRASS interface ===
There is a prototype GRASS-SWIG interface available (thanks to Sajith VK), find it in GRASS 6-CVS: '''swig/python/'''. Draft documentation is [http://download.osgeo.org/grass/grass6_progman/swig/ here]. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: [http://www.swig.org SWIG] (Simplified Wrapper and Interface Generator) is:

* A compiler that turns ANSI C/C++ declarations into scripting language interfaces.
* Completely automated (produces a fully working Python extension module).
* Language neutral. SWIG can also target Tcl, Perl, Guile, MATLAB (try PyLab+Matplotlib from python), etc...
* Attempts to eliminate the tedium of writing extension modules.

==== Python-SWIG examples ====

* Latest and greatest: [[http://trac.osgeo.org/grass/browser/grass/trunk/scripts GRASS 7 Python scripts]]

* [[PythonSwigExamples|More complicated examples]]

Sample script for GRASS 6 raster access (use within GRASS, Spearfish session):
<source lang="python">
#!/usr/bin/env python

import os, sys
from grass.lib import grass

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Raster Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_cell2(input, '')

# determine the inputmap type (CELL/FCELL/DCELL) */
data_type = grass.G_raster_map_type(input, mapset)

infd = grass.G_open_cell_old(input, mapset)
inrast = grass.G_allocate_raster_buf(data_type)

rown = 0
while True:
myrow = grass.G_get_raster_row(infd, inrast, rown, data_type)
print rown, myrow[0:10]
rown += 1
if rown == 476:
break

grass.G_close_cell(inrast)
grass.G_free(cell)
</source>

Sample script for vector access (use within GRASS, Spearfish session):

<source lang="python">
#!/usr/bin/python

# run within GRASS Spearfish session
# run this before starting python to append module search path:
# export PYTHONPATH=/usr/src/grass70/swig/python
# check with "import sys; sys.path"
# or:
# sys.path.append("/usr/src/grass70/swig/python")
# FIXME: install the grass bindings in $GISBASE/lib/ ?

import os, sys
from grass.lib import grass
from grass.lib import vector as grassvect

if "GISBASE" not in os.environ:
print "You must be in GRASS GIS to run this program."
sys.exit(1)

if len(sys.argv)==2:
input = sys.argv[1]
else:
input = raw_input("Vector Map Name? ")

# initialize
grass.G_gisinit('')

# find map in search path
mapset = grass.G_find_vector2(input,'')

# define map structure
map = grassvect.Map_info()

# define open level (level 2: topology)
grassvect.Vect_set_open_level (2)

# open existing map
grassvect.Vect_open_old(map, input, mapset)

# query
print 'Vect map: ', input
print 'Vect is 3D: ', grassvect.Vect_is_3d (map)
print 'Vect DB links: ', grassvect.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', grassvect.Vect_get_scale(map)
print 'Number of areas:', grassvect.Vect_get_num_areas(map)

# close map
grassvect.Vect_close(map)
</source>

==== TODO ====

* Implement modules support in a Python class using --interface-description and a Python-XML parser. This should be a generic class with module's name as parameter, returning back an object which describes the module (description, flags, parameters, status of not/required). See [http://trac.osgeo.org/grass/browser/grass/trunk/gui/wxpython/ GRASS 6 wxPython interface] for inspiration. Important is to auto-generate the GRASS-Python class at compile time with a Python script.

=== Python-GRASS add-ons ===

Stand-alone addons:

# Jáchym Čepický's G-ps.map, a GUI to typeset printable maps with ps.map (http://193.84.38.2/~jachym/index.py?cat=gpsmap)
# Jáchym Čepický's v.pydigit, a GUI to v.edit (http://les-ejk.cz/?cat=vpydigit)
# Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

=== Using GRASS gui.tcl in Python ===

Here is some example code to use the grass automatically generated guis in python code. This could (should) all be bundled up and abstracted away so that the implementation can be replaced later.

<source lang="python">
import Tkinter
import os

# Startup (once):

tk = Tkinter.Tk()
tk.eval ("wm withdraw .")
tk.eval ("source $env(GISBASE)/etc/gui.tcl")
# Here you could do various things to change what the gui does
# See gui.tcl and README.GUI

# Make a gui (per dialog)
# This sets up a window for the command.
# This can be different to integrate with tkinter:
tk.eval ('set path ".dialog$dlg"')
tk.eval ('toplevel .dialog$dlg')
# Load the code for this command:
fd = os.popen ("d.vect --tcltk")
gui = fd.read()
# Run it
tk.eval(gui)
dlg = tk.eval('set dlg') # This is used later to get and set

# Get the current command in the gui we just made:
currentcommand = tk.eval ("dialog_get_command " + dlg)

# Set the command in the dialog we just made:
tk.eval ("dialog_set_command " + dlg + " {d.vect map=roads}")
</source>

== Links ==

=== General guides ===

* [http://en.wikibooks.org/wiki/Python_Programming/ Wikibook Python Programming]
* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers
* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]

=== Programming ===

* Python and GRASS:
** GRASS Python interface to library functions: http://download.osgeo.org/grass/grass6_progman/swig/ based on SWIG http://www.swig.org/
** GRASS Python scripting library: http://download.osgeo.org/grass/grass6_progman/pythonlib.html
** PyWPS, GRASS-Web Processing Service http://pywps.wald.intevation.org

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* Python and GIS:
** [http://gispython.org/ Open Source GIS-Python Laboratory]

* Python and Statistics:
** [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* Bindings:
** SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
** [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006

[[Category:Development]]
[[Category:Linking to other languages]]
[[Category:Python]]

WinGRASS 6 Current Status

2008-10-19T21:23:05Z

⚠️Glynn: /* Won't fix (at least not immediately) */ Status update

__TOC__

See also '''[http://trac.osgeo.org/grass/wiki/BuildingOnWindows http://trac.osgeo.org/grass/wiki/BuildingOnWindows]'''

This page describes the current status of winGRASS development:
* Precompiled winGRASS/Cygwin packages are available for [http://grass.itc.it/grass63/binary/mswindows/cygwin/ GRASS 6.3],
* native winGRASS packages [http://geog-pc40.ulb.ac.be/grass/wingrass/ GRASS 6.3],
* and the last native winGRASS [http://download.osgeo.org/grass/grass63/binary/mswindows/ Self Contained Package].

== Current status - Summary ==

The native windows port of GRASS is slowly coming to a stage where it can be considered beta status. All main functions seem to work, but much more testing is needed. The port is of the current cvs branch GRASS 6.3. There are no ports of earlier versions.

The general idea is to reach a point where GRASS runs in Windows without any kind of unix emulation. Currently, this is possible, but limits the use to compiled modules as scripts are all of unix-shell type and cannot run within a Windows cmd.exe environment without a series of unix tools such as a shell, awk, sed, etc. So in order to run such scripts a collection of unix-like tools needs to be installed, such as Msys or Gnuwin32+Shell.

Another major feature not available in the windows version are the old-style interactive X monitors (i.e. the x0, PNG, PS, Cairo, etc, monitors opened with '<tt>d.mon x0</tt>'). Only direct rendering works currently. Display is thus "limited" to the Tcl/Tk and wxPython GUIs (the latter might still need some cleanup of unix-specific code). Modules like i.points and d.zoom will not work (see [[#Known_Issues]]).

== Installing binary snapshots ==

Regular binary snapshots for windows are available [http://geog-pc40.ulb.ac.be/grass/wingrass/ here]. To install them, just download and unzip. In order to be able to use the graphical user interface, you also have to download and install [http://www.activestate.com/products/activetcl/ ActiveState Tcl].

You can then launch the GRASS GUI by clicking on the grass63.bat which is in c:\grass\bin\ (or wherever you unzipped the package). This should launch the GUI which gives you access to all GRASS modules.

If you like the command line, you can launch Windows' cmd.exe via Start->Run->cmd.exe. Then type 'c:\grass\bin\grass63.bat -text' to launch grass without the GUI. If you want to access the GUI at a later stage, just type 'gis.m'.

If you want to have access to shell scripts, you also have to install [http://sourceforge.net/project/downloading.php?groupname=mingw&filename=MSYS-1.0.11-2004.04.30-1.exe Msys] and then adapt the grass63.bat script according to the examples in the file.

== Compiling by yourself ==

(based on work from Paul Kelly - [http://lists.osgeo.org/pipermail/grass-dev/2006-December/028097.html his message])

... or see new [http://www.webalice.it/marco.pasetti/grass/BuildFromSource.html GRASS Windows Native Binary Building Guide]

=== Requirements ===

* To compile winGRASS natively, you need the following additional libraries: ''libpng, PROJ.4, GDAL, Zlib, XDR''. They are available in a gzipped tar file (to get started quickly): http://www.stjohnspoint.co.uk/grass/ (get wingrass-extralibs.tar.gz).
* Additionally, you need [http://www.mingw.org/download.shtml Msys & MingW] (current version)
* [http://www.mingw.org/MinGWiki/index.php/bison bison]
* [http://www.mingw.org/MinGWiki/index.php/flex flex]

Decompressing bison and flex in the root msys directory should position the files in the correct directories.

'''Optionally:'''
* Freetype
* FFTW
* PDCurses

''TODO: is PDCurses really optionally?''

=== Configuration and compilation ===

The prefix where you untar that file you will need to supply to the GRASS configure as:

--with-includes=prefix --with-libs=prefix

Before compilation, you need to set your path in msys in order to add the path to the lib/ and bin/ directories of Paul's tarball before compiling. You might also need to edit the first few lines of the gdal-config script in the bin/ directory, to reflect the path where it is actually installed.

You also have to erase $(MANDIR) $(MANPAGES) from line 13 of man/Makefile, i.e. 'default: $(MANDIR) $(MANPAGES)' -> 'default:'.

If you get an error such as 'cannot open file `/msys/share/bison/m4sugar/m4sugar.m4': No such file or directory', one solution is to move around the msys bison installation a bit, so that m4sugar.m4 is available in the indicated path.

A working configure line is:
./configure --prefix=c:/grass --bindir=c:/grass/bin \
--with-includes=/c/grass/forgrass/include \
--with-libs=/c/grass/forgrass/lib --with-cxx --without-jpeg --without-tiff \
--without-postgres --with-opengl=windows --without-fftw --without-x \
--enable-shared=yes --with-tcltk-includes=/c/tcl/include \
--with-tcltk-libs=/c/tcl/bin

The configure line used for the current binary snapshots can be seen [http://geog-pc40.ulb.ac.be/grass/wingrass/winconfig.log here].

Compile with make.

After compiling you should copy libxdr.dll, libproj.dll, libpng.dll, libgdal-1.dll and libz.dll.1.2.3 into the GRASS lib directory and all the GDAL and PROJ .exe files in the bin directory into the GRASS bin directory, and then you have a more or less self-contained GRASS distribution.

For the GUI, including for displaying anything, you need to install [http://www.activestate.com/downloads/ Activestate Tcl/Tk] 8.4.13 (in c:\tcl).

=== Nullsoft installer ===

See http://trac.osgeo.org/grass/browser/grass/branches/develbranch_6/mswindows

[[Image:Wingrass63 installer1.jpg|220px|New winGRASS installer 1]]
[[Image:Wingrass63 installer2.jpg|220px|New winGRASS installer 2]]
[[Image:Wingrass63 installer3.jpg|220px|New winGRASS installer 3]]

== Known Issues ==

See also [http://www.nabble.com/forum/Search.jtp?query=wingrass&sort=date&local=y&forum=1200 GRASS Mailing list archives] and the compilation error log [http://geog-pc40.ulb.ac.be/grass/wingrass/winmakeerror.log here].

=== Won't fix (at least not immediately) ===

Issues listed here are rather impossible to fix due to the different nature of native Windows. Or, lend us a hand and let's try harder!

* No monitors

This means that you cannot launch any monitor launched with d.mon (x0, PNG, PS, etc). The only way you can render is directly to a file. But you cannot directly display to screen from the command line. This will be solved in GRASS 7 with a new rendering system and possibly via the new wxgrass GUI. So no work will probably be put into this until then.

The absence of monitors also makes impossible the use of interactive modules based on these monitors, such as:

** i.class
** i.ortho.photo/photo.2image
** i.ortho.photo/photo.2target
** i.points
** i.vpoints

i.points and i.vpoints have already been replaced by the gis.m georectifier module (File -> Georectify). In replacement of i.class you can digitize training areas with v.digit. This will not however, give you all the information i.class provides, such as the histogram of the region, the statistics and the display of matches. These modules will have to be rewritten to clearly separate display and backend parts, so that the backend can be run on the command line or from any GUI frontend. '''Volunteers needed.'''

Another module affected is d.vect.thematic which uses monitors. This will hopefully be replaced by a C-version in a not too far future.

* Scripts need *nix-like shell

All current GRASS scripts are written in shell language. This means they need a shell, and several related tools (awk, sed, etc), to function. This means that whoever wants to be able to run these scripts has to install a shell with these tools. Currently recommended is [http://sourceforge.net/project/downloading.php?groupname=mingw&filename=MSYS-1.0.11-2004.04.30-1.exe Msys] as this is a simple install of a package containing everything which is needed.

In 7.0, these scripts have been rewritten in Python, thus totally eliminating the need for any shell.

=== Platform specific issues ===

==== XP/2000 ====
nothing known specifically related to MS Windows XP/2000

==== Vista ====

* sometimes r.patch fails: http://trac.osgeo.org/grass/ticket/118
* ...

=== ToDo ===

==== Installer ====

* <strike>change the Uninstall icon</strike>
* <strike>fix the language errors in the StartMenu link's descriptions</strike>
* <strike>change the name of the South-Dakota sample database to Spearfish60</strike>
* <strike>add a GRASS Command Line link (cmd.exe) into the GRASS StartMenu group</strike>
* create a GRASS Addons installer or integrate the GRASS Addons in the current installer as downloadable options

==== Dependencies ====

===== GRASS Dependencies =====

* <strike>add the Indipendent JPEG support to GRASS *</strike>
* add the FFMPEG support in GRASS (reports an error in building OGSF library; probably needs to specify -lavutil in gcc command) ***
* add the NLS support in GRASS (needs gettext)
* add the wxWidgets support in GRASS (for the wxPython GUI v.digit replacement)

===== GDAL Dependencies =====

* add the ECW support in GDAL */**
* add the JPEG2000 support in GDAL (through Jasper or Kadaku *) **
* add the OGDI support in GDAL *
* add the MrSID support in GDAL */**

===== GRASS and GDAL Dependencies =====

* add the Xerces support in both GDAL and GRASS *
* add the ODBC support in both GDAL and GRASS */**
* add the MySQL support in both GDAL and GRASS */**

===== Miscellaneus Dependencies =====

* add the OpenSSL support in both PostgreSQL and SQLite *
* <strike>add the AVCE00 tools (build from source in minGW)</strike>
* <strike>add the E00compr tools (build from source in minGW)</strike>
* <strike>add the GPSBabel tool (use prebuilt binaries from GPSBabel Web Site)</strike>

<br>
<nowiki>*</nowiki> needs to build related libraries from source in MinGW
<br>
<nowiki>**</nowiki> needs to check the licences first
<br>
<nowiki>***</nowiki> FFMPEG has been already succesfully built on MinGW

==== Internal Libraries ====

* parser: find out why launching a module from the command line without parameters does not call module GUI

==== Vector modules ====

* v.in.ascii crashes on files with irregular line length (see [http://lists.osgeo.org/pipermail/grass-dev/2008-February/035268.html this thread])

==== Raster modules ====
* <strike>r.terraflow does not compile</strike> fix backported 27/3/2008
: This seems to be due to the use of the function getrusage() which is not supported under MinGW. Check this octave patch [http://osdir.com/ml/gnu.octave.maintainers/2006-03/msg00083.html email thread].

==== Other modules ====
* r.li moduels do not compile
: --HB: ''why not? what's the error?''

==== GRASS Addons ====
* compile the GRASS Addons

==== TclTk issues ====

* var=val style argument is not valid for batch files: equal sign is a separator like a space. http://support.microsoft.com/?kbid=71247 http://www.gatago.com/alt/msdos/batch/17358926.html
** Could you give an example of where this is a problem ?
* file command returns bad code (catch is needed): http://sources.redhat.com/ml/insight/2003-q1/msg00079.html
** catch {file copy}
** catch {file delete}
** catch {file rename -force} does not work. Delete old file first: catch {file delete}; catch {file rename}
** exec a batch file doing redirection (>&2, 2>&1)
* no -permissions file attributes
** catch {file attributes -permissions}

==== Miscellaneous ====

* metacharacter escape in "sh -c '$cmd'"
* modules not working: <strike>v.neighbors, v.kernel, r.cost</strike>
* <strike>Cannot open Help pages.</strike>
* Have to type "exit" in the console to save ~/.grassrc file. Then, close gis.m to finish the session.
* A previous installation of grass under cygwin is likely to cause problems with WinGrass. Follow the directions to remove cygwin at http://cygwin.com/faq/faq-nochunks.html#faq.setup.uninstall-all

The following items cannot be fixed in the near future:
** can't read "_data(.gronsole.gronsole,4,donecmd)": no such element in array error
*** Could you be more precise about this error ? When does it occur ?

== Dealing with shell scripts or .bat files ==

Bourne shell scripts require MSys (or some other Bourne shell), but you don't need to start GRASS from MSys.

The main issue with scripts is that Windows doesn't understand the "#!" notation used to specify the interpreter.

All of the supplied scripts in $GISBASE/scripts have a corresponding .bat file in $GISBASE/bin which invokes script via %GRASS_SH%. This allows you to run those scripts from the Windows command prompt.

If you write scripts of your own, you need to either add a corresponding .bat file, or give the script a .sh extension and associate that with the shell, e.g. via the ftype and assoc commands. You can use the PATHEXT variable to eliminate the need to type the extension.

== Other libraries ==

GDAL
* lib/gis/OBJ.*/fmode.o is needed for any GRASS related modules.
* modified ltmain.sh to install binary files from wrapper scripts.
* see also [http://trac.osgeo.org/gdal/wiki/BuildingWithMinGW GDAL Building With MinGW]

== Related efforts ==

* http://wiki.osgeo.org/index.php/OSGeo_Win32_Installer

[[Category: Development]]

GRASS and Python

2008-10-08T12:26:05Z

⚠️Glynn: Replace example script with real-world case (d.shadedmap) using "grass" module

''(for discussions on the new GRASS GUI, see [[GRASS GUI|here]])''

==Python SIGs==
Python Special Interest Groups are focused collaborative efforts to develop, improve, or maintain specific Python resources. Each SIG has a charter, a coordinator, a mailing list, and a directory on the Python website. SIG membership is informal, defined by subscription to the SIG's mailing list. Anyone can join a SIG, and participate in the development discussions via the SIG's mailing list. Below is the list of currently active Python SIGs, with links to their resources.

See more at http://www.python.org/community/sigs/

==Writing Python scripts in GRASS==

Python is a programming language which is more powerful than shell scripting but easier and more forgiving than C.
The Python script can contain simple module description definitions which will be processed with [http://grass.ibiblio.org/grass63/manuals/html63_user/g.parser.html g.parser], as shown in the example below. In this way with no extra coding a GUI can be built, inputs checked, and a skeleton help page can be generated automatically. In addition it adds links to the GRASS message translation system.
For code which needs access to the power of C, you can access the GRASS C library functions via the SWIG interface.

Have a look at [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_PYTHON SUBMITTING_PYTHON].

=== Running external commands from Python ===
For information on running external commands from Python, see:
http://docs.python.org/lib/module-subprocess.html

Avoid using the older os.* functions. Section 17.1.3 lists equivalents
using the Popen() interface, which is more robust (particularly on
Windows).

=== Example ===

Example of Python script, which is processed by g.parser:

#!/usr/bin/env python
#
############################################################################
#
# MODULE: d.shadedmap
# AUTHOR(S): Unknown; updated to GRASS 5.7 by Michael Barton
# Converted to Python by Glynn Clements
# PURPOSE: Uses d.his to drape a color raster over a shaded relief map
# COPYRIGHT: (C) 2004,2008 by the GRASS Development Team
#
# This program is free software under the GNU General Public
# License (>=v2). Read the file COPYING that comes with GRASS
# for details.
#
#############################################################################

#%Module
#% description: Drapes a color raster over a shaded relief map using d.his
#%End
#%option
#% key: reliefmap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of shaded relief or aspect map
#% required : yes
#%end
#%option
#% key: drapemap
#% type: string
#% gisprompt: old,cell,raster
#% description: Name of raster to drape over relief map
#% required : yes
#%end
#%option
#% key: brighten
#% type: integer
#% description: Percent to brighten
#% options: -99-99
#% answer: 0
#%end

import sys
import grass

def main():
drape_map = options['drapemap']
relief_map = options['reliefmap']
brighten = options['brighten']
ret = grass.run_command("d.his", h_map = drapemap, i_map = relief_map, brighten = brighten)
sys.exit(ret)

if __name__ == "__main__":
options, flags = grass.parser()
main()

==Python extensions for GRASS GIS==
=== wxPython GUI development for GRASS ===

* See the [[GRASS GUI]] wiki page

=== Python-SWIG-GRASS interface ===
There is a prototype GRASS-SWIG interface available (thanks to Sajith VK), find it in GRASS 6-CVS: '''swig/python/'''. Draft documentation is [http://mpa.itc.it/markus/grass63progman/swig/ here]. It now wraps both raster and vector data C functions plus the general GIS (G_*()) functions.

Background: [http://www.swig.org SWIG] (Simplified Wrapper and Interface Generator) is:

* A compiler that turns ANSI C/C++ declarations into scripting language interfaces.
* Completely automated (produces a fully working Python extension module).
* Language neutral. SWIG can also target Tcl, Perl, Guile, MATLAB (try PyLab+Matplotlib from python), etc...
* Attempts to eliminate the tedium of writing extension modules.

==== Python-SWIG examples ====

* [[PythonSwigExamples|More complicated examples]]

Sample script for raster access (use within GRASS, Spearfish session):
#!/usr/bin/python
import python_grass6 as g6lib

input = 'roads'
mapset = 'PERMANENT'

# initialize
g6lib.G_gisinit(<nowiki>''</nowiki>)
infd = g6lib.G_open_cell_old(input, mapset)
cell = g6lib.G_allocate_cell_buf()

rown=0
# the API still needs error checking to be added
while 1:
myrow = g6lib.G_get_map_row_nomask(infd, cell, rown)
print rown,myrow[0:10]
rown = rown+1
if rown==476:break

g6lib.G_close_cell(infd)
g6lib.G_free(cell)

Sample script for vector access (use within GRASS, Spearfish session):
#!/usr/bin/python
import python_grass6 as g6lib

input = 'soils'
mapset = 'PERMANENT'

# initialize
g6lib.G_gisinit(<nowiki>''</nowiki>)

# define map structure
map = g6lib.Map_info()

# define open level (level 2: topology)
g6lib.Vect_set_open_level (2)

# open existing map
g6lib.Vect_open_old(map, input, mapset)

# query
print 'Vect is 3D: ', g6lib.Vect_is_3d (map)
print 'Vect DB links: ', g6lib.Vect_get_num_dblinks(map)
print 'Map Scale: 1:', g6lib.Vect_get_scale(map)

# close map
g6lib.Vect_close(map)

==== TODO ====

* Implement modules support in a Python class using --interface-description and a Python-XML parser. This should be a generic class with module's name as parameter, returning back an object which describes the module (description, flags, parameters, status of not/required). See [http://freegis.org/cgi-bin/viewcvs.cgi/grass6/gui/wxpython/ GRASS 6 wxPython interface] for inspiration. Important is to auto-generate the GRASS-Python class at compile time with a Python script.

=== Python-GRASS add-ons ===

Stand-alone addons:

# Jáchym Čepický's G-ps.map, a GUI to typeset printable maps with ps.map (http://193.84.38.2/~jachym/index.py?cat=gpsmap)
# Jáchym Čepický's v.pydigit, a GUI to v.edit (http://les-ejk.cz/?cat=vpydigit)
# Jáchym Čepický's PyWPS, GRASS-Web Processing Service (http://pywps.wald.intevation.org)

=== Using Grass gui.tcl in python ===

Here is some example code to use the grass automatically generated guis in python code. This could (should) all be bundled up and abstracted away so that the implementation can be replaced later.

import Tkinter
import os

# Startup (once):

tk = Tkinter.Tk()
tk.eval ("wm withdraw .")
tk.eval ("source $env(GISBASE)/etc/gui.tcl")
# Here you could do various things to change what the gui does
# See gui.tcl and README.GUI

# Make a gui (per dialog)
# This sets up a window for the command.
# This can be different to integrate with tkinter:
tk.eval ('set path ".dialog$dlg"')
tk.eval ('toplevel .dialog$dlg')
# Load the code for this command:
fd = os.popen ("d.vect --tcltk")
gui = fd.read()
# Run it
tk.eval(gui)
dlg = tk.eval('set dlg') # This is used later to get and set

# Get the current command in the gui we just made:
currentcommand = tk.eval ("dialog_get_command " + dlg)

# Set the command in the dialog we just made:
tk.eval ("dialog_set_command " + dlg + " {d.vect map=roads}")

== Links ==

=== Programming ===

* [http://www.poromenos.org/tutorials/python Quick Python tutorial] for programmers of other languages
: [http://wiki.python.org/moin/BeginnersGuide/Programmers More Python tutorials] for programmers

* [http://www.python.org/dev/peps/pep-0008/ Python programming style guide]

* GRASS-SWIG interface http://download.osgeo.org/grass/grass6_progman/swig/ based on SWIG http://www.swig.org/

* PyWPS, GRASS-Web Processing Service http://pywps.wald.intevation.org

* SIP (C/C++ bindings generator) http://directory.fsf.org/all/Python-SIP.html
* [http://www.cython.org/ Cython] - C-Extensions for Python (compile where speed is needed)

* Python and OSGeo:
** [http://wiki.osgeo.org/wiki/OSGeo_Python_Library OSGeo Python Library]

* Python and GDAL/OGR:
** [http://mapserver.gis.umn.edu/community/conferences/MUM3/workshop/python Open Source Python GIS Hacks Mum'03]
** http://hobu.biz/software/OSGIS_Hacks - Python OSGIS Hacks '05
** http://zcologia.com/news/categorylist_html?cat_id=8
** http://www.perrygeo.net/wordpress/?p=4

* Python bindings to PROJ:
** http://www.cdc.noaa.gov/people/jeffrey.s.whitaker/python/pyproj.html

* [http://rpy.sourceforge.net/ RPy] - Python interface to the R-statistics programming language

* [http://gispython.org/ Open Source GIS-Python Laboratory]

* Other external projects
** [http://www.scipy.org Scientific Python]
** [http://wiki.python.org/moin/NumericAndScientific Numeric and Scientific]
** [http://w3.pppl.gov/~hammett/comp/python/python.html Info on Python for Scientific Applications]

=== Presentations ===

From FOSS4G2006:
* [http://www.foss4g2006.org/materialDisplay.py?contribId=136&sessionId=48&materialId=slides&confId=1 A Python sweeps in the GRASS] - A. Frigeri 2006
* [http://www.foss4g2006.org/materialDisplay.py?contribId=67&sessionId=48&materialId=slides&confId=1 GRASS goes web: PyWPS] - J. Cepicky 2006

[[Category:Development]]
[[Category:Linking to other languages]]
[[Category:Python]]

Replacement raster format

2008-10-04T07:43:18Z

⚠️Glynn: Disadvantages of tiled storage

{{MoveToTrac}}
GRASS's long-standing raster format is overdue for a major overhaul.<BR>
Below you will find some ideas and roadmaps for future work.<BR>
The idea of this page is to collect ideas and flesh out a
specification so that when the change occurs, all the
components will be in place, pitfalls expected, and
the implimentation, when it comes, quick and painless. Most
importanly it can serve to keep interested parties informed
and working together instead of in parallel forks.<BR>
Any changes to the data format will necessitate a bump in
major version number (i.e. from GRASS 6 to GRASS 7) so if
possible changes should happen in the same development cycle,
and relatively minor changes should be held back in
experimental status until a major change is committed.

__TOC__

see also [[GRASS 7 ideas collection#Raster]]

==== Core raster format ====
''Lead developer: Glynn Clements''

* Storage in tiles instead of by row.
** Reasoning: Glynn said on the mailing list: "In most cases, single-level tiled storage will give you close to the same performance with a lot less complexity."
** Function needed to check whether tiles are all null, or all the same value.
** What tile size should be used? Could be user/program specified, or standard value of something like 64x64. If there isn't a fixed value then there should be utility program that can convert tiled rasters to different tile sizes. -
*** However, row-oriented storage has the advantage that you can easily skip entire rows when downsampling. Using e.g. 64x1 "tiles" would provide both optimisations, but at the expense of reduced compression, as you need a pointer (8 bytes) for each tile, and the compression has to be restarted for each tile.
[[User:Ferrouswheel|Ferrouswheel]]
* Merge NULL file into main data array.

==== Directory structure ====

* Centralize map components in "<tt>$MAPSET/raster/$MAPNAME/*</tt>" instead of many "<tt>$MAPSET/cell/$MAPNAME</tt>", etc. directories.

Many library functions and modules will need to be updated.
The GRASS 6 vector format has already been ported to this structure.

* demo 2-way conversion scripts: [http://wald.intevation.org/tracker/index.php?func=detail&aid=372&group_id=21&atid=205 Gforge patch #372]

==== Meta-data support ====

The existing raster meta-data handling is rather weak.
(currently stored in <tt>$MAPSET/hist/$MAPNAME</tt>)
Total replacement will be the best option.

Brad Douglas suggests:
''It would be very advantageous to at least support metadata as specified
in [http://www.fgdc.gov/standards/projects/FGDC-standards-projects/csdgm_rs_ex/MetadataRemoteSensingExtens.pdf FGDC-STD-012-2002].
XML is an ideal file format.''

Nick Lawrence suggests:
The GIMP project is examining the concept of a general mult-layer bitmap format.

[http://create.freedesktop.org/wiki/index.php/General_multilayered_bitmap_exchange_format OpenRaster - Create Wiki]
[http://pippin.gimp.org/OpenRaster/ OpenRaster Sandbox]

==== Recent discussions ====

* http://www.nabble.com/-GRASS5--Raster-files-suggestion%3A-new-directory-layout-td8588651.html
* http://lists.osgeo.org/pipermail/grass-dev/2008-April/036994.html
* http://lists.osgeo.org/pipermail/grass-dev/2008-April/037578.html

Other suggestions:
* [[Time series in GRASS]] support

[[Category:Development]]

GRASS 7 ideas collection

2008-10-04T07:33:39Z

⚠️Glynn: Problems with allowing write access to other users' mapsets

{{MoveToTrac}}
== Maintenance of repository ==

For grass7 development will be used svn-trunk, for grass6 development is used separated branch [https://svn.osgeo.org/grass/grass/branches/develbranch_6 develbranch_6].

Planning is continued here: http://trac.osgeo.org/grass/wiki/Grass7Planning

== Terminology ==

See [[GRASS 7 Terminology]].

== API to access algorithms in modules ==

We need to better expose the "knowledge" which is contained at module level. We want to have it accessible via API, exposed in various programming languages such as C, Python, Perl, Java, ..

== Raster ==

See also [[Replacement raster format]]

=== Library ===
* allowing nulls to be embedded
* Split libgis into G_() part and Rast_() part
* Rewrite library from scratch. See [http://grass.itc.it/pipermail/grass-dev/2006-August/025025.html suggestions]
* Insert 'vertical' 2d rasters (e.g. [http://woodshole.er.usgs.gov/project-pages/longislandsound/images/Ghist_square2.jpg geophysical survey data])
* <strike>[http://freegis.org/cgi-bin/viewcvs.cgi/grass/gips/gip-0002.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup GRASS raster "live links" via GDAL]</strike>

=== Modules ===

==== rename ====
* rename r.in.gdal to r.import
* rename r.out.gdal to r.export
* rename r.volume 'data' parameter to something more standard like 'input' or 'map'

==== remove ====
* Remove r.bitpattern since r.mapcalc does it more nicely now
* Remove r.in.arc and r.out.arc, '''if''' a [http://intevation.de/rt/webrt?serial_num=4897 related bug in r.in.gdal] is fixed. The [http://bugzilla.remotesensing.org/show_bug.cgi?id=1071 integer/floating point detection for AAIGrid driver in GDAL] was fixed after 1.3.2 release, so r.in.gdal and r.out.gdal should be enough now.
: see delta comment about r.out.tiff below, sometimes the simple stuff works best! --HB

* remove '''r.resample''' and <strike>'''r.bilinear'''</strike> in favor of '''r.resamp.interp'''
: TODO: double-check that r.resample is in fact fully replaced by 'r.resamp.interp's method=nearest'. ie check that an alternate useful method is not lost.
* <strike>remove '''r.univar.sh'''; newly implemented '''r.univar''' features cover it</strike> '''done.'''

* remove r.out.tiff. New C r.out.gdal should cover all it's option now (doublecheck!). See [http://intevation.de/rt/webrt?serial_num=3680 RT #3680] (starting with date Sun, Nov 26 2006 14:54:23).
: It might be worth keeping r.out.tiff! It makes a nice delta when things don't go well (eg [https://svn.qgis.org/trac/ticket/348 QGIS bug#348]) --HB

* Remove remaining -v and -q flags for verbosity levels of modules.

==== Merge ====

* merge '''r.surf.idw''' and '''r.surf.idw2'''
: while r.surf.idw will only output CELL maps, it is Very Fast.

* r.sum, r.mode, r.median, r.average, r.statistics, r.univar, r.univar2 - maybe they can be reduced to just r.statistics and r.univar? See [http://intevation.de/rt/webrt?serial_num=1848 RT #1848] and a [http://grass.itc.it/pipermail/grass-dev/2006-November/027665.html thread on the GRASS dev list]

* r.resamp.rst: merge into r.resamp.interp to make resolution management identical to the other modules

* r.in.wms and r.in.srtm into r.in.gdal thanks to native support for [http://www.gdal.org/frmt_wms.html WMS] and [http://www.gdal.org/frmt_various.html#SRTMHGT SRTM] in GDAL 1.5
* '''r.buffer''' and '''r.grow'''

==== fix ====
* fix lseek() usage for Large File Support: see [http://grass.itc.it/pipermail/grass-dev/2006-December/028231.html list of affected modules]
* fix the raster map history management (truncating long history, odd storage). It should work like for vector maps in GRASS 6.
* r.volume centroids parameter only makes a level one vector with no attribute table; module should be updated to GRASS 6 vector library)

==== Good coding practice ====

* Input handling:

/* Define the different options */
input1 = G_define_standard_option(G_OPT_R_INPUT) ;
input1->key = _("albedo");
input1->description =_("Name of the Albedo map [0.0-1.0]");
input1->answer =_("albedo");
input1->guisection = _("Required");

In here you can find G_define_standard_option(G_OPT_R_INPUT) assuming
already those:
input1->type = TYPE_STRING;
input1->required = YES;
input1->gisprompt =_("old,cell,raster") ;

If your input is not required to run the module, you just create the
following line:
input1->required = NO;

* In a similar way, metadata/history storage:

G_short_history(result1, "raster", &history);
G_command_history(&history);
G_write_history(result1,&history);

* This is the standard incantation, but I have to find timestamp(), and
more details metadata maybe like sensor type for a start, or
source/origin of data... Can we make metadata having elements
(history->processing, history->timestamp, history->source(or
history->origin), etc?) then it could be filled up specifically.

* Or color palettes application is nice:

/* Color table for biomass */
G_init_colors(&colors);
G_add_color_rule(0,0,0,0,1,255,255,255,&colors);

* Changes (from Glynn):
I would prefer it if G_open_*_new() simply called
G_fatal_error() themselves if an error occurred. It's not as if there's
any reasonable alternative way to handle the error.

* Changes:

input = G_define_option(G_OPT_F(D?)_INPUT) ;
input->key =_("parameter");
input->type = TYPE_DOUBLE;
input->required = YES;
input->gisprompt =_("value, parameter");
input->description=_("Value of the parameter");
/*input->answer =_("0.000");*/
input->guisection = _("Required");

I could also think similarly for non-GRASS files actually
(configuration files sometimes need to be loaded separately)

== Vector ==
=== Radim's TODO list ===

[http://freegis.org/cgi-bin/viewcvs.cgi/grass6/doc/vector/TODO?rev=HEAD&content-type=text/vnd.viewcvs-markup Vector TODO list]
* Particularly important: "Keep topology and spatial index in file instead of in memory" --ML

=== Library ===
* 2d 'vertical' vector data (e.g. [http://sofia.usgs.gov/publications/maps/florida_geology/Txsectionbh.jpg Geologic Cross Sections])
* implement transactions for geometry handling (esp. v.edit, v.digit and to avoid leftover files when a vector command fails)
* Assume '''cat 0''' as the first possible, instead of 1. GRASS has supported cat 0 since around 2005, but it hasn't been widely used. According to Radim, using cat 0 allows for [http://sourceforge.net/mailarchive/message.php?msg_name=340505ef0601170244n1b5fe25bhd0a3eba7342b78d4%40mail.gmail.com exact mapping from OGR FID (which can be 0) to GRASS cat].
* support for elliptical arcs, quadratic and cubic splines. Elliptical arcs or circular arcs are very common in Swiss survey data (Amtliche Vermessung)

=== Modules ===

==== rename ====
* rename v.in.ogr to v.import
* rename v.out.ogr to v.export
* rename v.mkgrid to v.grid
* rename v.univar.sh to v.db.univar ([http://grass.itc.it/pipermail/grass-dev/2007-May/030883.html comment])

==== remove ====

* Remove [http://intevation.de/rt/webrt?serial_num=3600 doubled units in v.to.db GUI]

==== merge ====
* merge v.select and v.overlay
: needs discussion, they are doing fundamentally different things --HB

* merge v.sample and v.what.rast
: See a feature request [http://wald.intevation.org/tracker/index.php?func=detail&aid=506&group_id=21&atid=188 #506] in GForge.

==== fix ====
* Fix the [http://intevation.de/rt/webrt?serial_num=3623 Column 'cat_' already exists (duplicate name)] in v.in.ogr. Maybe by creating columns ''cat_1'', ''cat_2'' etc. each time a Grass vector is exported to shapefile and imported back to Grass?
* write Vect_map_exists() and implement in g.remove and v.digit -n (why wait for GRASS 7 ??)
* add '-d' dissolve to v.reclass
* add 'where=' to v.to.rast (why wait for GRASS 7 ??)
* <strike>implement Douglas-Peucker generalization ([http://www.ngdc.noaa.gov/mgg/shorelines/data/gshhs/ C code file])to substitute prune tool of v.clean ([http://grass.itc.it/pipermail/grass-dev/2007-May/thread.html#31446 done]?, see also GSoC)</strike>
** This is done. [http://grass.osgeo.org/grass63/manuals/html63_user/v.generalize.html v.generalize] does D-P and a lot more -WB
* Rewrite vector labeling. Needs more placement control options (may be db field value based), label overlapping prevention would be also good. May be we could borrow some ideas from MapServer? (ongoing: v.label.sa)
* v.what.vect - rename parameters "vector" to "map", "qvector" to "qmap"
* v.type - change type= option to from= and to=.(code's already in there)

==== enhance ====
* extend v.overlay to allow combination of all types (point, line, area)
* v.category: add possibility to create new layer categories on the basis of a column in the table linked to an existing layer

== General ==
=== Library ===
* Add support for planetary bodies reference systems
* <strike>Add new partial differential equation (PDE) library with OpenMP support</strike> (GRASS 6.3)

=== Modules ===

* g.remove, g.mremove, g.rename, g.copy: don't allow for default datatype (which is currently raster) [http://intevation.de/rt/webrt?serial_num=3009].
: controversial, needs more discussion --HB
* g.region
** [http://grass.itc.it/pipermail/grassuser/2007-February/038337.html Glynn's notes] - cleaning the print flags and new <tt>print=</tt> option
** <strike>Support '''vector's 3rd''' dimension in '''g.region vect= [-a]''', '''[res=]''', like the 2d extents are (or should be)</strike> see [http://trac.osgeo.org/grass/ticket/121 trac #121]

== Database ==
=== Library ===

* <strike>establish SQLite as default DBMI driver (DBF is too limited).</strike> '''done May 2008.'''

=== Modules ===
* allow cross-mapset database access, i.e. parse the '@mapset' notation appended to vector names (requires access via possibly different DBMI drivers)
* rename db.in.ogr to db.import

== Imagery ==
=== Library ===

Do merge of image libraries:

* A)
** lib/imagery/: standard lib, in use (i.* except for i.points3, i.rectify3)
** imagery/i.ortho.photo/libes/: standard lib, in use (i.ortho.photo, photo.*)
* B)
** lib/image3/: never finished improvement which integrated the standard lib and the ortho lib. Seems to provide also ortho rectification for satellite data (i.points3, i.rectify3)
* else
** the lib/imagery/c_*.c files should either be made part of i.cluster (nothing else uses it), or at
least split into a separate library.

=== Modules ===

* merge of i.points, i.vpoints, i.points3
: drop these altogether? (loss of interactive XDRIVER)
* merge of i.rectify and i.rectify3
: maybe depend on gdalwarp C API for this?
* addition of new resampling algorithms such as bilinear, cubic convolution (take from r.proj?)
* add other warping methods (maybe thin splines from GDAL?)
* implement/finish linewise ortho-rectification of satellite data
* Depreciate tape functions in next major revision of GRASS and create a tape module that accomplishes tape access.

== Raster3D ==
=== Library ===
* renaming of all G3D library functions to fulfil the grass coding standard
* extent/rewrite documentation
* localisation support (why wait for GRASS 7 ??)

=== Modules ===
* report and support modules like r3.stats, r3.support
* voxel -> vector (isosurfaces ...) and vector -> voxel (lines, faces, volumes) conversion modules
* module for 3d Kriging interpolation based on vector points
* a GRASS-Python/VTK visualisation/manipulation tool

== Display ==

=== New display architecture ===

''Comments from Glynn Clements (from [http://www.nabble.com/Cairo-monitor-driver-tf4620004.html#a13206009 here]):''

# Eliminating separate driver processes. Having to extend the protocol for each new operation has been a major drag on development.
# Use of floating-point for all graphics coordinates. For geographic data, the expected approach will be to set an appropriate transform then use cartographic coordinates.
# Common architecture for both video and hardcopy output. ps.map should be redundant.

In retrospect, #1 means that we don't really need support for the Windows/MacOSX GUI, just the ability to generate image files.

With X, we could take the shortcut of having d.* commands draw directly into an existing window, but I don't know whether that's possible on other platforms.

OTOH, it might be useful to be able to use the same functions for self-contained GUI programs (e.g. vector digitising) as for d.* commands.

=== Library ===
* Drop support for interactive xmon modules

=== Modules ===
* d.font etc.
** <strike>Huidae Cho merged d.text.freetype and d.text into d.text.new; drop them and rename d.text.new into d.text.</strike> '''done.'''
** merge d.font and d.font.freetype too
: now done in 6.3?

* d.vect
** consolidate parameter names (attrcol, wcolumn, rgb_column)
: -> attr_column, width_column, rgb_column?

* remove d.ask, d.menu, d.linegraph(?), <strike>d.mapgraph, d.text.freetype, d.paint.labels (symlink)</strike>, d.font.*
: rewrite d.ask, d.menu as WxGUI popup-window modules independent of display?

* <strike>remove d.m.</strike> '''done.'''

* d.legend, d.barscale, d.text, etc: make at=0,0 origin identical!
: FWIW, I copied the d.legend at= syntax from d.frame --HB

== Postscript ==
=== Modules ===
ps.map
* remove scale parameter
: -> from the command line, not the map instruction
* rename sizecol to sizecolumn (remove the given warning)
* use PAL/JPAL [http://geosysin.iict.ch/PAL cartographic labelling library] (GPL, C++ language, JNI wrapper)

See also "New display architecture" comments above.

== Parser ==

* "Add another semantic meaning to the parser system for a type safe enumerated list" (Cedric's words commenting the bug that [http://intevation.de/rt/webrt?serial_num=2969 '''v.type''' doesn't allow for selecting input and output type in '''GUI''']

* Making GRASS modules be less verbose. Use --verbose flag and GRASS_VERBOSE environment variable. All output (G_message, G_percetn, G_warning) should go to GRASS_LOG file which could be grassdata/location/mapset/.grass.log by default.
: less verbose: this is well underway in 6.3
: Note warning and errors are already logged to GIS_ERROR_LOG (see variables.html)

== Init shell and startup ==

* .grassrc6 is not what you expect. It holds the g.gisenv GIS variables, it's not a shell script containing commands like .bashrc is.
: Suggestion: We should change the name for 7.x. It isn't an "rc" file in the conventional sense.
:: Suggestion: make it even a $HOME/.grass7/ directory to store settings etc (e.g., from r.li and others)

* It is asked to run GRASS in its own shell to avoid portability issues [http://grass.itc.it/pipermail/grass-dev/2007-August/032607.html 1].

* Eliminate Init.sh. Glynn explains on [http://www.nabble.com/forum/ViewPost.jtp?post=12914361&framed=y GRASS user ML]: "Most of the environment can be set up through an e.g. /etc/env.d/grass script. The database, location and mapset can be set through g.mapset. The only slight subtlety is if you want multiple independent sessions, but that can be done with a fraction of the code in Init.sh."

* Provide a mechanism (g.access option?) to enable r/w access for users in mapsets they don't own. So that it they don't need to hack lib/gis/mapset_msc.c. Glynn explains on [http://www.nabble.com/forum/ViewPost.jtp?post=12914361&framed=y GRASS user ML]: "AFAICT, that restriction has been unnecessary ever since the lockfile was moved from the user's home directory to the mapset directory."
: Actually, I (Glynn) no longer think it's that simple. If other users can create directories within your mapset, they can create directories which you cannot remove, and in which you cannot add, remove or modify files. And this is quite likely to happen: most users will have a umask of 0022 or worse, meaning that other users (i.e. you) cannot modify any files or directories which they create.

== Data management ==

* store vertical units on per-map base, using code from [http://www.gnu.org/software/units/ units] software
: Support for free form unit meta-data added in 6.3. I don't mind it as a guide, but we shouldn't be limited to units found in ''units''. --HB

* store vertical map datum on per-location base (GDAL/OGR needs the same [http://lists.maptools.org/pipermail/gdal-dev/2005-October/006857.html enhancement])
: This requires more discussion. I'm not sure it's a good idea to do this location-wide. --HB
: On a per raster map basis done in 6.3 cvs.

* add versioning for maps (to recover previous map versions)
: see "v.info -h" ?

== Time series ==

* Implement better [[Time series in GRASS]] support (series of satellite data etc)
: for example?

== Visualization ==

* better support for faces and kernels in libgis
: not really Visualization, but....

== CLI ==

=== Parameters standardization ===

* Fix the parameters and flags. Make it a concept. See proposal in GRASS 5 [http://freegis.org/cgi-bin/viewcvs.cgi/grass/documents/parameter_proposal.txt?rev=HEAD&content-type=text/vnd.viewcvs-markup documents/parameter_proposal.txt]

=== Flags standardization ===

* Get rid of 'quiet/verbose' flags, preparation in GRASS 6, e.g.:
<pre>
/* please, remove before GRASS 7 released */
if(q->answer) {
putenv("GRASS_VERBOSE=0");
G_warning(_("The '-q' flag is superseded and will be removed "
"in future. Please use '--quiet' instead"));
}
</pre>

== GUI ==

* Multiplatform
* Fast, minimalist, number of windows reduced
* Manageable also from command line via d.* modules
* Facilitating easy development of custom GUI application based on GRASS
* <strike>drop '''d.m'''</strike> '''done.'''
* drop '''gis.m''' ??

* → [[WxPython-based GUI for GRASS]]

== Conceptual changes ==

* File organization in binaries:
** the grass etc dir is a mess... module should maintain arch-deps and arch-indep things in different paths -- <cite> frankie at #grass irc</cite>
** it's basically a FHS violation, i dunno if it is reported by lintian, anyway /usr/lib/grass should be used for arch-deps data, not for mixed stuff -- <cite> frankie at #grass irc</cite>
* Creating $HOME/.grass7 directory for
** Custom fonts
** r.li and other modules temp. files
** GEM addons installation
** Default path for custom scripts
** Custom symbols and EPS fill patterns
** Custom color maps
** Add here new item

== User Wishes ==

''This section is not really development related...''
* Create 3D animation w nviz showing GRASS 3D coolness. [[User:MarisN|MarisN]] 12:00, 4 August 2006 (CEST)
* here are some examples to get inspired (apparently that's already possible):
** [http://skagit.meas.ncsu.edu/~helena/publwork/grasskey02/grass02talk10.html dynamic surfaces and volumes]
**[http://skagit.meas.ncsu.edu/~helena/wrriwork/cenntenial/water01dsmall.gif some water]
**[http://skagit.meas.ncsu.edu/~helena/wrriwork/balsam/fanimwalk.gif particles]
** [http://www.fhpv.unipo.sk/kagerr/pracovnici/hofierka/pv_results.html solar radiation and energy]
* Convince the users to use ParaView [http://www.paraview.org] for sophisticated animations --[[User:Huhabla|huhabla]] 20:47, 14 August 2006 (CEST)
**(Add support for Paraview in GDAL/OGR or add GDAL/OGR support in ParaView to read directly data from GRASS) see discussion
* Or use [http://www.llnl.gov/visit/ VisIt software], it should be able to read GRASS maps directly via GDAL

== Complete GRASS Test Suite ==
* base a comprehensive test suite on [http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite/?C=M;O=D Soeren's GRASS Test Suite]
* automated error checking on all modules to catch data corruption issues

[[Category:Development]]
[[Category:Release Roadmap]]

AreaFillPatterns

2008-09-05T02:36:27Z

⚠️Glynn: /* Example Pattern files */

[http://grass.osgeo.org/grass64/manuals/html64_user/ps.map.html#vareas ps.map's vector area filling command] will let you set a fill pattern ([http://en.wikipedia.org/wiki/Hatching hatching]). You can create custom patterns. User contributed patterns can be found on this page.

''Alternative'':
[http://www.qgis.org QGIS] will let you load a GRASS map (with the GDAL GRASS-plugin installed) and change the area fill pattern on-screen.

=== Contributions ===

Please include a small example graphic. [[Special:Upload|Upload instructions]].

Also please include your name and some sort of license information.<BR>
e.g. "© 2006 Sara Grassuser, released into the public domain without restriction." This way others may freely improve and further distribute your work (e.g. it can be distributed with the next official GRASS release).

=== Authoring instructions ===

Use the ps.map ''vareas'' command's '''pat''' instruction with the full path to pattern file. The pattern file contains header and simple PS commands. It is similar to EPS but more limited, meaning that while each pattern file is a true EPS file, most EPS files are not usually useful as pattern files because they contain restricted commands. Color and width of patterns are set by '''fcolor''' and '''width''' instructions until overwritten in the pattern file. The pattern may be scaled with the '''scale''' instruction. Several standard hatching patterns are provided in <TT>$GISBASE/etc/paint/patterns/</TT>. You can also create your own custom pattern files in a text editor.

=== Example use ===

* [[Psmap_fill_patterns|Example ps.map script]] showing all standard fill patterns. Uses the [http://grass.osgeo.org/download/data6.php Spearfish sample dataset].

vareas fields
pat $GISBASE/etc/paint/patterns/brick.eps
where label ~ 'Natl. Forest'
fcolor green
end

=== Example Pattern files ===

* Standard pattern files can be found in <tt>$GISBASE/etc/paint/patterns/</tt> or from the [http://trac.osgeo.org/grass/browser/grass/branches/develbranch_6/ps/ps.map/patterns/ SVN web interface].

<ul><ul>
[[Image:Fillpatterns.png]]
</ul></ul>
''[http://bambi.otago.ac.nz/hamish/grass/fillpatterns.ps PostScript version of this image]'' (created with {{cmd|ps.map}} and {{cmd|v.mkgrid}})

==== Vertical line ====
('''|''')
%!PS-Adobe-2.0 EPSF-1.2
%%BoundingBox: 0 0 10 10
newpath
5 0 moveto
5 10 lineto
stroke

=== User contributions ===


-



[[Category: ps.map]]

Template:Cmd

2008-09-05T02:35:00Z

⚠️Glynn:

<span class="plainlinks">[http://grass.osgeo.org/grass{{{version|64}}}/manuals/html{{{version|64}}}_user/{{{1}}}.html {{{1}}}]</span><noinclude>
Module manual page external link. Usage:

<nowiki>{{cmd|module}}</nowiki>

or

<nowiki>{{cmd|module|version=64}}</nowiki>

For example

<nowiki>{{cmd|v.in.dxf}}</nowiki>

creates

{{cmd|v.in.dxf}}

[[Category:Templates]]
</noinclude>

GIS Concepts

2008-09-04T18:22:52Z

⚠️Glynn: /* Raster Data */

== Geodesy and Cartography ==
=== Background material ===

* [http://oceanservice.noaa.gov/education/kits/geodesy/welcome.html An introduction to Geodesy] from NOAA
* [http://en.wikipedia.org/wiki/Geodesy Wikipedia's Geodesy entry]
* [http://en.wikipedia.org/wiki/GIS Wikipedia's GIS entry]
* [http://earth-info.nima.mil/GandG/publications/ NGA Geodesy and Geophysics publications]
* [http://www.ordnancesurvey.co.uk/oswebsite/gps/information/coordinatesystemsinfo/guidecontents/index.html UK Ordnance Survey primer on coordinate system concepts] ([http://www.ordnancesurvey.co.uk/gps/docs/A_Guide_to_Coordinate_Systems_in_Great_Britain.pdf PDF])

=== Map projections ===

* [http://www.asprs.org/resources/grids/ ASPRS Grids and Datums]: detailed descriptions of national projections
* [http://www.mapref.org/ MapRef] - The Collection of Map Projections and Reference Systems for Europe
* [http://www.remotesensing.org/geotiff/proj_list/ Projections Transform Lists] (PROJ4)
* [http://www.dmap.co.uk/utmworld.htm UTM Zones]

EPSG:
* [http://www.epsg.org EPSG projection codes]
: [http://www.epsg-registry.org/ EPSG database search]
: [http://spatialreference.org/ Spatialreference community portal]

Projection galleries:
* [http://www.progonos.com/furuti/MapProj/CartIndex/cartIndex.html Map projection concepts] by Carlos Furuti
* [http://www.galleryofmapprojections.com Map projection gallery] by Paul Anderson

=== Map datums ===

* [http://www.colorado.edu/geography/gcraft/notes/datum/datum.html An introduction to geodetic datums] by Peter Dana
* [http://home.online.no/~sigurdhu/WGS84_Eng.html How WGS 84 defines the Earth]
* A discussion of [http://www.linz.govt.nz/core/surveysystem/geodeticinfo/conversions/datums/nzgd1949-nzgd2000/index.html 3-term, 7-term, and NTv2 grid datum transformations] by Land Information New Zealand
: (besides the web page have a look at the PDF fact sheet and guide linked therein)


==How GRASS deals with geodetics==

As far as GRASS is concerned, an ellipsoid and a spheroid are the same thing, and ellipsoid is the prefered name.

As far as GRASS is concerned, a datum is made up of an ellipsoid and an origin.
Setting a datum is optional, but highly recommended.

GRASS uses a modified version of the [http://proj.maptools.org PROJ.4] library.

=== Modules controling a location's map projection ===
* [http://grass.osgeo.org/grass64/manuals/html64_user/g.proj.html g.proj] help page
* [http://grass.osgeo.org/grass64/manuals/html64_user/g.setproj.html g.setproj] help page

=== Modules for reprojecting GIS maps and data ===

* [http://grass.osgeo.org/grass64/manuals/html64_user/r.proj.html r.proj] for reprojecting raster maps
* [http://grass.osgeo.org/grass64/manuals/html64_user/v.proj.html v.proj] for reprojecting vector maps
* [http://grass.osgeo.org/grass64/manuals/html64_user/m.proj.html m.proj] for reprojecting a list of coordinate pairs

=== Modules for georectifying images ===

* [http://grass.osgeo.org/grass64/manuals/html64_user/r.region.html r.region] for resetting a raster map's bounds information
* gis.m GIS manager GeoReferencing tool (File menu)
* [http://grass.osgeo.org/grass64/manuals/html64_user/i.points.html i.points] and [http://grass.osgeo.org/grass64/manuals/html64_user/i.vpoints.html i.vpoints] for setting GCPs
* [http://grass.osgeo.org/grass64/manuals/html64_user/i.rectify.html i.rectify] for georectifying imagery
* [http://www.gdal.org GDALwarp] (use with gdal_translate, see the i.warp script in the wiki [[GRASS_AddOns#Imagery_add-ons|AddOns]] page)

;[[Georeferencing]]

==GIS Data types==

===Raster Data===

Data which occurs in a regularly spaced grid. e.g. a satellite image or digital terrain map.<BR>
Region settings determine the spatial extent and resolution of the grid.

;[http://grass.osgeo.org/grass64/manuals/html64_user/rasterintro.html Raster Intro]
[[Replacement raster format]]

[[GRASS Raster Mask]]

[[GRASS raster semantics]]

===3D Raster Data (Voxel)===

A stack of 2D raster maps.

;[http://grass.osgeo.org/grass64/manuals/html64_user/raster3dintro.html Raster 3D Intro]

===Vector Data===

Data which occurs as a series of coordinates. e.g. a GPS position or coastline map. May be a point, line, area, etc in either 2D or 3D space. Generally independent of region settings.

;[http://grass.osgeo.org/grass64/manuals/html64_user/vectorintro.html Vector Intro]
[[Vectordata]]

=== Imagery Data ===
Pixelated photographic or satellite images, often imported from a
[http://en.wikipedia.org/wiki/GeoTIFF GeoTIFF] or PNG image file.

As far as the GIS is concerned this is just another raster map, but there are several modules specially tailored for rectification and processing common imagery types. e.g. ortho-photos or multi-channel LANDSAT data.

* [http://grass.osgeo.org/grass64/manuals/html64_user/imageryintro.html GRASS Imagery module introduction]

* The GRASS [[Image processing]] wiki page

===Site Data===
Old versions of GRASS (5 and earlier) treated point data separate to line and polygon data. GRASS 6 classes all vector data features the same. Convert old sites file data into GRASS 6 vector format with the GRASS 6 [http://grass.osgeo.org/grass64/manuals/html64_user/v.in.sites.html v.in.sites] or
[http://grass.osgeo.org/grass64/manuals/html64_user/v.in.sites.all.html v.in.sites.all] modules.

==Conversions between data types==

The following table is intended to catalog transformations from one type of data to another:<BR>
''[table is currently incomplete!]''

{| border="1"
| From / To
![http://grass.osgeo.org/grass64/manuals/html64_user/rasterintro.html Raster]
![http://grass.osgeo.org/grass64/manuals/html64_user/raster3dintro.html 3D Raster]
![http://grass.osgeo.org/grass64/manuals/html64_user/vectorintro.html Vector]
|-
! Raster
| r.mapcalc
| r.to.rast3
| r.to.vect, v.sample, r.volume
|-
! 3D Raster
| r3.to.rast, r3.cross.rast
| r3.mapcalc
|
|-
! Vector
| v.to.rast, v.surf.rst, v.surf.idw
| v.vol.rst, v.vol.idw, v.to.rast3
| v.clean
|-
! Data
| r.in.*
| r3.in.*
| v.in.*
|}

==How a GRASS project is organized==

GRASS data is stored in a three level structure, the database, location and mapset. These can be found in a series of nested directories on the user's computer. All three must exist and are set at GRASS startup time.

===The Database===

The directory in which all GIS data is to be stored.

e.g. <tt>~/grassdata/</tt>

===The Location===

A ''location'' is a GRASS project consisting of an area, projection definition (or unprojected), a grouping of mapsets, all with the same projection settings. A location is a subdirectory of the GRASS ''database''.

e.g. world_lat_lon, utm_zone_59, or west_coast

A ''location'' contains one or many ''mapsets''.

===The Mapset===

A ''mapset'' contains map(s), it is a subdirectory of a ''location''.
Conceptually, if several mapsets are used in a location, they may be assigned to different users (each has one or several own mapsets to work in and cannot modify thos of other users), and/or it they are used to organize a project (''location'') by subareas or subprojects.
There are no specific organizational limitations.

There is always a PERMANENT mapset which is readable from all other mapsets within the same location. Read access to maps in other mapsets is managed with the 'g.mapsets' command or by adding the "@" symbol and mapset name (e.g. <tt>map@othermapset</tt>).

==How the Open Source software development model works==

GRASS differs from many other GIS software packages used in the professional world in that it is developed and distributed by users for users; mostly on a volunteer basis, in the open, and is given away for free.

Emphasis is placed on interoperability and unlimited access to data as well as software flexibility and evolution rate (both added features and bug minimization).

''Free'' can have many meanings, as the links below illustrate, and within a project there is often a spectrum of philosophies and goals amongst developers. But it works - Free Software has revolutionized many sectors of the computing world over the last few years and continues to do so today.

* [http://www.gnu.org/philosophy/philosophy.html Philosophy of the Free Software Movement]
* [http://www.opensource.org The Open Source Initiative has a good explanation]
* [http://www.fsf.org The Free Software Foundation]
* [http://www.gnu.org/copyleft/gpl.html The GNU General Public License]

==Raster GIS Analysis==

===Simple Raster Math===

Sometimes when analyzing the relationship between two or more raster data sets, a relatively simple mathematical approach is best. One example using the r.mapcalc tool would be to look at changes between two raster data sets. By subtracting the values in these two data sets you can assume that resulting cells with a positive value have a possitive change and those with a negative value have negative change. If the cell values have a zero value then there would be no change.

GRASS comes bundled with the r.mapcalc tool as well as the d.m GUI interface for the tool accessable using the r.mapcalculator command. This GUI allows the user to easily assign raster sets to the variables used in the formulas and easily create mathematical strings that will result in a new raster data set containing the results.

[[Category:Development]]
[[Category:Community]]

GRASS pixel rules

2008-09-04T18:18:44Z

⚠️Glynn: GRASS pixel rules moved to GRASS raster semantics

#REDIRECT [[GRASS raster semantics]]

GRASS raster semantics

2008-09-04T18:18:44Z

⚠️Glynn: GRASS pixel rules moved to GRASS raster semantics

A quick summary c/o Glynn Clements:

==Region Calculations==

Well, the region isn't limited to raster data; it may also affect some
vector operations.

The region's bounds describe a rectangle in two-dimensional space. For
raster operations, this rectangle is subdivided into a grid of
rectangular cells, so the region's bounds are aligned with the edges
of the outermost cells.

==Cell Locations==

Cells are areas, not points, so they don't have locations. Their
corners have locations, as do their centres.

A cell with array indices (i,j) (easting, northing) corresponds to the
rectangle:

{ (x,y) : west + i * ewres <= x < west + (i+1) * ewres,
north - (j+1) * nsres <= y < north - j * nsres }

whose centre is at:

(west + (i+1/2) * ewres, north - (j+1/2) * nsres)

[Subject to wrapping of longitude values in lat/lon locations.]

==Raster to Vector Conversions==

IIRC, r.to.vect uses the midpoints of the cell's edges (i.e. one
coordinate will be on a grid line, the other will be mid-way between
grid lines).

==Resampling==

The built-in nearest-neighbour resampling of raster data calculates
the centre of each region cell, and takes the value of the raster cell
in which that point falls.

If the point falls exactly upon a grid line, the exact result will be
determined by the direction of any rounding error.

[One consequence of this is that downsampling by a factor which is an
even integer will always sample exactly on the boundary between cells,
meaning that the result is ill-defined.]

'''r.resample''' uses the built-in resampling, so it should produce
identical results.

'''r.resamp.interp''' method=nearest uses the same algorithm, but not the
same code, so it may not produce identical results in cases which are
decided by the rounding of floating-point numbers.

For method=bilinear and method=bicubic, the raster values are treated
as samples at each raster cell's centre, defining a piecewise-
continuous surface. The resulting raster values are obtained by
sampling the surface at each region cell's centre.

As the algorithm only interpolates, and doesn't extrapolate, a margin
of 0.5 (for bilinear) or 1.5 (for bicubic) cells is lost from the
extent of the original raster. Any samples taken within this margin
will be null.

AFAIK, '''r.resamp.rst''' behaves similarly, i.e. it computes a surface
assuming that the values are samples at each raster cell's centre, and
samples the surface at each region cell's centre.

For '''r.resamp.stats''' without -w, the value of each region cell is the
chosen aggregate of the values from all of the raster cells whose
centres fall within the bounds of the region cell.

With -w, the samples are weighted according to the proportion of the
raster cell which falls within the bounds of the region cell, so the
result is normally[1] unaffected by rounding error (a miniscule
difference in the position of the boundary results in the addition or
subtraction of a sample weighted by a miniscule factor).

[1] The min and max aggregates can't use weights, so -w has no effect
for those.

==General Rules==

For the most part, the interpretation is the "obvious" one, given:

1. Cells are areas rather than points.
2. Operations which need a point (e.g. interpolation) use the cell's
centre.

==Developer Notes Rules==
From a programming perspective, the functions:

G_row_to_northing()
G_col_to_easting()
G_northing_to_row()
G_easting_to_col()

all transform floating-point values.

Passing integer row or column indices to the first two functions will
return the coordinates of the cell's top-left corner; for the centre
coordinates, pass row+0.5 and/or col+0.5.

Similarly, the last two functions will typically return non-integral
values; use floor() to discard the fractional part and obtain the row
or column index of the cell within which the point lies.

Updating GRASS Documentation

2008-08-20T11:22:40Z

⚠️Glynn: Add: A brief guide to valid HTML

= How-to for Updating GRASS Manual Pages =

* [http://trac.osgeo.org/grass/browser/grass/trunk/doc/html_documentation.txt doc/html_documentation.txt] from the GRASS source code

== Overview ==

Module manual page:

Place the documentation in HTML format into '<module>.html', where
<module> is the name of the module. E.g. if the module is named
r.example, the documentation file should be named r.example.html.

The easiest way to do this is to study an existing HTML page
(to get the page style, e.g. vector/v.to.db/v.to.db.html).
With a few exceptions header and footer are NOT allowed.
You can add figures (PNG format), the figure name prefix should be the
module name. See raster/r.terraflow/r.terraflow.html for an example.

Note that the parameter information is auto-generated upon
compilation. This is done by running module in a virtual session
after compilation (see the output of 'make'). To subsequently
verify the final HTML page, check the resulting HTML pages which
will be stored with the name of the module.

The online WWW man pages will be updated every Saturday by SVN.

== Instructions ==

This page will provide general step-by-step instructions for updating and improving GRASS manual pages. Feel free to update and improve this page as well! See also [http://trac.osgeo.org/grass/browser/grass/trunk/SUBMITTING_DOCS SUBMITTING_DOCS] in the source code.

As an example, the vector program v.in.ascii will be used to illustrate the steps required to update its manual page. These steps can then be generalized for your case.

== Getting the latest source ==

* To begin, you must obtain the latest GRASS source code from the Subversion repositories. Detailed instructions on how to do so can be found [http://trac.osgeo.org/grass/wiki/DownloadSource here.]
* Once you have downloaded the SVN source code, open a terminal and change directory to where the source for a specific GRASS module is located - in this example, something like:
cd /your_svn_directory/grass6/vector/v.in.ascii

* Open a text editor and make your edits to <module>.html. Do not use a "WYSYWIG" HTML editor on those files, but either a normal text editor or something which is designed for editing HTML ''source'' (e.g. [X]Emacs' html-mode or psgml-mode). Save your edits by overwriting the original <module>.html.

== Help page sections ==

Please use the following section list as a ''guideline''.
The intent is to promote a unified user experience, not to limit the flow of information. If exceptions are needed, please use them sparingly.
Minor sections (<H3>, etc) may be free-form, as required.

=== Auto-generated ===
Modules using the parser interface will have these sections automatically generated from '<tt>g.module --html-description</tt>'
<pre>
<H2>NAME</H2>
<H2>KEYWORDS</H2>
<H2>SYNOPSIS</H2>
</pre>

=== Found in <module>.html ===
A number of major sections should be present in each help page.

<pre>
* = Required
! = Suggested
. = Optional

In recommended order
--------------------

* <H2>DESCRIPTION</H2>
! <H2>NOTE</H2>, <H2>NOTES</H2>
! <H2>EXAMPLE</H2>, <H2>EXAMPLES</H2>
. <H2>TODO</H2>
. <H2>BUGS</H2>
. <H2>REFERENCE</H2>, <H2>REFERENCES</H2>
* <H2>SEE ALSO</H2>
* <H2>AUTHOR</H2>, <H2>AUTHORS</H2>
</pre>

== Images ==

* Images can also be inserted in the html help page. See [http://grass.itc.it/grass63/manuals/html63_user/v.voronoi.html v.voronoi] for an example. Note that images won't show up in the Grass ''man'' pages (which are generated from the HTML), so they shouldn't be considered a substitute for an adequate textual description. Be sure to also send the image (preferably png format) along with your documentation patch.

PNG files are best for figures with solid chunks of a single color. They can get rather large for imagery. In those cases JPEGs are a better choice. In general JPEG is a lossy format so the image quality will not be as good.

To help keep the source distribution size small, try and keep the images small and the files under 50kb or so. Save PNGs at a compression setting of "9" with a minimal color pallet, you can also use tools like
<tt>pngcrush</tt> to compress them further.

== Examples ==

For non trivial modules please provide an example of the command line usage. It is good to have this double as a mini-tutorial, so please use one of the sample datasets (Spearfish or the new North Carolina one) or common dataset such as NASA's WMS or SRTM data files.

Examples should be coded like this:

<div class="code"><pre>
v.to.db map=soils type=area option=area col=area_size unit=h
</pre></div>

== HTML codes ==

The g.html2man tool is used to generate man pages from the HTML help files.

* The following html codes are understood to some extent by g.html2man (brackets removed): A, B, BLINK, BODY, BR, CODE, DD, DL, DT, EM, H2, H3, H4, HEAD, HEADER, HR, I, IMG, LI, OL, P, PRE, SUP, TABLE, TD, TH, TITLE, TR, UL.

* Others may be added to g.html2man as required.

== Creating and submitting a patch ==

* See the [[Patches]] wiki page

== Translations ==

Currently there is no framework for translating the help pages.

Idea: use an online translator such as AltaVista's Babelfish service or Google Translate.

: The top part of the page (generated by `g.module --html-description`) is translated by the $LANG variable and <grass/glocale.h>, so we should not be attempting to automatically translate the option and modules names. The idea for a two part translation is to make a modified version of tools/mkhtml.sh which (if ./config'd --with-nls) loops through major languages and creates html pages like $GISBASE/docs/html/de/, $GISBASE/docs/html/es/,... but instead of just pasting the english <module>.html files to the bottom have it save those as g.module_descr_en.html in a common dir.
: The translated help pages (generated with mkhtml_i18n.sh) would contain a lower frame which calls an online translation of the g.module_descr_en.html page from e.g. ibiblio.org/grass63/html_docs/en_descr/g.module_descr_en.html with the appropriate "lp=en_de" setting in the bablefish URL.
: ?

Examples of live whole-page translations for GRASS 6.3 help pages:
* Chinese- Simplified [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_zh&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Czh-CN&hl=en&ie=UTF8 Google]
* Chinese- Traditional [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_zt&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Czh-TW&hl=en&ie=UTF8 Google]
* Dutch [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_nl&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cnl&hl=en&ie=UTF8 Google]
* French [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_fr&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cfr&hl=en&ie=UTF8 Google]
* German [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_de&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cde&hl=en&ie=UTF8 Google]
* Greek [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_el&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cel&hl=en&ie=UTF8 Google]
* Italian [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_it&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cit&hl=en&ie=UTF8 Google]
* Japanese [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_ja&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cja&hl=en&ie=UTF8 Google]
* Korean [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_ko&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cko&hl=en&ie=UTF8 Google]
* Portuguese [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_pt&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cpt&hl=en&ie=UTF8 Google]
* Russian [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_ru&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Cru&hl=en&ie=UTF8 Google]
* Spanish [http://babelfish.altavista.com/babelfish/trurl_load?lp=en_es&url=http%3A%2F%2Fgrass.ibiblio.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html AltaVista] - [http://translate.google.com/translate?u=http%3A%2F%2Fgrass.osgeo.org%2Fgrass63%2Fmanuals%2Fhtml63_user%2Findex.html&langpair=en%7Ces&hl=en&ie=UTF8 Google]
=== Ideas for a translation framework ===

The above idea really sucks IMHO. Better not to have translated documentation at all than babelfish. --[[User:Steko|Steko]] 13:12, 18 February 2008 (CET)

A '''true''' translation framework for translation of both interface and documentation would be structured like this:
* web interface based on '''[http://translate.sourceforge.net/wiki/pootle/index pootle]''', to make contributions easy also for non-tech people (gettext, html, etc)
* for documentation use '''[http://po4a.alioth.debian.org/ po4a]''', that can be integrated with pootle.

== A brief guide to valid HTML ==

While web browsers will happily accept invalid HTML, the tools used to convert HTML documentation to Unix manual pages won't. For that reason, please try to ensure that the documentation is valid HTML, not just whatever your browser accepts.

If you have [http://openjade.sourceforge.net/ OpenSP/OpenJade], you can validate an HTML file with
e.g.:

<pre>nsgmls -s -c /usr/share/sgml/openjade-1.3.2/pubtext/HTML4.soc <filename>.html</pre>

[The program may be called nsgmls or onsgmls, and the exact location
where the catalogues are installed will vary.]

This needs to be done on the completed HTML file in
dist.<arch>/docs/html; the <module>.html files in the module
directories won't normally validate, as they lack the header which is
added by running the module with the --html-description.

The most common error is using block elements (e.g. <div>,
<pre>, <p>) in contexts where only inline elements are allowed
(e.g. <dt>).

The definitive reference of which elements are allowed where is the
'''[http://www.w3.org/TR/1998/REC-html40-19980424/sgml/loosedtd.html HTML 4.0 Transitional DTD]'''

E.g. the definition:

<code><!ELEMENT DT - O (%inline;)* -- definition term --></code>

indicates that only inline elements are allowed inside DT, while e.g.:

<code><!ELEMENT DD - O (%flow;)* -- definition description --></code>

indicates that both block and inline elements are allowed inside DD.

If you don't want to read the DTD, here's a rough summary:

Entity classes:
<pre>
%StyleSheet = <CSS stylesheet>
%Script = <JavaScript code>

%html.content = HEAD, BODY
%head.content = TITLE, ISINDEX, BASE
%heading = H1, H2, H3, H4, H5, H6
%fontstyle = TT, I, B, U, S, STRIKE, BIG, SMALL
%phrase = EM, STRONG, DFN, CODE, SAMP, KBD, VAR, CITE, ABBR,
ACRONYM
%special = A, IMG, APPLET, OBJECT, FONT, BASEFONT, BR, SCRIPT,
MAP, Q, SUB, SUP, SPAN, BDO, IFRAME
%formctrl = INPUT, SELECT, TEXTAREA, LABEL, BUTTON
%list = UL, OL, DIR, MENU
%head.misc = SCRIPT, STYLE, META, LINK, OBJECT
%pre.exclusion = IMG, OBJECT, APPLET, BIG, SMALL, SUB, SUP,
FONT, BASEFONT
%preformatted = PRE
%block = P, DL, DIV, CENTER, NOSCRIPT, NOFRAMES,
BLOCKQUOTE, FORM, ISINDEX, HR, TABLE, FIELDSET,
ADDRESS, %heading, %list, %preformatted
%inline = #PCDATA, %fontstyle, %phrase, %special, %formctrl
%flow = %block, %inline
</pre>

The immediate children permitted for each element are:
<pre>
A: %inline
ABBR: %inline
ACRONYM: %inline
ADDRESS: %inline, P
APPLET: %flow, PARAM
B: %inline
BDO: %inline
BIG: %inline
BLOCKQUOTE: %flow
BODY: %flow, INS, DEL
BUTTON: %flow
CAPTION: %inline
CENTER: %flow
CITE: %inline
CODE: %inline
COLGROUP: COL
DD: %flow
DEL: %flow
DFN: %inline
DIR: LI
DIV: %flow
DL: DT, DD
DT: %inline
EM: %inline
FIELDSET: %flow, LEGEND
FONT: %inline
FORM: %flow
FRAMESET: FRAMESET, FRAME, NOFRAMES
H1: %inline
H2: %inline
H3: %inline
H4: %inline
H5: %inline
H6: %inline
HEAD: %head.content, %head.misc
HTML: %html.content
I: %inline
IFRAME: %flow
INS: %flow
KBD: %inline
LABEL: %inline
LEGEND: %inline
LI: %flow
MAP: %block, AREA
MENU: LI
NOFRAMES: %flow
NOSCRIPT: %flow
OBJECT: %flow, PARAM
OL: LI
OPTGROUP: OPTION
OPTION: #PCDATA
P: %inline
PRE: %inline
Q: %inline
S: %inline
SAMP: %inline
SCRIPT: %Script
SELECT: OPTGROUP, OPTION
SMALL: %inline
SPAN: %inline
STRIKE: %inline
STRONG: %inline
STYLE: %StyleSheet
SUB: %inline
SUP: %inline
TABLE: CAPTION, COL, COLGROUP, THEAD, TFOOT, TBODY
TBODY: TR
TD: %flow
TEXTAREA: #PCDATA
TFOOT: TR
TH: %flow
THEAD: TR
TITLE: #PCDATA
TR: TH, TD
TT: %inline
U: %inline
UL: LI
VAR: %inline
</pre>
Some elements don't allow certain elements as descendents:
<pre>
A: A
BUTTON: %formctrl, A, FORM, ISINDEX, FIELDSET, IFRAME
DIR: %block
FORM: FORM
LABEL: LABEL
MENU: %block
PRE: %pre.exclusion
TITLE: %head.misc
</pre>
Notes:

* The children of DIR/MENU are LI, which is a block element, but those LI can't contain block elements. UL/OL don't have this restriction.

* <nowiki>DT cannot contain block elements, but DD can. This means that you can't use <div class="code"><pre> in a DT; use <span class="code"><tt> instead. DIV and PRE are block elements; SPAN and TT are inline.</nowiki>

* <nowiki>TABLE cannot have TR as a child. But TBODY can have TR, and TBODY allows both the start and end tags to be omitted, so <table><tr>....</tr></table> is really just a shorthand for <table><tbody><tr>.... </tr></tbody></table>.</nowiki>

* <nowiki>P cannot contain blocks. So <p>...<div> is actually shorthand for <p>...</p><div>. But <p>...<div>...</div>...</p> is an error, as the </p> doesn't match any open element (the <div> implicitly closed the original <p>, and P doesn't allow the start tag to be omitted).</nowiki>

* HTML, HEAD, BODY, and TBODY allow the start tag to be omitted. With the exception of TBODY, this feature shouldn't be used (it's a nuisance to implement if the number of valid child tags is large).

== See also ==

* Job offer [[Project_jobs#Documentation_manager_.28open.29|Documentation manager]]

* [[Development#Documentation|Doxygen generated help]] from the source code for the [http://grass.itc.it/devel/index.php#prog Programmers' Manual].

[[Category:Development]]

Updating GRASS Documentation

2008-08-20T10:58:08Z

⚠️Glynn: Change description.html references to <module.html>