src/tiff/contrib/addtiffo/README

   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