← Back to branch summary

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

« back to all changes in this revision

Viewing changes to lib/vector/vectorlib_indices.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/vector/vectorlib_indices.dox
 
1
/*! \page vlibIndices Spatial and category indices
 
2
 
 
3
by GRASS Development Team (http://grass.osgeo.org)
 
4
 
 
5
\tableofcontents
 
6
 
 
7
\section vlibSpidx Vector library spatial index management
 
8
 
 
9
Spatial index (based on R*-tree) is created with topology.
 
10
 
 
11
Spatial index occupies a lot of memory but it is necessary for 
 
12
topology building. Also, it takes some time to release the memory
 
13
occupied by spatial index (see dig_spidx_free()). The spatial index can
 
14
also be built in file to save memory by setting the environment variable
 
15
GRASS_VECTOR_LOWMEM.
 
16
 
 
17
The function building topology - Vect_build() - is usually called at
 
18
the end of modules (before Vect_close()) so it is faster to call
 
19
<tt>exit()</tt> and operating system releases all the memory much
 
20
faster.  By default the memory is not released.
 
21
 
 
22
It is possible to call Vect_set_release_support() before Vect_close()
 
23
to enforce memory release, but it takes some time on large files.
 
24
 
 
25
The spatial index is stored in file and not loaded for old vectors that
 
26
are not updated, saving a lot of memory. Spatial queries are done in 
 
27
file.
 
28
 
 
29
Currently most of the modules do not release the memory occupied for
 
30
spatial index and work like this (pseudocode):
 
31
 
 
32
\code
 
33
int main
 
34
{
 
35
     Vect_open_new();
 
36
     /* writing new vector */
 
37
 
 
38
     Vect_build();
 
39
     Vect_close();  /* memory is not released */
 
40
}
 
41
\endcode
 
42
 
 
43
In general it is possible to free the memory with Vect_set_release_support()
 
44
such as:
 
45
 
 
46
\code
 
47
int main
 
48
{
 
49
     Vect_open_new();
 
50
     /* writing new vector */
 
51
 
 
52
     Vect_build();
 
53
     Vect_set_release_support();
 
54
     Vect_close();  /* memory is released */
 
55
}
 
56
\endcode
 
57
 
 
58
but it takes a bit longer. 
 
59
 
 
60
It makes sense to release the spatial index if it is used only at the beginning
 
61
of a module or in permanently running programs like QGIS. Note that this
 
62
applies only when creating a new vector or updating an old vector.
 
63
For example:
 
64
 
 
65
\code
 
66
int main
 
67
{
 
68
     Vect_open_update();
 
69
     /* select features using spatial index, e.g.  Vect_select_lines_by_box() */
 
70
     Vect_set_release_support();
 
71
     Vect_close();  /* memory is released */
 
72
 
 
73
     /* do some processing which needs memory */
 
74
}
 
75
\endcode
 
76
 
 
77
See also \ref spatial_index data structure.
 
78
 
 
79
\subsection vlibSidxFileFormat Sidx file format specification
 
80
 
 
81
Spatial index file ('sidx') is read by Vect_open_sidx().
 
82
 
 
83
\subsubsection vlibSidxFileHead Header
 
84
 
 
85
Note: <tt>plus</tt> is instance of \ref Plus_head structure.
 
86
 
 
87
<table border="1" style="border-collapse: collapse" cellpadding="5">
 
88
<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
 
89
 
 
90
<tr><td>plus->spidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
 
91
<tr><td>plus->spidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
 
92
<tr><td>plus->spidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
 
93
<tr><td>plus->spidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
 
94
 
 
95
<tr><td>plus->spidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
 
96
                  flag; files are written in machine native order but
 
97
                  files in both little and big endian order may be
 
98
                  readl; zero for little endian</td></tr>
 
99
 
 
100
<tr><td>plus->spidx_port.off_t_size</td><td>C</td><td>1</td><td>off_t size (LFS)</td></tr>
 
101
 
 
102
<tr><td>plus->spidx_head_size</td><td>L</td><td>1</td><td>header size</td></tr>
 
103
 
 
104
<tr><td>plus->spidx_with_z</td><td>C</td><td>1</td><td>2D/3D vector data</td></tr>
 
105
 
 
106
<tr><td>ndims</td><td>C</td><td>1</td><td>Number of dimensions</td></tr>
 
107
 
 
108
<tr><td>nsides</td><td>C</td><td>1</td><td>Number of sides</td></tr>
 
109
 
 
110
<tr><td>nodesize</td><td>I</td><td>1</td><td>%Node size</td></tr>
 
111
 
 
112
<tr><td>nodecard</td><td>I</td><td>1</td><td>%Node card (?)</td></tr>
 
113
 
 
114
<tr><td>leafcard</td><td>I</td><td>1</td><td>Leaf card (?)</td></tr>
 
115
 
 
116
<tr><td>min_node_fill</td><td>I</td><td>1</td><td>Minimum node fill (?)</td></tr>
 
117
 
 
118
<tr><td>min_leaf_fill</td><td>I</td><td>1</td><td>Minimum leaf fill (?)</td></tr>
 
119
 
 
120
<tr><td>plus->Node_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
 
121
 
 
122
<tr><td>plus->Node_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
 
123
 
 
124
<tr><td>plus->Node_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
 
125
 
 
126
<tr><td>plus->Node_spidx_offset</td><td>O</td><td>1</td><td>%Node offset</td></tr>
 
127
 
 
128
<tr><td>plus->Line_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
 
129
 
 
130
<tr><td>plus->Line_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
 
