File: manual.txt

package info (click to toggle)
libgeotiff 1.5.1-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 3,300 kB
  • sloc: ansic: 8,080; sh: 3,977; makefile: 166
file content (453 lines) | stat: -rw-r--r-- 16,375 bytes parent folder | download
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
-------------------------------------------------------------

          Manual for Libgeotiff Library and Utilities

-------------------------------------------------------------

Documentation Author: Niles Ritter
Last Modified: 31 Jul 95
  
See: http://www.remotesensing.org/geotiff/api/index.html 
  for up to date API documentation
  
-------------------------------------------------------------
Contents:

  1. The LibGeoTIFF library
  
     1.1 Preliminaries
     1.2 Calling Sequences
	 1.3 Examples

  2. The LibGeoTIFF Utilities
  
     2.1 listgeo   - dump a GeoTIFF metadata file
	 2.2 geotifcp  - install GeoTIFF from metadata

-------------------------------------------------------------
1. The LibGeoTIFF library

-------------------------------------------------------------
1.1 Preliminaries

-------------------
1.1.1 Compliance:

    ANSI-C:  The GeoTIFF library is fully ANSI compliant and
	   should compile under any ANSI compiler. It is not guaranteed
	   to compile under K&R compilers.
	
	C++:   All headers have the appropriate C++ bindings permitting
	   the correct linkage to C++ routines.
	   
-------------------
1.1.2 Interfaces:

	xtiffio.h: the primary interface header file for all TIFF
				routines, using the extended GeoTIFF tags.
				
	geotiffio.h: the primary interface header file for all GTIF 
				 routines, keys and code values.

	geotiff.h:  an interface header file for all GTIF 
				 routines, if code values are not required.

	geokeys.h:   defines all valid GEOTIFF GeoKeys.
	
-------------------
1.1.3 Defined macros:

  All of the tag, key and key-value symbolic names in the GeoTIFF spec are
  supported and defined by the inclusion of "geotiffio.h". In addition,
  the following useful values are defined:
  
	GvCurrentVersion:  The current GeoTIFF Directory version. Should always be 1.
	GvCurrentRevision: The current GeoTIFF Key Revision.
	GvCurrentMinorRev: The current GeoTIFF Key-Value (minor) Revision.
	
	KvUndefined:      The universal Key value for "undefined" items.
	KvUserDefined:    The universal Key value for "user-defined" items.

	
-------------------
1.1.4 Defined Types:  

	TIFF             the type of a TIFF file descriptor (if LIBTIFF is used).
	GTIF             the type of a GeoTIFF file descriptor.
	GTIFPrintMethod  the type of a print method passed to GTIFPrint().
	GTIFReadMethod   the type of a read method passed to GTIFImport().
	geokey_t         the type of a GeoTIFF key variable.
	tagtype_t        the type of a TIFF tag variable, such as TYPE_DOUBLE.


-------------------
1.1.5 Key and Code Databases:

	All geokeys are defined and named in the database file
	"geokeys.inc", which in turn is included in "geokeys.h"
	and several other files. The symbolic enumerated names are identical
	to those used in the Appendix of the GeoTIFF spec.
	
	The geokey code values are stored in the other database files
	having the ".inc" suffix, which in turn are all referenced by
	the file "geovalues.h". The ones with names beginning with
	"epsg_" are codes registered in the EPSG/POSC tables, while
	those beginning with "geo_" are specific to GeoTIFF.
	

-------------------------------------------------------------
1.2 Calling Sequences

-------------------
1.2.1 TIFF-level interface


1.2.1.1  GTIFNew  -- Set up a new GeoTIFF file Descriptor
	GTIF*     GTIFNew(void *tif);

GTIFNew() takes an existing TIFF file descriptor and creates
a GTIF GeoTIFF file-I/O object for reading and writing
GeoTIFF keys and values. The TIFF file must currently be open,
though it may be either read or write mode.


1.2.1.2 GTIFFree
	void      GTIFFree(GTIF *gtif);

Destroys the GeoTIFF file descriptor following reading or writing
the keys.


1.2.1.3 GTIFWriteKeys
	int       GTIFWriteKeys(GTIF *gtif);

This routine must be called for a new GeoTIFF file after all of 
the desired Keys are defined and set with GTIFSetKey(). This does
not explicitly write anything out to the file, but it does call
the TIFF-level routines to install the TIFF tag values, which
in turn are written to the file when the TIFF file descriptor
is closed. A GeoTIFF file cannot be opened for updating; only
pure read or write is supported.


