/*! \mainpage GRASS 7 Programmer's Manual GRASS GIS (Geographic Resources Analysis Support System) is an open source, Free Software Geographical Information System (GIS) with raster, topological %vector, image processing, and graphics production functionality that operates on various platforms through a graphical user interface (GUI) or command line interface (CLI). It is released under GNU General Public License (GPL). This manual introduces the reader to the Geographic Resources Analysis Support System 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 Development Team, an international team of programmers, GRASS module authors are cited within their module's source code and the contributed manual pages. © 2000-2011 GRASS Development Team Published under GNU Free Documentation License (GFDL) This manual comes with ABSOLUTELY NO WARRANTY. The development of GRASS software and this manual is kindly supported by the Open Source Geospatial Foundation, who provides the GRASS main infrastructure. Main web site: http://grass.osgeo.org Table of contents - \subpage corelibs - \subpage libs - \subpage interfaces - \subpage gui - \subpage location - \subpage Compiling_and_Installing_GRASS_Modules - \subpage Makefile_Variables - \subpage Constructing_a_Makefile - \subpage Multiple_Architecture_Conventions - \subpage vectmodules - \subpage vectmodules_oper Missing entries below are either not yet uploaded to SVN (need to be migrated from GRASS 5 Programmer's manual) or are simply undocumented. \image html "grass7_arch.png" "GRASS 7 Architecture" PLEASE UPDATE FOR GRASS 7 \section corelibs Principal library (the name refers to the directory name in lib/ in the source code) - gis: \ref gislib - raster: \ref rasterlib - vector: \ref vectorlib \section libs Further libraries (the name refers to the directory name in lib/ in the source code) - arraystats: Library of statistics for arrays of doubles - \ref arraystats (new, under development) - bitmap: Bitmap library for X Window Bitmaps - \ref bitmap - btree: Binary tree library - \ref btree - cairodriver: \ref cairodriver - cdhc: Library for testing normality and exponentiality - \ref cdhc - cluster: \ref clusterlib (image processing) - datetime: DateTime library - \ref datetime - db: \ref dbmilib - display: \ref displaylib - %driver: Graphics monitor driver - dspf: DSPF libary - \ref dspf (obsolete?) - edit: Raster edit library (cellhd, history, cats) - \ref edit - external: External libraries from other projects (such as shapelib) - \ref external - fonts: Hershey library - \ref fonts - g3d: \ref g3dlib - gmath: \ref gmathlib (generic mathematical functions and BLAS/LAPACK library wrapper) - gpde: \ref gpdelib (partial differential equations library) - imagery: \ref imagerylib - init: \ref init (GRASS initialization code + scripts) - linkm: Linked list memory manager - \ref linkm (obsolete?) - ogsf: \ref ogsflib (OpenGL (R) ported gsurf library (required for NVIZ)) - pngdriver: PNG display driver library - \ref pngdriver - proj: \ref projlib (wrapper to PROJ4 projection library) - psdriver: PostScript display driver library - \ref psdriver - python: \ref pythonlib - raster: \ref rasterlib - rowio: \ref rowiolib - rst: Library for interpolation with regularized splines with tension - \ref rst - segment: \ref segmentlib (segment library for segmented raster reading) - sites: Old Sites library, now interfaced to \ref vectorlib - \ref sites - stats: Raster stats library - \ref stats - symbol: Drawing symbols for %point %vector data library - \ref symbol - vask: Cursor management library - \ref vask - %vector: \ref vectorlib (GRASS Vector and Direct Graph Library) - vedit: \ref veditlib - %vector editing - neta: \ref netalib - nviz: \ref nvizlib (used by wxGUI Nviz extension and CLI-based Nviz module) \section interfaces Interfaces - \ref pythonlib \section gui GUI - \ref wxpythonlib \section location File structure of GRASS Location A GRASS raster map consists of several files in several subdirectories in a mapset, organized as follows: - cellhd/: map header including projection code, coordinates representing the spatial extent of the raster map, number of rows and columns, resolution, and information about map compression; - cell/, fcell/ or grid3/: generic matrix of values in a compressed, portable format which depends on the raster data type (integer, floating %point or 3D grid); - hist/: history file which contains metadata such as the data source, the command that was used to generate the raster map, or other information provided by the user; - cats/: optional category file which contains text or numeric labels assigned to the raster map categories; - colr/: optional color table; - cell_misc/: optional timestamp, range of values, quantization rules (for floating %point maps) and null (no-data) files; A GRASS %vector maps are stored in several separate files in a single directory (see \ref vectorlib). While the attributes are stored in either a DBF file, a SQLite file or in an external DBMS (PostgreSQL, MySQL, ODBC), the geometric data are saved as follows: - head: %vector map ASCII header with information about the map creation (date and name), its scale and threshold; - coor: binary geometry file which includes the coordinates of graphic elements (primitives) that define the %vector feature; - topo: binary topology file describes the spatial relationships between the map's graphic elements; - hist: history ASCII file with complete commands that were used to create the %vector map, as well as the name and date/time of the map creation; - cidx: binary category index file which is used to %link the %vector object IDs to the attribute table rows; - dbln: ASCII file which contains definition(s) of %link to attribute storage in database (DBMS). \image html "loc_struct.png" "Diagram of GRASS file structure" \section Compiling_and_Installing_GRASS_Modules Compiling and Installing GRASS Modules GRASS modules are compiled and installed using the UNIX make command, which reads a file named Makefile (see \ref Multiple_Architecture_Conventions for more information) and then runs the compiler. The GRASS compilation process allows for multiple-architecture compilation from a single copy of the source code (for instance, if the source code is NFS mounted to various machines with differing architectures). This chapter assumes that the programmer is familiar with make and its accompanying Makefile. \todo Explain ''auto-conf'' \todo Include contents of SUBMITTING and INSTALL files from source code To compile enter following: \verbatim ./configure make make install \endverbatim Then the code will be compiled into "/usr/local/grass-7.x.y" directory. The start script "grass7x" will be placed into "/usr/local/bin/". Optionally other target directories can be specified while "configuring": \verbatim ./configure --prefix=/opt/grass-7.x.y --with-bindir=/usr/bin make make install \endverbatim This will store the GRASS binaries into the directory "/opt/grass-7.x.y" and the script mentioned above into "/usr/bin". The script "make" is required to compile single modules. The compilation process and requirements are discussed in more detail now. \subsection Makefile_Variables Makefile Variables \todo Update the list. GRASS Libraries. The following variables name the various GRASS libraries: - GISLIB - This names the GIS Library, which is the principal GRASS library. See \ref GIS_Library for details about this library, and \ref Loading_the_GIS_Library for a sample Makefile which loads this library. - SEGMENTLIB - This names the Segment Library, which manages large matrix data. See \ref Segment_Library for details about this library, and \ref Loading_the_Vask_Library for a sample Makefile which loads this library. - RASTERLIB - This names the Raster Graphics Library, which communicates with GRASS graphics drivers. See \ref Raster_Graphics_Library for details about this library, and \ref Loading_the_Raster_Graphics_Library for a sample Makefile which loads this library. - DISPLAYLIB - This names the Display Graphics Library, which provides a higher level graphics interface to RASTERLIB. See Display_Graphics_Library for details about this library, and Loading_the_Display_Graphics_Library for a sample Makefile which loads this library. UNIX Libraries: The following variables name some useful UNIX system libraries: - MATHLIB This names the math library. It should be used instead of the -lm loader option. - CURSES This names both the curses and termcap libraries. It should be used instead of the -lcurses/-lncurses and -ltermcap loader options. Do not use $CURSES if you use $VASK. - TERMLIB This names the termcap library. It should be used -instead of the ltermcap or -ltermlib loader options. Do not use -$TERMLIB if you use $VASK or $CURSES. Compiler and loader variables. The following variables are related to compiling and loading C programs: - EXTRA\_CFLAGS This variable can be used to add additional options to $CFLAGS. It has no predefined values. It is usually used to specify additional -I include directories, or -D preprocessor defines. \subsection Constructing_a_Makefile Constructing a Makefile The complete syntax for a Makefile is discussed in the UNIX documentation for make and will not be repeated here. The essential idea is that a target (e.g. a GRASS module) is to be built from a list of dependencies (e.g. object files, libraries, etc.). The relationship between the target, its dependencies, and the rules for constructing the target is expressed according to the following syntax: \code target: dependencies actions more actions \endcode If the target does not exist, or if any of the dependencies have a newer date than the target (i.e., have changed), the actions will be executed to build the target. The actions must be indented using a TAB. make is picky about this. It does not like spaces in place of the TAB. \section Multiple_Architecture_Conventions Multiple-Architecture Conventions The following conventions allow for multiple architecture compilation on a machine that uses a common or networked GRASS source code directory tree. Object files and library archives are compiled into subdirectories that represent the architecture that they were compiled on. These subdirectories are created in the $SRC directory as OBJ.arch and LIB.arch, where arch represents the architecture of the compiling machine. Thus, for example, $SRC/OBJ.sun4 would contain the object files for Sun/4 and SPARC architectures, and $SRC/LIB.686-pc-linux-gnu would contain library archives for Linux architectures. Likewise, $SRC/OBJ.686-pc-linux-gnu would contain the object files for Linux architectures, and $SRC/LIB.686-pc-linux-gnu would contain library archives for Linux architectures. Note that 'arch' is defined for a specific architecture during setup and compilation of GRASS, it is not limited to sun4 or any specific string. \section vectmodules Vector modules and their parameters/flags A module is a GRASS command invoked by the user. \subsection vectmodules_oper Modules operation Each module which modifies and writes data must read from input= and write to output= so that data may not be lost. For example v.spag works on map= at in GRASS GIS 5.0 but if program (system) crashes or threshold was specified incorrectly and vector was not backuped, data were lost. In this case map= option should be replaced by input= and output=. Topology is always built by default if the coor file was modified. Dimensionality is generally kept. Input 2D vector is written as 2D, 3D as 3D. There are a few modules which change the dimension on purpose. \subsection vectmodulesopt Modules parameters/flags -b do not build topo file; by default topo file is written -t create new table, default -u don't create new table -z write 3D vector map (if input was 2D) map= input vector map for modules without output input= input vector map output= output vector map type= type of elements: point,line,boundary,centroid,area cat= category or category list (example: 1,5,9-13,35) layer= layer number where= condition of SQL statement for selection of records column= column name (in external table) */