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