← Back to branch summary

~ubuntu-branches/ubuntu/vivid/grass/vivid-proposed

« back to all changes in this revision

Viewing changes to lib/gis/gisvectorlib.dox

  • Committer: Package Import Robot
  • Author(s): Bas Couwenberg
  • Date: 2015-02-20 23:12:08 UTC
  • mfrom: (8.2.6 experimental)
  • Revision ID: package-import@ubuntu.com-20150220231208-1u6qvqm84v430b10
Tags: 7.0.0-1~exp1
* New upstream release.
* Update python-ctypes-ternary.patch to use if/else instead of and/or.
* Drop check4dev patch, rely on upstream check.
* Add build dependency on libpq-dev to grass-dev for libpq-fe.h.
* Drop patches applied upstream, refresh remaining patches.
* Update symlinks for images switched from jpg to png.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/gis/gisvectorlib.dox
1
 
/*! \page gisvectorlib Vector File Processing
2
 
<!-- doxygenized from "GRASS 5 Programmer's Manual" 
3
 
     by M. Neteler 2/2004, 2006
4
 
  -->
5
 
 
6
 
See especially \ref Vector_Library for details (extra page). 
7
 
 
8
 
- \subpage gisvectintro
9
 
- \subpage Creating_and_Opening_New_Vector_Files
10
 
- \subpage Vector_Category_File
11
 
 
12
 
\section gisvectintro GRASS Vector File Processing
13
 
Authors:
14
 
<BR>
15
 
(Written by CERL,  with contributions from David D. Gray)
16
 
<P>
17
 
The <I>GIS Library</I> contains some functions related to vector file
18
 
processing. These include prompting the user for vector files,
19
 
locating vector files in the database, opening vector files, and a few
20
 
others.
21
 
 
22
 
<P>
23
 
<B>Note.</B> Most vector file processing, however, is handled by
24
 
routines in the <I>Vector Library</I>, which is described in
25
 
Vector_Library.
26
 
 
27
 
<P>
28
 
 
29
 
 
30
 
\subsection Prompting_for_Vector_Files Prompting for Vector Files
31
 
 
32
 
<P>
33
 
The following routines interactively prompt the user for a vector file
34
 
name.  In each, the <B>prompt</B> string will be printed as the first
35
 
line of the full prompt which asks the user to enter a vector file
36
 
name. If <B>prompt</B> is the empty string "" then an appropriate
37
 
prompt will be substituted. The name that the user enters is copied
38
 
into the <B>name</B> buffer. The size of name should be large enough
39
 
to hold any GRASS file name. Most systems allow file names to be quite
40
 
long. It is recommended that name be declared <tt>char name</tt>.
41
 
These routines have a built-in 'list' capability which allows the user
42
 
to get a list of existing vector files.
43
 
 
44
 
<P>
45
 
The user is required to enter a valid vector file name, or else hit
46
 
the RETURN key to cancel the request. If the user enters an invalid
47
 
response, a message is printed, and the user is prompted again. If the
48
 
user cancels the request, the NULL pointer is returned. Otherwise the
49
 
mapset where the vector file lives or is to be created is
50
 
returned. Both the name and the mapset are used in other routines to
51
 
refer to the vector file.
52
 
 
53
 
 
54
 
<P>
55
 
char *G_ask_vector_old(char *prompt, char *name) prompt for an
56
 
existing vector file
57
 
 
58
 
Asks the user to enter the name of an existing vector file in any
59
 
mapset in the database.
60
 
 
61
 
<P>
62
 
char *G_ask_vector_in_mapset(char *prompt, char *name) prompt for an
63
 
existing vector file
64
 
 
65
 
Asks the user to enter the name of an existing vector file in the
66
 
current mapset.
67
 
 
68
 
<P>
69
 
char *G_ask_vector_new(char *prompt, char *name) prompt for a new
70
 
vector file
71
 
 
72
 
Asks the user to enter a name for a vector file which does not exist
73
 
in the current mapset.
74
 
 
75
 
<P>
76
 
Here is an example of how to use these routines. Note that the
77
 
programmer must handle the NULL return properly:
78
 
 
79
 
\verbatim
80
 
char *mapset;
81
 
char name[GNAME_MAX];
82
 
 
83
 
mapset = G_ask_vector_old("Enter vector file to be processed", name);
84
 
 
85
 
if (mapset == NULL)
86
 
   exit(0);
87
 
\endverbatim
88
 
 
89
 
 
90
 
\subsection Finding_Vector_Files_in_the_Database Finding Vector Files
91
 
      in the Database
92
 
 
93
 
 
94
 
<P>
95
 
Noninteractive modules cannot make use of the interactive prompting
96
 
routines described above. For example, a command line driven module
97
 
may require a vector file name as one of the command arguments. GRASS
98
 
allows the user to specify vector file names (or any other database
99
 
file) either as a simple unqualified name, such as "roads", or as a
100
 
fully qualified name, such as "roads in <I>mapset</I>", where
101
 
<I>mapset</I> is the mapset where the vector file is to be
102
 
found. Often only the unqualified vector file name is provided on the
103
 
command line.
104
 
 
105
 
<P>
106
 
The following routines search the database for vector files:
107
 
 
108
 
<P>
109
 
int G_find_vector(char *name, char *mapset) find a vector file 
110
 
 
111
 
<P>
112
 
int G_find_vector2(char *name, char *mapset) find a vector
113
 
  file
114
 
 
115
 
Look for the vector file <B>name</B> in the database. The
116
 
<B>mapset</B> parameter can either be the empty string "", which means
117
 
search all the mapsets in the user's current mapset search path (see
118
 
Mapset_Search_Path for more details about the search path), or it can
119
 
be a specific mapset name, which means look for the vector file only
120
 
in this one mapset (for example, in the current mapset). If found, the
121
 
mapset where the vector file lives is returned. If not found, the NULL
122
 
pointer is returned.
123
 
 
124
 
<P>
125
 
The difference between these two routines is that if the user
126
 
specifies a fully qualified vector file which exists, then
127
 
<I>G_find_vector2()</I> modifies <B>name</B> by removing the "in
128
 
<I>mapset</I>" while <I>G_find_vector()</I> does not. Be warned that
129
 
G_find_vector2() should not be used directly on a command line
130
 
argument, since modifying argv[ ] may not be valid. The argument
131
 
should be copied to another character buffer which is then passed to
132
 
G_find_vector2(). Normally, the GRASS programmer need not worry about
133
 
qualified vs.  unqualified names since all library routines handle
134
 
both forms. However, if the programmer wants the name to be returned
135
 
unqualified (for displaying the name to the user, or storing it in a
136
 
data file, etc.), then <I>G_find_vector2()</I> should be used.
137
 
 
138
 
<P>
139
 
For example, to find a vector file anywhere in the database:
140
 
 
141
 
\verbatim
142
 
char name[GNAME_MAX];
143
 
char *mapset;
144
 
 
145
 
if ((mapset = G_find_vector(name,"")) == NULL)
146
 
   /* not found */
