🚀 go-pugleaf

In response to the SDSC Image Tools release posting, Jeff Hanson wrote:

	>>While I agree completely about the usefulness of source and would love
	>>to have for these tools in particular, do not pass up the opportunity
	>>to have the best single program conversion tool, imconv.

To which Steve Lamont replied:

	>Don't forget pbmplus *is* available in source code and does 99 percent
	>of what imconv does (and often does it faster!).  It's available with
	>the X11 distribution in the contrib directory or from your favorite
	>FTP site (wuarchive.uwstl.edu comes to mind).


As the authors of the SDSC Image Tools, we feel we must respond to this
posting to help clear up any misconceptions.  The SDSC Image Tools differ
in significant ways from the PBMPlus package.  The following rather long
message details some of these ways.


		Differences between the SDSC Image Tools and PBMPlus
		----------------------------------------------------


1.  The SDSC Image Tools were designed as a C function library rather than
    a set of independent tools, such as the PBMPlus package.  Using a function
    library, image manipulation algorithms are encapsulated into generic
    functions maintained in a central location.  Tool programmers are able to
    quickly write new tools by simply calling library routines.  Tool source
    is kept small and succinct.  If bugs are found in the underlying
    library's image algorithm, the bug is fixed in one place and all tools
    using that routine are relinked.  No tool source modification is required.

    In a non-library-oriented package, such as PBMPlus, new tools are written
    by copying image manipulation code from prior tools.  If the original code
    has a bug in it, so does the new tool.  Fixing such a bug requires searching
    through all tools looking for copies of the original algorithm, updating
    that source, recompiling and relinking.  The hassles of such an approach
    are the prime reasons we have function libraries of any kind, such as the
    standard C library, the math library, and so on.  One algorithm.  One copy
    of the code.  One place to go to fix bugs.

    This library approach allows programmers to create new high-functionality
    tools quickly, without a great deal of coding.  For instance, the
    SDSC Image Tool "imfill" fills an image or portion of an image with a
    solid color or a horizontal or vertical gradation.  "imfill" calls
    "ImVfbFill( )" to do the actual filling.  The same image filling
    algorithm, with all its gradation and multi-field filling intelligence,
    can be used again in other tools.  "imrotate", for instance, rotates an
    image and stores the result into a new file.  It uses "ImVfbFill( )" to
    fill in the rotated image's empty corners with a color or gradation
    selected by command-line arguments.  "imshear" also uses "ImVfbFill( )" to
    fill in the sheared image's empty corners.  And so on.  There is no
    duplication of fill code.  To accomplish this same task using PBMPlus,
    the programmer would have to clone code multiple times, cloning bugs as
    well.

2.  All SDSC Image Tools can read and write all of our supported image
    file formats.  This is another direct result of encapsulating file format
    handling within generic library functions.

    For instance, to read a Sun rasterfile, program this (with additional error
    checking, of course):

		FILE     *fp;
		TagTable *table;

		fp    = fopen( filename, "r" );
		table = TagTableAlloc( );
		ImFileFRead( fp, "ras", NULL, table );

    To read an SGI RGB file instead, change "ras" to "rgb" in the call to
    "ImFileFRead( )".  Or maybe you don't know what kind of file it is, so
    let the SDSC Image Tools figure it out for you by replacing "ras" with
    a call to "ImFileQFormat( )" (query file format):

		FILE     *fp;
		TagTable *table;

		fp    = fopen( filename, "r" );
		table = TagTableAlloc( );
		ImFileFRead( fp, ImFileQFormat( fp, filename ), NULL, table );

    With PBMPlus, however, "pbm" tools only read PBM bitmaps, "pgm" tools only
    read PGM grayscale images, and "ppm" tools only read PPM RGB images.
    Fortunately, a combined set of "pnm" tools have been added that can
    read PBM, PGM, or PPM files.  This would be more cool, however, if there
    were actually "pnm" tools for all functionality available in the older
    "pbm", "pgm", and "ppm" tools.  However, some functionality only exists
    in "ppm" but not in "pnm", and so on.

    Furthermore, PBMPlus tools that actually do something to images only work
    on PBMPlus file formats.  If you want to read any other kind of image, you
    first have to convert into one of the PBMPlus formats.  Then if you want
    a result in another format, such as for transfer to a Mac or PC, or use
    as a texture map in a ray tracer, you have to convert back out of the
    PBMPlus formats into what you really wanted in the first place.

    All SDSC Image Tools read and write all supported image file formats.
    "imrotate" reads and writes all formats.  "imshear" reads and writes all
    formats.  "imfill" reads and writes all formats.  And so on.  The user is
    never required to convert into and out of an unwanted intermediate file
    format.  Work is always done in the domain the user wants to work in, not
    in one the tools force them to work in.

