path: root/README

                              NETPBM


THIS IS THE PRIMARY DOCUMENTATION DISTRIBUTED WITH NETPBM.  SEE THE doc
DIRECTORY IN THE SOURCE TREE FOR OTHER INFORMATION, SUCH AS INSTALLATION
INSTRUCTIONS, AND SEE <http://netpbm.sourceforge.net>.

Netpbm is a toolkit for manipulation of graphic images, including
conversion of images between a variety of different formats.  There
are over 300 separate tools in the package including converters for
about 100 graphics formats.  Examples of the sort of image
manipulation we're talking about are: Shrinking an image by 10%;
Cutting the top half off of an image; Making a mirror image; Creating
a sequence of images that fade from one image to another;

For more information on what the package does, see
<http://netpbm.sourceforge.net/doc>.

The package is intended to be portable to many platforms. It has, at
least at one time, been tested under various Unix-based systems,
Windows, Mac OS X, VMS and Amiga OS.  The maintainer uses and builds
it on a platform that consists (in relevant part) mainly of GNU
software (you probably know this kind of system by the name "Linux").

The goal of Netpbm is to be a single source for all the primitive
graphics utilities, especially converters, one might need.  So if you
know of some freely redistributable software in this vein which is not
in the package yet, you should bring it to the attention of the Netpbm
maintainer so it can be included in the next release.

Netpbm does not contain interactive tools and doesn't have a graphical
interface.

Netpbm replaces the widely spread Pbmplus package (last released
December 10, 1991).  A lot of improvements and additions have been
made.  After the latest release of Pbmplus, a lot of additional
filters began circulating on the net, which was a fairly novel state
of affairs at the time.  The aim of Netpbm was to collect these and to
turn them into a package, hence the name "Netpbm."  This work has been
performed by programmers all over the world.  If _you_ have some code
to add, please contact the Netpbm maintainer.


USING NETPBM IN A WEBSITE
-------------------------

Many people use Netpbm to perform graphics functions in a web site.  They
have CGI scripts that invoke Netpbm programs to process images for display
on a web page.  Gallery and 4Images are two web site software packages
that rely on Netpbm for graphics manipulation.

Installing Netpbm requires different skills and system access than 
installing most other web site software.  You must be able to compile
C code for the web server machine and have a basic understanding of 
how files are organized and programs run on the web server.  Diagnosing
inevitable problems usually requires shell access to the web server.

Netpbm is basic graphics software that ought to be supplied by any
web hosting service.  If it isn't on your web server already, you should
request that the system administrator add it.

The Gallery project provides an easy install package for the parts of
Netpbm that Gallery needs, and provides technical support at:

    http://gallery.sourceforge.net/forums.php


DISTRIBUTION
------------

You'll find the latest release of Netpbm source code at
<http://prdownloads.sourceforge.net/netpbm/>.

The user manual is not in the source code package.  It is available online
at <http://netpbm.sourceforge.net/doc> and you can download it from there.
See the file doc/USERDOC for details.

A list of prebuilt Netpbm distributions is on the Netpbm
website, <http://netpbm.sourceforge.net>.


PREREQUISITES
-------------

Don't sweat the prerequisites too much.  In most cases, if you're
missing something, the build of the programs that depend on it will
bomb, but the rest of the Netpbm programs will build just fine.  And
you may not need the more demanding programs.

If you have trouble getting, building, or installing the
prerequisites, the Netpbm maintainer wants to know.  Since he uses
them himself, he can help you.  And if there is a problem with a
prerequisite package that its own maintainer cannot fix, it may be
possible to ship a fix with Netpbm.

To build and install Netpbm, you need GNU Make and a Perl interpreter.
You can get GNU Make from http://www.gnu.org/software and Perl from 
http://www.cpan.org.  It's possible to get around the Perl requirement
by running some of the steps on a different machine that has Perl and
doing others manually.  There is no practical substitute for GNU Make.

To build pnmtotiff or tifftopnm or pnmtotiffcmyk, you need the Tiff
library.  You can get it from http://www.libtiff.org.

