Geografic-Information-System/lib/gis/gisvectorlib.dox

/*! \page gisvectorlib Vector File Processing
<!-- doxygenized from "GRASS 5 Programmer's Manual" 
     by M. Neteler 2/2004, 2006
  -->

See especially \ref Vector_Library for details (extra page). 

- \subpage gisvectintro
- \subpage Creating_and_Opening_New_Vector_Files
- \subpage Vector_Category_File

\section gisvectintro GRASS Vector File Processing
Authors:
<BR>
(Written by CERL,  with contributions from David D. Gray)
<P>
The <I>GIS Library</I> contains some functions related to vector file
processing. These include prompting the user for vector files,
locating vector files in the database, opening vector files, and a few
others.

<P>
<B>Note.</B> Most vector file processing, however, is handled by
routines in the <I>Vector Library</I>, which is described in
Vector_Library.

<P>


\subsection Prompting_for_Vector_Files Prompting for Vector Files

<P>
The following routines interactively prompt the user for a vector file
name.  In each, the <B>prompt</B> string will be printed as the first
line of the full prompt which asks the user to enter a vector file
name. If <B>prompt</B> is the empty string "" then an appropriate
prompt will be substituted. The name that the user enters is copied
into the <B>name</B> buffer. The size of name should be large enough
to hold any GRASS file name. Most systems allow file names to be quite
long. It is recommended that name be declared <tt>char name</tt>.
These routines have a built-in 'list' capability which allows the user
to get a list of existing vector files.

<P>
The user is required to enter a valid vector file name, or else hit
the RETURN key to cancel the request. If the user enters an invalid
response, a message is printed, and the user is prompted again. If the
user cancels the request, the NULL pointer is returned. Otherwise the
mapset where the vector file lives or is to be created is
returned. Both the name and the mapset are used in other routines to
refer to the vector file.


<P>
char *G_ask_vector_old(char *prompt, char *name) prompt for an
existing vector file

Asks the user to enter the name of an existing vector file in any
mapset in the database.

<P>
char *G_ask_vector_in_mapset(char *prompt, char *name) prompt for an
existing vector file

Asks the user to enter the name of an existing vector file in the
current mapset.

<P>
char *G_ask_vector_new(char *prompt, char *name) prompt for a new
vector file

Asks the user to enter a name for a vector file which does not exist
in the current mapset.

<P>
Here is an example of how to use these routines. Note that the
programmer must handle the NULL return properly:

\verbatim
char *mapset;
char name[GNAME_MAX];

mapset = G_ask_vector_old("Enter vector file to be processed", name);

if (mapset == NULL)
   exit(0);
\endverbatim


\subsection Finding_Vector_Files_in_the_Database Finding Vector Files
      in the Database


<P>
Noninteractive modules cannot make use of the interactive prompting
routines described above. For example, a command line driven module
may require a vector file name as one of the command arguments. GRASS
allows the user to specify vector file names (or any other database
file) either as a simple unqualified name, such as "roads", or as a
fully qualified name, such as "roads in <I>mapset</I>", where
<I>mapset</I> is the mapset where the vector file is to be
found. Often only the unqualified vector file name is provided on the
command line.

<P>
The following routines search the database for vector files:

<P>
int G_find_vector(char *name, char *mapset) find a vector file 

<P>
int G_find_vector2(char *name, char *mapset) find a vector
  file

Look for the vector file <B>name</B> in the database. The
<B>mapset</B> parameter can either be the empty string "", which means
search all the mapsets in the user's current mapset search path (see
Mapset_Search_Path for more details about the search path), or it can
be a specific mapset name, which means look for the vector file only
in this one mapset (for example, in the current mapset). If found, the
mapset where the vector file lives is returned. If not found, the NULL
pointer is returned.

<P>
The difference between these two routines is that if the user
specifies a fully qualified vector file which exists, then
<I>G_find_vector2()</I> modifies <B>name</B> by removing the "in
<I>mapset</I>" while <I>G_find_vector()</I> does not. Be warned that
G_find_vector2() should not be used directly on a command line
argument, since modifying argv[ ] may not be valid. The argument
should be copied to another character buffer which is then passed to
G_find_vector2(). Normally, the GRASS programmer need not worry about
qualified vs.  unqualified names since all library routines handle
both forms. However, if the programmer wants the name to be returned
unqualified (for displaying the name to the user, or storing it in a
data file, etc.), then <I>G_find_vector2()</I> should be used.

<P>
For example, to find a vector file anywhere in the database:

\verbatim
char name[GNAME_MAX];
char *mapset;

if ((mapset = G_find_vector(name,"")) == NULL)
   /* not found */
