1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
|
<HEAD>
<TITLE>GRASS 5.7 Vector Format and API</TITLE>
</HEAD>
<BODY>
<P>
<H1>GRASS 5.7 Vector Format and API</H1>
This document describes new format for <B>GRASS vector files</B> with
<B>multicategory</B> and optional <B>3D</B> support.
<P>
You can send any comments to <A href=mailto:blazek@itc.it>Radim Blazek</A> and
<A href=mailto:ddgray@armadce.demon.co.uk>David D. Gray</A>
<P>
See also:
<ul>
<li><A HREF="http://grass.itc.it/grass57/index.html#development">Draft GRASS 5.7 Programmer's manual</A>
<li><A HREF="http://www.ing.unitn.it/~grass/conferences/GRASS2002/proceedings/proceedings/pdfs/Blazek_Radim.pdf">The
new GRASS 5.1 vector architecture</a>, R. Blazek, M. Neteler, M. Micarelli 2002. Proc. 'Open source GIS -
GRASS users conference', Sept. 2002, Trento, Italy.
</ul>
<h2>GRASS 5.7 vector architecture features </h2>
The new GRASS 5.7 vector architecture implementation covers
the new 3D, multi-attribute, multi-layer vector features.
Current available are:
<ul>
<li> multi-layer: features in one vector may represent more layers and
may be linked to more external tables;
<li> multi-attribute: attributes saved in external Relational Database Management
System (RDBMS) connected through DBMI library and drivers;
<li> 2D and 3D vector geometry with topology;
<li> multi-format: external data formats supported (SHAPE- file, PostGRASS etc.);
<li> portability: platform independent internal format for 32bit,
64bit etc. computer architectures;
<li> integrated Directed Graph Library: support for vector network analysis
<li> spatial index: based on R-tree method for fast vector geometry access
</ul>
<HR>
<ul>
<li><A HREF="#intro">Introduction</A></H4>
<li><A HREF="#dir">Directory structure</A></H4>
<li><A HREF="#coor">coor Format Specification</A></H4>
<li><A HREF="#head">head Format Specification</A></H4>
<li><A HREF="#topo">topo Format Specification</A></H4>
<li><A HREF="#lib">Library</A></H4>
<li><A HREF="#structures">New or Modified Constants, Structures, Functions</A></H4>
<li><A HREF="#attr">Attributes</A></H4>
<li><A HREF="#other">Other informations</A></H4>
<li><A HREF="#ascii">Vector ascii Format Specification</A></H4>
<li><A HREF="#options">Vector modules and options</A></H4>
<li><A HREF="#status">Vector Modules Status</A></H4>
<li><A HREF="#example">Example vector module</A></H4>
</ul>
<HR>
<H2><A NAME="intro">Introduction</A></H2>
<P>
The new format is very similar to old GRASS 4.x (5.0/5.3) vector format.
<P>
GRASS vector maps are stored in an arc-node representation, consisting of
curves called arcs. An arc is stored as a series of x,y,z coordinate pairs.
The two endpoints of an arc are called nodes. Two consecutive x,y,z pairs
define an arc segment. The user specifies the type on input to GRASS,
GRASS doesn't decide. GRASS allows for the line definition which allows
for the multiple type to co-exist in the same map. Centroid are assigned to
area it is within/inside (geometrically). An area is identified by an x,y,z
centroid point geometrically inside with a category number. This identifies
the area. Such centroids are stored in the same binary 'coor' file with
other primitives.
Each element may have none, one or more categories (cats). More cats are
distinguished by field number (field). Single and multi-category support
on modules level is implemented.
Z-coordinate is optional and both 2d and 3d files may be written.
<h3>Topology general characteristics</h3>
<ol>
<li> geometry and attributes are stored separately
(don't read both if it is not necessary (usually it is not))
<li> the format is topological (areas build from boundaries)
</ol>
<HR>
<H2><A NAME="dir">Directory structure</A></H2>
Directory structure and file names are a bit changed.
All vector files for one vector map are stored in one
directory:<BR>
<B>$MAPSET/vector/vector_name/</B> <BR>
This directory contains these files:<BR><BR>
<ul>
<li><b>coor</b> - binary file, coordinates [former dig/ file]
<li><b>topo</b> - binary file, topology [former dig_plus/ file]
<li><b>sidx</b> - binary file, spatial index
<li><b>head</b> - text file, header information [former part of dig/ file]
<li><b>dbln</b> - text file, link(s) to attribute table(s) <br>
<li><b>hist</b> - text file, vector map change history <br>
</ul>
<HR>
<H2><A NAME="coor">coor Format Specification</A></H2>
<H3>Head</H3>
<TABLE border=2>
<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
<TR><TD>Version_Major </TD><TD>C</TD><TD>1</TD><TD> </TD></TR>
<TR><TD>Version_Minor </TD><TD>C</TD><TD>1</TD><TD> </TD></TR>
<TR><TD>Earliest_Major</TD><TD>C</TD><TD>1</TD><TD> </TD></TR>
<TR><TD>Earliest_Minor</TD><TD>C</TD><TD>1</TD><TD> </TD></TR>
<TR><TD>byte_order</TD><TD>C</TD><TD>1</TD><TD>little or big endian flag;
files are written in machine native order but files
in both little and big endian order may be read</TD></TR>
<TR><TD>with_z</TD><TD>C</TD><TD>1</TD><TD>2D or 3D flag</TD></TR>
<TR><TD>size</TD><TD>L</TD><TD>1</TD><TD>coor file size</TD></TR>
<TR><TD>reserved</TD><TD>C</TD><TD>10</TD><TD>not used</TD></TR>
</TABLE>
<H3>Body</H3>
The body consists of line records:
<BR>
<TABLE border=2>
<TR><TD>Name</TD><TD>Type</TD><TD>Number</TD><TD>Description</TD></TR>
<TR><TD>record header</TD><TD>I</TD><TD>1</TD><TD>
<UL>
<LI><B>0. bit</B> : 1 - alive, 0 - dead line
<LI><B>1. bit</B> : 1 - categories, 0 - no categories
<LI><B>2.-3. bit</B> : type - one of: GV_POINT, GV_LINE,
GV_BOUNDARY, GV_CENTROID
<LI><B>4.-7. bit</B> : reserved, not used
<UL>
</TD></TR>
<TR><TD>ncats</TD><TD>C</TD><TD>1</TD><TD>number of categories
(written only if categories exist) </TD></TR>
<TR><TD>field</TD><TD>S</TD><TD>ncats</TD><TD>Category identifier,
distinguishes between more categories append to one line
(written only if categories exist)</TD></TR>
<TR><TD>cat</TD><TD>I</TD><TD>ncats</TD><TD>category value
(written only if categories exist)</TD></TR>
<TR><TD>ncoor</TD><TD>I</TD><TD>1</TD><TD>written for GV_LINES and GV_BOUNDARIES
only</TD></TR>
<TR><TD>x</TD><TD>D</TD><TD>ncoor</TD><TD> </TD></TR>
<TR><TD>y</TD><TD>D</TD><TD>ncoor</TD><TD> </TD></TR>
<TR><TD>z</TD><TD>D</TD><TD>ncoor</TD><TD>present if with_z in head
is set to 1</TD></TR>
</TABLE>
<BR>
<B>Types used in coor file</B>
<TABLE border=2>
<TR><TD>Type</TD><TD>Name</TD><TD>Size in Bytes</TD></TR>
<TR><TD>D</TD><TD>Double</TD><TD>8</TD></TR>
<TR><TD>L</TD><TD>Long </TD><TD>4</TD></TR>
<TR><TD>I</TD><TD>Int </TD><TD>4</TD></TR>
<TR><TD>S</TD><TD>Short </TD><TD>4</TD></TR>
<TR><TD>C</TD><TD>Char </TD><TD>1</TD></TR>
</TABLE>
<HR>
<H2><A NAME="head">head file format</A></H2>
The file is unordered list of key/value entries. The <I>key</I>
is a string separated from <I>value</I> by a colon and optional
whitespace. Key words are:<BR>
<PRE>
ORGANIZATION
DIGIT DATE
DIGIT NAME
MAP NAME
MAP DATE
MAP SCALE
OTHER INFO
ZONE
MAP THRESH
</PRE>
<HR>
<H2><A NAME="topo">topo file format</A></H2>
[docs missing]
<P>
Topology is written for native format, pseudo-topology is
written for PostGRASS, SHAPE-link.
<pre>
/* Vector types used in memory on run time - may change */
#define GV_POINT 0x01
#define GV_LINE 0x02
#define GV_BOUNDARY 0x04
#define GV_CENTROID 0x08
#define GV_FACE 0x10
#define GV_KERNEL 0x20
#define GV_AREA 0x40
</pre>
Face and kernel are 3D equivalents of boundary and centroid, but there
is no support (yet) for 3D topology (volumes). The only current use of
face is possibility to display vertical planes in NVIZ.
<pre>
/* Topology level details */
#define GV_BUILD_NONE 0
#define GV_BUILD_BASE 1
#define GV_BUILD_AREAS 2
#define GV_BUILD_ATTACH_ISLES 3 /* Attach islands to areas */
#define GV_BUILD_CENTROIDS 4 /* Assign centroids to areas */
#define GV_BUILD_ALL GV_BUILD_CENTROIDS
</pre>
GV_BOUNDARY contains geometry and it is used to build areas.
GV_LINE cannot form an area.
<h3>Topology Example 1:</h3>
A polygon may be formed by many boundaries (more primitives but connected).
One boundary is shared by adjacent areas.
<pre>
+--1--+--5--+
| | |
2 A 4 B 6
| | |
+--3--+--7--+
1,2,3,4,5,6,7 = 7 boundaries (primitives)
A,B = 2 areas
</pre>
<h3>Topology Example 2:</h3>
This is handled correctly in GRASS: A can be filled, B filled differently.
<pre>
+---------+
| A |
+-----+ |
| B | |
+-----+ |
| |
+---------+
</pre>
In GRASS, whenever 'inner' ring touches the boundary of outside area, even in
one point, it is no more 'inner' ring, it is simply another area.
A, B above can never be exported from GRASS as polygon A with inner ring B
because there are only 2 areas A and B and no island.
<h3>Topology Example 3:</h3>
v.in.ogr/v.clean can identify dangles and change the type from boundary
to line (in TIGER data for example).
Distinction between line and boundary isn't important only for dangles. Example:
<pre>
+-----+-----+
| . |
| . |
+.....+.....+
| . |
| x . |
+-----+-----+
---- road + boundary of one parcel => type boundary
.... road => type line
x parcel centroid (identifies whole area)
</pre>
Because lines are not used to build areas, we have only one area/centroid,
instead of 4 which would be necessary in TIGER.
<HR>
<H2><A NAME="lib">Library</A></H2>
For historical reasons, there are two libraries for vector: <BR><BR>
diglib, dig_*(), DIGLIB, libdig.a, digit library, grass3.x, 4.x<BR>
and<BR>
Vlib, Vect_*(), VECTLIB_REAL, libvect.a, vector library, grass4.x<BR><BR>
Vector library was introduced in grass4.0 to hide vector files' formats
and structures.
In GRASS 5.7 everything is accessed via Vect_* functions, for example:
<PRE>
xx = Map.Att[Map.Area[area_num].att].x;
</PRE>by new function<PRE>
Vect_get_area_centroid()
Vect_get_centroid_coor()
</PRE>
<P>
<HR>
<H2><A NAME="structures">New or Modified Constants, Structures, Functions</A></H2>
<PRE>
/* types used in memory on run time - may change */
#define GV_POINT 0x01
#define GV_LINE 0x02
#define GV_BOUNDARY 0x04
#define GV_CENTROID 0x08
#define GV_FACE 0x10
#define GV_KERNEL 0x20
#define GV_AREA 0x40
#define GV_VOLUME 0x80
#define GV_POINTS (GV_POINT | GV_CENTROID )
#define GV_LINES (GV_LINE | GV_BOUNDARY )
struct line_cats
{
int *field; /* pointer to array of fields */
int *cat; /* pointer to array of categories */
int n_cats; /* number of vector categories attached to element */
int alloc_cats; /* allocated space */
};
int Vect_open_new (struct Map_info *, char name *, int with_z);
long Vect_write_line (struct Map_info *, int type, struct line_pnts *, struct line_cats *);
int Vect_read_next_line (struct Map_info *, struct line_pnts *, struct line_cats *);
struct line_cats *Vect_new_cats_struct (void);
int Vect_reset_cats (struct line_cats *);
int Vect_destroy_cats_struct (struct line_cats *);
int Vect_cat_set (struct line_cats *, int, int);
int Vect_cat_get (struct line_cats *, int, int *);
int Vect_cat_del (struct line_cats *, int);
int Vect_reset_cats (struct line_cats *);
</PRE>
And many, many others ...
<HR>
<H2><A NAME="attr">Attributes</A></H2>
dig_cats files are not used any more and
vectors' attributes are stored in external database.
Connection with database is done through drivers based on DBMI library
(odbc, dbf, Postgres and MySQL drivers are available at this time). Records in table
are linked to vector entities by field and category number.
The field identifies table and the category identifies record.
I.e. for unique combination map+mapset+field+category exists one
unique combination driver+database+table+row.
<P>
For each pair <B>map + field</B> must be defined <B>table, key column,
database, driver</B>. This definition must be written to $MAPSET/DB text file.
Each row in DB file contains names separated by spaces in following order
([] - optional): <BR><BR>
<B>map[@mapset] field table [key [database [driver]]] </B><BR><BR>
If key, database or driver are omited (on second and higher row only)
last definition is used. Definition from DB file in other mapset
may be overwritten by definition in current mapset if mapset is specified
with map name.
<P>
Wild cards <B>*</B> and <B>?</B> may be used in map and mapset names.
<P>
Variables <B>$GISDBASE, $LOCATION, $MAPSET, $MAP, $FIELD</B>
may be used in table, key, database and driver names. Note that
$MAPSET is not current mapset but mapset of the map the rule is defined for.
<P>Note that features in GRASS vector may have attributes
in different tables or may be without attributes. Boundaries
forms areas but it may happen that some boundaries are not closed
(such boundaries would not appear in polygon layer).
Boundaries may have attributes. All types may be mixed in one vector.
<P>
Link to the table is permanent and it is stored in 'dbln' file in vector
directory. Tables are considered to be a part of the vector and g.remove,
for example, deletes linked tables of the vector.
Attributes must be joined with geometry.
<P>
<H3>Examples:</H3>
Examples are written mostly for dbf driver where database is full path to
directory with dbf files and table name is name of dbf file without
.dbf extension.
<P>
<PRE><B>* 1 tbl id $GISDBASE/$LOCATION/$MAPSET/vector/$MAP dbf</B></PRE>
This definition says that entities with category of field 1 are linked
to dbf tables with names tbl.dbf saved in vector directories of each map.<BR><BR>
<PRE><B>* 1 $MAP id $GISDBASE/$LOCATION/$MAPSET/dbf dbf</B></PRE>
Similar as above but all dbf files are in one directory dbf/ in mapset
and names of dbf files are $MAP.dbf<BR><BR>
<PRE><B>water* 1 rivers id /home/grass/dbf dbf</B>
<B>water* 2 lakes lakeid /home/guser/mydb</B>
<B>trans* 1 roads key basedb odbc</B>
<B>trans* 5 rails</B></PRE>
These definitions defines more fields for one map i.e. in one map may be more
features linked to more tables. Definition on first 2 rows are applied for example
on maps water1, water2, ... so that more maps may share one table.<BR><BR>
<PRE><B>water@PERMANENT 1 myrivers id /home/guser/mydbf dbf</B></PRE>
This definion overwrites definition saved in PERMANENT/DB and
links map from PERMANENT mapset to user's table.<BR><BR>
<P>
Modules should be written so that connections to database for each
vector field are independent. It should be possible to read attributes
of input map from one database and write to some other and even with
some other driver (should not be such problem).
<P>
There are open questions however. For example how to distinguish when
new table should be written and when not. For example definitions:<BR>
river 1 river id water odbc<BR>
river.backup* 1 NONE<BR>
could be used to say that tables should not be copied for backups of
map river because table is stored in reliable RDBMS.
<HR>
<H2><A NAME="other">Other Informations</A></H2>
<P>
Bounding box information was moved from coor file to topo file.
<HR>
<H2><A NAME="ascii">Vector ascii Format Specification</A></H2>
<P>
Ascii format in new version contains categories, new type
centroid and z-coordinates. Points and centroids are saved
as one coordinates pair instead of two. File is saved
in old dig_ascii directory but the name will be probably changed.
<H3>Head</H3>
The head of the file is similar as the head file of vector binary
format but contains bounding box also. Key words are:<BR>
<PRE>
ORGANIZATION
DIGIT DATE
DIGIT NAME
MAP NAME
MAP DATE
MAP SCALE
OTHER INFO
ZONE
WEST EDGE
EAST EDGE
SOUTH EDGE
NORTH EDGE
MAP THRESH
</PRE>
<H3>Body</H3>
The body begins by row:
<PRE>
VERTI:
</PRE>
followed by records of lines:
<PRE>
TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
Y X [Z]
....
Y X [Z]
[ FIELD CATEGORY]
....
[ FIELD CATEGORY]
</PRE>
Everything in <B>[]</B> is optional.
TYPE may be:<BR><BR>
<B>P</B> point (dot) <BR>
<B>p</B> dead point (dead dot) <BR>
<B>L</B> line <BR>
<B>l</B> dead line <BR>
<B>B(A)</B> boundary <BR>
<B>b(a)</B> dead boundary <BR>
<B>C</B> centroid <BR>
<B>c</B> dead centroid <BR>
<BR>
Example of records:
<PRE>
P 1 1
1234 3435
1 354
L 3 1
4132 4534
1453 1454
1453 4543
1 355
</PRE>
<HR>
<H2><A NAME="options">Vector modules and options</A></H2>
See also grass5/documents/parameter_proposal.txt
<H3>Operation</H3>
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 grass5.0 but if program (system) crashes or treshold was
specified incorrectly and vector was not backuped, data are lost.
In this case map= option should be replaced by input= and output=
<P>
Topology is always build by default if coor file was modified.
<P>
Dimension is kept. Input 2D vector is written as 2D, 3D as 3D.
<H3>Options</H3>
<B>-f</B> overwrite existing files, default <BR>
<B>-i</B> ask user before overwriting existing files <BR>
<B>-b</B> do not build topo file; topo file is written by default <BR>
<B>-q</B> quiet <BR>
<B>-v</B> run verbosely <BR>
<B>-t</B> create new table, default ??? <BR>
<B>-u</B> don't create new table ??? <BR>
<B>-z</B> write 3D file (if input was 2D) <BR>
<BR>
<B>map=</B> input vector for modules without output <BR>
<B>input=</B> input vector <BR>
<B>output=</B> output vector <BR>
<B>type=</B> type of elements: point,line,boundary,centroid,area <BR>
<B>cat=</B> category or category list (example: 1,5,9-13,35) <BR>
<B>field=</B> field number <BR>
<B>where=</B> condition of SQL statement for selection of records <BR>
<B>col=</B> column name (in external table) <BR>
<P>
<HR>
<H2><A NAME="status">Vector module upgrade status</A></H2>
<a href=v.modules.html>Vector upgrade status</a>
<HR>
<H2><A NAME="example">Vector module programming example</A></H2>
<a href=v.example/>Vector module C programming example</a> (slightly outdated, you better start
from new modules)
<hr>
<i>Document updated 2004 by M. Neteler</i><br>
$Date: 2005/07/01 20:16:46 $
</BODY>
</HTML>
|
