$Header: /usr/people/sam/tiff/RCS/README,v 1.19 93/08/09 17:01:16 sam Exp $

TIFF Software Release
---------------------

    Copyright (c) 1988, 1989, 1990, 1991, 1992 Sam Leffler
    Copyright (c) 1991, 1992 Silicon Graphics, Inc.

    Permission to use, copy, modify, distribute, and sell this software and 
    its documentation for any purpose is hereby granted without fee, provided
    that (i) the above copyright notices and this permission notice appear in
    all copies of the software and related documentation, and (ii) the names of
    Sam Leffler and Silicon Graphics may not be used in any advertising or
    publicity relating to the software without the specific, prior written
    permission of Sam Leffler and Silicon Graphics.

    THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
    EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
    WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  

    IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
    ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
    OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
    WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
    LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
    OF THIS SOFTWARE.



About This Software
-------------------
This is software provides support for the Tag Image Format (TIFF).
Included is a library, libtiff, for reading and writing TIFF, a
collection of tools for doing simple manipulations of TIFF images, and
documentation on the library and tools.  A random assortment of
TIFF-related software contributed by others is also included.

The library, along with associated tool programs, should handle most of
your needs for reading and writing files that follow the 5.0 or 6.0
TIFF spec.  There is also considerable support for some of the more
esoteric portions of the 6.0 TIFF spec.


How to tell which version you have
----------------------------------
The software version can be found by looking at the file named VERSION
that is located at the top of the source tree; the precise alpha number
is given in the file tiff.alpha.  If you have need to refer to this
specific software, you should identify it as:

    TIFF <version> <alpha>

where <version> is whatever you get from "cat VERSION" and <alpha> is
what you get from "cat tiff.alpha".


TIFF Support
------------
The library, should handle most of your needs for reading and writing
files that follow the 5.0 or 6.0 TIFF spec.  There is also considerable
support for some of the more esoteric portions of the 6.0 TIFF spec.

    o core requirements
	both "MM" and "II" byte orders are handled
	multiple subfiles can be read and written
	editing is NOT supported in that related subfiles (e.g.
	  a reduced resolution version of an image) are not automatically
	  updated
	
	Tags handled: NewSubfileType, ImageWidth, ImageLength, Rowsperstrip,
		      StripOffsets, StripByteCounts, XResolution, YResolution,
		      ResolutionUnit.
    o Class B for bilevel images
	SamplesPerPixel = 1
	BitsPerSample = 1
	Compression = 1 (none), 2 (CCITT 1D), or 32773 (PackBits)
	PhotometricInterpretation = 0 (Min-is-White), 1 (Min-is-Black)
    o Class G for grayscale images
	SamplesPerPixel = 1
	BitsPerSample = 4, 8
	Compression = 1 (none) 5 (LZW)
	PhotometricInterpretation = 0 (Min-is-White), 1 (Min-is-Black)
    o Class P for palette color images
	SamplesPerPixel = 1
	BitsPerSample = 1-8
	Compression = 1 (none) 5 (LZW)
	PhotometricInterpretation = 3 (Palette RGB)
	ColorMap
    o Class R for RGB full color images
	SamplesPerPixel = 3
	BitsPerSample = <8,8,8>
	PlanarConfiguration = 1, 2
	Compression = 1 (none) 5 (LZW)
	PhotometricInterpretation = 2 (RGB)
    o Class F for facsimile (proposed appendix to 5.0 spec)
	(Class B tags plus...)
	Compression = 3 (CCITT Group 3), 4 (CCITT Group 4)
	FillOrder = 1 (MSB), 2 (LSB)
	Group3Options = 1 (2d encoding), 4 (zero fill), 5 (2d+fill)
	ImageWidth = 1728, 2048, 2482
	NewSubFileType = 2
	ResolutionUnit = 2 (Inch), 3 (Centimeter)
	PageNumber, XResolution,  YResolution, Software,
	BadFaxLines, CleanFaxData, ConsecutiveBadFaxLines,
	DateTime, DocumentName, ImageDescription, Orientation
    o Class S for separated images (in 6.0)
	SamplesPerPixel = 4
	PlanarConfiguration = 1, 2
	Compression = 1 (none), 5 (LZW)
	PhotometricInterpretation = 5 (Separated)
	InkSet = 1 (CMYK)
	DotRange, InkNames, DotRange, TargetPrinter
    o Class Y for JPEG images (in 6.0)
	SamplesPerPixel = 3
	BitsPerSample = <8,8,8>
	PlanarConfiguration = 1, 2
	Compression = 1 (none),  5 (LZW), 6 (JPEG)
	PhotometricInterpretation = 6 (YCbCr)
	YCbCrCoefficients, YCbCrSubsampling, YCbCrPositioning
	(colorimetry info from Appendix H; see below)
    o Class "JPEG" for JPEG images (in 6.0)
	PhotometricInterpretation = 1 (grayscale), 2 (RGB), 5 (CMYK), 6 (YCbCr)
	(Class Y tags if YCbCr)
	(Class S tags if CMYK)
	Compression = 6 (JPEG)
	JPEGProc = 0 (baseline)
	JPEGQTables = ... (offsets to per-channel Q matrices)
	JPEGDCTables = .... (offsets to per-channel DC tables)
	JPEGACTables = .... (offsets to per-channel AC tables)
	JPEGRestartInterval
    o Tiled Images (in 6.0)
	TileWidth
	TileLength
	TileOffsets
	TileByteCounts
    o Image Colorimetry Information (in 6.0)
	WhitePoint
	PrimaryChromaticities
	TransferFunction
	ReferenceBlackWhite

