$Header: /usr/people/sam/tiff/RCS/README,v 1.15 92/03/31 11:31:13 sam Exp $ NOTE: The file CHANGES-v3.0 has a list of changes between v2.4.2 and this software. 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); ... 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