\endverbatim

\verbatim

char name[GNAME_MAX];

if (G_find_vector(name,G_mapset()) == NULL)
   /* not found */
\endverbatim

To check that the vector file exists in the current mapset:


\subsection Opening_an_Existing_Vector_File Opening an Existing Vector File


The following routine opens the vector file <B>name</B> in
<B>mapset</B> for reading.

<P>
The vector file <B>name</B> and <B>mapset</B> can be obtained
interactively using <I>G_ask_vector_old()</I> or <I>
G_ask_vector_in_mapset()</I>, and noninteractively using
<I>G_find_vector()</I> or <I>G_find_vector2().</I>

<P>
FILE *G_fopen_vector_old(char *name, char *mapset) open an existing
vector file

This routine opens the vector file <B>name</B> in <B>mapset</B> for
reading. A file descriptor is returned if the open is
successful. Otherwise the NULL pointer is returned (no diagnostic
message is printed).

<P>
The file descriptor can then be used with routines in the <I>Dig
Library</I> to read the vector file (See \ref Vector_Library).

<P>
<B>Note.</B> This routine does not call any routines in the <I>Dig
Library</I>; No initialization of the vector file is done by this
routine, directly or indirectly.



\section Creating_and_Opening_New_Vector_Files Creating and Opening
      New Vector Files


The following routine creates the new vector file <B>name</B> in the
current mapset (GRASS does not allow files to be created outside the
current mapset. See \ref Database_Access_Rules) and opens it for
writing. The vector file <B>name</B> should be obtained interactively
using <I>G_ask_vector_new().</I> If obtained noninteractively (e.g.,
from the command line), <I>G_legal_filename()</I> should be called
first to make sure that <B>name</B> is a valid GRASS file name.

<P>
<B>Warning.</B> If <B>name</B> already exists, it will be erased and
re-created empty. The interactive routine <I>G_ask_vector_new()</I>
guarantees that <B>name</B> will not exist, but if <B>name</B> is
obtained from the command line, <B>name</B> may exist. In this case
<I>G_find_vector()</I> could be used to see if <B>name</B> exists.

<P>
FILE *G_fopen_vector_new(char *name) open a new vector file

Creates and opens the vector file <B>name</B> for writing.

<P>
A file descriptor is returned if the open is successful. Otherwise the
NULL pointer is returned (no diagnostic message is printed).

<P>
The file descriptor can then be used with routines in the <I>Dig 
Library</I> to write the <I>vector file</I> (See \ref Vector_Library.)

<P>
<B>Note.</B> This routine does not call any routines in the <I>Dig
Library</I>; No initialization of the vector file is done by this
routine, directly or indirectly. Also, only the vector file itself
(i.e., the <I>dig</I> file), is created. None of the other vector
support files are created, removed, or modified in any way.


\subsection Reading_and_Writing_Vector_Files Reading and Writing Vector Files


Reading and writing vector files is handled by routines in the <I>Dig
Library.</I> See \ref Vector_Library for details.


\section Vector_Category_File Vector Category File

GRASS vector files have category labels associated with them. The
category file is structured so that each category in the vector file
can have a one-line description.

<P>
The routines described below read and write the vector category
file. They use the <I>Categories structure</I> which is described in
GIS_Library_Data_Structures.

<P>
<B>Note.</B> The vector category file has exactly the same structure
as the raster category file. In fact, it exists so that the module
<I>v.to.rast</I> can convert a vector file to a raster file that has
an up-to-date category file.

<P>
The routines described in
Querying_and_Changing_the_Categories_Structure which modify the
<I>Categories</I> structure can therefore be used to set and change
vector categories as well.

<P>
int G_read_vector_cats(char *name, name *mapset, struct Categories
*cats) read vector category file

The category file for vector file <B>name</B> in <B>mapset</B> is read
into the <B>cats</B> structure. If there is an error reading the
category file, a diagnostic message is printed and -1 is
returned. Otherwise, 0 is returned.

<P>
int G_write_vector_cats(char *name, struct Categories *cats) write
vector category file

Writes the category file for the vector file <B>name</B> in the
current mapset from the <B>cats</B> structure.

<P>
Returns 1 if successful. Otherwise, -1 is returned (no diagnostic is
printed).

*/