-
-
Notifications
You must be signed in to change notification settings - Fork 288
/
raster3dlib.dox
1751 lines (1369 loc) · 56.4 KB
/
raster3dlib.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 raster3dlib GRASS 3D Raster Volume Library
<!-- doxygenized from "GRASS 5 Programmer's Manual"
by M. Neteler 5/2004, 8/2005
-->
<i>TODO: Update for this page for GRASS 7, most of the function names have been changed from camel case to gnu underscore style.</i>
\tableofcontents
\section raster3dlib_Overview Overview
The 3D Raster Volume Library is used for the <tt>r3.*</tt> and vector
volume tools. The library uses a tile cache based approach to store
floating point values in arbitrary order in a volume. The coordinate
system of a volume is column and row compatible to the raster library
and counts from the bottom to the top of the cube.
<P>
Random reading and writing is supported until are tiles are flushed to the disk.
In case the tiles are written to the disk, random reading is still supported.
<P>
The size of the tile cache in memory can be set in bytes using the environmental variable RASTER3D_MAX_CACHE_SIZE.
Default size is 16777216 bytes.The number of tiles hold in memory can be specified with the environmental variable
RASTER3D_DEFAULT_CACHE_SIZE. Default is 1000.
\image html "raster3d_layout.png" "The volume coordinate system and tile layout of the 3D Raster Library"
\section Directory_Structure Directory Structure
<P>
The file format consists of a mapset element <EM>grid3</EM> which contains a
directory for every map. The elements for each map are
<P>
\verbatim
3d region file
color file (color)
categories file (cats)
range file (range)
timestamp file
cell file (cell)
header file (cellhd)
a directory containing display files (dsp)
\endverbatim
<P>
There is also a <EM>colr2</EM> mechanism provided. <EM>colr2</EM> color tables
are stored in <EM>grid3/colr2/MAPSET/MAP</EM>.
<P>
Note: color, categories, and the range can be used in the same way as in <EM>2d</EM>
GRASS with the exception of reading and writing. <EM>3d</EM> read and write
functions have to be used for this purpose.
\section Data_File_Format Data File Format
<UL>
<LI>Cell-values can be either double or float.
</LI>
<LI>Values are written in XDR-format.
</LI>
<LI>NULL-values are stored in an embedded fashion.
</LI>
<LI>The cell-values are organized in <EM>3d</EM>-tiles.
</LI>
<LI>The tile dimensions can be chosen when a new map is opened.
</LI>
<LI>Every tile of a map has the same dimension except those which overlap the
region boundaries.
</LI>
<LI>Compression is used to store tiles.
</LI>
</UL>
<P>
The data file has the following format:
<P>
\verbatim
xdr_int nofBytesLong;
xdr_int nofBytesUsed;
encoded_long indexOffset;
compressed_tile[] tiles;
compressed_encoded_long[] index;
\endverbatim
<P>
\section Transportability_of_data_file Transportability of data file
<P>
All numbers stored in the data file are either XDR-encoded or encoded by some
other method (for variables of type long only).
<P>
\section Tile_Data_NULL_values Tile Data NULL-values
<P>
RASTER3D uses the same functions as <EM>2d</EM> GRASS to set and test NULL-values. The
storage in the file is different though. NULL-values are stored with a special
bit-pattern if maximum precision is chosen. They are stored by adding an
additional bit if the precision is smaller.
<P>
\section Tile_Data_Compression Tile Data Compression
NOTE: RLE compression was removed because of error-prone implementation.
De-compression is still available for backward compatibility.
Default compression is now zip.
<P>
There are three methods of compression provided. The compression
methods can either be those defined by default, set by environment
variables or explicitly set at run-time.
\verbatim
Precision
zlib
\endverbatim
<P>
Precision indicates how many of the mantissa bits should be stored on
file. This number can be any value between 0 and 23 for floats and
between 0 and 52 for doubles. Choosing a small precision is the most
effective way to achieve good compression.
<P>
The default and suggested setting is to use precision and zlib.
<P>
Additional compression is achieved by storing the extra NULL-bit in a
separate bit-array. Using this scheme NULL-values need not actually be
represented in the array of cell values. This array is stored together
with the cell-values of the tile.
\section Tile_Cache Tile Cache
<P>
Tiles can either be read and written directly or use an intermediate
cache instead.
<P>
In non-cache mode the application should only use the functions
<P>
int Rast3d_readTile()
<P>
and
<P>
int Rast3d_writeTile()
<P>
to read and write tiles. The application can use one tile provided by the map
structure as buffer. See <TT>Rast3d_getTilePtr()</TT>.
<P>
In cache mode the application can access cell-values directly by their
coordinates. The corresponding functions are
<P>
int Rast3d_get_value()
<P>
and
<P>
int Rast3d_put_value()
<P>
and their corresponding typed versions.
<BR>
<P>
If the map is new then in addition to the memory-cache a file-cache is provided.
This allows the application to write the cell-values in any arbitrary order.
Tiles are written (flushed) to the data-file either at closing time or if
explicitly requested.
<BR>
<P>
If the map is new <TT>Rast3d_get_value()</TT> can be used even if the tile which
contains the cell has already been flushed to the data file. In this case the
tile is simply read back into the memory-cache from the data file.
<BR>
<P>
Explicitly flushing tiles can have the advantage that less disk space is
occupied since tiles are stored in a uncompressed fashion in the file-cache.
Flushing tiles explicitly can cause problems with accuracy though if precision
is less than the maximum precision and an already flushed value is used for
computations later in the program.
<BR>
<P>
The type of the cell-values of the tiles in memory can be chosen independently
of the type of the tiles in the file. Here, once again one has to consider
possible problems arising from mixing different precisions.
<BR>
<P>
As an example consider the case where the data is stored in the file with double
precision and the tiles are stored in memory in single precision. Then using
<TT>Rast3d_get_value()</TT> will actually return a double precision number whose precision
is only 23 bits. It is therefore a good idea to use the types in the memory
consistently.
<BR>
<P>
\section Header_File Header File
<P>
The header file has the following format:
<P>
\verbatim
Proj: 1
Zone: 1
North: 2.0000000000000
South: 0.5000000000000
East: 4.0000000000000
West: 3.0000000000000
Top: 6.0000000000000
Bottom: 5.0000000000000
nofRows: 30
nofCols: 20
nofDepths: 14
e-w resol: 0.05
n-s resol: 0.05
t-b resol: 0.071428571
TileDimensionX: 8
TileDimensionY: 8
TileDimensionZ: 8
CellType: double
useCompression: 1
useRle: 1
Precision: -1
nofHeaderBytes: 12
useXdr: 1
hasIndex: 1
Units: none
VerticalUnits: 1
\endverbatim
<P>
Except for the first 14 fields the entries of the header file should
not be modified. The precision value -1 indicates that maximum
precision is used.
<BR>
<P>
Binary files not in RASTER3D format can be read by the library. The
following actions have to be taken:
<P>
Make a new map directory in the <EM>grid3</EM> element of the mapset (say <EM>mymap</EM>).
Copy the file into <EM>mymap/cell</EM> and generate a header file <EM>mymap/cellhd</EM>.
<P>
In the following example the relevant values of <EM>mymap/cellhd</EM> are shown:
<P>
\verbatim
TileDimensionX: A
TileDimensionY: B
TileDimensionZ: C
useCompression: 0
useRle: 0
Precision: -1
nofHeaderBytes: X
useXdr: 0
hasIndex: 0
\endverbatim
<P>
The values of <EM>A</EM>, <EM>B</EM>, and <EM>C</EM> have to be chosen
according to one of the following patterns:
<P>
\verbatim
A >= 1, B == 1, C == 1, or
A >= nofRows, B >= 1, C == 1, or
A >= nofRows, B >= nofCols, C >= 1.
\endverbatim
<P>
A larger tile size reduces the number of tile-reads. If in the third pattern
<EM>C</EM> is chosen larger than or equal to <EM>nofDepths</EM>, the entire region is
considered one large tile.
<P>
The value <EM>nofHeaderBytes</EM> indicates the offset in the file to the first
data entry.
<P>
For performance reasons it is a good idea to use function
<TT>Rast3d_retile()</TT> before using the file in other applications.
<P>
\section Region_Structure Region Structure
<P>
\verbatim
typedef struct{
double north, south;
double east, west;
double top, bottom;
int rows, cols, depths; // data dimensions in cells
double ns_res, ew_res, tb_res;
int proj; // Projection (see gis.h)
int zone; // Projection zone (see gis.h)
} RASTER3D_Region;
\endverbatim
<P>
\section Windows Windows
<P>
Window capability similar to that of <EM>2d</EM> GRASS is provided (compare
Region). Additional features are the window for the third dimension
as well as the possibility to choose a different window for every map. The
window can be specified at the time of opening an old map. It can be modified
at any time later in the program. The resampling method can be the default
nearest neighbor method as well as an application provided method.
<BR>
<P>
The default <EM>3d</EM> window file is <EM>WIND3</EM> located in the mapset.
Application programs should use <TT>Rast3d_useWindowParams()</TT> to allow the
user to overwrite this default.
<P>
The window file has the following format:
<P>
\verbatim
Proj: 1
Zone: 1
North: 2.0
South: 0.5
East: 4.0
West: 3.0
Top: 5.0
Bottom: 6.0
nofRows: 30
nofCols: 20
nofDepths: 14
e-w resol: 0.05000000000000000
n-s resol: 0.05000000000000000
t-b resol: 0.07142857142857142
\endverbatim
<P>
Note: after reading the window file the fields <EM>e-w</EM>, <EM>n-s</EM>, and <EM>t-b</EM>
are recomputed internally.
<P>
A note about windows and caching. Caching is performed on the level of tiles
read from the file. There is no caching performed on resampled data. This is
different from <EM>2d</EM> GRASS since resampling for a specific value is
performed every time it is being accessed.
<P>
\section Masks Masks
<P>
RASTER3D provides a mask for the <EM>3d</EM> region. The mask structure is
automatically initialized at the time the first file is opened. The same
structure is used for all the files. The default for every file is that the
mask is turned off. If masking should be performed, the application program has
to turn on masking explicitly. If masking is turned on for a file, the
cell-values of a tile are automatically checked against the mask. Values which
are masked out, are set to NULL.
<P>
Note: changing the status of masking after one or more tiles have already
been read does not affect the tiles which are already stored in the cache.
<P>
Any arbitrary 3d raster map can be used as mask file: NULL-values are interpreted as
<TT>"mask-out"</TT>, all other values are interpreted as <TT>"don't mask
out"</TT>. Using <EM>r3.mask</EM> to convert a 3d raster map into a mask file instead of
simply copying (or renaming) the directory will significantly reduce to amount
of disk space and the access time for the mask.
<P>
\section Include_File Include File
<P>
Exported RASTER3D constants and structures can be found in <EM>raster3d.h</EM>.
<P>
\section RASTER3D_Defaults RASTER3D Defaults
<P>
There are three methods to set default variables. First, the default can be set
at compile time in <EM>g3ddefault.c</EM>. This value has lowest priority.
<P>
Second, the default can be set via an environment variable. Third, the value
can be set explicitly set at run time. This value has highest priority.
<P>
There are also functions provided to query the value.
<P>
\section Cache_Mode Cache Mode
<P>
\subsection Limiting_the_maximum_cache_size Limiting the maximum cache size
<P>
The limit is specified in bytes. It is a limit on the size of cell-data stored
in the cache and does not include the support structure.
<P>
Default RASTER3D_CACHE_SIZE_MAX_DEFAULT. This is currently set to 16meg and can
be changed at compilation time of the library.
<P>
Environment variable RASTER3D_MAX_CACHE_SIZE.
<P>
void Rast3d_setCacheLimit(int nBytes)Set cache limit
<P>
int Rast3d_getCacheLimit(int nBytes)Get cache limit
<P>
\subsection Setting_the_cache_size Setting the cache size
<P>
This value specifies the number of tiles stored in the cache. It is the value
used if at opening time of a map RASTER3D_USE_CACHE_DEFAULT is used for the cache
mode. Any other value used at opening time will supersede the default value. A
default value of 0 indicates that non-cache mode should be used by default.
<P>
Default RASTER3D_CACHE_SIZE_DEFAULT. This is currently set to 1000 and can be
changed at compilation time of the library.
<P>
Environment variable RASTER3D_DEFAULT_CACHE_SIZE.
<P>
void Rast3d_setCacheSize(int nTiles)
<P>
int Rast3d_getCacheSize()
<P>
\section Compression Compression
\subsection Toggling_compression_mode Toggling compression mode
<P>
This value specifies whether compression should be used while writing a new
map. It does not have any effect on old maps.
<P>
Default RASTER3D_COMPRESSION_DEFAULT. This is set to RASTER3D_COMPRESSION. This
default should not be changed.
<P>
Environment variables RASTER3D_USE_COMPRESSION and RASTER3D_NO_COMPRESSION.
<P>
See functions Rast3d_setCompressionMode() (cf.
Section 22.3.2.3 ) and Rast3d_getCompressionMode() (cf. Section 22.3.2.3 ).
<P>
\subsection Toggling_RLE_compression Toggling RLE compression
NOTE: RLE compression is not used any longer, the RLE code is still present to assure backward compatibility.
G_zlib_write() and G_zlib_read() are used for compression now.
<P>
This value specifies whether RLE compression should be used (in addition to
precision).
<P>
Default RASTER3D_USE_RLE_DEFAULT. This is currently set to RASTER3D_USE_RLE and can
be changed at compilation time of the library.
<P>
Environment variables RASTER3D_USE_RLE and RASTER3D_NO_RLE.
<P>
See functions Rast3d_setCompressionMode() (cf.
Section 22.3.2.3) and Rast3d_getCompressionMode() (cf. Section 22.3.2.3).
\section Setting_the_precision Setting the precision
<P>
This number specifies how many mantissa bits should be used when writing a cell
value. The minimum value is 0. The maximum value is 23 or RASTER3D_MAX_PRECISION
for type FCELL_TYPE, it is 52 or RASTER3D_MAX_PRECISION for type DCELL_TYPE.
<P>
Default RASTER3D_PRECISION_DEFAULT. This is set to RASTER3D_MAX_PRECISION. This
default should not be changed.
<P>
Environment variables RASTER3D_PRECISION and RASTER3D_MAX_PRECISION.
<P>
void Rast3d_setCompressionMode(int doCompress, int doLzw, int doRle, int
precision) <EM>doCompress</EM> should be one of RASTER3D_NO_COMPRESSION and
RASTER3D_COMPRESSION, <EM>doRle</EM> should be either RASTER3D_NO_RLE or
RASTER3D_USE_RLE, and <EM>precision</EM> should be either RASTER3D_MAX_PRECISION or
a positive integer.
<P>
void Rast3d_getCompressionMode(int *doCompress, int *doLzw, int *doRle,
int *precision)
<P>
\section Tiles Tiles
\subsection Setting_the_tile_dimensions Setting the tile dimensions
<P>
The dimensions are specified in number of cell.
<P>
Defaults RASTER3D_TILE_X_DEFAULT, RASTER3D_TILE_Y_DEFAULT, and
RASTER3D_TILE_Z_DEFAULT. These are currently set to 8 and can be changed at
compilation time of the library.
<P>
Environment variables RASTER3D_TILE_DIMENSION_X, RASTER3D_TILE_DIMENSION_Y, and
RASTER3D_TILE_DIMENSION_Z.
<P>
void Rast3d_setTileDimension(int tileX, int tileY, int tileZ)
<P>
void Rast3d_getTileDimension(int *tileX, int *tileY, int *tileZ)
<P>
\section Setting_the_tile_cell_value_type Setting the tile cell-value type
<P>
Specifies which type is used to write cell-values on file. This type can be
chosen independently of the type used to store cell-values in memory.
<P>
Default RASTER3D_FILE_TYPE_DEFAULT. This is set to DCELL_TYPE. This default
should not be changed.
<P>
Environment variables RASTER3D_WRITE_FLOAT and RASTER3D_WRITE_DOUBLE.
<P>
void Rast3d_setFileType(int type)
<P>
int Rast3d_getFileType(int type)
<P>
\section Setting_the_window Setting the window
<P>
The window is set from a <EM>3d</EM> window file.
<P>
The default <EM>3d</EM> window file is <EM>WIND3</EM> located in the current mapset.
<P>
Possible choices for <EM>3d</EM> window files are <EM>name</EM> which refers to a
window file in the <EM>3d</EM> window database located at <EM>windows3d</EM> of the
current mapset; or file names which are identified by a leading <EM><TT>"/"</TT></EM>
or <EM><TT>"."</TT></EM>; or fully qualified
names, i.e. <EM>file@mapset</EM> which refer to window files in the <EM>3d</EM> window
database of mapset. Note, that names <EM>WIND3</EM> and <EM>WIND3@mapset</EM> do not
specify the default window name in the (current)
mapset but rather a window file in the window database of the (current) mapset.
<P>
Environment variable RASTER3D_DEFAULT_WINDOW3D.
<P>
See functions
<P>
<TT>Rast3d_useWindowParams()</TT>,
<P>
<TT>Rast3d_setWindow()</TT>, and
<P>
<TT>Rast3d_setWindowMap()</TT>.
<P>
\section Setting_the_Units Setting the Units
The data untis of a map can be described using a string.
The vertical units are defined in gis.h and can be spatial or temporal.
<P>
No environment variable.
<P>
\verbatim
void Rast3d_set_unit (map, unit)
RASTER3d_Map; // the map
char *unit; // The data unit description
void Rast3d_set_vertical_unit (map, unit)
RASTER3d_Map; // the map
char *unit; // Use the standard from units.c in lib/gis
void Rast3d_set_vertical_unit2 (map, unit)
RASTER3d_Map; // the map
int unit; // defined in gis.h
\endverbatim
\section Error_Handling Error Handling: Setting the error function
<P>
This variable specifies the function which is invoked when an error
(not a fatal error) occurs. For example setting the error function to
<TT>Rast3d_fatalError</TT> simplifies debugging with dbx and also might show
errors which are missed because the application does not check the
return value.
<P>
Default <TT>Rast3d_skipError</TT>.
<P>
Environment variables RASTER3D_USE_FATAL_ERROR and RASTER3D_USE_PRINT_ERROR.
<P>
void Rast3d_setErrorFun(void (*fun)(char *))
<P>
The following 3 functions are possible choices for error functions.
<P>
void Rast3d_skipError(char (*msg)(char *)) This function ignores the
error.
<P>
void Rast3d_printError(char (*msg)(char *)) This function prints the
error message <EM>msg</EM> to <EM>stderr</EM> and returns.
<P>
void Rast3d_fatalError(char (*msg)(char *)) This function prints the
error message <EM>msg</EM> to <EM>stderr</EM>, flushes <EM>stdout</EM>
and <EM>stderr</EM>, and terminates the program with a segementation fault.
<P>
\section RASTER3D_Function_Index RASTER3D Function Index
\subsection Opening_and_Closing_RASTER3D_Files Opening and Closing RASTER3D Files
<P>
void *Rast3d_openCellOld(char *name, char *mapset, RASTER3D_Region *window,
int type, int cache)Opens existing g3d-file <EM>name</EM> in <EM>mapset</EM>.
<P>
Tiles are stored in memory with <EM>type</EM> which must be any of FCELL_TYPE,
DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies the
cache-mode used and must be either RASTER3D_NO_CACHE, RASTER3D_USE_CACHE_DEFAULT,
RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ,
RASTER3D_USE_CACHE_XYZ, the result of <TT>Rast3d_cacheSizeEncode()</TT> (cf.
Section 22.4.6), or any positive integer which
specifies the number of tiles buffered in the cache. <EM>window</EM> sets the
window-region for the map. It is either a pointer to a window structure or
RASTER3D_DEFAULT_WINDOW, which uses the window stored at initialization time or
set via <TT>Rast3d_setWindow()</TT> (cf. Section 22.4.16).
To modify the window for the map after it has already been opened use
<TT>Rast3d_setWindowMap()</TT> (cf. Section 22.4.16).
<P>
Returns a pointer to the cell structure ... if successful, NULL ...
otherwise.
<P>
void *Rast3d_openCellNew(char *name, int type, int cache, RASTER3D_Region
*region)Opens new g3d-file with <EM>name</EM> in the current mapset. Tiles
are stored in memory with <EM>type</EM> which must be one of FCELL_TYPE,
DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies the
cache-mode used and must be either RASTER3D_NO_CACHE, RASTER3D_USE_CACHE_DEFAULT,
RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ,
RASTER3D_USE_CACHE_XYZ, the result of <TT>Rast3d_cacheSizeEncode()</TT> (cf.
Section 22.4.6), or any positive integer which
specifies the number of tiles buffered in the cache. <EM>region</EM> specifies
the 3d region.
<P>
Returns a pointer to the cell structure ... if successful,
NULL ... otherwise.
<P>
void *Rast3d_openCellNewParam(char *name, int typeIntern, int cache,
RASTER3D_Region *region, int type, int doLzw, int doRle, int precision, int tileX,
int tileY, int tileZ)Opens new g3d-file with <EM>name</EM> in the current
mapset. Tiles are stored in memory with <EM>typeIntern</EM> which must be one of
FCELL_TYPE, DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies
the cache-mode used and must be either RASTER3D_NO_CACHE,
RASTER3D_USE_CACHE_DEFAULT, RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y,
RASTER3D_USE_CACHE_Z, RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ,
RASTER3D_USE_CACHE_YZ, RASTER3D_USE_CACHE_XYZ, the result of
<TT>Rast3d_cacheSizeEncode()</TT> (cf.
Section 22.4.6), or any positive integer which
specifies the number of tiles buffered in the cache. <EM>region</EM> specifies
the 3d region.
<P>
In addition the properties of the new file have to be specified. It is
assumed by default that compression is used. This function first sets the
global default values to the specified values, and then restores the original
global defaults. This function can be used in conjunction with
<TT>Rast3d_setStandard3dInputParams()</TT> (cf.
Section 22.4.18) and
<TT>Rast3d_getStandard3dParams()</TT>.
<P>
Returns a pointer to the cell structure ... if successful, NULL ...
otherwise.
<P>
int Rast3d_closeCell(void *map)Closes g3d-file. If <EM>map</EM> is new
and cache-mode is used for <EM>map</EM> then every tile which is not flushed
before closing is flushed.
<P>
Returns 1 ... if successful, 0 ... otherwise.
<P>
void *Rast3d_open_new_opt_tile_size(const char *name, int cache, RASTER3D_Region * region, int type, int maxSize)
Opens new g3d-file with <em>name</em> in the current mapset. This method tries to compute
optimal tile size based on the number of rows, cols and depths and the maximum allowed tile size in KB.
Tiles are stored in memory using RASTER3D_TILE_SAME_AS_FILE method. <em>cache</em> specifies the
cache-mode used and must be either RASTER3D_NO_CACHE, RASTER3D_USE_CACHE_DEFAULT,
RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ,
RASTER3D_USE_CACHE_XYZ, the result of <tt>Rast3d_cache_size_encode ()</tt>
(cf.{g3d:G3d.cacheSizeEncode}), or any positive integer which
specifies the number of tiles buffered in the cache. <em>region</em> specifies
the 3d region.
The map is created using the <em>type</em> which must be of FCELL_TYPE or DCELL_TYPE.
<P>
Returns a pointer to the cell structure ... if successful,
NULL ... otherwise.
<P>
\subsection Reading_and_Writing_Tiles Reading and Writing Tiles
<P>
These functions read or write data directly to the file (after performing the
appropriate compression) without going through the cache. In order to avoid
unexpected side-effects the use of these functions in cache mode is
discouraged.
<P>
int Rast3d_readTile(void *map, char *tileIndex, int tile, int type)
Reads tile with index <EM>tileIndex</EM> into the <EM>tile</EM> buffer. The cells
are stored with type <EM>type</EM> which must be one of FCELL_TYPE and
DCELL_TYPE. If the tile with <EM>tileIndex</EM> is not stored on the file
corresponding to <EM>map</EM>, and <EM>tileIndex</EM> is a valid index <EM>tile</EM>
is filled with NULL-values.
<P>
Returns
1 ... if successful,
0 ... otherwise.
<P>
int Rast3d_readTileFloat(void *map, char *tileIndex, int tile)
Is equivalent to Rast3d_readTile (map, tileIndex, tile, FCELL_TYPE).
<P>
int Rast3d_readTileDouble(void *map, char *tileIndex, int tile)
Is equivalent to Rast3d_readTile (map, tileIndex, tile, DCELL_TYPE).
<P>
int Rast3d_writeTile(void *map, char *tileIndex, int tile, int type)
Writes tile with index <EM>tileIndex</EM> to the file corresponding to <EM>map</EM>. It is assumed that the cells in <EM>tile</EM> are of <EM>type</EM> which
must be one of FCELL_TYPE and DCELL_TYPE. The actual type used to write the
tile depends on the type specified at the time when <EM>map</EM> is initialized.
<P>
A tile can only be written once. Subsequent attempts to write the same tile
are ignored.
<P>
Returns
1 ... if successful,
2 ... if write request was ignored,
0 ... otherwise.
<P>
int Rast3d_writeTileFloat(void *map, char *tileIndex, int tile)
Is equivalent to <TT>Rast3d_writeTile (map, tileIndex, tile, FCELL_TYPE).</TT>
<P>
int Rast3d_writeTileDouble(void *map, char *tileIndex, int tile)
Is equivalent to <TT>Rast3d_writeTile (map, tileIndex, tile, DCELL_TYPE).</TT>
<P>
\subsection Reading_and_Writing_Cells Reading and Writing Cells
<P>
void Rast3d_getValue(void *map, int x, int y, int z, char *value, int
type) Returns in <EM>*value</EM> the cell-value of the cell with
window-coordinate <EM>(x, y, z)</EM>. The value returned is of <EM>type</EM>.
<P>
This function invokes a fatal error if an error occurs.
<P>
float Rast3d_getFloat(void *map, int x, int y, int z)Is equivalent to
<TT>Rast3d_getValue (map, x, y, z, &value, FCELL_TYPE);</TT> return value.
<P>
double Rast3d_getDouble(void *map, int x, int y, int z)Is equivalent
to <TT>Rast3d_getValue (map, x, y, z, &value, DCELL_TYPE);</TT> return value.
<P>
void Rast3d_getValueRegion(void *map, int x, int y, int z, char*value,
int type) Returns in <EM>*value</EM> the cell-value of the cell with
region-coordinate <EM>(x, y, z)</EM>. The value returned is of <EM>type</EM>.
Here <EM>region</EM> means the coordinate in the cube of data in the file, i.e.
ignoring geographic coordinates.
<P>
This function invokes a fatal error if an error occurs.
<P>
float Rast3d_getFloatRegion(void *map, int x, int y, int z)Is
equivalent to <TT>Rast3d_getValueRegion (map, x, y, z, &value, FCELL_TYPE);</TT>
return value.
<P>
\code
Rast3d_getDoubleRegion(map, x, y, z)
\endcode
is equivalent to
\code
Rast3d_getValueRegion(map, x, y, z, &value, DCELL_TYPE)
\endcode
<P>
int Rast3d_putValue(void *map, int x, int y, int z, char *value, int
type)After converting <EM>*value</EM> of <EM>type</EM> into the type specified
at the initialization time (i.e. <EM>typeIntern</EM>) this function writes the
value into the tile buffer corresponding to cell-coordinate <EM>(x, y, z)</EM>.
<P>
Returns
<P>
1 ... if successful,
0 ... otherwise.
<P>
int Rast3d_putFloat(void *map, int x, int y, int z, char *value)Is
equivalent to Rast3d_putValue (map, x, y, z, &value, FCELL_TYPE).
<P>
int Rast3d_putDouble(void *map, int x, int y, int z, char *value) Is
equivalent to Rast3d_putValue (map, x, y, z, &value, DCELL_TYPE).
<P>
\subsection Loading_and_Removing_TilesLoading and Removing Tiles
<P>
char *Rast3d_getTilePtr(void *map, int tileIndex) This function
returns a pointer to a tile which contains the data for the tile with index
<EM>tileIndex</EM>. The type of the data stored in the tile depends on the type
specified at the initialization time of <EM>map</EM>. The functionality is
different depending on whether <EM>map</EM> is old or new and depending on the
cache-mode of <EM>map</EM>.
<BR>
<P>
If <EM>map</EM> is old and the cache is not used the tile with <EM>tileIndex</EM>
is read from file and stored in the buffer provided by the map structure.
The pointer to this buffer is returned. If the buffer already contains the
tile with <EM>tileIndex</EM> reading is skipped. Data which was stored in
earlier calls to <TT>Rast3d_getTilePtr</TT> is destroyed. If the tile with
<EM>tileIndex</EM> is not stored on the file corresponding to <EM>map</EM>, and
<EM>tileIndex</EM> is a valid index the buffer is filled with NULL-values.
<BR>
<P>
If <EM>map</EM> is old and the cache is used the tile with <EM>tileIndex</EM> is
read from file and stored in one of the cache buffers. The pointer to buffer
is returned. If no free cache buffer is available an unlocked cache-buffer
is freed up and the new tile is stored in its place. If the tile with
<EM>tileIndex</EM> is not stored on the file corresponding to <EM>map</EM>, and
<EM>tileIndex</EM> is a valid index the buffer is filled with NULL-values. If one
of the cache buffers already contains the tile with <EM>tileIndex</EM> reading
is skipped and the pointer to this buffer is returned.
<BR>
<P>
If <EM>map</EM> is new and the cache is not used the functionality is the same
as if <EM>map</EM> is old and the cache is not used. If the tile with
<EM>tileIndex</EM> is already stored on file, it is read into the buffer, if not,
the cells are set to null-values. If the buffer corresponding to the pointer
is used for writing, subsequent calls to <TT>Rast3d_getTilePtr</TT> may destroy the
values already stored in the buffer. Use <TT>Rast3d_flushTile</TT> to write the buffer
to the file before reusing it for a different index. The use of this buffer
as write buffer is discouraged.
<BR>
<P>
If <EM>map</EM> is new and the cache is used the functionality is the same as if
<EM>map</EM> is old and the cache is used with the following exception. If
<EM>tileIndex</EM> is a valid index and the tile with this index is not found in
the cache and is not stored on the file corresponding to <EM>map</EM>, then the
file cache is queried next. If the file-cache contains the tile it is loaded
into the cache (memory-cache). Only if the file-cache does not contain the
tile it is filled with NULL-values. Tile contents of buffers are never
destroyed. If a cache buffer needs to be freed up, and the tile stored in the
buffer has not been written to the file corresponding to <EM>map</EM> yet, the
tile is copied into the file-cache.
<BR>
<P>
Care has to be taken if this function is used in non-cache mode since it is
implicitly invoked every time a read or write request is issued. The only
I/O-functions for which it is safe to assume that they do not invoke
<TT>Rast3d_getTilePtr</TT> are <TT>Rast3d_readTile()</TT> and
<TT>Rast3d_writeTile()</TT> and their corresponding type-specific versions.
<P>
Returns
a pointer to a buffer ... if successful,
NULL ... otherwise.
<P>
int Rast3d_tileLoad(void *map, int tileIndex)
Same functionality as <TT>Rast3d_getTilePtr()</TT> but does not return the
pointer.
<P>
Returns
1 ... if successful,
0 ... otherwise.
<P>
int Rast3d_removeTile(void *map, inttileIndex) Removes a tile
from memory-cache if tile is in memory-cache. For new maps the
application does not know whether the tile is in the memory-cache or in
the file-cache. Therefore, for new maps this function should be
preceded by <TT>Rast3d_tileLoad()</TT>.
<P>
<EM>(Question: Is this a useful function?)</EM>
<P>
Returns 1 ... if successful, 0 ... otherwise.
<P>
\subsection Write_Functions_used_in_Cache_Mode Write Functions used in Cache Mode
<P>
int Rast3d_flushTile(void *map, int tileIndex) Writes the tile with
<EM>tileIndex</EM> to the file corresponding to <EM>map</EM> and removes the tile
from the cache (in non-cache mode the buffer provided by the map-structure is
written).
<P>
If this tile has already been written before the write request is ignored.
If the tile was never referred to before the invocation of Rast3d_flushTile, a
tile filled with NULL-values is written.
<P>
Returns
1 ... if successful,
0 ... otherwise.
<P>
int Rast3d_flushTileCube(void *map, int xMin, int yMin, int zMin, int
xMax, int yMax, int zMax) Writes the tiles with tile-coordinates