1.2.1.4 GTIFDirectoryInfo
	void      GTIFDirectoryInfo(GTIF *gtif, int *versions, int *keycount);

Returns header information about the GeoTIFF file directory. The <versions>
is an array of 3 integers, giving the GeoTIFF Version, followed by
the major and minor revisions. The <keycount> argument returns the number
of keys currently defined in this file. 

-------------------
1.2.2 GeoKey Access 


1.2.2.1 GTIFKeyInfo
	int       GTIFKeyInfo(GTIF *gtif, geokey_t key, int *size, tagtype_t* type);

Returns the number of values defined for key <key> if currently defined in the file, and 
returns in <size> the size of individual key values, and the <type>. If the
key is not defined, 0 is returned. You may pass in NULL pointers to any parameters
you do not need (such as the type).


1.2.2.1 GTIFKeyGet
	int       GTIFKeyGet(GTIF *gtif, geokey_t key, void *val, int index, int count);

Accesses the key value(s). If there are multiple values (such as ASCII), they
may be accessed individually, starting at <index> and returning <count> values.
The total number of values accessed is returned. Note: unline TIFFGetField() 
memory is not allocated for multiple-value arrays such as ASCII. To get the
length of an array call GTIFKeyInfo first, which returns the size and count
of the data.  If the values are key-codes they should be declared of type
"geocode_t", which is unsigned SHORT.


1.2.2.1 GTIFKeySet
	int       GTIFKeySet(GTIF *gtif, geokey_t keyID, tagtype_t type, int count,...);

Defines and sets the specified key values. Note that this does not install the
tag-level information in the file; to do that you must call GTIFWriteKeys().
For single-valued non-ASCII keys (which are most of them), you must pass the
values in by value not reference. You must use the correct type for the
values: doubles for floating point, strings for ASCII, and "geocode_t" for
SHORT codes (the symbolic names may be used in most cases).


1.2.3 Metadata Import-Export utilities 

	void      GTIFPrint(GTIF *gtif, GTIFPrintMethod print, void *fd);
	int       GTIFImport(GTIF *gtif, GTIFReadMethod scan, void *fd);
	
	char*     GTIFKeyName(geokey_t key);
	char*     GTIFValueName(geokey_t key,int value);
	char*     GTIFTypeName(tagtype_t type);
	char*     GTIFTagName(int tag);
	int       GTIFKeyCode(char * key);
	int       GTIFValueCode(geokey_t key,char *value);
	int       GTIFTypeCode(char *type);
	int       GTIFTagCode(char *tag);

The GTIFPrint() routine dumps a GeoTIFF metadata stream out to
a specified file <fd>, either for human interpretation or for
input to another program. If <fd> is NULL the data is written
to the standard output.  

The GTIFImport() routine performs the inverse; given a metadata file
specified by <fd> (or stdin if <fd> is NULL) install the corresponding
tags and keys into the current GeoTIFF file. Note that the 
import routine only calls GTIFKeySet(), and so it is up to the
client program to call GTIFWriteKey() in order to explicitly
write the keys out to the file.

The GTIFxxxName() routines all take a numeric code, key or tag and
return a pointer to a static string name associated with the value.
In the case of Key-Values, the key must be explicitly defined in
order to establish the scope of the name-search. A string is always
returned; however, if the code is not recognized the string is
of the format "Unknown-%d", where %d is the input code value.

The GTIFxxxCode() routines perform the reverse operation; given
an ASCII string name it tries to find the corresponding code,
key or tag numerical value, in a case-sensitive manner. If the
string is not recognized the value -1 is return (no valid codes
are negative). For consistency, any strings of the form "Unknown-%d"
where %d is a decimal integer will return the specified integer. 

Note: be careful when assigning variables to GTIFxxxCode; for example,
the geokey_t type is unsigned, and so if -1 is returned, this will
result in a value of 65535. To be safe, always use signed integers
for the assignment, and pass them on to an unsigned type after
checking that the value is positive.


-------------------------------------------------------------
1.3 Examples


