| 1 | addtiffo 1.0 |
| 2 | ============ |
| 3 | |
| 4 | The addtiffo utility is used to add overview pyramids to an existing |
| 5 | TIFF or GeoTIFF file. Some applications can take advantage of these |
| 6 | overviews to accelerate overview display performance of large rasters. |
| 7 | |
| 8 | This release of addtiffo is primarily intended for compatibility testing |
| 9 | with applications, and to see if there is interest in a cleaner release |
| 10 | of the capability ... perhaps incorporation into the libtiff tools |
| 11 | distribution. |
| 12 | |
| 13 | Please feel free to contact me with questions, or problems. |
| 14 | |
| 15 | warmerda@home.com |
| 16 | http://home.gdal.org/~warmerda/ |
| 17 | |
| 18 | |
| 19 | Usage |
| 20 | ----- |
| 21 | |
| 22 | Usage: addtiffo [-r {average/nearest} [-subifd] |
| 23 | tiff_filename [resolution_reductions] |
| 24 | |
| 25 | Example: |
| 26 | % addtiffo abc.tif 2 4 8 16 |
| 27 | |
| 28 | The numeric arguments are the list of reduction factors to |
| 29 | generate. In this example a 1/2, 1/4 1/8 and 1/16 |
| 30 | |
| 31 | |
| 32 | |
| 33 | Limitations |
| 34 | ----------- |
| 35 | |
| 36 | See 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 | |
| 56 | TIFF File Tags |
| 57 | -------------- |
| 58 | |
| 59 | The results of running addtiffo on a 1024x1024 tiled greyscale file |
| 60 | with the arguments ``2 4 8 16'' is to add four additional TIFF directories |
| 61 | appended on the file with the SUBFILETYPE flag to 0x1 indicating the extra |
| 62 | items are reduced resolution images. |
| 63 | |
| 64 | The tiffinfo output of such a file might look like this: |
| 65 | |
| 66 | TIFF 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 |
| 74 | TIFF 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 |
| 83 | TIFF 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 |
| 92 | TIFF 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 |
| 101 | TIFF 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 | |
| 112 | Building |
| 113 | -------- |
| 114 | |
| 115 | You will need a C compiler. You will need to have libtiff already |
| 116 | built and installed. The provided Makefile should work on most Unix systems. |
| 117 | A similar file will be needed for Windows, but is not provided. |
| 118 | |
| 119 | The CFLAGS and LIBS macros in the Makefile will have to be updated to |
| 120 | point to the correct location of the libtiff include files, and library. |
| 121 | |
| 122 | |
| 123 | Credits |
| 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 | |