NETPBM
Release 10.0
THIS IS THE PRIMARY DOCUMENTATION DISTRIBUTED WITH NETPBM. SEE THE doc
DIRECTORY IN THE SOURCE TREE FOR OTHER INFORMATION, SUCH AS INSTALLATION
INSTRUCTIONS.
Netpbm is a toolkit for manipulation of graphic images, including
conversion of images between a variety of different formats. There
are over 220 separate tools in the package including converters for
more than 80 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;
The man page Netpbm.1 in the package has a more complete description
of what the package does.
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 (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. The aim of Netpbm was to collect these and to
turn them into a package. This work has been performed by programmers
all over the world. If _you_ have some code to add, please contact
the Netpbm maintainer.
DISTRIBUTION
------------
You'll find the latest release of Netpbm source code at
<http://download.sourceforge.net/netpbm/>.
A prebuilt version for Cygwin (Windows) is at
<ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/porters/Humblet_Pierre_A/V1.1>
Contact Pierre A. Humblet <Pierre.Humblet@ieee.org>.
A prebuilt version for DJGPP/GNU (DOS/Windows) is maintained by Mariano
Alvarez Fernandez <malfer@teleline.es>. See
<http://www.terra.es/personal/malfer/netpbm/netpbm.htm>.
A prebuilt version for Windows using Mingw32 and GNU Bash is
distributed by the GnuWin32 Project. See
<http://gnuwin32.sourceforge.net/packages/netpbm.htm>.
A prebuilt version for Solaris is at
<http://www.ibiblio.org/pub/packages/solaris/sparc/>.
Contact Mark Ashley <Mark.Ashley@Sun.COM>.
Check out <http://freshmeat.net> to see if the distribution has changed
since this file was written.
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 6 or better. With Release 5, 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 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.gnu.org/ghostscript/ .
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
For more prerequisite information for CYGWIN (Windows), see the Cygwin
section below.
INSTALLATION
------------
For most typical platforms, you can just do
configure
followed by
make
To build all the programs. Then
make install
to install them all.
The 'configure' program is not GNU Autoconf -- it is a simple program
specific to Netpbm that prompts you for information about your system.
If your system is not typical, you'll have to do a little more work,
as described below under "custom installation."
When you don't set up the build properly (and Configure is unable to guess
your configuration), the build error messages you get are anything but
indicative of your mistake. So if you have build error messages you can't
interpret, see the COMMON BUILD ERROR MESSAGES section.
The only tricky part about installing is setting up the shared libraries
that are part of Netpbm. 'make install' copies them into place, but that
may not be enough. If you get mysterious "file not found" kinds of
errors and are not an expert with shared libraries, see the section
"SHARED LIBRARIES" below.
You may want to append the contents of the file 'magic' to your 'file'
database (typically /etc/magic). This allows the 'file' program to
recognize a bunch of file formats, including the Netpbm formats.
The --keep-going option to Make is handy, because it causes Make to
make anything it can, as opposed to quitting as soon as something goes
wrong. With so many parts having so many requirements, it's not
unusual for a few things to fail to build, but that doesn't affect
everything else. You can work on the failed parts and repeat the make
and it will attempt to build whatever it hasn't successfully built
yet.
INSTALLATION - CYGWIN
---------------------
(See also the general installation instructions above).
Cygwin is a software package that sets up a Unix-like platform on a
Windows (win32) system. Here are some specific things you need in
that environment to build and use Netpbm. All these programs and
libraries are parts of cygwin package.
Programs:
1) gcc suite
2) binutils
3) bash
4) dlltool
5) flex & byacc
6) patch
7) install
8) rm, ln, cp and other file utilities
Libraries:
1) libtiff (cygtiff3.dll)
2) libpng (cygpng2.dll)
3) libjpeg6b (cygjpeg6b.dll)
4) libz (cygz.dll)
Find Cygwin at http://sources.redhat.com/cygwin/ .
One problem special to Windows is the common existence of directories
with space in their names (e.g. Windows 2000's "Documents and
Settings" directory. (Such filenames are possible on non-Windows
systems, but are highly unconventional). Don't try to build Netpbm in
such a directory or with files in such a directory. It ought to work,
but it just doesn't. And the error messages are far from helpful,
since those spaces completely change the nature of the commands that
include them.
One way to deal with this is to use the Cygwin "mount" facility to map
the Windows path "c:/Documents and Settings/aaa/bbb/cccc/Distributions" to
something short and friendly, such as /Distributions.
INSTALLATION - MAKING ONLY THE PARTS YOU NEED
---------------------------------------------
If you don't need the whole package, but just want one tool in it that you
heard about, you can make just that one. For example, to make Ppmtojpeg,
just do
configure
cd ppm
make ppmtojpeg
It will build Ppmtojpeg and any of its dependencies, but nothing else.
You have to install it manually.
When you build just one program, you should request static libraries
in the configure step, because for just one program, the shared
libraries would be pure masochism.
CUSTOM INSTALLATION
-------------------
This section explains how to customize the installation in the case that
your platform is, or your requirements are, not among the simple cases that
'configure' understands. 'configure' is really just a convenient way to
build the Makefile.config file, and in the most general case, you build
that file manually.
Makefile.config contains settings for various things that vary from
one system to the next, like file paths. Start with the distributed
file Makefile.config.in. Copy it as Makefile.config, then edit it.
Search for your platform name (Solaris, SunOS, NetBSD, Cygwin, BeOS,
and Tru64 are among those mentioned) to see recommended settings for
your platform.
Unless you want to do some make file rewriting, you will need to use
GNU Make even if nothing else on your system is GNU, because the
Netpbm make files exploit some advanced features of GNU Make. Often,
systems have both GNU Make and a native Make. In this case, GNU Make
is named 'gmake'. If you don't have it yet, see www.gnu.org/software.
GNU Make is free, easy to install, and works just about anywhere.
If your system is even too exotic to accomodate with settings in
Makefile.config, you may need to modify things in the main make files
or pm_config.h.
If you figure out how to install on other platforms, contact the
Netpbm maintainer to have the 'configure' program or these
instructions improved for the next person.
INSTALLATION - MISCELLANEOUS
----------------------------
After installing the manual pages, you may want to create the "whatis"
file by doing a catman -w -M <directory>, or makewhatis -w, or
whatever the equivalent is on your system. Without Whatis, you may
have a hard time finding the Netpbm tools you have installed.
INSTALLATION - SHARED LIBRARIES
-------------------------------
There are over 220 programs in the Netpbm package and they do a lot of
common things. In order to avoid the expense of copying the code for
those common things into every program, Netpbm places it in 4 shared
libraries: libpbm, libpgm, libppm, and libpnm. When you invoke a
Netpbm program, your system notices that it needs these libraries and
accesses them too.
The tricky part of installing the shared (runtime) libraries is
telling your system where to find them in the event that you invoke a
Netpbm program. And that varies from one system to the next.
On a GNU libc system (essentially, any Linux system), if you put
the Netpbm shared libraries in a conventional spot (say, /lib) and
reboot your system, chances are you will have no trouble running
Netpbm programs. But if you want to fine tune things, read up on
ld-linux.so (GNU libc's dynamic linker) and ldconfig and consider the
/etc/ld.so.conf file and LD_LIBRARY_PATH environment variables. Use
'ldd' to see if you have a shared library issue. If it shows any
shared library as "not found", you've got library trouble.
One final note: New Netpbm executables often can run OK with old
Netpbm shared libraries. This means if you don't correctly install
the new libraries, you may run what you think is a new Netpbm program,
but in actuality be accessing the old Netpbm library, and you may not
even notice a problem right away. But eventually, you may find some
things not working the way they should. Again, 'ldd' will give you
peace of mind.
INSTALLATION WITHOUT SHARED LIBRARIES
-------------------------------------
Since shared libraries can be such a pain, and in fact some systems
don't even have them, you can build Netpbm with static libraries
instead. Just answer "static" to the static/shared question when you
run 'configure' (if you don't use 'configure', set NETPBMLIBTYPE as
directed in Makefile.config).
If you do this, you probably want to do a merge build instead of the
normal build (there's a question for that in the Configure program).
This creates several large ("merged") programs that contain the
functions of lots of smaller programs. When you invoke a merged
program, it behaves like the smaller program whose name matches the
command you used to invoke the merged program. For example, Ppmtogif
and Ppmtobmp get merged into a program called Ppmmerge. You install
it with a symbolic link such that when you invoke 'ppmtogif' you get
'ppmmerge'. When you invoke 'ppmtogif', Ppmmerge executes Ppmtogif.
Hence, 'make install' installs the large merged programs and creates
lots of symbolic links to them.
The point of this is to reduce the duplication of all the library
functions across large numbers of programs.
COMMON BUILD ERROR MESSAGES
---------------------------
When you fail to configure Netpbm properly for your environment (and
the Configure program isn't smart enough to do it for you), the error
messages you get are anything but indicative of your mistake. I've
compiled some of the common ones that have been reported to me here
with explanations of the root cause.
[actually, I don't have any yet. Email me yours and I'll add it.]
SUPPORT
-------
The maintainer of Netpbm, since September 1999, is Bryan Henderson:
bryanh@giraffe-data.com. Or as a backup, giraffedata@yahoo.com.
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 and releases fixes to
known bugs before others have a chance to encounter them. The HISTORY
file in the package may be useful if you want to find out whether
upgrading to the current release would solve your problem.
HISTORY
-------
See the file HISTORY.
MORE INFORMATION
----------------
A good place to start for information about the wide world of computer
graphics is http://www.faqs.org/faqs/graphics/ .
Information about PNG is at http://schaik.com/png.
COPYRIGHTS
----------
See the file COPYRIGHT.
Generated by dwww version 1.14 on Wed Jan 22 15:26:27 CET 2025.