In addition, the library supports some optional compression algorithms
that are, in some cases, of dubious value.
	Compression = 32766	NeXT 2-bit encoding
	Compression = 32809	ThunderScan 4-bit encoding

[JPEG compression should fit into this library simply by replacing
 the existing stub JPEG compression module.  That is, all YCbCr and
 JPEG-related tags are supported in this version of the library.]

The following tags are recognized and handled by the library (as
described in the table).  If no use is indicated, then the library
reads and writes the tag, but does not use it internally.

Tag Name		Value	R/W	Library's Use
-----------------------------------------------------
NewSubFileType		254	R/W	(called SubFileType)
SubFileType		255	R/W	(called OSubFileType)
ImageWidth		256	R/W	lots
ImageLength		257	R/W	lots
BitsPerSample		258	R/W	lots
Compression		259	R/W	choosing compression routines
PhotometricInterpretation 262	R/W	Group 3 and JPEG code
Thresholding		263	R/W	
CellWidth		264		parsed but ignored
CellLength		265		parsed but ignored
FillOrder		266	R/W	control bit order
DocumentName		269	R/W
ImageDescription 	270	R/W
Make			271	R/W
Model			272	R/W
StripOffsets		273	R/W	data i/o
Orientation		274	R/W
SamplesPerPixel		277	R/W	lots
RowsPerStrip		278	R/W	data i/o
StripByteCounts		279	R/W	data i/o
MinSampleValue		280	R/W
MaxSampleValue		281	R/W
XResolution		282	R/W
YResolution		283	R/W	used by Group 3 2d encoding
PlanarConfiguration	284	R/W	data i/o
PageName		285	R/W
XPosition		286	R/W
YPosition		286	R/W
FreeOffsets		288		parsed but ignored
FreeByteCounts		289		parsed but ignored
GrayResponseUnit	290		parsed but ignored
GrayResponseCurve	291		parsed but ignored
Group3Options		292	R/W	used by Group 3 code
Group4Options		293	R/W
ResolutionUnit		296	R/W
PageNumber		297	R/W
ColorResponseUnit	300		parsed but ignored
TransferFunction	301	R/W
Software		305	R/W
DateTime		306	R/W
Artist			315	R/W
HostComputer		316	R/W
Predictor		317	R/W	used by LZW code
WhitePoint		318	R/W
PrimaryChromacities	319	R/W
ColorMap		320	R/W
TileWidth		322	R/W	data i/o
TileLength		323	R/W	data i/o
TileOffsets		324	R/W	data i/o
TileByteCounts		324	R/W	data i/o
BadFaxLines		326	R/W
CleanFaxData		327	R/W
ConsecutiveBadFaxLines	328	R/W
InkSet			332	R/W
InkNames		333	R/W
DotRange		336	R/W
TargetPrinter		337	R/W
ExtraSamples		338	R/W	lots
SampleFormat		339	R/W
JPEGProc		512	R/W	JPEG code
JPEGQRestartInterval	515	R/W	JPEG code
JPEGQTables		519	R/W	JPEG code
JPEGDCTables		520	R/W	JPEG code
JPEGACTables		521	R/W	JPEG code
YCbCrCoefficients	529	R/W	used by TIFFReadRGBAImage
YCbCrSubsampling	530	R/W	tile/strip size calculations
YCbCrPositioning	531	R/W
ReferenceBlackWhite	532	R/W
Matteing		32995	R	(obsoleted by ExtraSamples)
DataType		32996	R	(obsoleted by SampleFormat)
ImageDepth		32997	R/W	tile/strip calculations
TileDepth		32998	R/W	tile/strip calculations