3.  Another natural result of developing the SDSC Image Tools as a C function
    library is the ease with which image file handling can be added to existing
    tools.  Non-SDSC users have built AVS and Explorer modules using the
    SDSC Image Tools library, added image handling support to existing tools,
    written windowing system user interfaces for the tools, and so on.

    At SDSC, we have implemented a generic lpr-based print filter system that
    drives a number of computer graphics output devices from any of the
    supported image file formats.  For instance, users of the system can queue
    images to be printed to slides on a film recorder using:

		vpr -Pslides title.rgb frames*.pix credits{1,2,3,4}.ras

    There are no hardcopy device-specific file formats.  There is no need to
    convert your SGI RGB image to quirky device protocol streams, then
    transfer the file over to the specific host that drives the printer, then
    invoke printer-specific software to print your image.  Instead, vpr handles
    it all.  Images are transferred via lpr to the remote host that drives
    the printer.  The lpr daemon invokes a device-specific print filter that
    reads in the images, using the Image Tools library, adjusts image colors
    appropriately for the device, again using the Image Tools library, and
    scales the image up or down to the device resolution, once again using
    the Image Tools library.  The final image is written directly to the
    device, with communications protocol handled on the spot.

    This kind of integration of image file format I/O into existing tools is not
    possible using the PBMPlus package.  File format code is distributed all
    about into multiple PBMPlus tools.  There is no file format function
    library.

4.  The SDSC Image Tools were designed to support a wide range of image
    storage types:  monochrome, grayscale, color indexed (also called
    pseudocolor), and RGB (also called truecolor), and images of all these
    types that have alpha channels, Z-buffers, and other non-visual pixel
    channels.

    The PBMPlus tools, however, only support monochrome, grayscale, and RGB
    images.  Alpha channels are unsupported and silently stripped from input
    files as you convert into the less-functional PBMPlus file formats.  There
    is no support whatsoever for color indexed images, such as those used by
    non-RGB color graphics displays and most color image file formats.  To
    handle a color indexed image, PBMPlus converts it to RGB.  The color table
    is applied to the color indexes and then tossed.  The "indexed-ness" of
    the original image is lost.  This is unacceptable.

    Consider a scientific data set that has been rendered by mapping different
    data values to different color indexes with no two data values sharing the
    same color table index.  Data values between 1 and 10, for instance,
    map to color indexes 1 to 10.  The color table is then loaded to
    illustrate a data classification scheme.  Color table entries 1-5 are
    mapped to red, while 6-10 are mapped to blue, and so on.  By simply
    changing the color table the scientist can highlight different data items
    to detect patterns and anomalies.

    But if you map this color indexed image and its data classification color
    table to RGB, all color indexes that are red become permanently mapped to
    red in the RGB image.  They can never be reclassified.  Data exploration
    is impossible.  The color "indexed-ness" of the source image has been
    lost and the scientific usefulness of the image has been reduced.
    If you use PBMPlus, you have no choice because PBMPlus does not support
    color indexed images.  The SDSC Image Tools do.

5.  Along a similar vein, the SDSC Image Tools retain as much as possible of
    the original source image's data during file format conversion.  This
    includes non-pixel data like image window names in XWD files, hotspots
    in Mirosoft Windows cursor files, and XOR masks in Microsoft Windows icon
    files.  For instance, the following operation has no loss of data:

	imconv input.xwd output.xwd

    Everything in the input XWD file will be transferred to the output XWD
    file, window name and all.

    Using PBMPlus, however, the intermediate PBMPlus file formats cannot store
    image window names, gamma correction factors, cursor hotspots, or icon XOR
    masks.  All of this data is silently thrown out during file format
    conversion process.  The following operation using PBMPlus loses the
    XWD image window name:

	xwdtopnm input.xwd | pnmtoxwd > output.xwd

    This loss of data is an artifact of PBMPlus using an intermediate file
    format incapable of holding non-pixel data.  This is, in fact, a tough
    problem.  How do you design an intermediate format that can hold anything,
    so that you don't get any loss of data in format conversion?  HDF is one
    approach to this problem.  It defines tags and values for many of the
    most common image-related attributes, then allows the user to define
    further tags for unanticipated image attributes.  Conversion into and out
    of HDF has a minimum loss of data.

    The SDSC Image Tools use a different approach.  Instead of defining an
    intermediate file format, they define an imtermediate memory-only set of
    data structures, called "Tag Tables", "Virtual Frame Buffers", and
    "Color Lookup Tables."  Because they are memory data structures, and not
    file formats, they are considerably more flexible.  They can store
    anything that might be found in an input file.

    Format readers parse the input file and drop tags and values into the
    tag table.  Format writers scan the tag table for items relevant for the
    output format and write them out.  The XWD reader, for instance, reads
    in the image window name and drops it into the tag table along with the
    image pixels and color table.  The Sun rasterfile RAS writer scans the
    tag table for images and color tables and writes them out, but it ignores
    the image window name because the RAS format does not support image names.
    The XWD writer, on the other hand, does pick out the image name from the
    tag table and write it out to the output format.  It all depends upon the
    abilities and limitations of the output file format.  The SDSC Image Tools
    do not arbitrarily limit image data to those things that fit into an
    intermediate file format.

