GRASS-Wiki - User contributions [en]

GRASS and Shell

2011-02-14T23:07:06Z

⚠️Caitifty: /* Setting the variables */ add variables if script will be called from php

It is fairly easy to write a GRASS job as Shell script which launches GRASS, does the operation and cleans up the temporary files.

=== What's this? ===

Often it is convenient to automate repeated jobs. GRASS can be controlled via user scripts to facilitate daily work.
How to start? Using command line is a kind of writing scripts without saving them - so, you may start to write
'''your first script''' by saving the executed commands in a text file (use your preferred editor to do so, ideally
save the script file in ASCII format).

=== A first script ===

Comments should be started with a '#' character. The first line indicates the shell interpreter to be used, here "sh" which is always in the /bin/ directory.

Silly example:

#!/bin/sh
# my first script

# plot current region settings
g.region -p

# leave with exit status 0 which means "ok":
exit 0

Save this in a file "myscript.sh" and run it within GRASS GIS from the command line:

sh myscript.sh

It should print the current region settings and finish.

=== Setting the variables ===

You have to set a couple of variables to enable GRASS command to run (see ''''GRASS Batch jobs'''' below for easier solution!).

''[http://article.gmane.org/gmane.comp.gis.grass.user/17980 See this post] to the mailing list. Proabably need to update this wiki page with that information.''

# Example in bash shell syntax:

# path to GRASS binaries and libraries:
export GISBASE=/usr/local/grass64

export PATH=$PATH:$GISBASE/bin:$GISBASE/scripts
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GISBASE/lib

# use process ID (PID) as lock file number:
export GIS_LOCK=$$

# settings for graphical output to PNG file (optional)
export GRASS_PNGFILE=/tmp/grass6output.png
export GRASS_TRUECOLOR=TRUE
export GRASS_WIDTH=900
export GRASS_HEIGHT=1200
export GRASS_PNG_COMPRESSION=1

# settings if you will be calling the script from another program - eg a php web page using system() or exec()
export HOME=/var/www
export USER=www-data
export GROUP=www-data

The following variable defines where the GRASS settings file is stored. This can be anywhere on the system. You could also generate the '.grassrc6' on the fly in your script, even with different name. Just indicate it correctly:

# path to GRASS settings file
export GISRC=$HOME/.grassrc6

Now you can test:

# this should print the GRASS version used:
g.version
# other calculations go here ...

You should cleanup internal tmp files like this:

# run GRASS' cleanup routine
$GISBASE/etc/clean_temp

# remove session tmp directory:
rm -rf /tmp/grass6-$USER-$GIS_LOCK

If this works, you can launch other GRASS commands. The approach works within Shell scripts and also in the command line terminal.

=== Example ===

* GRASS shell script job to generate a [http://grass.osgeo.org/spearfish/php_grass_earthquakes.php Recent Earthquakes Map]
: ({{website|spearfish/grass_earthquakes.sh|grass_earthquakes.sh shell script}})

=== Parallel GRASS jobs ===

See [[Parallel GRASS jobs]] for openMosix, PBS etc.

=== GRASS Batch jobs ===

There is (now) an alternative method to easily run jobs in GRASS from a collection of commands in a shell script file. Just define the environmental variable GRASS_BATCH_JOB with the shell script file containing GRASS (or whatever) commands, preferably with full path. Then launch GRASS and it will be executed. It is best to launch GRASS in -text mode and to provide GISDBASE/location/mapset as parameters. The job script needs executable file permissions (chmod).

Example:

chmod u+x $HOME/my_grassjob.sh
export GRASS_BATCH_JOB=$HOME/my_grassjob.sh
grass64 ~/grassdata/spearfish60/neteler/

The grass64 command starts GRASS in the given mapset, executes the contents of the job file and leaves GRASS. Since the normal startup/closure is used, all tmp files are properly removed.

Note: The $HOME variable (or the ~ shortcut) cannot be used in the batch job since the variables are not available here.

To deactivate the batch job mode, run (bash example):

unset GRASS_BATCH_JOB

=== Unattended execution ===

* {{wikipedia|GNU_Screen}} is another ''extremely'' valuable tool if you need to detatch and leave long-running processes unattended. It is well worth your time to learn how to use it if you run scripts on remote systems. There are many good tutorials on the web.
: Usage:
:: Run "screen" in the terminal. You will reach again the command line but now in screen mode. Now start GRASS.
::: - To disconnect from the session press Control-A, Control-D.
::: - To list your screens type "screen -ls" (to find it back)
::: - To reconnect with a disconnected screen run "screen -r [identifier]" (the "identifier" you need only if you have several screens running)
:: Enjoy.

* Along with the "{{wikipedia|nohup}}" (no hang-up) command you can login to your machine, launch the job and leave the machine again.
The process will continue after you logged off when you start it with nohup:
nohup grass64 ~/grassdata/spearfish60/neteler/ &

=== Receive a notification when finished ===

Maybe put email notification at the end of 'my_grassjob.sh' using the "mail" or the "mutt" program, for example like this:

echo "Finished at `date`" > /tmp/done.txt && \
EDITOR=touch mutt -s "Job done" \
me@mydomain.org < /tmp/done.txt && rm -f /tmp/done.txt

or like this:
mail -s "GRASS job $0 finished" me@mydomain.org <<EOF
GRASS GIS has finished the batch job $0
EOF

=== See also ===

* Other GRASS environment {{cmd|variables}}
* [[GRASS_and_Python#Python-SWIG-GRASS_interface|SWIG bindings]] (Python/Perl/etc)
* Advance bash-scripting guide [http://tldp.org/LDP/abs/abs-guide.pdf]
* [[Working with GRASS without starting it explicitly]]

[[Category:FAQ]]
[[Category:Linking to other languages]]

Digitizing Area Features

2010-04-18T19:59:08Z

⚠️Caitifty: /* Specific instructions for digitizing areas */ change code snippet to use <source> tag

=Digitizing area features with attributes=

==Introduction==
GIS users with experience creating and editing non-topological shapefiles sometimes encounter problems when adding attributes to area features in the GRASS digitizer <tt> v.digit </tt>. This section will attempt to offer a few tips and clear up this issue. Much has already been written explaining the strict topological vector model which GRASS uses. Please read first: 
:from the wiki- [http://grass.osgeo.org/wiki/Vector_FAQ_GRASS6] [http://grass.osgeo.org/wiki/Vectordata] 
:and from the manual pages- [http://grass.osgeo.org/grass63/manuals/html63_user/vectorintro.html]

==Problem Description==
When creating a polygon shapefile, after the user finishes clicking around the perimeter of the polygon, GIS software applications will often pop up a window with all the attribute columns available and the user enters values for that polygon. In the non-topological shapefile format, the area boundary and the enclosed polygon are one and the same. Thus the boundary attributes also refer to the enclosed area. In the shapefile diagram below the labels A-1, A-2, A-3 are taken from the polygon attribute table. This fact might seem so obvious to shapefile users that they would wonder why it needs mentioning.

In the strict topological model used in GRASS, this is not the case. In a GRASS vector the surrounding boundary, and its enclosed area are two separate entities, which have two separate rows in the accompanying attribute table. The boundary is made up of line segments, and the area is represented by its ''centroid'' – a point within the closed boundary. (Centroids should be placed only within closed boundaries.) A line segment which is part of the boundary enclosing an area does not “belong” to that area, rather it often is common to two adjacent areas. In the GRASS vector diagram below, boundary B-1 separates areas A-1 and A-2. Boundaries B-3 and B-8 separate between areas A-1 and A-3. Furthermore, the boundary of area A-2 is composed of B-1, B-2 and B-5. Obviously it would not make sense to attach '''area''' attributes to any boundary, so instead the area ''centroids'' serve to connect to the attribute table rows holding the area attributes. Thus, the labels B-1, B-2, etc. come from the vector attribute table (line features) and the A-1, A-2 labels, also from the attribute table, are ''centroid'' features. Using the GRASS digitizer, <tt>v.digit</tt>, care needs to be taken to attach attributes to the correct features.

[[Image:Shape.png|left|400px]] [[Image:Grass_vectors.png|center|400px]]

==Best Practices==
First, it's worth pointing out that when using <tt>v.in.ogr</TT> to import a polygon shapefile into GRASS, steps are automatically taken to insure that the resulting vector gets the attributes as expected. (This behind-the-scenes procedure might actually fool naive users into believing that GRASS vectors are just like polygon shapefiles).
*Polygons are imported as boundary lines
*These lines are split at intersections, and all overlapping boundaries are removed (topologically cleaned)
*Centroids are placed in each closed boundary
*The centroids are given a cat value, and attributes from the original shapefile are inserted into the attached database

Following are suggestions for adding attributes when using the GRASS digitizer, which more or less duplicate the above process. Detailed explanations of the <tt>v.digit</tt> interface can be found both in the GRASS ([http://www.grassbook.org/ Book]) and the GDF Hannover ([http://www.gdf-hannover.de/lit_html/grass60_v1.2_en/node56.html tutorial]). The new wxGUI digitizer has a good manual page at: [http://grass.osgeo.org/grass64/manuals/html64_user/wxGUI.Vector_Digitizing_Tool.html]

===General case===
The process that users should follow when manually creating area vectors with <tt>v.digit</tt> will produce boundaries with no attributes, and a centroid connected thru its cat value to the area attributes. First, in the <tt>v.digit</tt> interface, use the settings dialog to set up the attribute table as required by the data, and choose an appropriate snapping tolerance. Also in the settings dialog, under the Attributes tab, there is a drop down list to choose Category Mode (how the cat values will be chosen). For digitizing boundaries, it is possible to choose “No category” since, as explained above, the boundary lines themselves might not require any attributes. Next digitize boundaries, being careful to
*close boundaries which delineate areas.
*never digitize the boundary between adjacent areas twice
*be sure to enter a node at every intersection of two boundary lines (no crossing boundaries without an intersection node)
Now, back in the Settings->Attributes window, reset the Category Mode to “Next not used”, and begin to digitize centroids for each area. After marking the location for a centroid, enter all attribute data into the table relevant to that area. And that's it.

===A Special Case===
There are situations where attributes need to be attached also to the boundary lines. For example: in a project mapping out species distribution, the boundaries might have an attribute value indicating the rate of spread of a species across a border. In this case, the boundaries will get a cat value (optionally defined as a separate GRASS “layer”, with a separate database connection). While digitizing, the user will enter values into the attribute table relevant to each boundary. But still, centroids need to be digitized, and attributes entered for each centroid which are relevant to the areas.

===Another Special Case===
In some situations a single boundary line exactly encompasses an area, with no adjacent areas. (In other words, each area is an “isle” in GRASS terminology.) An example might be a vector map of water bodies. Obviously no water body touches any other. And the perimeter is one continuous line. Users might want the attribute table to be attached to both the area and the boundary – perhaps to display the length of the perimeter along the perimeter rather than at the centroid. In order to achieve this, boundaries will be digitized with a cat value, and the centroids will be forced to use that same cat value as the boundary. This is done as follows. While working on the boundary, the user should take note of its category value. Next, before marking the centroid, the user will switch the Category Mode to “Manual entry”. Now she digitizes the centroid for that closed boundary and manually types in the same cat value as the surrounding boundary. This creates two vector features: a boundary line and a centroid, with identical category values, and thus a single row in the database. So all attributes are common to both the boundary and the centroid (area).

===Note: v.centroids===
The GRASS tool for adding missing centroids to closed boundaries is <tt>v.centroids</tt>. It is important to realize that the centroids will be created with category values that have no connection to the enclosing boundaries. If you run <tt>v.centroids</tt> on a vector that already has closed boundary lines with attribute values, these attribute values will '''not be attached to the area enclosed''', since the new centroids will be assigned some new category value. This point is explained in the <tt>v.centroids</tt> [[http://grass.osgeo.org/grass63/manuals/html63_user/v.centroids.html manual]] page.

--[[User:Micha|Micha]] 22:12, 14 February 2009 (UTC)

===Specific instructions for digitizing areas===

I found this issue to be not that well documented, so here's a specific method for digitizing areas:

An area comprises two primitives - a boundary and a centroid. The boundary has no attributes; the centroid holds the attributes (if any).

To create an area, a two step process is needed. First, a boundary is defined, then a centroid added. You can batch them - define all the boundaries then add the centroids. I don't know the rules for overlapping areas though - might be better to do those separately.

In this example, you have some existing map layers (for example a layer showing some parks as areas and a layer showing roads) and you want to create a new area by manually digitizing an area based on the existing map layers (eg you want to digitize an area bounded by some specific streets near a park).

These steps create a new map, give it an attribute table, link the attribute table to the map, and open the new map in v.digit displaying the existing layer/s:

<source lang="bash">
v.in.ascii -e output=newmapname
echo 'create table newmapname (cat integer, DAY date)' | db.execute
v.db.connect -o map=newmapname table=newmapname
v.digit map=newmapname bgcmd="d.vect map=existingmap1 type=area fcolor=green; d.vect map=existingmap2"
</source>

You can create as many attribute fields as you want within the () area, using whatever field types are allowable for the database type you're using. If you're using an 'external' database type like mysql, you can also just create a cat field in this step and use regular mysql commands or tools to add additional fields to the table if that's easier.

In the window that opens, zoom the the relevant area, then click the 'Digitize new boundary' button. IMPORTANT: Before doing anything else, CHANGE MODE TO 'No Category'. Use the tool to define the boundary of the area, and right-click to close the boundary. If the boundary is successfully closed, the boundary line will turn bright green. If not, it'll remain grey. Easiest fix is to click the 'move vertex' button, move one of the vertices back a bit, then using the 'create new boundary' tool, join the two red crosses. This almost always works, for some reason I can never get the original boundary to join properly. The 'settings' tool also lets you change snapping distance, but altering that hasn't helped me much yet. If the boundary isn't bright green after all this, it isn't closed and the next step won't work.

Select the 'Digitize new centroid' tool. IMPORTANT: Before continuing, CHANGE MODE BACK TO 'Next not used'. Use the tool to select somewhere inside the boundary. The attributes window will open, and you can fill in any area attributes you've created columns for.

You've now created a new area with attributes. Yay.

Click 'Save and exit'. You're done.

Digitizing Area Features

2010-04-18T19:55:51Z

⚠️Caitifty: /* Specific instructions for digitizing areas */ fix linewrap on code

=Digitizing area features with attributes=

==Introduction==
GIS users with experience creating and editing non-topological shapefiles sometimes encounter problems when adding attributes to area features in the GRASS digitizer <tt> v.digit </tt>. This section will attempt to offer a few tips and clear up this issue. Much has already been written explaining the strict topological vector model which GRASS uses. Please read first: 
:from the wiki- [http://grass.osgeo.org/wiki/Vector_FAQ_GRASS6] [http://grass.osgeo.org/wiki/Vectordata] 
:and from the manual pages- [http://grass.osgeo.org/grass63/manuals/html63_user/vectorintro.html]

==Problem Description==
When creating a polygon shapefile, after the user finishes clicking around the perimeter of the polygon, GIS software applications will often pop up a window with all the attribute columns available and the user enters values for that polygon. In the non-topological shapefile format, the area boundary and the enclosed polygon are one and the same. Thus the boundary attributes also refer to the enclosed area. In the shapefile diagram below the labels A-1, A-2, A-3 are taken from the polygon attribute table. This fact might seem so obvious to shapefile users that they would wonder why it needs mentioning.

In the strict topological model used in GRASS, this is not the case. In a GRASS vector the surrounding boundary, and its enclosed area are two separate entities, which have two separate rows in the accompanying attribute table. The boundary is made up of line segments, and the area is represented by its ''centroid'' – a point within the closed boundary. (Centroids should be placed only within closed boundaries.) A line segment which is part of the boundary enclosing an area does not “belong” to that area, rather it often is common to two adjacent areas. In the GRASS vector diagram below, boundary B-1 separates areas A-1 and A-2. Boundaries B-3 and B-8 separate between areas A-1 and A-3. Furthermore, the boundary of area A-2 is composed of B-1, B-2 and B-5. Obviously it would not make sense to attach '''area''' attributes to any boundary, so instead the area ''centroids'' serve to connect to the attribute table rows holding the area attributes. Thus, the labels B-1, B-2, etc. come from the vector attribute table (line features) and the A-1, A-2 labels, also from the attribute table, are ''centroid'' features. Using the GRASS digitizer, <tt>v.digit</tt>, care needs to be taken to attach attributes to the correct features.

[[Image:Shape.png|left|400px]] [[Image:Grass_vectors.png|center|400px]]

==Best Practices==
First, it's worth pointing out that when using <tt>v.in.ogr</TT> to import a polygon shapefile into GRASS, steps are automatically taken to insure that the resulting vector gets the attributes as expected. (This behind-the-scenes procedure might actually fool naive users into believing that GRASS vectors are just like polygon shapefiles).
*Polygons are imported as boundary lines
*These lines are split at intersections, and all overlapping boundaries are removed (topologically cleaned)
*Centroids are placed in each closed boundary
*The centroids are given a cat value, and attributes from the original shapefile are inserted into the attached database

Following are suggestions for adding attributes when using the GRASS digitizer, which more or less duplicate the above process. Detailed explanations of the <tt>v.digit</tt> interface can be found both in the GRASS ([http://www.grassbook.org/ Book]) and the GDF Hannover ([http://www.gdf-hannover.de/lit_html/grass60_v1.2_en/node56.html tutorial]). The new wxGUI digitizer has a good manual page at: [http://grass.osgeo.org/grass64/manuals/html64_user/wxGUI.Vector_Digitizing_Tool.html]

===General case===
The process that users should follow when manually creating area vectors with <tt>v.digit</tt> will produce boundaries with no attributes, and a centroid connected thru its cat value to the area attributes. First, in the <tt>v.digit</tt> interface, use the settings dialog to set up the attribute table as required by the data, and choose an appropriate snapping tolerance. Also in the settings dialog, under the Attributes tab, there is a drop down list to choose Category Mode (how the cat values will be chosen). For digitizing boundaries, it is possible to choose “No category” since, as explained above, the boundary lines themselves might not require any attributes. Next digitize boundaries, being careful to
*close boundaries which delineate areas.
*never digitize the boundary between adjacent areas twice
*be sure to enter a node at every intersection of two boundary lines (no crossing boundaries without an intersection node)
Now, back in the Settings->Attributes window, reset the Category Mode to “Next not used”, and begin to digitize centroids for each area. After marking the location for a centroid, enter all attribute data into the table relevant to that area. And that's it.

===A Special Case===
There are situations where attributes need to be attached also to the boundary lines. For example: in a project mapping out species distribution, the boundaries might have an attribute value indicating the rate of spread of a species across a border. In this case, the boundaries will get a cat value (optionally defined as a separate GRASS “layer”, with a separate database connection). While digitizing, the user will enter values into the attribute table relevant to each boundary. But still, centroids need to be digitized, and attributes entered for each centroid which are relevant to the areas.

===Another Special Case===
In some situations a single boundary line exactly encompasses an area, with no adjacent areas. (In other words, each area is an “isle” in GRASS terminology.) An example might be a vector map of water bodies. Obviously no water body touches any other. And the perimeter is one continuous line. Users might want the attribute table to be attached to both the area and the boundary – perhaps to display the length of the perimeter along the perimeter rather than at the centroid. In order to achieve this, boundaries will be digitized with a cat value, and the centroids will be forced to use that same cat value as the boundary. This is done as follows. While working on the boundary, the user should take note of its category value. Next, before marking the centroid, the user will switch the Category Mode to “Manual entry”. Now she digitizes the centroid for that closed boundary and manually types in the same cat value as the surrounding boundary. This creates two vector features: a boundary line and a centroid, with identical category values, and thus a single row in the database. So all attributes are common to both the boundary and the centroid (area).

===Note: v.centroids===
The GRASS tool for adding missing centroids to closed boundaries is <tt>v.centroids</tt>. It is important to realize that the centroids will be created with category values that have no connection to the enclosing boundaries. If you run <tt>v.centroids</tt> on a vector that already has closed boundary lines with attribute values, these attribute values will '''not be attached to the area enclosed''', since the new centroids will be assigned some new category value. This point is explained in the <tt>v.centroids</tt> [[http://grass.osgeo.org/grass63/manuals/html63_user/v.centroids.html manual]] page.

--[[User:Micha|Micha]] 22:12, 14 February 2009 (UTC)

===Specific instructions for digitizing areas===

I found this issue to be not that well documented, so here's a specific method for digitizing areas:

An area comprises two primitives - a boundary and a centroid. The boundary has no attributes; the centroid holds the attributes (if any).

To create an area, a two step process is needed. First, a boundary is defined, then a centroid added. You can batch them - define all the boundaries then add the centroids. I don't know the rules for overlapping areas though - might be better to do those separately.

In this example, you have some existing map layers (for example a layer showing some parks as areas and a layer showing roads) and you want to create a new area by manually digitizing an area based on the existing map layers (eg you want to digitize an area bounded by some specific streets near a park).

These steps create a new map, give it an attribute table, link the attribute table to the map, and open the new map in v.digit displaying the existing layer/s:

<code>
v.in.ascii -e output=newmapname

echo 'create table newmapname (cat integer, DAY date)' | db.execute

v.db.connect -o map=newmapname table=newmapname

v.digit map=newmapname bgcmd="d.vect map=existingmap1 type=area fcolor=green; d.vect map=existingmap2"
</code>

You can create as many attribute fields as you want within the () area, using whatever field types are allowable for the database type you're using. If you're using an 'external' database type like mysql, you can also just create a cat field in this step and use regular mysql commands or tools to add additional fields to the table if that's easier.

In the window that opens, zoom the the relevant area, then click the 'Digitize new boundary' button. IMPORTANT: Before doing anything else, CHANGE MODE TO 'No Category'. Use the tool to define the boundary of the area, and right-click to close the boundary. If the boundary is successfully closed, the boundary line will turn bright green. If not, it'll remain grey. Easiest fix is to click the 'move vertex' button, move one of the vertices back a bit, then using the 'create new boundary' tool, join the two red crosses. This almost always works, for some reason I can never get the original boundary to join properly. The 'settings' tool also lets you change snapping distance, but altering that hasn't helped me much yet. If the boundary isn't bright green after all this, it isn't closed and the next step won't work.

Select the 'Digitize new centroid' tool. IMPORTANT: Before continuing, CHANGE MODE BACK TO 'Next not used'. Use the tool to select somewhere inside the boundary. The attributes window will open, and you can fill in any area attributes you've created columns for.

You've now created a new area with attributes. Yay.

Click 'Save and exit'. You're done.

Digitizing Area Features

2010-04-17T20:44:29Z

⚠️Caitifty: Add specific directions for creating an area/centroid with attributes

=Digitizing area features with attributes=

==Introduction==
GIS users with experience creating and editing non-topological shapefiles sometimes encounter problems when adding attributes to area features in the GRASS digitizer <tt> v.digit </tt>. This section will attempt to offer a few tips and clear up this issue. Much has already been written explaining the strict topological vector model which GRASS uses. Please read first: 
:from the wiki- [http://grass.osgeo.org/wiki/Vector_FAQ_GRASS6] [http://grass.osgeo.org/wiki/Vectordata] 
:and from the manual pages- [http://grass.osgeo.org/grass63/manuals/html63_user/vectorintro.html]

==Problem Description==
When creating a polygon shapefile, after the user finishes clicking around the perimeter of the polygon, GIS software applications will often pop up a window with all the attribute columns available and the user enters values for that polygon. In the non-topological shapefile format, the area boundary and the enclosed polygon are one and the same. Thus the boundary attributes also refer to the enclosed area. In the shapefile diagram below the labels A-1, A-2, A-3 are taken from the polygon attribute table. This fact might seem so obvious to shapefile users that they would wonder why it needs mentioning.

In the strict topological model used in GRASS, this is not the case. In a GRASS vector the surrounding boundary, and its enclosed area are two separate entities, which have two separate rows in the accompanying attribute table. The boundary is made up of line segments, and the area is represented by its ''centroid'' – a point within the closed boundary. (Centroids should be placed only within closed boundaries.) A line segment which is part of the boundary enclosing an area does not “belong” to that area, rather it often is common to two adjacent areas. In the GRASS vector diagram below, boundary B-1 separates areas A-1 and A-2. Boundaries B-3 and B-8 separate between areas A-1 and A-3. Furthermore, the boundary of area A-2 is composed of B-1, B-2 and B-5. Obviously it would not make sense to attach '''area''' attributes to any boundary, so instead the area ''centroids'' serve to connect to the attribute table rows holding the area attributes. Thus, the labels B-1, B-2, etc. come from the vector attribute table (line features) and the A-1, A-2 labels, also from the attribute table, are ''centroid'' features. Using the GRASS digitizer, <tt>v.digit</tt>, care needs to be taken to attach attributes to the correct features.

[[Image:Shape.png|left|400px]] [[Image:Grass_vectors.png|center|400px]]

==Best Practices==
First, it's worth pointing out that when using <tt>v.in.ogr</TT> to import a polygon shapefile into GRASS, steps are automatically taken to insure that the resulting vector gets the attributes as expected. (This behind-the-scenes procedure might actually fool naive users into believing that GRASS vectors are just like polygon shapefiles).
*Polygons are imported as boundary lines
*These lines are split at intersections, and all overlapping boundaries are removed (topologically cleaned)
*Centroids are placed in each closed boundary
*The centroids are given a cat value, and attributes from the original shapefile are inserted into the attached database

Following are suggestions for adding attributes when using the GRASS digitizer, which more or less duplicate the above process. Detailed explanations of the <tt>v.digit</tt> interface can be found both in the GRASS ([http://www.grassbook.org/ Book]) and the GDF Hannover ([http://www.gdf-hannover.de/lit_html/grass60_v1.2_en/node56.html tutorial]). The new wxGUI digitizer has a good manual page at: [http://grass.osgeo.org/grass64/manuals/html64_user/wxGUI.Vector_Digitizing_Tool.html]

===General case===
The process that users should follow when manually creating area vectors with <tt>v.digit</tt> will produce boundaries with no attributes, and a centroid connected thru its cat value to the area attributes. First, in the <tt>v.digit</tt> interface, use the settings dialog to set up the attribute table as required by the data, and choose an appropriate snapping tolerance. Also in the settings dialog, under the Attributes tab, there is a drop down list to choose Category Mode (how the cat values will be chosen). For digitizing boundaries, it is possible to choose “No category” since, as explained above, the boundary lines themselves might not require any attributes. Next digitize boundaries, being careful to
*close boundaries which delineate areas.
*never digitize the boundary between adjacent areas twice
*be sure to enter a node at every intersection of two boundary lines (no crossing boundaries without an intersection node)
Now, back in the Settings->Attributes window, reset the Category Mode to “Next not used”, and begin to digitize centroids for each area. After marking the location for a centroid, enter all attribute data into the table relevant to that area. And that's it.

===A Special Case===
There are situations where attributes need to be attached also to the boundary lines. For example: in a project mapping out species distribution, the boundaries might have an attribute value indicating the rate of spread of a species across a border. In this case, the boundaries will get a cat value (optionally defined as a separate GRASS “layer”, with a separate database connection). While digitizing, the user will enter values into the attribute table relevant to each boundary. But still, centroids need to be digitized, and attributes entered for each centroid which are relevant to the areas.

===Another Special Case===
In some situations a single boundary line exactly encompasses an area, with no adjacent areas. (In other words, each area is an “isle” in GRASS terminology.) An example might be a vector map of water bodies. Obviously no water body touches any other. And the perimeter is one continuous line. Users might want the attribute table to be attached to both the area and the boundary – perhaps to display the length of the perimeter along the perimeter rather than at the centroid. In order to achieve this, boundaries will be digitized with a cat value, and the centroids will be forced to use that same cat value as the boundary. This is done as follows. While working on the boundary, the user should take note of its category value. Next, before marking the centroid, the user will switch the Category Mode to “Manual entry”. Now she digitizes the centroid for that closed boundary and manually types in the same cat value as the surrounding boundary. This creates two vector features: a boundary line and a centroid, with identical category values, and thus a single row in the database. So all attributes are common to both the boundary and the centroid (area).

===Note: v.centroids===
The GRASS tool for adding missing centroids to closed boundaries is <tt>v.centroids</tt>. It is important to realize that the centroids will be created with category values that have no connection to the enclosing boundaries. If you run <tt>v.centroids</tt> on a vector that already has closed boundary lines with attribute values, these attribute values will '''not be attached to the area enclosed''', since the new centroids will be assigned some new category value. This point is explained in the <tt>v.centroids</tt> [[http://grass.osgeo.org/grass63/manuals/html63_user/v.centroids.html manual]] page.

--[[User:Micha|Micha]] 22:12, 14 February 2009 (UTC)

===Specific instructions for digitizing areas===

I found this issue to be not that well documented, so here's a specific method for digitizing areas:

An area comprises two primitives - a boundary and a centroid. The boundary has no attributes; the centroid holds the attributes (if any).

To create an area, a two step process is needed. First, a boundary is defined, then a centroid added. You can batch them - define all the boundaries then add the centroids. I don't know the rules for overlapping areas though - might be better to do those separately.

In this example, you have some existing map layers (for example a layer showing some parks as areas and a layer showing roads) and you want to create a new area by manually digitizing an area based on the existing map layers (eg you want to digitize an area bounded by some specific streets near a park).

These steps create a new map, give it an attribute table, link the attribute table to the map, and open the new map in v.digit displaying the existing layer/s:

<code>
v.in.ascii -e output=newmapname
echo 'create table newmapname (cat integer, DAY date)' | db.execute
v.db.connect -o map=newmapname table=newmapname
v.digit map=newmapname bgcmd="d.vect map=existingmap1 type=area fcolor=green; d.vect map=existingmap2"
</code>

You can create as many attribute fields as you want within the () area, using whatever field types are allowable for the database type you're using. If you're using an 'external' database type like mysql, you can also just create a cat field in this step and use regular mysql commands or tools to add additional fields to the table if that's easier.

In the window that opens, zoom the the relevant area, then click the 'Digitize new boundary' button. IMPORTANT: Before doing anything else, CHANGE MODE TO 'No Category'. Use the tool to define the boundary of the area, and right-click to close the boundary. If the boundary is successfully closed, the boundary line will turn bright green. If not, it'll remain grey. Easiest fix is to click the 'move vertex' button, move one of the vertices back a bit, then using the 'create new boundary' tool, join the two red crosses. This almost always works, for some reason I can never get the original boundary to join properly. The 'settings' tool also lets you change snapping distance, but altering that hasn't helped me much yet. If the boundary isn't bright green after all this, it isn't closed and the next step won't work.

Select the 'Digitize new centroid' tool. IMPORTANT: Before continuing, CHANGE MODE BACK TO 'Next not used'. Use the tool to select somewhere inside the boundary. The attributes window will open, and you can fill in any area attributes you've created columns for.

You've now created a new area with attributes. Yay.

Click 'Save and exit'. You're done.