131
 
 
132
<tr><td>plus->Line_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
 
133
 
 
134
<tr><td>plus->Line_spidx_offset</td><td>O</td><td>1</td><td>Line offset</td></tr>
 
135
 
 
136
<tr><td>plus->Area_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
 
137
 
 
138
<tr><td>plus->Area_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
 
139
 
 
140
<tr><td>plus->Area_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
 
141
 
 
142
<tr><td>plus->Area_spidx_offset</td><td>O</td><td>1</td><td>Area offset</td></tr>
 
143
 
 
144
<tr><td>plus->Isle_spidx->n_nodes</td><td>I</td><td>1</td><td>Number of nodes</td></tr>
 
145
 
 
146
<tr><td>plus->Isle_spidx->n_leafs</td><td>I</td><td>1</td><td>Number of leafs</td></tr>
 
147
 
 
148
<tr><td>plus->Isle_spidx->n_levels</td><td>I</td><td>1</td><td>Number of levels</td></tr>
 
149
 
 
150
<tr><td>plus->Isle_spidx_offset</td><td>O</td><td>1</td><td>Isle offset</td></tr>
 
151
 
 
152
<tr><td>plus->Face_spidx_offset</td><td>O</td><td>1</td><td>Face offset</td></tr>
 
153
 
 
154
<tr><td>plus->Volume_spidx_offset</td><td>O</td><td>1</td><td>Volume offset</td></tr>
 
155
 
 
156
<tr><td>plus->Hole_spidx_offset</td><td>O</td><td>1</td><td>Hole offset</td></tr>
 
157
 
 
158
<tr><td>plus->coor_size</td><td>O</td><td>1</td><td>Coor file size</td></tr>
 
159
</table>
 
160
 
 
161
\section vlibCidx Vector library category index management
 
162
 
 
163
The category index (stored in the cidx file) improves the performance
 
164
of all selections by cats/attributes (SQL, e.g. <tt>d.vect
 
165
cats=27591</tt>, <tt>v.extract list=20000-21000</tt>). This avoids
 
166
that all selections have to be made by looping through all vector
 
167
lines.  Category index is also essential for simple feature
 
168
representation of GRASS vectors.
 
169
 
 
170
Category index is created for each field. In memory, it is stored in
 
171
\ref Cat_index data structure.
 
172
 
 
173
Category index is built with topology, but it is <b>not updated</b> if
 
174
vector is edited on level 2.  Category index is stored in 'cidx' file,
 
175
'cat' array is written/read by one call of dig__fwrite_port_I() or
 
176
dig__fread_port_I().
 
177
 
 
178
Stored values can be retrieved either by index in 'cat' array (if all
 
179
features of given field are required) or by category value (one or few
 
180
features), always by <tt>Vect_cidx_*()</tt> functions.
 
181
 
 
182
To create category index, it will be necessary to rebuild topology for
 
183
all existing vectors.  This is an opportunity to make (hopefully) last
 
184
changes in 'topo', 'cidx' formats.
 
185
 
 
186
\subsection vlibCidxFileFormat Cidx file format specification
 
187
 
 
188
Category index file ('cidx') is read by Vect_cidx_open().
 
189
 
 
190
\subsubsection vlibCidxFileHead Header
 
191
 
 
192
Note: <tt>plus</tt> is instance of \ref Plus_head structure.
 
193
 
 
194
<table border="1" style="border-collapse: collapse" cellpadding="5">
 
195
<tr><td><b>Name</b></td><td><b>Type</b></td><td><b>Number</b></td><td><b>Description</b></td></tr>
 
196
 
 
197
<tr><td>plus->cpidx_Version_Major </td><td>C</td><td>1</td><td>file version (major)</td></tr>
 
198
<tr><td>plus->cpidx_Version_Minor </td><td>C</td><td>1</td><td>file version (minor)</td></tr>
 
199
<tr><td>plus->cpidx_Back_Major</td><td>C</td><td>1</td><td>supported from GRASS version (major)</td></tr>
 
200
<tr><td>plus->cpidx_Back_Minor</td><td>C</td><td>1</td><td>supported from GRASS version (minor)</td></tr>
 
201
 
 
202
<tr><td>plus->cidx_port->byte_order</td><td>C</td><td>1</td><td>little or big endian
 
203
                  flag; files are written in machine native order but
 
204
                  files in both little and big endian order may be
 
205
                  readl; zero for little endian</td></tr>
 
206
 
 
207
<tr><td>plus->cidx_head_size</td><td>L</td><td>1</td><td>cidx head size</td></tr>
 
208
 
 
209
<tr><td>plus->n_cidx</td><td>I</td><td>1</td><td>number of fields</td></tr>
 
210
 
 
211
<tr><td>field</td><td>I</td><td>n_cidx</td><td>field number</td></tr>
 
212
 
 
213
<tr><td>n_cats</td><td>I</td><td>n_cidx</td><td>number of categories</td></tr>
 
214
 
 
215
<tr><td>n_ucats</td><td>I</td><td>n_cidx</td><td>number of unique categories</td></tr>
 
216
 
 
217
<tr><td>n_types</td><td>I</td><td>n_cidx</td><td>number of feature types</td></tr>
 
218
 
 
219
<tr><td>rtype</td><td>I</td><td>n_cidx * n_types</td><td>Feature type</td></tr>
 
220
 
 
221
<tr><td>type[t]</td><td>I</td><td>n_cidx * n_types</td><td>Number of items</td></tr>
 
222
 
 
223
</table>
 
224
 
 
225
 
 
226
*/