6.  The SDSC Image Tools and PBMPlus both support a wide range of image file
    formats.  The following is a list of those formats.  The first column is
    the source or vendor sponsoring the file format and the second column is
    the most common name for the format.  Columns three and four indicate
    whether the format has read (R), write (W), or both (RW) support in the
    PBMPlus or SDSC Image Tools packages.  A blank in these columns means the
    format is not supported in that package.  Formats have been roughly
    grouped by the type of image data they can store.

						  Read / Write
						    support
	Source				Format	PBM+	IM Tools
	------				------	----	--------

	-- Monochrome-only formats
	Ascii				ascii	 W			
	Atari GEM			gem	RW			
	Bennet Yee "face"		ybm	RW			
	BitGraph			bg	 W			
	CMU Window Manager		cmuwm	RW			
	EPSON printer			epson	 W			
	Gemini 10X printer		10x	 W			
	GraphOn				go	 W			
	Group 3 FAX			g3	RW			
	LaserJet			lj	 W			
	MGR ?				mgr	RW			
	Macintosh Macpaint		macp	RW	RW		
	Microsoft Windows		bmp		RW		
	Mirosoft Windows		cur		RW		
	PBMPlus				pbm	RW	RW		
	PC doodle brush			brush	R			
	Printronix			ptx	 W			
	Sun SunView			icon	RW	RW		
	UNIX				plot	 W			
	X Window System			x10bm	 W			
	X Window System			xbm	RW	RW		
	ZINC ?				zinc	 W			


	-- Grayscale-only formats
	Astronomy guys			fits	RW			
	FaceSaver			fs	RW			
	NYU				hips	R			
	Symbolics 			lispm	RW			
	PBMPlus				pgm	RW	RW		


	-- Color-index only formats
	Microsoft Windows		ico		RW		
	X Window System			puzz	 W			
	Motif				uil	 W			


	-- RGB-only formats
	Gould Scanner			gould	R			
	NCSA				icr	 W			
	Sun TAAC			iff		RW		
	??				img	R			
	MTV				mtv	R			
	Atari Degas			pi1	RW			
	Atari Degas			pi3	RW			
	PIXAR				pic		RW		
	Alias				pix		RW		
	PBMPlus				ppm	RW	RW		
	QRT Ray Tracer			qrt	R			
	raw				raw	R			
	SGI				rgb		RW		
	Wavefront			rla		RW		
	Utah Raster Toolkit		rle		RW		
	Atari Spectrum			spct	R			
	Atari Spectrum			spu	R			
	SDSC				synu		RW		
	AVS				x		RW		
	XIM				xim	R			
	X Window System			xpm	RW			


	-- Mixed formats
	Adobe				eps	RW	 W		
	Compuserve Standard		gif	RW	RW		
	NCSA Standard			hdf		RW		
	Amiga				ilbm	RW			
	PC				pcx	RW	RW		
	Macintosh Standard		pict	R	RW		
	Adobe				ps		 W		
	Sun				rast	RW	RW		
	Targa				tga	R	RW		
	Aldus Standard			tiff	RW	RW		
	Khoros				viff		RW		
	X Window System			xwd	RW	RW		

	( Please, no flames about the correctness of the above list.  Some
	  of these formats are pretty obscure, and have absolutely no
	  explanations given in either the PBMPlus code or its man pages. )

    PBMPlus support is strongest for monochrome and grayscale file formats
    used on PCs, Ataris, Macs, and other low-end systems.  PBMPlus also
    focuses on smaller software packages (like QRT and MTV), games and
    cute programs (like PUZZ, and FS), and printer device protocol files
    (like PTX and EPSON).

    The SDSC Image Tools instead concentrate on high-end systems and high-end
    color formats, such as Alias PIX, Wavefront RLA, Khoros VIFF, NCSA HDF,
    Sun TAAC IFF, PIXAR PIC, AVS X, and SGI RGB.  These file formats dominate
    the high-end workstation graphics world and are those we found ourselves
    most in need of during scientific visualization and animation work.
    PBMPlus supports none of these.

    PBMPlus image file format support is also strangely sparse.  Some formats
    can only be read, but not written.  Other formats can only be written,
    but not read.

    The SDSC Image Tools support read and write handlers for all supported
    file formats, except PostScript and EPS.  These formats are written
    but not read.  To read PostScript or EPS files properly requires the
    implementation of a full PostScript interpreter and is well beyond
    the scope of this project.

