README
1 addtiffo 1.0
2 ============
3
4The addtiffo utility is used to add overview pyramids to an existing
5TIFF or GeoTIFF file. Some applications can take advantage of these
6overviews to accelerate overview display performance of large rasters.
7
8This release of addtiffo is primarily intended for compatibility testing
9with applications, and to see if there is interest in a cleaner release
10of the capability ... perhaps incorporation into the libtiff tools
11distribution.
12
13Please feel free to contact me with questions, or problems.
14
15warmerda@home.com
16http://home.gdal.org/~warmerda/
17
18
19Usage
20-----
21
22Usage: addtiffo [-r {average/nearest} [-subifd]
23 tiff_filename [resolution_reductions]
24
25Example:
26 % addtiffo abc.tif 2 4 8 16
27
28The numeric arguments are the list of reduction factors to
29generate. In this example a 1/2, 1/4 1/8 and 1/16
30
31
32
33Limitations
34-----------
35
36See tif_overview.cpp for up to date details.
37
38 o Currently only images with bits_per_sample of a multiple of eight
39 will work.
40
41 o The code will attempt to use the same kind of compression,
42 photometric interpretation, and organization as the source image, but
43 it doesn't copy geotiff tags to the reduced resolution images.
44
45 o Reduced resolution overviews for multi-sample files will currently
46 always be generated as PLANARCONFIG_SEPARATE. This could be fixed
47 reasonable easily if needed to improve compatibility with other
48 packages. Many don't properly support PLANARCONFIG_SEPARATE.
49
50 o Overviews are always written as appended IFDs, rather than using the
51 ``tree of tree's'' approach using the SUBIFD tag. I wanted to implement
52 both, but it isn't currently easy to add a SUBIFD tag to an existing
53 main tiff IFD with libtiff. I hope to try this again later.
54
55
56TIFF File Tags
57--------------
58
59The results of running addtiffo on a 1024x1024 tiled greyscale file
60with the arguments ``2 4 8 16'' is to add four additional TIFF directories
61appended on the file with the SUBFILETYPE flag to 0x1 indicating the extra
62items are reduced resolution images.
63
64The tiffinfo output of such a file might look like this:
65
66TIFF Directory at offset 0x118008
67 Image Width: 1024 Image Length: 1024
68 Tile Width: 256 Tile Length: 112
69 Bits/Sample: 8
70 Compression Scheme: none
71 Photometric Interpretation: min-is-black
72 Samples/Pixel: 1
73 Planar Configuration: single image plane
74TIFF Directory at offset 0x15e1d2
75 Subfile Type: reduced-resolution image (1 = 0x1)
76 Image Width: 512 Image Length: 512
77 Tile Width: 256 Tile Length: 112
78 Bits/Sample: 8
79 Compression Scheme: none
80 Photometric Interpretation: min-is-black
81 Samples/Pixel: 1
82 Planar Configuration: separate image planes
83TIFF Directory at offset 0x1732b8
84 Subfile Type: reduced-resolution image (1 = 0x1)
85 Image Width: 256 Image Length: 256
86 Tile Width: 256 Tile Length: 112
87 Bits/Sample: 8
88 Compression Scheme: none
89 Photometric Interpretation: min-is-black
90 Samples/Pixel: 1
91 Planar Configuration: separate image planes
92TIFF Directory at offset 0x17a366
93 Subfile Type: reduced-resolution image (1 = 0x1)
94 Image Width: 128 Image Length: 128
95 Tile Width: 128 Tile Length: 112
96 Bits/Sample: 8
97 Compression Scheme: none
98 Photometric Interpretation: min-is-black
99 Samples/Pixel: 1
100 Planar Configuration: separate image planes
101TIFF Directory at offset 0x17b40c
102 Subfile Type: reduced-resolution image (1 = 0x1)
103 Image Width: 64 Image Length: 64
104 Tile Width: 64 Tile Length: 64
105 Bits/Sample: 8
106 Compression Scheme: none
107 Photometric Interpretation: min-is-black
108 Samples/Pixel: 1
109 Planar Configuration: separate image planes
110
111
112Building
113--------
114
115You will need a C compiler. You will need to have libtiff already
116built and installed. The provided Makefile should work on most Unix systems.
117A similar file will be needed for Windows, but is not provided.
118
119The CFLAGS and LIBS macros in the Makefile will have to be updated to
120point to the correct location of the libtiff include files, and library.
121
122
123Credits
124-------
125
126 o Intergraph Corporation for partially funding the work.
127
128 o Global Geomatics for partially funding reorganization of the overview
129 building ability as a separate utility.
130
131 o Orrin Long, and Ed Grissom of Intergraph for explaining what needed to
132 be done.
133
134 o Max Martinez of Erdas for his discussion of external overviews.
135
136 o Atlantis Scientific who supported adding averaging, and some other
137 generalizations.
138
139 o Frank Warmerdam for writing the bulk of the code.
140
141 o Sam Leffler since this only exists because of his libtiff.
142
143