147
 
\endverbatim
148
 
 
149
 
\verbatim
150
 
 
151
 
char name[GNAME_MAX];
152
 
 
153
 
if (G_find_vector(name,G_mapset()) == NULL)
154
 
   /* not found */
155
 
\endverbatim
156
 
 
157
 
To check that the vector file exists in the current mapset:
158
 
 
159
 
 
160
 
\subsection Opening_an_Existing_Vector_File Opening an Existing Vector File
161
 
 
162
 
 
163
 
The following routine opens the vector file <B>name</B> in
164
 
<B>mapset</B> for reading.
165
 
 
166
 
<P>
167
 
The vector file <B>name</B> and <B>mapset</B> can be obtained
168
 
interactively using <I>G_ask_vector_old()</I> or <I>
169
 
G_ask_vector_in_mapset()</I>, and noninteractively using
170
 
<I>G_find_vector()</I> or <I>G_find_vector2().</I>
171
 
 
172
 
<P>
173
 
FILE *G_fopen_vector_old(char *name, char *mapset) open an existing
174
 
vector file
175
 
 
176
 
This routine opens the vector file <B>name</B> in <B>mapset</B> for
177
 
reading. A file descriptor is returned if the open is
178
 
successful. Otherwise the NULL pointer is returned (no diagnostic
179
 
message is printed).
180
 
 
181
 
<P>
182
 
The file descriptor can then be used with routines in the <I>Dig
183
 
Library</I> to read the vector file (See \ref Vector_Library).
184
 
 
185
 