The Matteing and DataType tags have been obsoleted by the 6.0
ExtraSamples and SampleFormat tags.  Consult the documentation on the
ExtraSamples tag and Associated Alpha for elaboration.  Note however
that if you use Associated Alpha, you are expected to save data that is
pre-multipled by Alpha.  If this means nothing to you, check out Porter
& Duff's paper in the '84 SIGGRAPH proceedings: "Compositing Digital
Images".

The ImageDepth tag is a non-standard, but registered tag that specifies
the Z-dimension of volumetric data.  The combination of ImageWidth,
ImageLength, and ImageDepth, defines a 3D volume of pixels that are
further specified by BitsPerSample and SamplesPerPixel.  The TileDepth
tag (also non-standard, but registered) can be used to specified a
subvolume "tiling" of a volume of data.

The JPEG, Colorimetry, and CMYK tags are additions that appear in TIFF
6.0.  Consult the TIFF 6.0 specification included in the doc directory.


The TIFF Library
----------------
libtiff is the software library that you can use to read and write TIFF
files (most all the tools use it to do their work).  The library
provides two interfaces, one for strip-based images and one for
tile-based images.  The normal interface is through a simple
scanline-based interface that works with images organized as strips.
For example, to read the contents of a file, the following might be used:

	#include "tiffio.h"

	TIFF *tif;
	unsigned long imagelength;
	char *buf;
	long row;

	tif = TIFFOpen("myfile.tif", "r");
	TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imagelength);
	buf = malloc(TIFFScanlineSize(tif));
	for (row = 0; row < imagelength; row++)
		TIFFReadScanline(tif, buf, row);

(this example assumes samples are packed contiguously.)  Similarly, to
write a file, something like the following can be used:

	tif = TIFFOpen("myfile.tif", "w");
	TIFFSetField(tif, TIFFTAG_IMAGEWIDTH, imagewidth);
	TIFFSetField(tif, TIFFTAG_COMPRESSION, COMPRESSION_LZW);
	... <set other required tags>
	row = 0;
	while (...more scanlines to write...)
		TIFFWriteScanline(tif, buf, row);
	TIFFClose(tif);

(once again, we assume samples are packed contiguously.)

A 2D tile-based interface is also provided as an alternative to the
scanline-orientated interfaces.  With this interface, an image is
broken up into a set of rectangular areas called tiles.  All the tiles
in an image have the same size, and the tile width and length must each
be a multiple of 16 pixels.  Tiles are ordered left-to-right and
top-to-bottom in an image.  As for scanlines, samples can be packed
contiguously or separately.  When separated, all the tiles for a sample
are colocated in the file.  That is, all the tiles for sample 0 appear
before the tiles for sample 1, etc.

Tiles and strips may also be extended in a z dimension to form
volumes.  Data volumes are organized as "slices".  That is, all the
data for a slice is colocated.  Volumes whose data is organized in
tiles can also have a tile depth so that data can be organized in
cubes.