7.  Image file format conversion in the PBMPlus package is done with a
    collection of ** 87 ** separate tools!  To read a Sun Rasterfile, use
    "rasttopbm" or "rasttoppm" or "rasttopnm".  To write it back out again,
    use "pbmtorast" or "ppmtorast" or "pnmtorast".  That's 6 tools for just
    one file format.

    The SDSC Image Tools place file format support in the C function library.
    All tools simply call the top level read or write routine in the library.
    That routine then fans out to all the appropriate file format read and
    write handlers.  This lets tools support all formats from a single tool.

    The prime tool for image file format conversion in the SDSC Image Tools
    is "imconv", which supports all 30+ formats within 1 tool, not 87.

8.  The SDSC Image Tools are implemented atop a binary I/O package that
    portably handles reading and writing binary data to files, streams, and
    data arrays.  Such a package is absolutely necessary in order to handle
    differences in byte order, word size, floating point format, and structure
    padding.  The use of such a binary I/O package has allowed us to port the
    Image Tools, without any change of higher-level code, to a dozen
    architectures, including Suns, SGIs, DEC hosts, and even our Cray Y-MP.

    The PBMPlus package is not implemented with portability in mind.  There
    are numerous instances within the code where byte order or word size
    is assumed.  Such code will not work on a Cray, for instance.

9.  The SDSC Image Tools were designed to have a consistent and intuitive user
    interface.  All tools have -help arguments to display on-line help
    information distilled from the full man pages.  Argument parsing is
    consistent throughout the package.

    Man pages exist in the SDSC Image Tools for all command-line tools, all
    function library routines, and all image file formats.  Man pages explain
    tool or routine usage, motivation for usage, algorithms used, and give
    multiple usage examples.  File format man pages explain where the file
    format comes from, where it is typically used, and how we support it.

    PBMPlus tools, however, use a mish-mash of command-line argument styles and
    virtually never have on-line help.  Man pages are sparse and almost never
    include usage examples.  The following, for instance, is the entire
    PBMPlus man page for the "icontopbm" converter for the Sun icon file format:

	NAME
		icontopbm - convert a Sun icon into a protable bitmap
	SYNOPSIS
		icontopbm [ iconfile ]
	DESCRIPTION
		Reads a Sun icon as input.  Produces a portable bitmap as
		output.
	SEE ALSO
		pbmtoicon(1), pbm(5)
	AUTHOR
		Copyright (C) 1988 by Jef Poskanzer.

    The SDSC Image Tools man page on the Sun icon format takes three pages.
    It includes syntax examples for calling "ImFileRead( )" and "ImFileWrite( )"
    to read and write the format, and describes the purpose and typical use
    of Sun icon files.  Here's the first two paragraphs of the DESCRIPTION
    section:

	DESCRIPTION
		icon image files are used by Sun Microsystem's SunView  win-
		dow  system,  NeWS window system, OpenWindows NeWS tool set,
		and X11 XView tool set for the storage  of  icons,  cursors,
		fill  patterns,  and  pieces  of widgets (like button check-
		marks).

		Sun icon files can be  most  easily  generated  using  Sun's
		iconedit(1)  icon and cursor editor.  The Sun operating sys-
		tem release includes a directory of standard icons, cursors,
		background patterns, and widget pieces in icon format in the
		directory /usr/include/images.  See  the  Sun  documentation
		set  for  details  on  how to use the tools dealing with Sun
		icon files.

    The man page goes on to give common file name prefixes for Sun icon files
    and a brief overview of the Sun icon file format itself, including a
    sample icon.  The DOCUMENTATION section of the man page tells you where
    to find out more about the file format, and SEE ALSO points you to
    additional related tools, routines, and file formats, such as the
    Microsoft Windows icon format.


And so on.  There are significant differences between the SDSC Image Tools
and the PBMPlus package.  Let us return to the net posting that sparked this
discussion:

	>Don't forget pbmplus *is* available in source code and does 99 percent
	>of what imconv does (and often does it faster!).  It's available with
	>the X11 distribution in the contrib directory or from your favorite
	>FTP site (wuarchive.uwstl.edu comes to mind).

