|
|
@@ -1,282 +0,0 @@
|
|
|
-/*! \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).
|
|
|
-
|
|
|
-*/
|
Martin Landa