-
-
Notifications
You must be signed in to change notification settings - Fork 294
/
gislib.dox
1626 lines (1139 loc) · 55.3 KB
/
gislib.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
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
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*! \page gislib GRASS GIS General Library (aka GIS Library)
<!-- doxygenized from "GRASS 5 Programmer's Manual"
by M. Neteler 2/2004, 2005, 2006
-->
by GRASS Development Team (https://grass.osgeo.org)
\tableofcontents
\par Subpages
- \subpage gislib_cmdline_parsing
This chapter is divided as follows:
- \subpage gislibintro
- \subpage init
- \subpage diag
- \subpage envir
- \subpage dbaseaccess
- \subpage Fully_Qualified_File_Names
- \subpage finding
- \subpage Legal_File_Names
- \subpage Opening_an_Existing_Database_File_for_Reading
- \subpage Opening_an_Existing_Database_File_for_Update
- \subpage Creating_and_Opening_a_New_Database_File
- \subpage Database_File_Management
- \subpage Region
- \subpage Database_Region
- \subpage Active_Module_Region
- \subpage Projection_Information
- \subpage Latitude_Longitude_Databases
- \subpage Coordinates
- \subpage Global_Wraparound
- \subpage Miscellaneous
- \subpage Calculations
- \subpage Raster_Area_Calculations
- \subpage Polygonal_Area_Calculations
- \subpage Distance_Calculations
- \subpage General_Plotting_Routines
- \subpage Temporary_Files
- \subpage String_Manipulation_Functions
- \subpage Enhanced_UNIX_Routines
- \subpage Running_in_the_Background
- \subpage Partially_Interruptible_System_Call
- \subpage ENDIAN_test
- \subpage Miscellaneous
- \subpage GIS_Library_Data_Structures
- \subpage struct_Cell_head
- \subpage struct_Categories
- \subpage struct_Colors
- \subpage struct_History
- \subpage struct_Range
- \subpage Loading_the_GIS_Library
- \subpage TimeStamp_functions
- \subpage Memory_Allocation
\section gislibintro Introduction
The <em>GIS Library</em> is the primary programming library provided
with the GRASS system. <b>Programs must use this library to access the
GIS database.</b> It contains the routines which locate, create, open,
rename, and remove GRASS database files. It contains the routines
which read and write raster files. It contains routines which
interface the user to the database, including prompting the user,
listing available files, validating user access, etc. It also has
some general purpose routines (string manipulation, user information,
etc.) which are not tied directly to database processing.
It is assumed that the reader has read \ref location for a general
description of GRASS databases, \ref Raster_File_Processing for
details about raster map layers in GRASS, and \ref Region_and_Mask
(<b>???</b>) which discusses regions and masks. The routines in the
<em>GIS Library</em> 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 <b>grass/gis.h</b> be
included in any code using these routines. Therefore, programmers
should always include this file when writing code using routines from
this library:
\code
#include <grass/gis.h>
\endcode
<b>Note:</b> All routines and global variables in this library,
documented or undocumented, start with the prefix <b>G_</b>. To avoid
name conflicts, programmers should not create variables or routines in
their own modules which use this prefix.
\subsection init Library Initialization
It is <B>mandatory</B> that the system be initialized before any other
library routines are called.
G_gisinit() initialize GIS library.
This routine reads the user's GRASS environment file into memory and
makes sure that the user has selected a valid database and mapset. It
also initializes hidden variables used by other routines. If the
user's database information is invalid, an error message is printed
and the module exits. The <b>program_name</b> is stored for later
recall by G_program_name(). It is recommended that argv[0] be
used for the program_name:
\code
int main (int argc, char **argv)
{
G_gisinit(argv[0]);
}
\endcode
\subsection diag Diagnostic Messages
The following routines are used by other routines in the library to
report warning and error messages. They may also be used directly by
GRASS programs.
- G_fatal_error() print error message and exit
- G_debug() print debug message
- G_warning() print warning message and continue
These routines report errors to the user. The normal mode is to write
the <em>message</em> to the screen (on the standard error
output). G_warning() will return and G_fatal_error() will exit.
If the standard error output is not a tty device, then the message is
mailed to the user instead.
If the file GIS_ERROR_LOG exists (with write permission), in either
the user's home directory or in the <tt>$GISBASE</tt> directory, the
messages will also be logged to this file.
While most applications will find the normal error reporting quite
adequate, there will be times when different handling is needed. For
example, graphics modules may want the messages displayed graphically
instead of on the standard error output. If the programmer wants to
handle the error messages differently, the following routines can be
used to modify the error handling:
- G_set_error_routine() change error handling
This routine provides a different error handler for G_fatal_error()
and G_warning(). The <em>handler</em> routine must be defined as
follows:
\code
int handler(char *message, int fatal)
\endcode
where <i>message</i> is the message to be handled and <i>fatal</i>
indicates the type of error:
- 1 (fatal error)
- or 0 (warning).
<b>Note:</b> The handler only provides a way to send the message
somewhere other than to the error output. If the error is fatal, the
module will exit after the handler returns.
- G_unset_error_routine() reset normal error handling
This routine resets the error handling for G_fatal_error() and
G_warning() back to the default action.
- G_sleep_on_error() sleep on error
- G_suppress_warnings() suppress warnings
\subsection envir Environment and Database Information
The following routines return information about the current database
selected by the user. Some of this information is retrieved from the
user's GRASS environment file. Some of it comes from files in the
database itself. See \ref Environment_Variables for a discussion of
the GRASS environment.
The following four routines can be used freely by the programmer:
- G_location() current location name
Returns the name of the current database location. This routine should
be used by modules that need to display the current location to the
user. See \ref Locations for an explanation of locations.
- G_mapset() current mapset name
Returns the name of the current mapset in the current location. This
routine is often used when accessing files in the current mapset. See
\ref Mapsets for an explanation of mapsets.
- G_myname() location title
Returns a one line title for the database location. This title is read
from the file MYNAME in the PERMANENT mapset. See also \ref
Permanent_Mapset for a discussion of the PERMANENT mapset.
- G_gisbase() top level module directory
Returns the full path name of the top level directory for GRASS
programs. This directory will have subdirectories which will contain
modules and files required for the running of the system. Some of
these directories are:
\verbatim
bin commands run by the user
etc modules and data files used by GRASS commands
html help files
\endverbatim
The use of G_gisbase() to find these subdirectories enables GRASS modules
to be written independently of where the GRASS system is actually installed
on the machine. For example, to run the module <i>sroff</i> in the GRASS
<tt>etc</tt> directory:
\code
char command[200];
sprintf(command, "%s/etc/sroff", G_gisbase());
G_spawn(command, "sroff", NULL);
\endcode
The following two routines return full path UNIX directory names. They
should be used only in special cases. They are used by other routines
in the library to build full UNIX file names for database
files. <B>The programmer should not use the next two routines to
bypass the normal database access routines.</B>
- G_gisdbase() top level database directory
Returns the full UNIX path name of the directory which holds the
database locations. See \ref GISDBASE for a full explanation of this
directory.
- G_location_path() current location directory
Returns the full UNIX path name of the current database location. For
example, if the user is working in location <I>spearfish</I> in the
<tt>/home/user/grassdata</tt> database directory, this routine will
return a string which looks like
<tt>/home/user/grassdata/spearfish</tt>.
These next routines provide the low-level management of the
information in the user's GRASS environment file. <B>They should not
be used in place of the higher level interface routines described
above.</B>
- G_getenv()
- G_getenv_nofatal()
These routines look up the variable <em>name</em> in the GRASS
environment and return its value (which is a character string). If
<em>name</em> is not set, G_getenv() issues an error message and calls
exit(). G_setenv_nogisrc() just returns the NULL pointer.
- G_setenv()
- G_setenv_nogisrc()
These routines set the the GRASS environment variable <em>name</em> to
<em>value</em>. If <em>value</em> is NULL, the <em>name</em> is unset.
Both routines set the value in module memory, but only G_setenv()
writes the new value to the user's GRASS environment file.
\section dbaseaccess Fundamental Database Access Routines
In general, a user can only access data in the current location. For most
modules, it's meaningless to access data from a different location as
the projection will be wrong. A handful of modules (e.g. r.proj,
v.proj) support accessing data from a different location, and in such
cases there's no need for the user to own the source mapset, or even
to own any mapset in the source location.
Since r54264, it is possible to bypass the ownership check by setting
GRASS_SKIP_MAPSET_OWNER_CHECK to any non-empty string. This was added
mostly for accessing VFAT/NTFS-format external drives or network
shares where the ownership checks don't behave correctly. It should
not be used on multi-user systems, nor set by programs.
But other than that, a user cannot make a mapset the current mapset (i.e.
the one a user can modify) unless the user owns it. The user can access data from
any mapset for which they have the relevant filesystem permissions
(i.e. read permission for files, execute permission for the ancestor
directories, read permission for any directories which need to be
enumerated).
Originally this restriction was related to locking (the lock file was
created in the user's home directory, so being able to set the current
mapset to a directory which the user didn't own meant that they could have
multiple sessions modifying a mapset concurrently).
That's no longer an issue (the lock file is created in the mapset
directory). However, the other issue is that allowing someone other
than the owner to modify the directory can result in problems for its
owner.
Creating a new map typically creates a subdirectory of cell_misc for
that map, and some files within it (e.g. a "null" file). Any new files
and subdirectories will be owned by their creator (not the mapset's
owner) and will have permissions determined by the current umask. The
result is that there's no guarantee that tha mapset's owner will be
able to delete (or even access) such files or directories.
In short, it's a safety mechanism against people trying to share
directories by making them group-writeable without fully understanding
the implications.
The routines described in this section provide the low-level interface
to the GRASS database. They search the database for files, prompt the
user for file names, open files for reading or writing, etc. The
programmer should never bypass this level of database interface. These
routines must be used to access the GRASS database unless there <b>are
other higher level library routines which perform the same
function</b>. For example, routines to process raster files (see \ref
Raster_File_Processing), vector files (see \ref
Vector_File_Processing), etc., should be used instead.
In the descriptions below, the term database <i>element</i> is used.
Elements are subdirectories within a mapset and are associated with a
specific GRASS data type. For example, raster files live in the "cell"
and "fcell" element. See \ref Elements for more details.
\subsection Fully_Qualified_File_Names Fully Qualified File Names
All GRASS routines which access database files must be given both the
file name and the mapset where the file resides. Often the name and
the mapset are 2 distinct character strings. However, there is a need
for a single character string which contains both the name and the
mapset (e.g., for interactive interfacing to command-line
programs). This form of the name is known as the <em>fully qualified
file name</em> and is built by the following routine:
- G_fully_qualified_name()
Returns a fully qualified name for the file <i>name</i> in
<i>mapset</i> Currently this string is in the form <i>name@mapset</i>,
but the programmer should pretend not to know this and always call
this routine to get the fully qualified name.
The following example shows how an interactive version of <tt>d.rast</tt>
interfaces with the command-line version of <tt>d.rast</tt>:
\code
#include <stdlib.h>
#include <grass/gis.h>
int main(int argc, char *argv[])
{
char name[GNAME_MAX], *mapset, *fqn;
char command[1024];
G_gisinit(argv[0]);
mapset = G_ask_cell_old("", name);
if (mapset == NULL)
exit(EXIT_SUCCESS);
fqn = G_fully_qualified_name(name, mapset);
sprintf(command, "d.rast map='%s'", fqn);
G_spawn(command, "d.rast", NULL);
exit(EXIT_SUCCESS);
}
\endcode
\subsection finding Finding Files in the Database
Command line driven module requires a database file name as one of the
command arguments. In this case, the programmer must search the
database to find the mapset where the file resides.
The following routines search the database for files:
- G_find_file()
Look for the file <i>name</i> under the specified <i>element</i> in
the database. The <i>mapset</i> parameter can either be the empty
string "", which means search all the mapsets in the user's current
mapset search path, or it can be a specific mapset, which means. Look
for the file only in this one mapset (for example, in the current
mapset).
If found, the mapset where the file lives is returned. If not found,
the NULL pointer is returned.
If the user specifies a fully qualified file name, (i.e, a name that
also contains the mapset; see \ref Fully_Qualified_File_Names) then
G_find_file() modifies <em>name</em> by eliminating the mapset from
the <em>name</em>.
For example, to find a "paint/labels" file anywhere in the database:
\code
char name[GNAME_MAX];
char *mapset;
if ((mapset = G_find_file("paint/labels", name, "")) == NULL)
/* not found */
\endcode
To check that the file exists in the current mapset:
\code
char name[GNAME_MAX];
if (G_find_file("paint/labels", name, G_mapset()) == NULL)
/* not found */
\endcode
\subsection Legal_File_Names Legal File Names
Not all names that a user may enter will be legal files for the GRASS
databases. The routines which create new files require that the new
file have a legal name. If the name is obtained from the command line,
the programmer must check that the name is legal. The following
routine checks for legal file names:
- G_legal_filename()
\subsection Opening_an_Existing_Database_File_for_Reading Opening an Existing Database File for Reading
The following routines open the file <i>name</i> in <i>mapset</i> from
the specified database <i>element</i> for <b>reading</b> (but not for
writing). The file <i>name</i> and <i>mapset</i> can be obtained using
G_find_file().
The database file <i>name</i> under the <i>element</i> in the
specified <i>mapset</i> is opened for reading (but not for writing).
- G_open_old()
The UNIX open() routine is used to open the file. If the file does not
exist, -1 is returned. Otherwise the file descriptor from the open()
is returned.
- G_fopen_old()
The UNIX fopen() routine, with "r" read mode, is used to open the
file. If the file does not exist, the NULL pointer is
returned. Otherwise the file descriptor from the fopen() is returned.
\subsection Opening_an_Existing_Database_File_for_Update Opening an Existing Database File for Update
The following routines open the file <i>name</i> in the current mapset
from the specified database <i>element</i> for <b>writing</b>. The
file must exist. Its <i>name</i> can be obtained using G_find_file().
The database file <i>name</i> under the <i>element</i> in the current
mapset is opened for reading and writing.
- G_open_update()
The UNIX open() routine is used to open the file. If the file does not
exist, -1 is returned. Otherwise the file is positioned at the end of
the file and the file descriptor from the open() is returned.
- G_fopen_append()
The UNIX fopen() routine, with "a" append mode, is used to open the
file. If the file does not exist, the NULL pointer is
returned. Otherwise the file is positioned at the end of the file and
the file descriptor from the fopen() is returned.
\subsection Creating_and_Opening_a_New_Database_File Creating and Opening a New Database File
The following routines create the new file <i>name</i> in the current
mapset (GRASS does not allow files to be created outside the current
mapset; see \ref Database_Access_Rules) under the specified database
<i>element</i> and open it for writing. The database <i>element</i> is
created, if it does not already exist.
The file <i>name</i> is obtained noninteractively (e.g., from the
command line), G_legal_filename() should be called first to make sure
that <i>name</i> is a valid GRASS file name. <b>Warning:</b> It is not
an error for <i>name</i> to already exist. However, the file will be
removed and recreated empty. G_find_file() could be used to see if
<i>name</i> exists.
The database file <i>name</i> under the <i>element</i> in the current
mapset is created and opened for writing (but not reading).
- G_open_new()
The UNIX open() routine is used to open the file. If the file does not
exist, -1 is returned. Otherwise the file is positioned at the end of
the file and the file descriptor from the open() is returned.
- G_fopen_new()
The UNIX fopen() routine, with "w" write mode, is used to open the
file. If the file does not exist, the NULL pointer is
returned. Otherwise the file is positioned at the end of the file and
the file descriptor from the fopen() is returned.
\subsection Database_File_Management Database File Management
The following routines allow the renaming and removal of database
files in the current mapset (These functions only apply to the current
mapset since GRASS does permit users to modify things in mapsets other
than the current mapset; see \ref Database_Access_Rules).
- G_rename() rename a database file
- G_remove() remove a database file
<b>Note:</b> These functions only apply to the specific <i>element</i>
and not to other "related" elements. For example, if <i>element</i> is
"cell", then the specified raster file will be removed (or renamed),
but the other support files, such as "cellhd" or "cats", will not. To
remove these other files as well, specific calls must be made for each
related <i>element</i>.
\section Region Region
The region concept is explained in \ref Region. It can be thought of as a
two-dimensional matrix with known boundaries and rectangular cells.
There are logically two different regions. The first is the database
region that the user has set in the current mapset. The other is the
region that is active in the module. This active module region is what
controls reading and writing of raster file data. The vector map
export does not take care for the active region settings.
The routines described below use a GRASS data structure
<tt>Cell_head</tt> to hold region information. This structure is
defined in the "gis.h" header file. It is discussed in detail under
\ref GIS_Library_Data_Structures.
\subsection Database_Region Database Region
Reading and writing the user's database region are done by the
following routines:
Note: Previous versions of GRASS called this the "window". Due to
overuse of this term (database window, graphics window, etc.), the
term was changed to "region". However, to maintain compatibility with
existing programs, library routine names were not changed - hence the
term "window" is used in the routine name (where "region" should
probably be used instead).
- G_get_window()
Reads the database region as stored in the WIND file in the user's
current mapset into region.
An error message is printed and exit() is called if there is a problem
reading the region.
<b>Note:</b> GRASS applications that read or write raster files should
not use this routine since its use implies that the active module
region will not be used. Programs that read or write raster file data
(or vector data) can query the active module region using
G_window_rows() and G_window_cols().
- G_put_window()
Writes the database region file (WIND) in the user's current mapset
from region.
<b>Warning:</b> Since this routine actually changes the database
region, it should only be called by modules which the user knows will
change the region. It is probably fair to say that only the
<tt>g.region</tt> should call this routine.
There is another database region. This region is the default region
for the location. The default region provides the user with a
"starting" region, i.e., a region to begin with and return to as a
reference point. The GRASS modules <tt>g.region</tt> allow the user to
set their database region from the default region (see \ref
Permanent_Mapset for a discussion of the default region). The
following routine reads this region:
- G_get_default_window()
\subsection Active_Module_Region Active Module Region
The <em>active module region</em> is the one that is used when reading
and writing raster file data. This region determines the resampling
when reading raster data. It also determines the extent and resolution
of new raster files.
Initially the active module region and the user's database region are
the same, but the programmer can make them different. The following
routines manage the active module region.
- G_window_rows() number of rows in active region
- G_window_cols() number of columns in active region
These routines return the number of rows and columns (respectively) in
the active module region. Before raster files can be read or written,
it is necessary to known how many rows and columns are in the active
region. For example:
\code
int nrows, cols;
int row, col;
nrows = G_window_rows();
ncols = G_window_cols();
for (row = 0; row < nrows; row++) {
/* read row ... */
for (col = 0; col < ncols; col++) {
/* process col ... */
}
}
\endcode
- G_set_window() set the active region
This routine sets the active region from given region. Setting the
active region does not change the WIND file in the database. It simply
changes the region for the duration of the module.
However, the new region setting is not retained across the UNIX exec()
call. This implies that G_set_window() cannot be used to set the
region for a module to be executed using the system() or popen()
routines.
<b>Note:</b> This routine overrides the region as set by the user. Its
use should be very limited since it changes what the user normally
expects to happen. If this routine is not called, then the active
region will be the same as what is in the user's WIND file.
<b>Warning:</b> Calling this routine with already opened raster files
has some side effects. If there are raster files which are open for
reading, they will be read into the newly set region, not the region
that was active when they were opened. However, CELL buffers allocated
for reading the raster files are not automatically reallocated. The
module must reallocate them explicitly. Also, this routine does not
change the region for raster files which are open for writing. The
region that was active when the open occurred still applies to these
files.
- G_get_set_window() get the active region
Gets the values of the currently active region into region. If
G_set_window() has been called, then the values set by that call are
retrieved. Otherwise the user's database region is retrieved.
<b>Note:</b> For modules that read or write raster data, and really
need the full region information, this routine is preferred over
G_get_window(). However, since G_window_rows() and G_window_cols()
return the number of rows and columns in the active region, the
programmer should consider whether or not the full region information
is really needed before using this routine.
- G_align_window() align two regions
Modifies the input region to align to the reference region. The
resolutions in region are set to match those in refefence region and
the region edges (north, south, east, west) are modified to align with
the grid of the reference region.
The <i>region</i> may be enlarged if necessary to achieve the
alignment. The north is rounded northward, the south southward, the
east eastward and the west westward.
- G_col_to_easting()
Converts a column relative to a region to an easting.
<b>Note:</b> col is a double: col+0.5 will return the easting for the
center of the column; col+0.0 will return the easting for the western
edge of the column; and col+1.0 will return the easting for the
eastern edge of the column.
- G_row_to_northing()
Converts a row relative to a region to a northing.
<b>Note:</b> row is a double: row+0.5 will return the northing for the
center of the row; row+0.0 will return the northing for the northern
edge of the row; and row+1.0 will return the northing for the southern
edge of the row.
- G_easting_to_col()
Converts an easting relative to a region to a column.
<b>Note:</b> The result is a double. Casting it to an integer will
give the column number.
- G_northing_to_row()
Converts a northing relative to a region to a row.
<b>Note:</b> the result is a double. Casting it to an integer will
give the row number.
\section Projection_Information Projection Information
The following routines return information about the cartographic
projection and zone. See \ref Region for more information about these
values.
- G_projection()
This routine returns a code indicating the projection for the active
region. The current values are:
- PROJECTION_XY - unreferenced x,y (imagery data)
- PROJECTION_UTM - UTM
- PROJECTION_SP - State Plane
- PROJECTION_LL - Latitude-Longitude
- PROJECTION_OTHER - Other (more than 121 projections are supported)
- G_database_projection_name()
Returns a pointer to a string which is a printable name for projection
code (as returned by G_projection()).
- G_database_unit_name()
Returns a string describing the database grid units.
- G_database_units_to_meters_factor()
Returns a factor which converts the grid unit to meters (by
multiplication). If the database is not metric (eg. imagery) then 0.0
is returned.
- G_zone()
This routine returns the zone for the active region. The meaning for
the zone depends on the projection. For example zone 18 for projection
type 1 would be UTM zone 18.
\subsection Latitude_Longitude_Databases Latitude-Longitude GIS Databases
GRASS supports databases in a longitude-latitude grid using a
projection where the x coordinate is the longitude and the y
coordinate is the latitude. This projection is called the Equidistant
Cylindrical Projection (also known as Plate Carree). ECP has the
property that <em>where am I</em> and <em>row-column</em> calculations
are identical to those in planimetric grids (like UTM, Universal
Transverse Mercator Projection). This implies that normal GRASS
registration and overlay functions will work without any special
considerations or modifications to existing code. However, the
projection is not planimetric. This means that distance and area
calculations are no longed Euclidean.
Also, since the world is round, maps may not have edges in the
east-west direction, especially for global databases. Maps may have
the same longitude at both the east and west edges of the
display. This feature, called global wraparound, must be accounted for
by GRASS modules (particularly vector based functions, like plotting).
What follows is a description of the GIS Library routines that are
available to support latitude-longitude databases.
\subsection Coordinates Coordinates
Latitudes and longitudes are specified in degrees. Northern latitudes
range from 0 to 90 degrees, and southern latitudes from 0 to
-90. Longitudes have no limits since longitudes ±360 degrees are
equivalent.
Coordinates are represented in ASCII using the format
<tt>dd:mm:ssN</tt> or <tt>dd:mm:ssS</tt> for latitudes,
<tt>ddd:mm:ssE</tt> or <tt>ddd.mm.ssW</tt> for longitudes, and
<tt>dd.mm.ss</tt> for grid resolution. For example, 80:30:24N
represents a northern latitude of 80 degrees, 30 minutes, and 24
seconds. 120:15W represents a longitude 120 degrees and 15 minutes
west of the prime meridian. 30:15 represents a resolution of 30
degrees and 15 minutes. These next routines convert between ASCII
representations and the machine representation for a coordinate. They
work both with latitude-longitude projections and planimetric
projections.
<b>Note:</b> In each subroutine, the programmer must specify the
projection number. If the projection number is PROJECTION_LL (defined
in "gis.h"), then latitude-longitude ASCII format is invoked.
Otherwise, a standard floating-point to ASCII conversion is made.
- G_format_easting() easting to ASCII
- G_format_northing() northing to ASCII
Converts the double representation of the given coordinate to its
ASCII representation.
- G_format_resolution()
Converts the double representation of the resolution to its
ASCII representation.
- G_scan_easting() ASCII easting to double
- G_scan_northing() ASCII northing to double
Converts the ASCII coordinate string in to its double representation.
- G_scan_resolution() ASCII resolution to double
Converts the ASCII "resolution" string to its double representation
(into resolution).
The following are examples of how these routines are used.
\code
double north;
char buf[50];
G_scan_northing(buf, north, G_projection()); /* ASCII to double */
G_format_northing(north, buf, G_projection()); /* double to ASCII */
G_format_northing(north, buf, -1); /* double to ASCII */
/* This last example forces floating-point ASCII format */
\endcode
\subsection Global_Wraparound Global Wraparound
These next routines provide a mechanism for determining the relative
position of a pair of longitudes. Since longitudes of ±360 are
equivalent, but GRASS requires the east to be bigger than the west,
some adjustment of coordinates is necessary.
- G_adjust_easting()
Returns east larger than west. If the region projection is
PROJECTION_LL, then this routine returns an equivalent <i>east</i>
that is larger, but no more than 360 degrees larger, than the
coordinate for the western edge of the region. Otherwise no adjustment
is made and the original <i>east</i> is returned.
- G_adjust_east_longitude()
This routine returns an equivalent <i>east</i> that is larger, but no
more than 360 larger than the <i>west</i> coordinate.
This routine should be used only with latitude-longitude coordinates.
- G_shortest_way()
Returns shortest way between eastings.
\subsection Miscellaneous Miscellaneous
- G_ellipsoid_name()
This routine returns a pointer to a string containing the name for the
ellipsoid in the GRASS ellipsoid table. It can be used as follows:
\code
int n;
char *name;
for(n = 0; name = G_ellipsoid_name(n); n++)
fprintf(stdout, "%s\n", name);
\endcode
- G_get_ellipsoid_by_name()
This routine returns the semi-major axis (in meters) and
eccentricity squared for the named ellipsoid.
- G_get_ellipsoid_parameters()
This routine returns the semi-major axis (in meters) and the
eccentricity squared for the ellipsoid associated with the
database. If there is no ellipsoid explicitly associated with the
database, it returns the values for the WGS 84 ellipsoid.
- G_meridional_radius_of_curvature()
Returns the meridional radius of curvature at a given longitude:
\f$
\rho = \frac{a (1-e^2)}{(1-e^2\sin^2 lon)^{3/2}}
\f$
- G_transverse_radius_of_curvature()
Returns the transverse radius of curvature at a given longitude:
\f$
\nu = \frac{a}{(1-e^2\sin^2 lon)^{1/2}}
\f$
- G_radius_of_conformal_tangent_sphere()
Returns the radius of the conformal sphere tangent to ellipsoid at a
given longitude:
\f$
r = \frac{a (1-e^2)^{1/2}}{(1-e^2\sin^2 lon)}
\f$
- G_pole_in_polygon()
For latitude-longitude coordinates, this routine determines if the
polygon contains one of the poles.
\section Calculations Calculations
\subsection Raster_Area_Calculations Raster Area Calculations
The following routines perform area calculations for raster maps.
They are based on the fact that while the latitude-longitude grid is
not planimetric, the size of the grid cell at a given latitude is
constant. The first routines work in any projection.
- G_begin_cell_area_calculations()
This routine must be called once before any call to
G_area_of_cell_at_row(). It can be used in either planimetric
projections or the latitude-longitude projection.
- G_area_of_cell_at_row()
This routine returns the area in square meters of a cell in the
specified row. This value is constant for planimetric grids and varies
with the row if the projection is latitude-longitude.
- G_begin_zone_area_on_ellipsoid()
Initializes raster area calculations for an ellipsoid.
- G_area_for_zone_on_ellipsoid()
Returns the area between latitudes scaled by the factor passed to
G_begin_zone_area_on_ellipsoid().
- G_begin_zone_area_on_sphere()
Initializes raster area calculations for a sphere.
- G_area_for_zone_on_sphere()
Returns the area between latitudes.
\subsection Polygonal_Area_Calculations Polygonal Area Calculations
These next routines provide area calculations for polygons. Some of
the routines are specifically for latitude-longitude, while others
will function for all projections.
However, there is an issue for latitude-longitude that does not occur
with planimetric grids. Vector/polygon data is described as a series
of x,y coordinates. The lines connecting the points are not stored but
are inferred. This is a simple, straight-forward process for
planimetric grids, but it is not simple for latitude-longitude. What
is the shape of the line that connects two points on the surface of a
globe?
One choice (among many) is the shortest path from <tt>x1,y1</tt> to
<tt>x2,y2</tt>, known as the geodesic. Another is a straight line on
the grid. The area routines described below assume the
latter. Routines to work with the former have not yet been developed.
- G_begin_polygon_area_calculations()
This initializes the polygon area calculation routines. It is used
both for planimetric and latitude-longitude projections.
- G_area_of_polygon()
Returns the area in square meters of the polygon. It is used both for
planimetric and latitude-longitude projections.
<B>Note.</B> If the database is planimetric with the non-meter grid,
this routine performs the required unit conversion to produce square
meters.
- G_planimetric_polygon_area()
Return the area in map units of the polygon,