A typical use of LIBGEOTIFF for creating a GeoTIFF file is

	#include "xtiffio.h"  /* for TIFF */
	#include "geotiffio.h" /* for GeoTIFF */
	void main()
	{
		TIFF *tif=(TIFF*)0;  /* TIFF-level descriptor */
		GTIF *gtif=(GTIF*)0; /* GeoKey-level descriptor */
		
		/* Open TIFF descriptor to write GeoTIFF tags */
		tif=XTIFFOpen(fname,"w");  
		if (!tif) goto failure;
		
		/* Open GTIF Key parser */
		gtif = GTIFNew(tif);
		if (!gtif) goto failure;
		
		/* Set up standar TIFF file */
		TIFFSetField(tif,TIFFTAG_IMAGEWIDTH,    WIDTH);
		/* set other TIFF tags and write out image ... */
				
		/* Set GeoTIFF information */
		GTIFKeySet(gtif, GTModelTypeGeoKey, TYPE_SHORT, 1, ModelGeographic);
		/* set other GeoTIFF keys ... */
		
		/* Store the keys into the TIFF Tags */
		GTIFWriteKeys(gtif);
		
		/* get rid of the key parser */
		GTIFFree(gtif);
		
		/* save and close the TIFF file descriptor */
		XTIFFClose(tif);
		
		exit (0);
	failure:
		exit (-1);
	}

While a typical use of the code for reading tags is:

	#include "xtiffio.h"  /* for TIFF */
	#include "geotiffio.h" /* for GeoTIFF */
	enum {VERSION=0,MAJOR,MINOR};
	void main()
	{
		TIFF *tif=(TIFF*)0;  /* TIFF-level descriptor */
		GTIF *gtif=(GTIF*)0; /* GeoKey-level descriptor */
		int versions[3];
		int cit_length;
		geocode_t model;    /* all key-codes are of this type */
		char *citation;
		
		/* Open TIFF descriptor to read GeoTIFF tags */
		tif=XTIFFOpen(fname,"r");  
		if (!tif) goto failure;
		
		/* Open GTIF Key parser; keys will be read at this time. */
		gtif = GTIFNew(tif);
		if (!gtif) goto failure;

		/* Get the GeoTIFF directory info */
		GTIFDirectoryInfo(gtif,versions,0);
		if (versions[MAJOR] > 1)
		{
			printf("this file is too new for me\n"); goto failure;
		}
		if (!GTIFKeyGet(gtif, GTModelTypeGeoKey, &model, 0, 1))
		{
			printf("Yikes! no Model Type\n") goto failure;
		}
		
		/* ASCII keys are variable-length; compute size */
		cit_length = GTIFKeyInfo(gtif,GTCitationGeoKey,&size,&type);
		if (cit_length > 0)
		{
			citation = malloc(size*cit_length);
			if (!citation) goto failure;
			GTIFKeyGet(gtif, GTCitationGeoKey, citation, 0, cit_length);
			printf("Citation:%s\n",citation);
		}

		/* Get some TIFF info on this image */
		TIFFGetField(tif,TIFFTAG_IMAGEWIDTH,    &width);
		
		/* get rid of the key parser */
		GTIFFree(gtif);
		
		/* close the TIFF file descriptor */
		XTIFFClose(tif);
		
		exit (0);
	failure:
		exit (-1);
	}



-------------------------------------------------------------
2. The LibGeoTIFF Utilities

-------------------------------------------------------------
2.1 listgeo   - dump a GeoTIFF metadata file

Syntax:   listgeo [-tfw] [-no_norm] [-t tabledir] inputfile

The program listgeo takes a GeoTIFF file as input and dumps to
the standard output a GeoTIFF "metadata" file, which is human
readable, and may also be used as input to other programs which
use the "GTIFImport" routine, such as geotifcp, below.

The -tfw flag may be passed to force generation of an ESRI style .tfw
file as well as the metadata file.  

The -no_norm flag will supress reporting of normalized parameters, and
reporting of corner points. 

------------------------
GeoTIFF Metadata Format:

For the formalist junkies, we will define a GeoTIFF metadata format
in an unambiguous fashion, and follow that by a concrete example.

The metadata format is defined as follows (all strings not placed
between <braces> are string literals, case-sensitive, and any entry
followed by "*" or "*<number>" indicates multiple entries):