To build ppmtojpeg or jpegtopnm, you need the JPEG/JFIF library from
the Independent JPEG Group (IJG).  You can get it at
ftp://ftp.uu.net/graphics/jpeg.  See http://www.ijg.org for more
information.  You need Release 6b or better.  With earlier releases, Netpbm
build fails with undefined jpeg symbols.  The basic JPEG library installation
procedure installs only the runtime part of the package -- you nee the
development part as well, so run 'make install-lib'.  The JPEG library 
documentation erroneously calls this installing "the library itself."
This apparently was written before shared libraries.  With shared libraries,
"the library itself" is part of the runtime installation, but install-lib
still installs the compile-time stuff you need.

You may also need the JPEG library to build the Tiff converters.  If
your Tiff library references a shared JPEG library, then you do.  The
Tiff library may also include a static copy of the JPEG library, in
which case you won't need a separate JPEG library.  Or it may have
been built without any JPEG compression capability, in which case you
won't need a separate JPEG library, but the Tiff converters won't be
able to handle Tiff with JPEG compression.

The same goes for Ppmtompeg.  You need the jpeg library if you want to
create MPEGs from JPEGs (without the loss of quality that comes with
converting from JPEG to PPM first), and if you don't have the JPEG
library and don't say so in Makefile.config, you won't be able to
build Ppmtompeg at all.

To build or use Pnmtopng and Pngtopnm, you need the Zlib compression
library and the PNG library (libpng).  You can get Zlib from
ftp://quest.jpl.nasa.gov/pub/zlib or
ftp://metalab.unc.edu/pub/Linux/libs.  You can get libpng from
http://www.libpng.org/pub/png/libpng.html or
http://libpng.sourceforge.net.  Older libpng won't work -- you get
unresolved external references to png_sig_cmp and png_set_sig_bytes.

You may also need the Zlib library to build the Tiff converters, in
the same way as the Tiff converters require the JPEG libraries, as
explained above.

Pstopnm (the Postscript to PNM image converter) requires Ghostscript
(installed with the name 'gs' in your command search path).  And it 
requires in particular that Ghostscript be built with the relevant 
PNM device drivers.  See http://www.ghostscript.com/doc/GPL/ .

The Utah Raster Toolkit is not a prerequisite because Netpbm includes
a subset of it that meets the needs of Pnmtorle and Rletopnm.
However, you can also substitute the real package by properly
configuring Makefile.config.  You can get it from 
ftp://ftp.cs.utah.edu/pub/dept/OLD/pub/urt-3.1b.tar.Z.  There's a 
patch at ftp://ptolemy.berkeley.edu/pub/misc/urt/urt-3.1b-3.1b1.patch

You generally need a compiler other than Gcc 2.96.  Gcc 2.96 has a bug
in its inlining optimization.  It generates incorrect code.  Netpbm
source code takes advantage of inlining and you normally build Netpbm
with inlining enabled.  Therefore, if you use Gcc 2.96 you will get
broken Netpbm programs.  The usual symptom is bogus syntax error
messages when you run the program.  You can avoid this compiler bug by
using a -O0 compile option instead of the usual -O3.  The automatic
configuration program will usually detect that you need this and set
it up for you.  This will make some programs noticeably slower,
though.

Netpbm requires about 3.5 MiB of disk space, not including documentation.
The documentation is 1.1 MiB, but you don't necessarily have to install
it; you can just access the public copy.


INSTALLATION
------------

See doc/INSTALL.


SUPPORT
-------

The maintainer of Netpbm, since September 1999, is Bryan Henderson:

  bryanh@giraffe-data.com.  

If for some reason that email address doesn't work, you can reach
Bryan at giraffedata@yahoo.com as a backup.  Please don't mail to 
both at the same time.  Bryan doesn't need two copies of your email.

Bryan actively maintains the package and wants to know about any bugs
or problems people have with Netpbm or suggestions for improvement.

There is no bug reporting database or mailing list.  These would not
be very useful with Netpbm because Bryan personally responds to all
bug reports and requests for help immediately.  All known bugs in the
"latest" release are listed in its release notes on Sourceforge
(updated as the bugs are reported) and the "stable" release is
generally maintained so as not to have known bugs for more than a few
days.  The doc/HISTORY file in the package may be useful if you want
to find out whether upgrading to the current release would solve your
problem.  The information in that file, on a per-release basis, is 
also in the change histories on Sourceforge.



MORE INFORMATION, DOCUMENTATION
-------------------------------

For more information about Netpbm, see <http://netpbm.sourceforge.net/doc>.

The 'doc' directory in the source tree has more information.

A good place to start for information about the wide world of computer
graphics is http://www.faqs.org/faqs/graphics/  .