<P>
186
 
<B>Note.</B> This routine does not call any routines in the <I>Dig
187
 
Library</I>; No initialization of the vector file is done by this
188
 
routine, directly or indirectly.
189
 
 
190
 
 
191
 
 
192
 
\section Creating_and_Opening_New_Vector_Files Creating and Opening
193
 
      New Vector Files
194
 
 
195
 
 
196
 
The following routine creates the new vector file <B>name</B> in the
197
 
current mapset (GRASS does not allow files to be created outside the
198
 
current mapset. See \ref Database_Access_Rules) and opens it for
199
 
writing. The vector file <B>name</B> should be obtained interactively
200
 
using <I>G_ask_vector_new().</I> If obtained noninteractively (e.g.,
201
 
from the command line), <I>G_legal_filename()</I> should be called
202
 
first to make sure that <B>name</B> is a valid GRASS file name.
203
 
 
204
 
<P>
205
 
<B>Warning.</B> If <B>name</B> already exists, it will be erased and
206
 
re-created empty. The interactive routine <I>G_ask_vector_new()</I>
207
 
guarantees that <B>name</B> will not exist, but if <B>name</B> is
208
 
obtained from the command line, <B>name</B> may exist. In this case
209
 
<I>G_find_vector()</I> could be used to see if <B>name</B> exists.
210
 
 
211
 
<P>
212
 
FILE *G_fopen_vector_new(char *name) open a new vector file
213
 
 
214
 
Creates and opens the vector file <B>name</B> for writing.
215
 
 
216
 
<P>
217
 
A file descriptor is returned if the open is successful. Otherwise the
218
 
NULL pointer is returned (no diagnostic message is printed).
219
 
 
220
 
<P>
221
 
The file descriptor can then be used with routines in the <I>Dig 
222
 
Library</I> to write the <I>vector file</I> (See \ref Vector_Library.)
223
 
 
224
 
<P>
225
 
<B>Note.</B> This routine does not call any routines in the <I>Dig
226
 
Library</I>; No initialization of the vector file is done by this
227
 
routine, directly or indirectly. Also, only the vector file itself
228
 
(i.e., the <I>dig</I> file), is created. None of the other vector
229
 
support files are created, removed, or modified in any way.
230
 
 
231
 
 
232
 
\subsection Reading_and_Writing_Vector_Files Reading and Writing Vector Files
233
 
 
234
 
 
235
 
Reading and writing vector files is handled by routines in the <I>Dig
236
 
Library.</I> See \ref Vector_Library for details.
237
 
 
238
 
 
239
 
\section Vector_Category_File Vector Category File
240
 
 
241
 
GRASS vector files have category labels associated with them. The
242
 
category file is structured so that each category in the vector file
243
 
can have a one-line description.
244
 
 
245
 
<P>
246
 
The routines described below read and write the vector category
247
 
file. They use the <I>Categories structure</I> which is described in
248
 
GIS_Library_Data_Structures.
249
 
 
250
 
<P>
251
 
<B>Note.</B> The vector category file has exactly the same structure
252
 
as the raster category file. In fact, it exists so that the module
253
 
<I>v.to.rast</I> can convert a vector file to a raster file that has
254
 
an up-to-date category file.
255
 
 
256
 
<P>
257
 
The routines described in
258
 
Querying_and_Changing_the_Categories_Structure which modify the
259
 
<I>Categories</I> structure can therefore be used to set and change
260
 
vector categories as well.
261
 
 
262
 
<P>
263
 
int G_read_vector_cats(char *name, name *mapset, struct Categories
264
 
*cats) read vector category file
265
 
 
266
 
The category file for vector file <B>name</B> in <B>mapset</B> is read
267
 
into the <B>cats</B> structure. If there is an error reading the
268
 
category file, a diagnostic message is printed and -1 is
269
 
returned. Otherwise, 0 is returned.
270
 
 
271
 
<P>
272
 
int G_write_vector_cats(char *name, struct Categories *cats) write
273
 
vector category file
274
 
 
275
 
Writes the category file for the vector file <B>name</B> in the
276
 
current mapset from the <B>cats</B> structure.
277
 
 
278
 
<P>
279
 
Returns 1 if successful. Otherwise, -1 is returned (no diagnostic is
280
 
printed).
281
 
 
282
 
*/