-
-
Notifications
You must be signed in to change notification settings - Fork 288
/
imagerylib.dox
424 lines (310 loc) · 12.5 KB
/
imagerylib.dox
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
/*! \page imagerylib GRASS Imagery Library
<!-- doxygenized from "GRASS 5 Programmer's Manual"
by M. Neteler 2/2004
-->
\section imageryintro Introduction to Imagery Library
The <I>Imagery Library</I> was created for version 3.0 of GRASS to
support integrated image processing directly in GRASS. It contains
routines that provide access to the <I>group</I> database structure
which was also introduced in GRASS 3.0 for the same purpose. It is
assumed that the reader has read Database_Structure for a general
description of GRASS databases, \ref Image_Data_Groups for a description of
imagery groups, and \ref Raster_Maps for details about map layers in
GRASS. The routines in the \ref Imagery_Library are presented in functional
groupings, rather than in alphabetical order. The order of
presentation will, it is hoped, provide a better understanding of how
the library is to be used, as well as show the interrelationships
among the various routines. Note that a good way to understand how to
use these routines is to look at the source code for GRASS modules
which use them. Most routines in this library require that the header
file <grass/imagery.h> be included in any code using these
routines. Therefore, programmers should always include this file when
writing code using routines from this library:
\verbatim
#include <grass/imagery.h>
\endverbatim
<P>
<B>Note.</B> All routines and global variables in this library,
documented or undocumented, start with the prefix <B>I_.</B> To avoid
name conflicts, programmers should not create variables or routines in
their own modules which use this prefix.
\subsection Group_Processing Group Processing
The group is the key database structure which permits integration of
image processing in GRASS.
<P>
\subsection Prompting_for_a_Group Prompting for a Group
<P>
The following routines interactively prompt the user for a group name
in the current mapset (This library only works with groups in the
current mapset. Other mapsets, even those in the user's mapset search
path, are ignored.) 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
group 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>group</B> buffer. The size of group 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 group</tt>. These routines have a built-in 'list' capability
which allows the user to get a list of existing groups.
<P>
The user is required to enter a valid group 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, 0 is returned; otherwise, 1 is returned.
<P>
int I_ask_group_old() prompt for an existing group
Asks the user to enter the name of an existing <B>group</B> in the
current mapset.
<P>
<B>Note.</B> The user is not warned if the <B>group</B> exists. The
programmer should use <I>I_find_group()</I> to determine if the
<B>group</B> exists.
<P>
Here is an example of how to use these routines. Note that the
programmer must handle the 0 return properly:
\verbatim
char group[INAME_LEN];
if ( ! I_ask_group_any ("Enter group to be processed", group))
exit(0);
\endverbatim
<P>
\subsection Finding_Groups_in_the_Database Finding Groups in the Database
<P>
Sometimes it is necessary to determine if a given group already
exists. The following routine provides this service:
<P>
int I_find_group() does group exist?
Returns 1 if the specified <B>group</B> exists in the current mapset;
0 otherwise.
\subsection REF_File REF File
<P>
These routines provide access to the information contained in the REF
file for groups and subgroups, as well as routines to update this
information. They use the <I>Ref</I> structure, which is defined in
the <grass/imagery.h> header file; see \ref Imagery_Library_Data_Structures.
<P>
The contents of the REF file are read or updated by the following
routines:
<P>
int I_get_group_ref() read group REF file
Reads the contents of the REF file for the specified <B>group</B> into
the <B>ref</B> structure.
<P>
Returns 1 if successful; 0 otherwise (but no error messages are printed).
<P>
int I_put_group_ref() write group REF file
Writes the contents of the <B>ref</B> structure to the REF file for
the specified <B>group.</B>
<P>
Returns 1 if successful; 0 otherwise (and prints a diagnostic error).
<P>
<B>Note.</B> This routine will create the <B>group</B>, if it does not
already exist.
<P>
int I_get_subgroup_ref() read subgroup REF file
Reads the contents of the REF file for the specified <B>subgroup</B>
of the specified <B>group</B> into the <B>ref</B> structure.
<P>
Returns 1 if successful; 0 otherwise (but no error messages are printed).
<P>
int I_put_subgroup_ref() write subgroup REF file
Writes the contents of the <B>ref</B> structure into the REF file for
the specified <B>subgroup</B> of the specified <B>group.</B>
<P>
Returns 1 if successful; 0 otherwise (and prints a diagnostic error).
<P>
<B>Note.</B> This routine will create the <B>subgroup</B>, if it does
not already exist.
<P>
These next routines manipulate the <I>Ref</I> structure:
<P>
int I_init_group_ref() initialize Ref structure
This routine initializes the <B>ref</B> structure for other library
calls which require a <I>Ref</I> structure. This routine must be
called before any use of the structure can be made.
<P>
<B>Note.</B> The routines I_get_group_ref() and I_get_subgroup_ref() call
this routine automatically.
<P>
int I_add_file_to_group_ref() add file name to Ref structure
This routine adds the file <B>name</B> and <B>mapset</B> to the list
contained in the <B>ref</B> structure, if it is not already in the
list. The <B>ref</B> structure must have been properly
initialized. This routine is used by programs, such as
<I>i.maxlik</I>, to add to the group new raster files created from
files already in the group.
<P>
Returns the index into the <I>file</I> array within the <B>ref</B>
structure for the file after insertion; see \ref
Imagery_Library_Data_Structures.
<P>
int I_transfer_group_ref_file() copy Ref lists
This routine is used to copy file names from one <I>Ref</I> structure
to another. The name and mapset for file <B>n</B> from the <B>src</B>
structure are copied into the <B>dst</B> structure (which must be
properly initialized).
<P>
For example, the following code copies one <I>Ref</I> structure to another:
\verbatim
struct Ref src,dst;
int n;
/* some code to get information into src */
...
I_init_group_ref(&dst);
for (n = 0; n < src.nfiles; n++)
I_transfer_group_ref_file (&src, n, &dst);
\endverbatim
<P>
This routine is used by <I>g.gui.gcp</I> to create the REF file for a
subgroup.
<P>
int I_free_group_ref() free Ref structure
This routine frees memory allocated to the <B>ref</B> structure.
\subsection TARGET_File TARGET File
<P>
The following two routines read and write the TARGET file.
<P>
int I_get_target() read target information
Reads the target <B>location</B> and <B>mapset</B> from the TARGET
file for the specified group. Returns 1 if successful; 0 otherwise
(and prints a diagnostic error). This routine is used by
<I>g.gui.gcp</I> and <I>i.rectify</I> and probably should not be used
by other programs.
<P>
<B>Note.</B> This routine does <B>not</B> validate the target information.
<P>
int I_put_target() write target information
Writes the target <B>location</B> and <B>mapset</B> to the TARGET file
for the specified <B>group.</B> Returns 1 if successful; 0 otherwise
(but no error messages are printed).
<P>
This routine is used by <I>i.target</I> and probably should not be
used by other programs.
<P>
<B>Note.</B> This routine does <B>not</B> validate the target
information.
\subsection POINTS_File POINTS File
<P>
The following routines read and write the POINTS file, which contains
the image registration control points. This file is created and
updated by the module <I>g.gui.gcp</I>,and read by <I>i.rectify.</I>
<P>
These routines use the <I>Control_Points</I> structure, which is
defined in the <grass/imagery.h> <I>header file</I>; see \ref
Imagery_Library_Data_Structures.
<P>
<B>Note.</B> The interface to the <I>Control_Points</I> structure
provided by the routines below is incomplete. A routine to initialize
the structure is needed.
<P>
int I_get_control_points() read group control points
Reads the control points from the POINTS file for the <B>group</B>
into the <B>cp</B> structure. Returns 1 if successful; 0 otherwise
(and prints a diagnostic error).
<P>
<B>Note.</B> An error message is printed if the POINTS file is
invalid, or does not exist.
<P>
int I_new_control_point() add new control point
Once the control points have been read into the <B>cp</B> structure,
this routine adds new points to it. The new control point is given by
<B>e1</B> (column) and <B>n1</B> (row) on the image, and the <B>e2</B>
(east) and <B>n2</B> (north) for the target database. The value of
<B>status</B> should be 1 if the point is a valid point; 0
otherwise.Use of this routine implies that the point is probably good,
so status should be set to 1.
<P>
int I_put_control_points() write group control points
Writes the control points from the <B>cp</B> structure to the POINTS
file for the specified group.
<P>
<B>Note.</B> Points in <B>cp</B> with a negative <I>status</I> are not
written to the POINTS file.
\subsection Loading_the_Imagery_Library Loading the Imagery Library
<P>
The library is loaded by specifying $(IMAGERYLIB) in the
Makefile. The following example is a complete Makefile which
compiles code that uses this library:
<P>
<B>Makefile for $(IMAGERYLIB)</B>
\verbatim
#UPDATE THIS EXAMPLE!!
OBJ = main.o sub1.o sub2.o
PGM: $(OBJ) $(IMAGERYLIB) $(GISLIB)
$(CC) $(LDFLAGS) -o $@ $(OBJ) $(IMAGERYLIB) $(GISLIB)
$(IMAGERYLIB): # in case the library changes
$(GISLIB): # in case the library changes
\endverbatim
<B>Note.</B> This library must be loaded with $(GISLIB) since it uses
routines from that library. See \ref GIS_Library or details on that
library. See \ref Compiling_and_Installing_GRASS_Modules for a complete
discussion of Makefiles.
\section Imagery_Library_Data_Structures Imagery Library Data Structures
Some of the data structures in the <grass/imagery.h> header file are
described below.
\subsection struct_Ref struct Ref
<P>
The <I>Ref</I> structure is used to hold the information from the REF
file for groups and subgroups. The structure is:
\verbatim
struct Ref
{
int nfiles; /* number of REF files */
struct Ref_Files
{
char name[INAME_LEN]; /* REF file name */
char mapset[INAME_LEN]; /* REF file mapset */
} *file;
struct Ref_Color
{
unsigned char *table; /* color table for min-max values */
unsigned char *index; /* data translation index */
unsigned char *buf; /* data buffer for reading color file */
int fd; /* for image i/o */
CELL min, max; /* min,max CELL values */
int n; /* index into Ref_Files */
} red, grn, blu;
};
\endverbatim
The <I>Ref</I> structure has <I>nfiles</I> (the number of raster
files), <I>file</I> (the name and mapset of each file), and
<I>red,grn,blu</I> (color information for the group or subgroup) Note:
The red,grn,blu elements are expected to change as the imagery code
develops. Do not reference them. Pretend they do not exist.
<P>
There is no function interface to the <I>nfiles</I> and <I>file</I>
elements in the structure. This means that the programmer must
reference the elements of the structure directly (The nfiles and file
elements are not expected to change in the future). The name and
<I>mapset for the i th file are file[i].name, and file[i].mapset.</I>
<P>
For example, to print out the names of the raster files in the structure:
\verbatim
int i;
struct Ref ref;
...
/* some code to get the REF file for a group into <B>ref</B> */
...
for (i = 0; i<ref.nfiles; i++)
fprintf(stdout, "%s in %s\n", ref.file[i].name, ref.file[i].mapset);
\endverbatim
\subsection struct_Control_Points struct Control_Points
The <I>Control_Points</I> structure is used to hold the control points
from the group POINTS file. The structure is:
\verbatim
struct
Control_Points
{
int count; /* number of control points */
double *e1; /* image east (column) */
double *n1; /* image north (row) */
double *e2; /* target east */
double *n2; /* target north */
int *status; /* status of control point */
};
\endverbatim
The number of control points is <I>count.</I>
<P>
Control point <I>i</I> is <I>e1</I> [i], <I>n1</I> [i], <I>e2</I> [i],
<I>n2</I> [i], and its status is <I>status</I> [i].
*/