<Geotiff_Metadata> = <Geotiff_Header> + <GeoTIFF_Body> + <GeoTIFF_Trailer>

   <Geotiff_Header> = <White_Space> + Geotiff_Information: + <Return>
   <GeoTIFF_Trailer> = <White_Space> + End_Of_Geotiff. + <Return>
   <GeoTIFF_Body> = <GeoTIFF_Info> + <GeoTIFF_Tags> + <GeoTIFF_Keys>
      <GeoTIFF_Info> = <GeoTIFF_Version> + <GeoTIFF_Revision>
         <GeoTIFF_Version> = Version: + <Single_Space> + <Version> + <Return>
            <Version> = <Integer>
         <GeoTIFF_Revision> = Revision: + 
               <Single_Space> + <Major_Rev> + <Period> + <Minor_Rev> + <Return>
               <Major_Rev> = <Integer>
               <Minor_Rev> = <Integer>
      <GeoTIFF_Tags> =  <Tag_Header> + <Tag_Entry>* + <Tag_Trailer>
         <Tag_Header> = <White_Space> + Tagged_Information: + <Return>
         <Tag_Trailer> = <White_Space> + End_Of_Tags. + <Return>
         <Tag_Entry> = <Tag_Entry_Header> + <Tag_Entry_Row>*
            <Tag_Entry_Header> = <White_Space> + 
                     <Tag_Name> + <Tag_Dimension> + <Colon> + <Return>
               <Tag_Dimension>  = "(" + <NRows> + <Comma> + <NCols> + ")"
		 	      <NRows> = <Integer>
		 	      <NCols> = <Integer>
            <Tag_Entry_Row> = <White_Space> + <Double_Float>*<NCols> + <Return>
      <GeoTIFF_Keys> =  <Key_Header> + <Key_Entry>* + <Key_Trailer>
         <Key_Header> = <White_Space> + Keyed_Information: + <Return>
         <Key_Trailer> = <White_Space> + End_Of_Keys. + <Return>
         <Key_Entry> = <Key_Entry_Header> + <Key_Entry_Value>
            <Key_Entry_Header> = <White_Space> + 
                     <Key_Name> + <Key_Dimension> + <Colon> + <Return>
              <Key_Dimension> = "(" + <Key_Format> + <Comma> + <Key_Count> + ")"
            <Key_Entry_Value> = (<Key_Value> | <Numeric_Value> | <Ascii_Value>)
               <Numeric_Value> = (<Integer> | <Double_Float>)
               <Ascii_Value> = <Double_Quote> + <String> + <Double_Quote>

   <Tag_Name> = All symbolic tag names defined in GeoTIFF spec.
   <Key_Name> = All symbolic key names defined in GeoTIFF spec.
   <Key_Value> = All symbolic value names defined in GeoTIFF spec.
   <Key_Format> = (Short | Ascii | Double)
   
And for the pedantic:
   <White_Space> = (<Single_Space> | <Tab>)*
   <Double_Float> = <Mantissa><Exponent>
   <Mantissa> = <Sign><Integer><Period><Integer>
   <Exponent> = ( |e<Sign><Integer>)
   <Sign> = ( |+|-)
   <Integer> = (0|1|2|3|4|5|6|7|8|9)*
   ...


Example (default output of listgeo):

Geotiff_Information:
   Version: 1
   Key_Revision: 0.2
   Tagged_Information:
      ModelTiepointTag (2,3):
         0                  0                  0
       130                 32                  0
      ModelPixelScaleTag (1,3):
         1                  1                  0
      End_Of_Tags.
   Keyed_Information:
      GTModelTypeGeoKey (Short,1): ModelTypeGeographic
      GTRasterTypeGeoKey (Short,1): RasterPixelIsArea
      GTCitationGeoKey (Ascii,16): "Just An Example"
      GeographicTypeGeoKey (Short,1): User-Defined
      GeogCitationGeoKey (Ascii,24): "Everest Ellipsoid Used."
      GeogGeodeticDatumGeoKey (Short,1): User-Defined
      GeogLinearUnitsGeoKey (Short,1): Linear_Meter
      GeogAngularUnitsGeoKey (Short,1): Angular_Degree
      GeogEllipsoidGeoKey (Short,1): Ellipse_Everest_1830_1967_Definition
      GeogSemiMajorAxisGeoKey (Double,1): 6377298.556
      GeogInvFlatteningGeoKey (Double,1): 300.8017
      End_Of_Keys.
   End_Of_Geotiff.
   
   
-------------------------------------------------------------
2.2 geotifcp  - Copy a TIFF file and install GeoTIFF info from metadata.

Syntax:   geotifcp [options] [-e esri_worldfile] [-g metadata] input output

The program geotifcp is identical in function to the LIBTIFF program
"tiffcp", with the additional feature that if the "-g <metadata>"
option is used the GeoTIFF information from the file <metadata> 
will be installed into the output file.  The "-e worldfile" option will 
override the tiepoint and scale information from the metadata file based
on the contents of the ESRI worldfile. 

If the "-g" option is not used, the opposite effect occurs: all 
GeoTIFF information is filtered out of the input file before being
written to the new output file.

"geotifcp" inherits all the other file-transformation capabilities
of the tiffcp program; for help on the additional parameters give
the command:

  %  geotifcp -h

-------------------------------------------------------------