-  PBMPlus clearly does *not* do 99% of what the SDSC Image Tools do.

-  PBMPlus is not faster.  It couldn't be.  To do anything in it you first
   have to convert your image file to one of the PBMPlus file formats.  Then,
   after doing your task, you have to convert back out again into the format
   you really want your result in.  At a minimum this requires two extra file
   reads and two extra file writes.

   For example, to rotate an 8-bit Sun Rasterfile by 45 degrees, you must do
   the following operations in PBMPlus:

	rasttopnm file.ras > file.pnm		-- RAS to PNM
	pnmrotate 45.0 file.pnm > rfile.pnm	-- Rotate by 45
	ppmquant 256 rfile.pnm > r256file.pnm	-- Reduce to 256 colors
	pnmtorast r256file.pnm > rfile.ras	-- PNM to RAS

   The "ppmquant" is necessary because the rotated image will have more than
   256 colors (an artifact of the rotation algorithm).  Calling "pnmtorast"
   on an image with more than 256 colors generates an RGB RAS file, not an
   8-bit RAS file suitable for display on a SPARCstation.  So, if we want an
   8-bit RAS file, we first have to quantize the image back down to 256 colors.

   This same task may be accomplished using the SDSC Image Tools:

	imrotate file.ras -rot 45.0 -outindex rfile.ras

   These operations were timed using an 8-bit 512x480 Sun Rasterfile of the
   standard Mandrill.  File I/O was to and from local disk on a Sun
   SPARCstation 2.

		    Execution Times (in seconds)
			Real	User	Sys
			----	----	---
	PBMPlus		95.9	90.7	3.0
	Image Tools	11.5	10.7	0.5

   On this operation, the SDSC Image Tools accomplished the task 8.3 times
   faster than PBMPlus.

   Actually, we had to hack the test.  The Mandrill we had was a 24-bit
   Utah Raster toolkit RLE image which we first had to convert to a RAS file,
   because PBMPlus doesn't support RLE files.  After conversion, "rasttopnm"
   complained it was unable to read the file.  This turned out to be because
   we'd converted the file using "imconv", which had, as always, defaulted to
   the best compression possible and generated a compressed RAS file (a
   standard part of the RAS file specification).  However, "rasttopnm" doesn't
   understand compressed RAS files, so we had to convert the RAS file once
   more into something PBMPlus could understand.  This extra hassle and
   compute time was not included in the times reported above.

-  Version 2.1 of the SDSC Image Tools are available via anonymous ftp from
   "ftp.sdsc.edu".  Tool source code is included.  Library source code is not.

-  Version 2.1 of the SDSC Utilities library, including the binary I/O package,
   argument parsing package, and tag table package are also available via
   anonymous ftp from "ftp.sdsc.edu".  Library source code is not included.



Further information on the SDSC Image Tools may be found in the following:

	Nadeau, D.R., "Software Tools for Image Conversion and Printing,"
	Proceedings of the Visions of Supercomputing, Cray Users Group
	Conference, September 1991.

	Nadeau, D.R., Elvins, T.T., and Bailey, M.J., "Image Handling in a
	Multi-vendor Environment," Proceedings of the IEEE Visualization '91
	Conference, IEEE Computer Society Press, October 1991.

	Nadeau, D.R., Elvins, T.T., "Network Resources in a Scientific
	Computing Environment," Proceedings of the Third Eurographics
	Workshop on Visualization in Scientific Computing, April 1992.

	San Diego Supercomputer Center, SDSC Image Tools manual pages,
	Version 2.1, December 1992.

Related information may be found in the following:

	Elvins, T.T., "A Visualization Computing Environment for a Widely
	Dispersed Scientific Community," State of the Art in Data
	Visualization, ACM SIGGRAPH 90 course notes, Course Number 27, 1990.

	Elvins, T.T., Nadeau, D.R., "NetV:  An Experimental Network-based
	Volume Visualization System," Proceedings of the Second IEEE Conference
	on Visualization, October 1991.

	Elvins, T.T., Nadeau, D.R., "Scientific Visualization in a Network
	Computing Environment," Proceedings of the EUROGRAPHICS UK 1992
	Conference, 1992.

	Nadeau, D.R., Bailey, M.J., "Network Video Device Control,"
	Proceedings of the Third IEEE Conference on Visualization, October 1992.

Thank you.


---
Dave Nadeau						nadeau@sdsc.edu
Advanced Scientific Visualization Laboratory		(619) 534-5062
San Diego Supercomputer Center
P.O. Box 85608   San Diego, CA   92186-9784