/mode/users/src/master/tiff/README,v 1.3 1994/06/29 17:23:04 fedor Exp
NOTE: The file CHANGES-v3.0 has a list of changes between
v2.4.2 and this software.
TIFF Software "Release" 3.00a
-----------------------------
Note: This library has been patched to allow the library to read/write
files to streams rather than file descriptors. In order to use this
capability, you need to define STREAM_SUPPORT in libtiff/Makefile.
For true streams libraries, like NeXT or GnuStep/objcX, also define
HAVE_STREAMS_STREAMS_H. At the current time GnuStep/objcX does not support
true streams, so don't define this.
If you do not define these macros, the library will work as normal.
Contact Adam Fedor (fedor@boulder.colorado.edu) for more information.
TIFF Software "Release" 3.00
----------------------------
This is Version 3.00 of my public domain TIFF support software.
Included is a library, libtiff, for reading and writing TIFF files.
The library, along with associated tool programs, should handle most of
your needs for reading and writing files that follow the 5.0 TIFF spec
for Classes B, G, P, and R. There is also considerable support for
proposed additions that are to appear in 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 (Appendix K to appear 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 (Appendix O to appear in 6.0)
SamplesPerPixel = 3
BitsPerSample = <8,8,8>
PlanarConfiguration = 1, 2
Compression = 1 (none), 5 (LZW), 32865 (JPEG)
PhotometricInterpretation = 6 (YCbCr)
YCbCrCoefficients, YCbCrSubsampling, YCbCrPositioning
(colorimetry info from Appendix H; see below)
o Class "JPEG" for JPEG images (Appendix P to appear 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 (Appendix L to appear in 6.0)
TileWidth
TileLength
TileOffsets
TileByteCounts
o Image Colorimetry Information (Appendix H to appear 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
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
DataType 32996 R
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. Note that the ExtraSamples tag is
only supported as needed to store Associated Alpha data. 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 planned additions for TIFF
6.0. Consult the appropriate TIFF appendices for the descriptions of
these tags.
LIBTIFF
-------
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 comprised of 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.
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
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
contrib/xv patches to XV version 2.00 to make it support TIFF
(XV is an X-based viewer from John Bradley)
Don't send me mail asking about these programs. Send questions
and/or bug reports directly to the authors.
DOCUMENTATION:
-------------
A copy of the 5.0 spec is included in the doc directory. This document
was obtained by Bill Johnston of LBL who retrieved it from simtel20.
Beware that the document has been modified slightly from the original
version to enhance printability. We've tried to be very careful in making
any changes, but there's always the possibility of mistakes being
introduced.
Another document describes a proposed addition to TIFF 6.0 for Associated
Alpha data (i.e. what is now the Matteing tag).
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. If the archive that you retrieve was v3.0.tar.Z,
then the images should be in the same directory in an archive named
v3.0pics.tar.Z.
BUILDING THE SOFTWARE
---------------------
The software, as distributed, is setup for building the software on an
SGI machine (release 4.0.1 if you care). 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.hpux Makefile for HP machines running HP-UX
Makefile.mips Makefile for a MIPS running MIPS OS 2.?
Makefile.next Makefile for a NeXT
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, you'll want to 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.
There is a mailing list associated with the software,
tiff@ucbvax.berkeley.edu, that you can join by sending a message to
tiff-request@ucbvax.berkeley.edu. You can also reach me directly at
sam@sgi.com.
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 will
state 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.
FILE CONTENTS
-------------
At least the following files are included in the distribution:
libtiff/prototypes.h stuff for ANSI function prototypes
libtiff/tiff.h TIFF spec definitions
libtiff/tiffio.h public TIFF library definitions
libtiff/tiffioP.h private TIFF library definitions
libtiff/tiffcompat.h UNIX-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_compat.c OS-related compatibility stuff
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/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
doc/5.0spec raw text version of TIFF 5.0 spec
doc/ClassF.txt raw text version of current Class F (fax) document
doc/alpha.ps PostScript version of proposed TIFF 6.0 appendix
doc/extra.ps PostScript version of proposed TIFF 6.0 tag
doc/TIFF6.ps PostScript version of 1st draft of TIFF 6.0 spec
man/man1 UNIX manual pages for tools
man/man3 UNIX manual pages for libtiff functions
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.