The interface for tiles is similar to scanlines.  To read a tiled image,
code of the following sort might be used:

	unsigned long imageWidth, imageLength;
	unsigned long tileWidth, tileLength;
	unsigned long x, y;
	char *buf;

	tif = TIFFOpen("myfile.tif", "r");
	TIFFGetField(tif, TIFFTAG_IMAGEWIDTH, &imageWidth);
	TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imageLength);
	TIFFGetField(tif, TIFFTAG_TILEWIDTH, &tileWidth);
	TIFFGetField(tif, TIFFTAG_TILELENGTH, &tileLength);
	buf = malloc(TIFFTileSize(tif));
	for (y = 0; y < imageLength; y += tileLength)
		for (x = 0; x < imageWidth; x += tileWidth)
			TIFFReadTile(tif, buf, x, y, 0);

(once again, we assume samples are packed contiguously.)

Note that unlike the stdio library, libtiff only supports reading OR
writing of a file.   There is also an append mode, but this has not
really been tested.


TIFF Tools
----------
There are two device-dependent programs:

o tiffgt is used to display the contents of a TIFF file on a
  framebuffer.  The version included in this release was written
  for the Silicon Graphics Graphics Library (GL), although it
  should be a simple matter to tailor it for other systems.
o tiffsv is used to save all or part of a framebuffer in a
  TIFF file.  Once again, the version of tiffsv included here
  was written for the GL, but should be tailorable to other devices.
  (Note, tiffsv uses the readdisplay routine that was introduced
  in IRIX 4.0.)

The remaining programs should be device-independent:

o tiffinfo formats information about one or more TIFF files
o tiffdump displays the verbatim contents of the TIFF directory in a
  file (it's very useful for debugging bogus files that you may get from
  someone that claims they support TIFF).
o tiffcp is used to copy, concatenate, and convert TIFF images (e.g.
  switching from Compression=5 to Compression=1).
o tiff2ps is a program that converts a TIFF image to PostScript.
o tiffcmp can be used to compare the contents of two TIFF files (it does
  not check all the directory information, but does check all the data).
o tiff2bw is a simple program to convert a color image to grayscale.
o ras2tiff is a quick hack that converts Sun rasterfile format images to
  TIFF -- it's less than complete.
o rgb2ycbcr converts an RGB, grayscale, or bilevel TIFF image to a
  YCbCr TIFF image.
o gif2tiff is a quick hack that converts GIF 87a format images to TIFF.
o ppm2tiff is a quick hack that converts PPM format images to TIFF.
o fax2tiff converts raw Group 3 facsimile data to TIFF.
o pal2rgb converts a Palette color image to a full color RGB image by
  applying the colormap.
o tiffdither dithers a b&w image into a bilevel image (suitable for
  use in creating fax files)
o tiffsplit creates one or more single-image files from a (possibly)
  multi-image file
o Finally, tiffmedian is a version of Paul Heckbert's median cut program
  that reads an RGB TIFF image, and creates a TIFF palette file as a
  result.  It's useful for converting full-color RGB images to 8-bit
  color for your friends that have cheapo 8-bit framebuffers.

There is also:

o sgi2tiff, a program to convert SGI image files to TIFF.  This
  program is only useful on SGI machines as it uses -limage.

Check out the manual pages for details about the above programs.


Contributed Stuff
-----------------
The directory contrib has contributed software:

contrib/dbs	an X-based TIFF viewer from Dan & Chris Sears (has not
		been updated in a long time and does not compile)
