GRASS Development Team GRASS 5.0 Programmer's Manual Geographic Resources Analysis Support System 30th January 2004 Edited by Markus Neteler Member of GRASS Development Team ITC-irst Istituto per la Ricerca Scientifica e Tecnologica Via Sommarive, 18 38050 Povo (Trento), Italy GMS Laboratory University of Illinois-Champaign, Urbana, Illinois Center of Applied Spatial Research Baylor University, Waco, Texas 30th January 2004, Draft Version Based on preliminary programming notes on GRASS 5 written by Olga Waupotitsch and Michael Shapiro (CERL), Bill Brown (GMSL) and Darrel McCauley (Purdue) and the former GRASS 4.2 Programmer's Manual edited by Steve Clamons, Bruce Byars (Baylor University) and basically written by Michael Shapiro, James Westervelt, Dave Gerdes, Majorie Larson, and Kenneth R. Brownfield (CERL) ABSTRACT GRASS (Geographical Resources Analysis Support System) is a comprehensive GIS with raster, topological vector, image processing, and graphics production functionality. This manual in- troduces the reader to the Geographic Resources Analysis Support System version 5.0 from the programming perspective. Design theory, system support libraries, system maintenance, and system enhancement are all presented. Standard GRASS 4.x conventions are still used in much of the code. This work is part of ongoing research being performed by the GRASS Develop- ment Team coordinated at ITC-irst, Trento, Italy), a worldwide programmer's team (see below), the GMS Laboratory at University of Illinois-Champaign (U.S.A.) and the Center of Applied Geographic and Spatial Research at Baylor University (U.S.A.). GRASS module authors are cited within their module's source code and the contributed manual pages. 30th January 2004 ¡ c 2000 Markus Neteler / GRASS Development Team Published under GNU Free Documentation License (GFDL) http://www.fsf.org/copyleft/fdl.html (see C GNU Free Documentation License (p. 499)) This manual comes with ABSOLUTELY NO WARRANTY. The development of GRASS software and this manual is kindly supported by Intevation GmbH, Osnabrück, Germany, who provide the GRASS CVS repository. European Headquarters: http://grass.itc.it Unites States Headquarters: http://www3.baylor.edu/grass/ Foreword This manual represents documentation for the third revision to the Geographic Resources Anal- ysis Support System (GRASS) Geographic Information System (GIS) with version 4.x being replaced with 5.0. This work was originally performed by the Environmental Division (EN) of the U.S. Army Construction Engineering Research Laboratory (USACERL). In August, 1997, GRASS devel- opment was taken up by the GRASS Development Team at Baylor University. From Summer 1999 to Summer 2001 the GRASS project was coordinated at University of Hannover, Germany, since Summer 2001 at ITC-irst, Trento, Italy. Original Authors of the GRASS 4.x Programmer's Manual are Michael Shapiro, James West- ervelt, Dave Gerdes, Majorie Larson, and Kenneth R. Brownfield. It is upon their work that this is based, and we wish for full acknowledgement to go to them for their efforts. Dr. James Westervelt has provided valuable insight into GRASS for this project. Dr. Robert Lozar of USA-CERL has also been instrumental in the release of the GRASS 4.2 manual. The upgrade to GRASS 5 programming API is based on comprehensive notes written in 1995 by Olga Waupotitsch and Michael Shapiro (CERL), Bill Brown (GMSL) and Darrel McCauley (Purdue University). Their documents have been written in HTML and were merged into this manual. Further core designers of GRASS 5 libraries and modules have been Roman Waupotitsch, James Westervelt, David Gerdes, Helena Mitasova, Jaro Hofierka and Lubos Mi- tas. A rather complete list of GRASS programmers can be found online: http://grass.itc.it/grasscredits.html http://www3.baylor.edu/grass/grasscredits.html Please notify us in case of contributors missing in this list. Other Related Materials in the GRASS 5.0 Series GRASS 5.0 Command Reference NOTE: This manual is far from being completely updated. Please send your useful comments to Markus Neteler ([email protected]). i GRASS 5 Core Team Members (Status: 10/2000) Roger Bivand (Norway), Radim Blazek (Czechia), Bill Brown (U.S.A.), Huidae Cho (South Ko- rea), David D. Gray (U.K.), Jaro Hofierka (Slovak), Justin Hickey (Thailand), John Huddleston (U.S.A.), Bill Hughes (U.S.A.), Andreas Lange (Germany), Pierre de Mouveaux (France), Lu- bos Mitas (U.S.A.), Helena Mitasova (U.S.A.), Eric G. Miller (U.S.A.), Eric Mitchell (U.S.A.), Markus Neteler (Germany), Bernhard Reiter (Germany), Alexander Shevlakov (Russia), Frank Warmerdam (U.S.A.), Michel Wurtz (France), Lisa Zygo (U.S.A.) Get latest list here: http://freegis.org/cgi-bin/viewcvs.cgi/~checkout~/grass/AUTHORS ii Book status and History Note: This page will disappear when the book is finished. This page reflects the current status of the "GRASS 5.0 Programmer's Manual" and needs to be updated regularly by book authors. [$Id: status.tex,v 1.23 2001/04/05 17:20:32 markus Exp $] Current status: Markus Neteler 4/2001: * added HTML web pages, converted to Latex: - FP added, but needs to be merged furtherly within existing text - datetime added, but function definitions missing (?, ask Bill Brown) - sites API added - g3d API added * comments are in [] like [GRASS 5: ...] Here further updates are required. * added small PROJ4/GRASS API Contributions from David D. Gray (vector) Eric G. Miller (sites) File list: progmangrass50.tex -> head of document progmangrass50.sty -> layout parameters, \Gfunc and Gprog environment are defined here chapter1.tex: "Introduction" - latex updated chapter2.tex: "Development Guidelines" - latex updated chapter3.tex: "Multilevel" - latex updated chapter4.tex: "Database Structure" - latex updated - added 121 projections chapter5.tex: "Raster Maps" - latex updated chapter6.tex: "Vector Maps" - latex updated - 64 bit support needs to be included (Bill Hughes?) chapter7.tex: "Point Data: Site List Files" - latex updated iii chapter8.tex: "Image Data: Groups" - latex updated chapter9.tex: "Region and Mask" - latex updated - is window/region terminology clear? chapter10.tex: "Environment Variables" - latex updated - several new variables missing chapter11.tex: "Compiling and Installing GRASS Modules" - Auto-conf is not yet explained chapter12a.tex: "GIS Library 1" - latex updated Reference for function definition in Latex!! chapter12b.tex: "GIS Library 2" - latex updated for new 5.x functions chapter12c.tex: "GIS Library 3" - latex updated - added new parser functionality (implemented by Huidae Cho <[email protected]>) - added unix sockets (Eric G. Miller) chapter13.tex: "Vector Library" - latex updated chapter14.tex: "Imagery Library" - latex updated chapter15.tex: "Raster Graphics Library" - latex updated chapter16.tex: "Display Graphics Library" - latex updated - added new functions: * D_set_dig_name(name) * sets the name of the dig file currently displayed * * D_get_dig_name(name) * returns the name of the dig file currently displayed implemented by Huidae Cho <[email protected]> chapter17.tex: "Lock Library" - latex updated chapter18.tex: "Rowio Library" - latex updated chapter19.tex: "Segment Library" - latex updated chapter20.tex: "Vask Library" - latex updated iv proj_datum.tex: "coordinate conversion library" - latex updated - added supported proj list - added PROJ4/GRASS API grid3d.tex: "GRID3D voxel format" - latex updated chapter21.tex: "DateTime Library" - latex updated %% Original Chapter 21 is outdated and belongs to GRASS 4.0/v.digit2. % replaced by DateTime description gsurf.tex: "gsurf Library for OpenGL programming" - latex updated gui.tex: "tcltkgrass and XML/Python GUI programming" - added chapter22.tex: "Digitizer/Mouse/Trackball Files (.dgt)" gmath.tex: "Numerical math interface to LAPACK/BLAS" - added, latex o.k. chapter23.tex: "Writing a Graphics Driver" chapter24.tex: "Writing a Paint Driver" chapter25.tex: "Writing GRASS Shell Scripts" chapter26.tex: "GRASS CVS repository" appendix.tex: - index available now, generated by makeindex --------------- Contributions: - David D Gray <[email protected]>: G__write_cats returns 1 on successful completion - affects at least: G_write_cats, G_write_vector_cats Fixed. Numerical math interface to LAPACK/BLAS added - Andreas Lange <[email protected]>: CC-doc.tex completely written - Eric G. Miller: G_readsites_xyz v TODO list - Errata G_tokenize() G_number_of_tokens() and G_free_tokens() are missing (see libes/gis/token.c) ------ From: Glynn Clements <[email protected]> Date: Mon, 30 Apr 2001 00:16:23 +0100 1. XDRIVER now supports the RGB_RASTER operation natively; if it's using a TrueColor or DirectColor visual, it uses logical operations to convert the data (tested on a 5:6:5 display). No Colormaps, lookup-tables or similar. 2. libdisplay contains some new functions for RGB raster operations: D_draw_raster_RGB D_draw_d_raster_RGB D_draw_f_raster_RGB D_draw_c_raster_RGB D_draw_cell_RGB D_cell_draw_setup_RGB D_raster_of_type_RGB D_set_colors_RGB These are all more or less analogous to the corresponding functions without the _RGB suffix, the main difference being that they take three sets of raster data instead of one. These functions all use the RGB_RASTER operation, so there are no colour tables involved. The CELL/FCELL/DCELL values are converted to bytes using the appropriate channel[1] from the specified colour table (typically the one from the layer). [1] I.e. the red components are used for the red layer, etc. If the layers have suitable grey-scale