src/tiff/contrib/addtiffo/README

	addtiffo 1.0
	============

The addtiffo utility is used to add overview pyramids to an existing
TIFF or GeoTIFF file.  Some applications can take advantage of these
overviews to accelerate overview display performance of large rasters.

This release of addtiffo is primarily intended for compatibility testing
with applications, and to see if there is interest in a cleaner release
of the capability ... perhaps incorporation into the libtiff tools
distribution.

Please feel free to contact me with questions, or problems.

warmerda@home.com
http://home.gdal.org/~warmerda/


Usage
-----

Usage: addtiffo [-r {average/nearest} [-subifd]
                tiff_filename [resolution_reductions]

Example:
 % addtiffo abc.tif 2 4 8 16

The numeric arguments are the list of reduction factors to
generate.  In this example a 1/2, 1/4 1/8 and 1/16


Limitations
-----------

See tif_overview.cpp for up to date details.

  o Currently only images with bits_per_sample of a multiple of eight
    will work.

  o The code will attempt to use the same kind of compression,
    photometric interpretation, and organization as the source image, but
    it doesn't copy geotiff tags to the reduced resolution images.

  o Reduced resolution overviews for multi-sample files will currently
    always be generated as PLANARCONFIG_SEPARATE.  This could be fixed
    reasonable easily if needed to improve compatibility with other
    packages.  Many don't properly support PLANARCONFIG_SEPARATE.

  o Overviews are always written as appended IFDs, rather than using the
    ``tree of tree's'' approach using the SUBIFD tag.  I wanted to implement
    both, but it isn't currently easy to add a SUBIFD tag to an existing
    main tiff IFD with libtiff.  I hope to try this again later.


TIFF File Tags
--------------

The results of running addtiffo on a 1024x1024 tiled greyscale file
with the arguments ``2 4 8 16'' is to add four additional TIFF directories
appended on the file with the SUBFILETYPE flag to 0x1 indicating the extra
items are reduced resolution images.

The tiffinfo output of such a file might look like this:

TIFF Directory at offset 0x118008
  Image Width: 1024 Image Length: 1024
  Tile Width: 256 Tile Length: 112
  Bits/Sample: 8
  Compression Scheme: none
  Photometric Interpretation: min-is-black
  Samples/Pixel: 1
  Planar Configuration: single image plane
TIFF Directory at offset 0x15e1d2
  Subfile Type: reduced-resolution image (1 = 0x1)
  Image Width: 512 Image Length: 512
  Tile Width: 256 Tile Length: 112
  Bits/Sample: 8
  Compression Scheme: none
  Photometric Interpretation: min-is-black
  Samples/Pixel: 1
  Planar Configuration: separate image planes
TIFF Directory at offset 0x1732b8
  Subfile Type: reduced-resolution image (1 = 0x1)
  Image Width: 256 Image Length: 256
  Tile Width: 256 Tile Length: 112
  Bits/Sample: 8
  Compression Scheme: none
  Photometric Interpretation: min-is-black
  Samples/Pixel: 1
  Planar Configuration: separate image planes
TIFF Directory at offset 0x17a366
  Subfile Type: reduced-resolution image (1 = 0x1)
  Image Width: 128 Image Length: 128
  Tile Width: 128 Tile Length: 112
  Bits/Sample: 8
  Compression Scheme: none
  Photometric Interpretation: min-is-black
  Samples/Pixel: 1
  Planar Configuration: separate image planes
TIFF Directory at offset 0x17b40c
  Subfile Type: reduced-resolution image (1 = 0x1)
  Image Width: 64 Image Length: 64
  Tile Width: 64 Tile Length: 64
  Bits/Sample: 8
  Compression Scheme: none
  Photometric Interpretation: min-is-black
  Samples/Pixel: 1
  Planar Configuration: separate image planes


Building
--------

You will need a C compiler.  You will need to have libtiff already
built and installed.  The provided Makefile should work on most Unix systems.
A similar file will be needed for Windows, but is not provided.

The CFLAGS and LIBS macros in the Makefile will have to be updated to
point to the correct location of the libtiff include files, and library.


Credits
-------

 o Intergraph Corporation for partially funding the work.

 o Global Geomatics for partially funding reorganization of the overview
   building ability as a separate utility.

 o Orrin Long, and Ed Grissom of Intergraph for explaining what needed to
   be done.

 o Max Martinez of Erdas for his discussion of external overviews.

 o Atlantis Scientific who supported adding averaging, and some other
   generalizations.

 o Frank Warmerdam for writing the bulk of the code.

 o Sam Leffler since this only exists because of his libtiff.
Commit	Line	Data
	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