contrib/ras	two programs by Patrick Naughton for converting
		between Sun rasterfile format and TIFF (these
		require libpixrect.a, as opposed to the one in
		tools that doesn't)
contrib/fax2ps	a program that converts TIFF/F images to an encoded
		form of PostScript that is faster to print than just
		dumping a full raster
contrib/vms	scripts and files from Karsten Spang for building
		the library and tools under VMS

Don't send me mail asking about these programs.  Send questions
and/or bug reports directly to the authors.


Documentation
-------------
A copy of the 6.0 spec available by public ftp from sgi.com in the
directory graphics/tiff.  TIFF6.ps is the PostScript of the final 6.0
spec as provided by Aldus.  TIFF6.ps.Z is a compress(1)'d version of
TIFF6.ps.


Test Images
-----------
Test images are available for most formats supported by the library.
The images are kept in a separate archive that should be located along
with this software.  For example, if the archive that you retrieve was
v3.1.tar.Z, then the images should be in the same directory in an
archive named v3.1pics.tar.Z.


Building the Software
---------------------
To configure things for your machine, check for Makefiles in the
libtiff and tools directories for your machine:

    Makefile.aix	Makefile for an IBM RS/6000 running AIX
    Makefile.apollo	Makefile for an Apollo
    Makefile.gcc	Makefile for use with gcc (the GNU compiler)
    Makefile.hpux	Makefile for HP machines running HP-UX
    Makefile.mips	Makefile for a MIPS running MIPS OS 2.?
    Makefile.mpw	Makefile for an Apple Macintosh with MPW
    Makefile.next	Makefile for a NeXT
    Makefile.sco	Makefile for a PC running SCO ODT 2.0 (or similar)
    Makefile.sgi	Makefile for a VGX, GT, GTX, or Personal Iris
    Makefile.sun	Makefile for a Sun-3 or Sun-4 running SunOS 3.5+
    Makefile.tahoe	Makefile for a TAHOE running 4.3BSD
    Makefile.vax	Makefile for a VAX running 4.3BSD

If your machine is not represented, you'll have to make up a Makefile
that is right for you.  In libtiff the important things to setup are

    AR=/usr/bin/ar			whatever your library archiver is called
    RANLIB=/usr/bin/ranlib		if you need to ranlib a library
    IPATH=-I. -I/usr/include/bsd	list of directories to search includes
    CONF=....				configuring optional support

To build the library, just

	cd libtiff; make

In the tools directory, pick the appropriate Makefile as in the libtiff
directory.  If no Makefile is present for your machine, create one, setup
the MACHALL macro,

	MACHALL=ras2tiff tiffgt tiffsv

and add definitions for how to build tiffgt and tiffsv for your machine
(if appropriate).  Note also that for building the fax2tiff program, the
CONF_LIBRARY macro in the Makefile MUST agree with the definition in the
Makefile in the libtiff directory!  If this is not true, then fax2tiff
will not work.

To build the tools library, just

	cd ../tools; make


Checking out the Software
-------------------------
Assuming you have working versions of tiffgt and tiffsv, you can just
use them to view any of the sample images  (the list is given below).
Otherwise, you can check out the operation of the library with tiffcp
and tiffcmp. For example,

	tiffcp -lzw cramps.tif x.tif
	tiffcmp cramps.tif x.tif

(tiffcmp should be silent if the files compare correctly).


Bugs and such....
-----------------
This software is free.  The only thing that I ask in return is that you
tell me when you find a problem or fix a bug.  I also gladly accept
software contributions, although I hesitate to include such software in
my regular stuff if I am personally unable to test it.

A mailing list for users of this software is located on sgi.com.
If you want to join this mailing list or have a list-related request
such as getting your name removed from it, send a request to

    majordomo@whizzer.wpd.sgi.com

For example, to subscribe, send the line "subscribe tiff" in
the body of your message.  The line "help" will return a list of
the commands understood by the mailing list management software.

Submissions (including bug reports) should be directed to:

    tiff@sgi.com

When corresponding about this software please always specify what
version you have, what system you are running on.

If all else fails, I can be reached by sending mail to sam@sgi.com
(but beware that I'm more likely to respond to mail sent to the
mailing list than mail sent directly to me).


Acknowledgements
----------------
The LZW algorithm is derived from the compress program (the proper
attribution is included in the source code).  The Group 3 fax stuff
originated as code from Jef Poskanzer, but has since been rewritten
several times.  The latest version uses an algorithm from Michael
Marking -- consult libtiff/mkg3states.c for further information.
Many other people have, by now, helped with bug fixes and code.


Warning
-------
It appears that Unisys is actively pursuing copyright control on the
LZW compression algorithm.  In particular, users of the LZW compression
within the TIFF framework.  For this reason the TIFF 6.0 spec states
that LZW compression is not recommended.  It is unclear at this time
what compression algorithm will be used in place of it.  I have no idea
what this means to you or to this library.  I make no warranty or
guarantees with regard to the LZW support in this library.


Use and Copyright
-----------------
Silicon Graphics has seen fit to allow me to give this work away.  It
is free.  There is no support or guarantee of any sort as to its
operations, correctness, or whatever.  If you do anything useful with
all or parts of it you need to honor the copyright notices.   I would
also be interested in knowing about it and, hopefully, be acknowledged.

	Sam Leffler	(sam@sgi.com)



Table of Contents
-----------------
At least the following files are included in the distribution:

libtiff/tiff.h			TIFF spec definitions
libtiff/tiffio.h		public TIFF library definitions
libtiff/tiffiop.h		private TIFF library definitions
libtiff/tiffcomp.h		OS-compatibility definitions
libtiff/t4.h			CCITT Group 3 1d code tables+definitions
libtiff/tif_fax3.h		CCITT Group 3-related definitions

libtiff/tif_aux.c		auxilary directory-related functions
libtiff/tif_ccittrle.c		CCITT 1d Huffman compression
libtiff/tif_compress.c		list of supported compression algorithms
libtiff/tif_dir.c		directory tag interface code
libtiff/tif_dirinfo.c		directory known tag support code
libtiff/tif_dirread.c		directory reading code
libtiff/tif_dirwrite.c		directory writing code
libtiff/tif_dumpmode.c		"no" compression algorithm
libtiff/tif_fax3.c		CCITT Group 3 fax compression
libtiff/tif_fax4.c		CCITT Group 4 fax compression
libtiff/tif_getimage.c		code to read an entire image into an RGBA raster
libtiff/tif_jpeg.c		JPEG compression placeholder
libtiff/tif_lzw.c		LZW encoding and decoding
libtiff/tif_next.c		NeXT 2-bit decoding algorithm (no encoding)
libtiff/tif_machdep.c		machine/architecture-specific code
libtiff/tif_open.c		open and simply query code
libtiff/tif_packbits.c		Packbits encoding and decoding
libtiff/tif_print.c		directory printing support
libtiff/tif_swab.c		byte and bit swapping support
libtiff/tif_strip.c		some strip-related code
libtiff/tif_thunder.c		Thunderscan decoding (no encoding)
libtiff/tif_tile.c		some tile-related code
libtiff/tif_unix.c		UNIX-related OS support
libtiff/tif_apple.c		Apple-related OS support
libtiff/tif_msdos.c		MSDOS-related OS support
libtiff/tif_vms.c		VMS-related OS support
libtiff/mkg3states.c		program to generate G3 decoding state tables
libtiff/mkspans.c		program to generate black-white span tables

tools/getopt.c		public domain getopt from Berkeley used by tools
tools/fax2tiff.c	convert raw facsimile data to TIFF
tools/gif2tiff.c	convert GIF87 file to TIFF
tools/pal2rgb.c		convert TIFF Palette image to TIFF RGB
tools/ppm2tiff.c	convert PPM image file to TIFF
tools/ras2tiff.c	convert Sun rasterfile format to TIFF (limited)
tools/rgb2ybcr.c	convert TIFF to YCbCr TIFF
tools/sgi2tiff.c	convert SGI image file to TIFF
tools/sgigt.c		TIFF picture get for SGI framebuffer (uses GL)
tools/sgisv.c		save image on SGI framebuffer in TIFF file
tools/tiff2bw.c		convert color TIFF file to B&W
tools/tiff2ps.c		convert TIFF to PostScript
tools/tiffcmp.c		compare two TIFF files
tools/tiffcp.c		copy/convert TIFF files (used to change compression)
tools/tiffdither.c	dither grayscale to bilevel
tools/tiffdump.c	dump TIFF header and directory tags w/o library
tools/tiffinfo.c	print info about TIFF file(s)
tools/tiffmedian.c	median cut RGB -> palette conversion program
tools/tiffsplit.c	split a multi-page TIFF into single-page TIFFs
tools/ycbcr.c		RGB->YCbCr->RGB test program

man/man1		UNIX manual pages for tools
man/man3		UNIX manual pages for libtiff functions