diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/netpbm.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/netpbm.1 | 1421 |
1 files changed, 1421 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/netpbm.1 b/upstream/debian-bookworm/man1/netpbm.1 new file mode 100644 index 00000000..d8b9636d --- /dev/null +++ b/upstream/debian-bookworm/man1/netpbm.1 @@ -0,0 +1,1421 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "User manual for Netpbm" 1 "08 August 2020" "netpbm documentation" + +.SH NAME +netpbm - netpbm library overview + +.UN overview +.SH Overview Of Netpbm +.UN overview +.PP +\fBNetpbm\fP is a package of graphics programs and a programming +library. +.PP + There are over 330 separate programs in the package, most of +which have "pbm", "pgm", "ppm", "pam", or "pnm" in their names. For example, +.BR "pamscale" (1)\c +\& and +.BR "giftopnm" (1)\c +\&. +.PP +For example, you might use \fBpamscale\fP to shrink an image by +10%. Or use \fBpamcomp\fP to overlay one image on top of another. +Or use \fBpbmtext\fP to create an image of text. Or reduce the number +of colors in an image with \fBpnmquant\fP. +.PP +\fBNetpbm\fP is an open source software package, distributed via +the +.UR http://sourceforge.net/projects/netpbm +Sourceforge \fBnetpbm\fP project +.UE +\&. + +.UN index +.SH Table Of Contents + +.IP \(bu + +.UR #overview +Overview Of Netpbm +.UE +\& +.IP \(bu + +.UR #formats +The Netpbm Formats +.UE +\& + +.IP \(bu + +.UR #impconv +Implied Format Conversion +.UE +\& +.IP \(bu + +.UR #transparency +Netpbm and Transparency +.UE +\& + +.IP \(bu + +.UR #programs +The Netpbm Programs +.UE +\& + +.IP \(bu + +.UR #commonoptions +Common Options +.UE +\& +.IP \(bu + +.UR #directory +Directory +.UE +\& +.IP \(bu + +.UR #prognotes +How To Use The Programs +.UE +\& + +.IP \(bu + +.UR #libnetpbm +The Netpbm Library +.UE +\& +.IP \(bu + +.UR #config +netpbm-config +.UE +\& +.IP \(bu + +.UR #memoryusage +Memory Usage +.UE +\& +.IP \(bu + +.UR #cpuusage +CPU Usage +.UE +\& +.IP \(bu + +.UR #netpbmforgimp +Netpbm For Gimp +.UE +\& +.IP \(bu + +.UR #companion +Companion Software +.UE +\& + +.IP \(bu + +.UR #phpnetpbm +PHP-NetPBM +.UE +\& + +.IP \(bu + +.UR #othersoftware +Other Graphics Software +.UE +\& + +.IP \(bu + +.UR #viewers +Image Viewers +.UE +\& +.IP \(bu + +.UR #capturers +Image Capturers +.UE +\& +.IP \(bu + +.UR #visual +Visual Graphics Software +.UE +\& +.IP \(bu + +.UR #programmingtools +Programming Tools +.UE +\& +.IP \(bu + +.UR #toolsforformats +Tools For Specific Graphics Formats +.UE +\& +.IP \(bu + +.UR #document +Document/Graphics Software +.UE +\& +.IP \(bu + +.UR #otherothersoftware +Other +.UE +\& + +.IP \(bu + +.UR #otherfmt +Other Graphics Formats +.UE +\& +.IP \(bu + +.UR #history +History +.UE +\& +.IP \(bu + +.UR #author +Author +.UE +\& + + +.UN programs +.SH The Netpbm Programs +.PP +The Netpbm programs are generally useful run by a person from a +command shell, but are also designed to be used by programs. A common +characteristic of Netpbm programs is that they are simple, fundamental +building blocks. They are most powerful when stacked in pipelines. +Netpbm programs do not use graphical user interfaces and do not seek +input from a user. The only programs that display graphics at all are +the very primitive display programs \fBpamx\fP and \fBppmsvgalib\fP, +and they don't do anything but that. +.PP +Each of these programs has its own manual, as linked in the +directory below. +.PP +The Netpbm programs can read and write files greater than 2 GiB wherever +the underlying system can. There may be exceptions where the programs use +external libraries (The JPEG library, etc.) to access files and the external +library does not have large file capability. Before Netpbm 10.15 (April +2003), no Netpbm program could read a file that large. + +.UN commonoptions +.SS Common Options +.PP +There are a few options that are present on all programs that are based +on the Netpbm library, including virtually all Netpbm programs. These +are not mentioned in the individual manuals for the programs. +.PP +You can use two hyphens instead of one on these options if you like. + + + +.TP +\fB-quiet\fP + Suppress all informational messages that would otherwise be +issued to Standard Error. (To be precise, this only works to the +extent that the program in question implements the Netpbm convention +of issuing all informational messages via the \fBpm_message()\fP +service of the Netpbm library). + +.TP +\fB-version\fP +Instead of doing anything else, report the version of the +\fBlibnetpbm\fP library linked with the program (it may have been +linked statically into the program, or dynamically linked at run +time). Normally, the Netpbm programs and the library are installed +at the same time, so this tells you the version of the program and all +the other Netpbm files it uses as well. + +.TP +\fB-plain\fP +If the program generates an image in PNM format, generate it in the +"plain" (aka "ascii") version of the format, as opposed to the "raw" (aka +"binary") version. +.sp +Note that the other Netpbm format, PAM, does not have plain and raw +versions, so this option has no effect on a program that generates PAM output. +.sp +This option was introduced in Netpbm 10.10 (October 2002). From Netpbm 10.32 +(February 2006) through Netpbm 10.62 (March 2013), the option is invalid with +a program that generates PAM output (instead of ignoring the option, the +program fails). + + + +.UN directory +.SS Directory +.PP +Here is a complete list of all the Netpbm programs (with links to +their manuals): +.PP +.BR "Netpbm program directory" (1)\c +\& + + +.UN prognotes +.SS How To Use The Programs +.PP +As a collection of primitive tools, the power of Netpbm is multiplied +by the power of all the other unix tools you can use with them. These +notes remind you of some of the more useful ways to do this. Often, +when people want to add high level functions to the Netpbm tools, they +have overlooked some existing tool that, in combination with Netpbm, +already does it. +.PP +Often, you need to apply some conversion or edit to a whole bunch of files. +.PP +As a rule, Netpbm programs take one input file and produce one output file, +usually on Standard Output. This is for flexibility, since you so often +have to pipeline many tools together. +.PP +Here is an example of a shell command to convert all your of PNG files +(named *.png) to JPEG files named *.jpg: +.nf +for i in *.png; do pngtopam $i | ppmtojpeg >`basename $i .png`.jpg; done + +.fi +.PP +Or you might just generate a stream of individual shell commands, one +per file, with awk or perl. Here's how to brighten 30 YUV images that +make up one second of a movie, keeping the images in the same files: + +.nf +ls *.yuv + | perl -ne 'chomp; + print yuvtoppm $_ | pambrighten -value +100 | ppmtoyuv >tmp$$.yuv; + mv tmp$$.yuv $_ + ' + | sh + +.fi +.PP +The tools \fBfind\fP (with the \fB-exec\fP option) and +\fBxargs\fP are also useful for simple manipulation of groups of files. +.PP +Some shells' "process substitution" facility can help where a +non-Netpbm program expects you to identify a disk file for input and +you want it to use the result of a Netpbm manipulation. Say +the hypothetical program \fBprintcmyk\fP +takes the filename of a Tiff CMYK file as input and what you have is a +PNG file +\fBabc.png\fP. + +Try: +.nf +printcmyk <({ pngtopam abc.png | pnmtotiffcmyk ; }) + +.fi +.PP +It works in the other direction too, if you have a program that +makes you name its output file and you want the output to go through a +Netpbm tool. + + +.UN formats +.SH The Netpbm Formats +.PP +All of the programs work with a set of graphics formats called the +"netpbm" formats. Specifically, these formats are +.BR "pbm" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "ppm" (1)\c +\&, +and +.BR "pam" (1)\c +\&. + +The first three of these are sometimes known generically as +"pnm". + +Many of the Netpbm programs convert from a Netpbm format to another +format or vice versa. This is so you can use the Netpbm programs to +work on graphics of any format. It is also common to use a +combination of Netpbm programs to convert from one non-Netpbm format +to another non-Netpbm format. Netpbm has converters for about 100 +graphics formats, and as a package Netpbm lets you do more graphics +format conversions than any other computer graphics facility. +.PP +The Netpbm formats are all raster formats, i.e. they describe an image +as a matrix of rows and columns of pixels. In the PBM format, the +pixels are black and white. In the PGM format, pixels are shades of +gray. In the PPM format, the pixels are in full color. The PAM format +is more sophisticated. A replacement for all three of the other formats, +it can represent matrices of general data including but not limited to +black and white, grayscale, and color images. +.PP +Programs designed to work with PBM images have "pbm" in their names. +Programs designed to work with PGM, PPM, and PAM images similarly have +"pgm", "ppm", and "pam" in their names. +.PP +All Netpbm programs designed to read PGM images see PBM images as if +they were PGM too. All Netpbm programs designed to read PPM images +see PGM and PBM images as if they were PPM. See +.UR #impconv + Implied Format Conversion +.UE +\&. +.PP + Programs that have "pnm" in their names read PBM, PGM, +and PPM but unlike "ppm" programs, they distinguish between +those formats and their function depends on the format. For example, +.BR "pnmtopng" (1)\c +\& creates a black and white PNG +output image if its input is PBM or PGM, but a color PNG output image +if its input is PPM. And \fBpnmrotate\fP produces an output image of +the same format as the input. A hypothetical \fBppmrotate\fP program +would also read all three PNM input formats, but would see them all as +PPM and would always generate PPM output. +.PP +Programs that have "pam" in their names read all the Netpbm +formats: PBM, PGM, PPM, and PAM. They sometimes treat them all as if +they are PAM, using an implied conversion, but often they recognize +the individual formats and behave accordingly, like a "pnm" program +does. See +.UR #impconv +Implied Format Conversion +.UE +\&. +.PP +Finally, there are subformats of PAM that are equivalent to PBM, +PGM, and PPM respectively, and Netpbm programs designed to read +PBM, PGM, and/or PPM see those PAM images as if they were the former. +For example, \fBppmhist\fP can analyze a PAM image of tuple type +RGB (i.e. a color image) as if it were PPM. +.PP + If it seems wasteful to you to have three separate PNM formats, be +aware that there is a historical reason for it. In the beginning, +there were only PBMs. PGMs came later, and then PPMs. Much later +came PAM, which realizes the possibility of having just one aggregate +format. +.PP +The formats are described in the specifications of +.BR "pbm" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "ppm" (1)\c +\&, +and +.BR "pam" (1)\c +\&. + +.UN impconv +.SS Implied Format Conversion +.PP +A program that uses the PGM library subroutines to read an image +can read a PBM image as well as a PGM image. The program sees the PBM +image as if it were the equivalent PGM image, with a maxval of 255. +\fBnote:\fP This sometimes confuses people who are looking +at the formats at a lower layer than they ought to be because a zero +value in a PBM raster means white, while a zero value in a PGM raster +means black. +.PP +A program that uses the PPM library subroutines to read an image +can read a PGM image as well as a PPM image and a PBM image as well as +a PGM image. The program sees the PBM or PGM image as if it were the +equivalent PPM image, with a maxval of 255 in the PBM case and the +same maxval as the PGM in the PGM case. +.PP +A program that uses the PAM library subroutines to read an image +can read a PBM, PGM, or PPM image as well as a PAM image. The program +sees a PBM image as if it were the equivalent PAM image with tuple +type \fBBLACKANDWHITE\fP. It sees a PGM image as if it were the +equivalent PAM image with tuple type \fBGRAYSCALE\fP. It sees a PPM +image as if it were the equivalent PAM image with tuple type +\fBRGB\fP. But the program actually can see deeper if it wants to. +It can tell exactly which format the input was and may respond +accordingly. For example, a PAM program typically produces output in +the same format as its input. +.PP +A program that uses the PGM library subroutines to read an image +can read a PAM image as well a PGM image, if the PAM is a grayscale or +black and white visual image. That canonically means the PAM has a +depth of 1 and a tuple type of GRAYSCALE or BLACKANDWHITE, but +most Netpbm programs are fairly liberal and will take any PAM at all, +ignoring all but the first plane. +.PP +There is a similar implied conversion for PPM library subroutines +reading PAM. There is nothing similar for PBM, so if you need for a +PBM program to read a PAM image, run it through \fBpamtopnm\fP. + + +.UN transparency +.SS Netpbm and Transparency +.PP +In many graphics formats, there's a means of indicating that certain +parts of the image are wholly or partially transparent, meaning that +if it were displayed "over" another image, the other image +would show through there. Netpbm formats deliberately omit that +capability, since their purpose is to be extremely simple. +.PP +In Netpbm, you handle transparency via a transparency mask in a +separate (slightly redefined) PGM image. In this pseudo-PGM, what +would normally be a pixel's intensity is instead an opaqueness value. +See +.BR "pgm" (1)\c +\&. +.BR "pamcomp" (1)\c +\& is an example of a program that uses +a PGM transparency mask. +.PP +Another means of representing transparency information has recently +developed in Netpbm, using PAM images. In spite of the argument given +above that Netpbm formats should be too simple to have transparency +information built in, it turns out to be extremely inconvenient to +have to carry the transparency information around separately. This is +primarily because Unix shells don't provide easy ways to have networks +of pipelines. You get one input and one output from each program in a +pipeline. So you'd like to have both the color information and the +transparency information for an image in the same pipe at the same +time. +.PP +For that reason, some new (and recently renovated) Netpbm programs +recognize and generate a PAM image with tuple type RGB_ALPHA or +GRAYSCALE_ALPHA, which contains a plane for the transparency +information. See +.BR "the PAM specification" (1)\c +\&. + + + + +.UN libnetpbm +.SH The Netpbm Library +.PP +The Netpbm programming library, +.BR "libnetpbm" (1)\c +\&, makes it easy to write programs +that manipulate graphic images. Its main function is to read and +write files in the Netpbm formats, and because the Netpbm package +contains converters for all the popular graphics formats, if your +program reads and writes the Netpbm formats, you can use it with any +formats. +.PP +But the library also contain some utility functions, such as character +drawing and RGB/YCrCb conversion. +.PP +The library has the conventional C linkage. Virtually all programs +in the Netpbm package are based on the Netpbm library. + + +.UN config +.SH netpbm-config +.PP +In a standard installation of Netpbm, there is a program named +\fBnetpbm-config\fP in the regular program search path. We don't +consider this a Netpbm program -- it's just an ancillary part of a +Netpbm installation. This program tells you information about the +Netpbm installation, and is intended to be run by other programs that +interface with Netpbm. In fact, \fBnetpbm-config\fP is really a +configuration file, like those you typically see in the \fI/etc/\fP +directory of a Unix system. +.PP +Example: +.nf + $netpbm-config --datadir + /usr/local/netpbm/data + +.fi + +If you write a program that needs to access a Netpbm data file, it can +use such a shell command to find out where the Netpbm data files are. +.PP +\fBnetpbm-config\fP is the only file that must be installed in +a standard directory (it must be in a directory that is in the default +program search path). You can use \fBnetpbm-config\fP as a bootstrap +to find all the other Netpbm files. +.PP +There is no detailed documentation of \fBnetpbm-config\fP. If you're +in a position to use it, you should have no trouble reading the file +itself to figure out how to use it. + +.UN memoryusage +.SH Memory Usage +.PP +An important characteristic that varies among graphics software is +how much memory it uses, and how. Does it read an entire image into +memory, work on it there, then write it out all at once? Does it read one +and write one pixel at a time? In Netpbm, it differs from one program +to the next, but there are some generalizations we can make. +.PP +Most Netpbm programs keep one row of pixels at a time in memory. +Such a program reads a row from an input file, processes it, then +writes a row to an output file. Some programs execute algorithms that +can't work like that, so they keep a small window of rows in memory. +Others must keep the entire image in memory. If you think of what job +the program does, you can probably guess which one it does. +.PP +When Netpbm keeps a pixel in memory, it normally uses a lot more +space for it than it occupies in the Netpbm image file format. +.PP +The older programs (most of Netpbm) use 12 bytes per pixel. This +is true even for a PBM image, for which it only really takes one bit +to totally describe the pixel. Netpbm does this expansion to make +implementing the programs easier -- it uses the same format regardless +of the type of image. +.PP +Newer programs use the "pam" family of library functions +internally, which use memory a little differently. These functions are +designed to handle generic tuples with a variable numbers of planes, so no +fixed size per-tuple storage is possible. A program of this type uses 4 bytes +per sample (a tuple is composed of samples), plus a pointer (4-8 bytes) per +tuple. In a graphic image, a tuple is a pixel. So an ordinary color image +takes 16-20 bytes per pixel. +.PP +When considering memory usage, it is important to remember that +memory and disk storage are equivalent in two ways: + + +.IP \(bu +Memory is often virtual, backed by swap space on disk storage. So +accessing memory may mean doing disk I/O. + +.IP \(bu +Files are usually cached and buffered, so that accessing a disk file +may just mean accessing memory. + +.PP +This means that the consequences of whether a program works from +the image file or from a memory copy are not straightforward. +.PP +Note that an image takes a lot less space in a Netpbm format file, +and therefore in an operating system's file cache, than in Netpbm's +in-memory format. In non-Netpbm image formats, the data is even +smaller. So reading through an input file multiple times instead of +keeping a copy in regular memory can be the best use of memory, and many +Netpbm programs do that. But some files can't be read multiple times. +In particular, you can't rewind and re-read a pipe, and a pipe is +often the input for a Netpbm program. Netpbm programs that re-read +files detect such input files and read them into a temporary file, +then read that temporary file multiple times. +.PP +A few Netpbm programs use an in-memory format that is just one bit +per pixel. These are programs that convert between PBM and a format that +has a raster format very much like PBM's. In this case, it would actually +make the program more complicated (in addition to much slower) to use +Netpbm's generic 12 byte or 8 byte pixel representation. +.PP +By the way, the old axiom that memory is way faster than disk is not +necessarily true. On small systems, it typically is true, but on a +system with a large network of disks, especially with striping, it is +quite easy for the disk storage to be capable of supplying data faster +than the CPU can use it. + +.UN cpuusage +.SH CPU Usage +.PP +People sometimes wonder what CPU facilities Netpbm programs and the +Netpbm programming library use. The programs never depend on particular +features existing (assuming they're compiled properly), but the speed +and cost of running a program varies depending upon the CPU features. +.PP +Note that when you download a binary that someone else compiled, even +though it appears to be compiled properly for your machine, it may be compiled +improperly for that machine if it is old, because the person who compiled it +may have chosen to exploit features of newer CPUs in the line. For example, +an x86 program may be compiled to use instructions that are present on an +80486, but not on an 80386. You would probably not know this until you run +the program and it crashes. +.PP +But the default build options almost always build binaries that are as +backward compatible with old CPUs as possible. An exception is a build for a +64 bit x86 CPU. While the builder could build a program that runs on a 32 bit +x86, it does not do so by default. A default build builds a program will not +run on an older 32-bit-only x86 CPU. +.PP +One common build option is to use MMX/SSE operands with x86 CPUs. +Those are not available on older x86 CPUs. The builder by default does not +generate code that uses MMX/SSE when building for 32 bit x86 CPUs, but +does when building for 64 bit x86. +.PP +One area of particular importance is floating point arithmetic. +The Netpbm image formats are based on integers, and Netpbm arithmetic +is done with integers where possible. But there is one significant +area that is floating point: programs that must deal with light +intensity. The Netpbm formats use integers that are proportional to +brightness, and brightness is exponentially related to light +intensity. The programs have to keep the intermediate intensity +values in floating point in order not to lose precision. And the +conversion (gamma function) between the two is heavy-duty floating +point arithmetic. + +Programs that mix pixels together have to combine light intensity, so +they do heavy floating point. Three of the most popular Netpbm +programs do that: +.BR "\fBpamscale\fP" (1)\c +\& +(shrink/expand an image), +.BR "\fBpamcomp\fP" (1)\c +\& +(overlay an image over another one), and +.BR "\fBpamditherbw\fP" (1)\c +\& (Make a black and white +image that approximates a grayscale image). +.PP +The Netpbm image formats use 16 bit integers. The Netpbm code uses +"unsigned int" size integers to work with them. + + +.UN netpbmforgimp +.SH Netpbm For Gimp +.PP +The Gimp is a visual image editor for Unix and X, so it does the kinds +of things that Netpbm does, but interactively in a user-friendly way. +The Gimp knows a variety of graphics file formats and image transformations, +but you can extend it with plugins. +.PP +A particularly easy way to write a Gimp plugin is to write a Netpbm program +(remember that a fundamental mission of Netpbm is make writing image +manipulation programs easy) and then use \fB +.UR http://netpbm2gimp.sourceforge.net/ +netpbm2gimp +.UE +\&\fP to compile +that same source code into a Gimp plugin. +.PP +You can turn a program that converts from a certain graphics file format +to Netpbm format into a Gimp \fIload\fP plugin. Likewise, you +can turn a program that converts \fIto\fP a certain graphics format +\fIfrom\fP Netpbm format into a Gimp \fIstore\fP plugin. Finally, +a program that transforms images in Netpbm format can become a +\fIprocess\fP plugin. +.PP +And the \fBnetpbm2gimp\fP project has already packaged for you a few +hundred of the Netpbm programs as Gimp plugins. With this package you can, +for example, edit an image in any of the arcane graphics file formats that +Netpbm understands but no other image editor in existence does. + + +.UN companion +.SH Companion Software + +.UN phpnetpbm +.SS PHP-NetPBM +.PP +If you're using Netpbm to do graphics for a website, you can invoke +the Netpbm programs from a PHP script. To make this even easier, +check out +.UR http://sourceforge.net/projects/phpnetpbm +PHP-NetPBM +.UE +\&, +a PHP class that interacts with Netpbm. Its main goal is to decrease the +pain of using Netpbm when working with images in various formats. It +includes macro commands to perform manipulations on many files. +.PP +I can't actually recommend PHP-NetPBM. I spent some time staring +at it and was unable to make sense of it. Some documentation is in +fractured English and other is in an unusual character set. But a PHP +expert might be able to figure it out and get some use out of it. + +.UN othersoftware +.SH Other Graphics Software +.PP +Netpbm contains primitive building blocks. It certainly is not a +complete graphics software library. + +.UN othercmdline +.SS Command Line Programs +.PP +\fBImageMagick\fP does many of the same things - mainly the more +popular ones - that Netpbm does, including conversion between popular +formats and basic editing. \fBconvert\fP, \fBmogrify\fP, \fBmontage\fP, and +\fBanimate\fP are popular programs from the \fBImageMagick\fP +package. \fBImageMagick\fP runs on Unix, Windows, Windows NT, Macintosh, and +VMS. +.PP +\fBImageMagick\fP also contains the program \fBdisplay\fP, which is a +.UR #viewers +viewer +.UE +\& and +.UR #visual +visual editor +.UE +\&. + +.UN viewers +.SS Image Viewers +.PP +The first thing you will want to make use of any of these tools is a +viewer. (On GNU/Linux, you can use Netpbm's \fBpamx\fP or \fBppmsvgalib\fP +in a pinch, but it is pretty limiting). \fBzgv\fP is a good full service +viewer to use on a GNU/Linux system with the SVGALIB graphics display driver +library. You can find \fBzgv\fP +at \fB +.UR ftp://ftp.ibiblio.org/pub/Linux/apps/graphics/viewers/svga +ftp://ftp.ibiblio.org/pub/Linux/apps/graphics/viewers/svga +.UE +\&.\fP +.PP +\fBzgv\fP even has a feature in it wherein you can visually crop +an image and write an output file of the cropped image using +.BR "pamcut" (1)\c +\&. + +See the \fB-s\fP option to \fBzgv\fP. +.PP +For the X inclined, there is also \fBxzgv\fP. +.PP +\fBxwud\fP (X Window Undump) is a classic application program in the X +Window System that displays an image in an X window. It takes the special X +Window Dump format as input; you can use +Netpbm's +.BR "\fBpnmtoxwd\fP" (1)\c +\& to create it. You're +probably better off just using Netpbm's +.BR "\fBpamx\fP" (1)\c +\&. +.PP +\fBxloadimage\fP and its extension \fBxli\fP are also common +ways to display a graphic image in X. +.PP +\fBgqview\fP is a more modern X-based image viewer. +.PP +\fBqiv\fP is a small, very fast viewer for X. +.PP +To play mpeg movies, such as produced by \fBppmtompeg\fP, +try +.BR "mplayer" (1)\c +\& or +\fB +.UR http://sourceforge.net/projects/xine +xine +.UE +\&.\fP +.PP +See \fB +.UR ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers/X +ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers/X +.UE +\&\fP. + +.UN capturers +.SS Image Capturers +.PP +\fBxwd\fP (X Window Dump), a classic application program in the X Window +System, captures the contents of an X window, in its own special image format, +called X Window Dump File. You can use +Netpbm's +.BR "\fBxwdtopnm\fP" (1)\c +\& to turn it into something +more useful. +.PP +.UR http://www.rcdrummond.net/fbdump/ +\fBfbdump\fP +.UE +\& +Capturers the current contents of a video display on the local computer +and generates a PPM image of it. It works with Linux framebuffer devices. + + +.UN visual +.SS Visual Graphics Software +.PP +Visual graphics software is modern point-and-click software that +displays an image and lets you work on it and see the results as you go. +This is fundamentally different from what Netpbm programs do. +.PP +\fBxv\fP is a very old and very popular simple image editor in the +Unix world. It does not have much in the way of current support, +or maintenance, though. +.PP +Gimp is a visual image editor for Unix and the X Window System, in the same +category as the more famous, less capable, and much more expensive Adobe +Photoshop, etc. for Windows. +See \fB +.UR http://www.gimp.org +http://www.gimp.org +.UE +\&\fP. And you can +add most of Netpbm's function to Gimp +using +.UR http://netpbm2gimp.sourceforge.net/ +Netpbm2gimp +.UE +\&. +.PP +\fBImageMagick\fP contains the program \fBdisplay\fP, which is another +visual image editor. It has fewer functions than Gimp. This program uses the +X Window System. The package also contains +.UR #othercmdline +command line +.UE +\& graphics programs. +.PP +Electric Eyes, \fBkuickshow\fP, and \fBgthumb\fP are also visual +editors for the X/Window system, and \fBKView\fP and \fBgwenview\fP +are specifically for KDE. + +.UN programmingtools +.SS Programming Tools +.PP +If you're writing a program in C to draw and manipulate images, check out +.UR https://github.com/libgd/libgd +gd +.UE +\&. Netpbm contains a C library +for drawing images (\fBlibnetpbm\fP's "ppmd" routines), but it is +not as capable or documented as \fBgd\fP. There are wrapper libraries +available for Perl, PHP, and other language. +.PP +You can easily run any Netpbm program from a C program with +the \fBpm_system\fP function from the Netpbm programming library, but that is +less efficient than \fBgd\fP functions that do the same thing. +.PP +.UR http://cairographics.org/ +Cairo +.UE +\& is similar. +.PP +\fBIlib\fP is a C subroutine library with functions for adding +text to an image (as you might do at a higher level with +\fBpbmtext\fP, \fBpamcomp\fP, etc.). It works with Netpbm input and +output. Find it at \fB +.UR http://www.k5n.us/Ilib.php +k5n.us +.UE +\&\fP. +Netpbm also includes character drawing functions in the +.BR "libnetpbm" (1)\c +\& library, but they do not have as +fancy font capabilities (see +.BR "ppmdraw" (1)\c +\& +for an example of use of the Netpbm character drawing functions). +.PP +.UR http://www.pango.org/ +Pango +.UE +\& is another text rendering +library, with an emphasis on internationalization. +.PP +Pango and Cairo complement each other and work well together. +.PP +\fBGD\fP is a library of graphics routines that is part of PHP. +It has a subset of Netpbm's functions and has been found to resize +images more slowly and with less quality. + +.UN toolsforformats +.SS Tools For Specific Graphics Formats +.PP +\fBmencode\fP, which is part of the +.BR "mplayer" (1)\c +\& package, +creates movie files. It's like a much more advanced version of +.BR "\fBppmtompeg\fP" (1)\c +\&, without the Netpbm +building block simplicity. +.PP +.UR http://mjpeg.sourceforge.net +\fBMJPEGTools\fP +.UE +\& is software +for dealing with the MJPEG movie format. +.PP +To create an animated GIF, or extract a frame from one, use +\fBgifsicle\fP. \fBgifsicle\fP converts between animated GIF and +still GIF, and you can use \fBpamtogif\fP and \fBgiftopnm\fP to +connect up to all the Netpbm utilities. See \fB +.UR http://www.lcdf.org/gifsicle +http://www.lcdf.org/gifsicle +.UE +\&\fP. +.PP +To convert an image of text to text (optical character recognition +- OCR), use \fBgocr\fP (think of it as an inverse of \fBpbmtext\fP). +See \fB +.UR http://jocr.sourceforge.net/ +http://jocr.sourceforge.net/ +.UE +\&\fP. +.PP +\fB +.UR http://schaik.com/pngsuite +http://schaik.com/pngsuite +.UE +\&\fP +contains a PNG test suite -- a whole bunch of PNG images exploiting the +various features of the PNG format. +.PP +Other versions of Netpbm's \fBpnmtopng\fP/\fBpngtopam\fP are at +.BR " +http://www.schaik.com/png/pnmtopng.html" (1)\c +\&. +.PP +The version in Netpbm was actually based on that package a long time +ago, and you can expect to find better exploitation of the PNG format, +especially recent enhancements, in that package. It may be a little +less consistent with the Netpbm project and less exploitive of recent +Netpbm format enhancements, though. +.PP +\fB +.UR http://pngwriter.sourceforge.net +pngwriter +.UE +\&\fP is a +C++ library for creating PNG images. With it, you plot an image pixel +by pixel. You can also render text with the FreeType2 library. +.PP +\fBjpegtran\fP Does some of the same transformations as Netpbm is +famous for, but does them specifically on JPEG files and does them +without loss of information. By contrast, if you were to use Netpbm, +you would first decompress the JPEG image to Netpbm format, then +transform the image, then compress it back to JPEG format. In that +recompression, you lose a little image information because JPEG is a +lossy compression. Of course, only a few kinds of lossless +transformation are possible. \fBjpegtran\fP comes with the +Independent JPEG Group's ( +.UR http://www.ijg.org +http://www.ijg.org) +.UE +\& JPEG library. +.PP + Some tools to deal with EXIF files (see also Netpbm's +.BR "jpegtopnm" (1)\c +\& and +.BR "pnmtojpeg" (1)\c +\&): + +To dump (interpret) an EXIF header: Exifdump (( +.UR http://www.math.u-psud.fr/~bousch/exifdump.py +http://www.math.u-psud.fr/~bousch/exifdump.py) +.UE +\&) +or +.UR http://www.sentex.net/~mwandel/jhead +Jhead +.UE +\&. +.PP +A Python EXIF library and dumper: +.UR http://pyexif.sourceforge.net. +http://pyexif.sourceforge.net. +.UE +\& +.PP +Here's some software to work with IOCA (Image Object Content +Architecture): +.UR http://www.forminnovation.com +ImageToolbox +.UE +\& ($2500, demo +available). This can convert from TIFF -> IOCA and back again. +.PP +.UR https://ameri-imager.software.informer.com/ +Ameri-Imager +.UE +\& is +an image and video editor. ($40 Windows only). +.PP +\fBpnm2ppa\fP converts to HP's "Winprinter" format (for +HP 710, 720, 820, 1000, etc). It is a superset of Netpbm's +\fBpbmtoppa \fP and handles, notably, color. However, it is more of +a printer driver than a Netpbm-style primitive graphics building +block. See +.UR http://sourceforge.net/projects/pnm2ppa +The Pnm2ppa /Sourceforge Project +.UE +\& +.PP +\fBDjVuLibre\fP is a package of software for using the DjVu +format. It includes viewers, browser plugins, decoders, simple +encoders, and utilities. The encoders and decoders can convert +between DjVu and PNM. See +.UR http://djvu.sourceforge.net/ + the DjVu website. +.UE +\& + + +.UN document +.SS Document/Graphics Software +.PP +There is a large class of software that does document processing, +and that is somewhat related to graphics because documents contain +graphics and a page of a document is for many purposes a graphic +image. Because of this slight intersection with graphics, I cover +document processing software here briefly, but it is for the most part +beyond the scope of this document. +.PP +First, we look at where Netpbm meets document processing. +\fBpstopnm\fP converts from Postscript and PDF to PNM. It +effectively renders the document into images of printed pages. +\fBpstopnm\fP is nothing but a convenient wrapper for +.UR http://www.ghostscript.com/ +Ghostscript +.UE +\&, and in particular +Netpbm-format device drivers that are part of it. \fBpnmtops\fP and +\fBpbmtoepsi\fP convert a PNM image to a Postscript program for +printing the image. But to really use PDF and Postscript files, you +generally need more complex document processing software. +.PP +Adobe invented Postscript and PDF and products from Adobe are for many +purposes the quintessential Postscript and PDF tools. +.PP +Adobe's free Acrobat Reader displays PDF and converts to +Postscript. The Acrobat Reader for unix has a program name of +"acroread" and the -toPostScript option (also see the +-level2 option) is useful. +.PP +Other software from Adobe, available for purchase, interprets and creates +Postscript and PDF files. "Distill" is a program that converts Postscript to +PDF. +.PP +.UR http://www.foolabs.com/xpdf/ +\fBxpdf\fP +.UE +\& also reads PDF +files. +.PP +GSview, ghostview, gv, ggv, and kghostview are some other viewers for +Postscript and PDF files. +.PP +The program \fBps2pdf\fP, part of Ghostscript, converts from Postscript +to PDF. +.PP +.BR "bmpp" (1)\c +\& converts from +Netpbm and other formats to PDF. + +.PP +Two packages that produce more kinds of Encapsulated Postscript +than the Netpbm programs, including compressed kinds, are +.BR "bmpp" (1)\c +\& and +.UR http://imgtops.sourceforge.net/ +imgtops +.UE +\&. +.PP +\fBdvips\fP converts from DVI format to Postscript. DVI is the format +that Tex produces. Netpbm can convert from Postscript to PNM. Thus, you +can use these in combination to work with Tex/Latex documents graphically. +.PP +.UR http://wvware.sourceforge.net +\fBwvware\fP +.UE +\& converts +a Microsoft Word document (.doc file) to various other formats. While +the web page doesn't seem to mention it, it reportedly can extract an +embedded image in a Word document as a PNG. +.PP +.UR http://www.verypdf.com/artprint +Document Printer +.UE +\& +converts various print document formats (Microsoft Word, PDF, HTML, etc.) +to various graphic image formats. ($38, Windows only). +.PP +Latex2html converts Latex document source to HTML document source. +Part of that involves graphics, and Latex2html uses Netpbm tools for +some of that. But Latex2html through its history has had some rather +esoteric codependencies with Netpbm. Older Latex2html doesn't work +with current Netpbm. Latex2html-99.2beta8 works, though. + +.UN otherothersoftware +.SS Other +.PP +The \fBfile\fP program looks at a file and tells you what kind of +file it is. It recognizes most of the graphics formats with which +Netpbm deals, so it is pretty handy for graphics work. Netpbm's +.BR "anytopnm" (1)\c +\& program depends on \fBfile.\fP +See +\fB +.UR ftp://ftp.astron.com/pub/file +ftp://ftp.astron.com/pub/file +.UE +\&\fP. +.PP +The +.UR http://www.cs.utah.edu/gdc/projects/urt +Utah Raster Toolkit +.UE +\& from the +.UR http://www.cs.utah.edu/gdc +Geometric Design And Computation group +.UE +\& in the Department of Computer Science at University of +Utah serves a lot of the same purpose as Netpbm, but without the emphasis on +format conversions. This package is based on the RLE format, which you can +convert to and from the Netpbm formats. +.PP +\fBIvtools\fP is a suite of free X Window System drawing editors for +Postscript, Tex, and web graphics production, as well as an embeddable +and extendable vector graphic shell. It uses the Netpbm facilities. +See \fB +.UR http://www.ivtools.org +http://www.ivtools.org +.UE +\&\fP. +.PP +Chisato Yamauchi <cyamauch@ir.isas.jaxa.jp> has written a free +c/Fortran graphic library: +.UR http://www.ir.isas.jaxa.jp/~cyamauch/eggx_procall/ +EGGX/ProCall +.UE +\&. +He says he tried to write the ultimate easy-to-use graphic kit for X. It is +for drawing upon an X11 window, but for storage, it outputs PPM. He suggests +Netpbm to convert to other formats. +.PP +The program \fBmorph\fP morphs one image into another. It uses +Targa format images, but you can use \fBtgatoppm\fP and +\fBppmtotga\fP to deal with that format. You have to use the +graphical (X/Tk) Xmorph to create the mesh files that you must feed to +\fBmorph\fP. \fBmorph\fP is part of the Xmorph package. See \fB +.UR http://xmorph.sourceforge.net/ +http://xmorph.sourceforge.net/ +.UE +\&\fP. + + +.UN otherfmt +.SH Other Graphics Formats +.PP +People never seem to tire of inventing new graphics formats, often +completely redundant with pre-existing ones. Netpbm cannot keep up +with them. Here is a list of a few that we know Netpbm does +\fInot\fP handle (yet). +.PP +Various commercial Windows software handles dozens of formats that +Netpbm does not, especially formats typically used with Windows programs. +ImageMagick is probably the most used free image format converter and it +also handles lots of formats Netpbm does not. + + + +.IP \(bu +WebP was announced by Google in October 2010 as a more compressed +replacement for JFIF (aka JPEG) on the web. + +.IP \(bu +JPEG-LS is similar to JFIF (aka JPEG) except that it is capable of +representing all the information in any raster image, so you could convert +from, say, PNM, without losing any +information. +.UR http://charls.codeplex.com +CharLS +.UE +\& is a programming +library for JPEG-LS. + + +.IP \(bu +Lossless JPEG is a similarly lossless variation of JPEG. It predates +every other lossless JPEG variation, but had only brief interest. You can +find code for encoding and decoding Lossless JPEG +on +.UR https://github.com/thorfdbg/libjpeg +GitHub +.UE +\&. + +.IP \(bu +JPEG XR offers greater dynamic range, a wider range of colors, and more +efficient compression than JFIF (aka JPEG). Windows and Internet Explorer +understand this format, starting with Windows 7 and Internet Explorer 9, along +with many other programs. This format was previously known as Windows Media +Photo and HD Photo. + +.IP \(bu +Direct Draw Surface (DDS)is the de facto standard wrapper format for S3 +texture compression, as used in all modern realtime graphics applications. +Besides Windows-based tools, there is a \fBGimp\fP plugin for this format. + +.IP \(bu +DjVu is a web-centric format and software platform for +distributing documents and images. Promoters say it is a good +replacement for PDF, PS, TIFF, JFIF(JPEG), and GIF for distributing scanned +documents, digital documents, or high-resolution pictures, because it +downloads faster, displays and renders faster, looks nicer on a +screen, and consumes less client resources than competing formats. +.sp +For more information, see +.UR http://djvu.sourceforge.net/ + the DjVu website. +.UE +\& + +.IP \(bu + +.UR http://www.web3d.org/x3d/specifications/vrml +VRML (Virtual Reality Modelling Language) +.UE +\& + +.IP \(bu + +CALS (originated by US Department Of Defense, favored by architects). +It is described in this 1997 listing of graphics formats: +.UR http://www.faqs.org/faqs/graphics/fileformats-faq/part3/ + http://www.faqs.org/faqs/graphics/fileformats-faq/part3/ +.UE +\&. CALS +has at times been an abbreviation of various things, all of which appear +to be essentially the same format, but possibly slightly different: + + +.IP \(bu +Computer Aided Logistics Support +.IP \(bu +Computer Aided Acquisition and Logistics Support +.IP \(bu +Continuous Acquisition and Life-cycle Support +.IP \(bu +Commerce At Light Speed + + + +The US Navy publishes +.UR https://www.navsea.navy.mil/Home/Warfare-Centers/NSWC-Carderock/Resources/Technical-Information-Systems/IETMs/Specifications-Standards/CALS-Standards/ +specs +.UE +\& +for it. + +.IP \(bu + +array formats dx, general, netcdf, CDF, hdf, cm +.IP \(bu + +CGM+ + +.IP \(bu +HDR formats OpenEXR, SGI TIFF LogLuv, floating point TIFF, +Radiance RGBE + +.IP \(bu +Windows Meta File (.WMF). Libwmf converts from WMF to things like +Latex, PDF, PNG. Some of these can be input to Netpbm. + +.IP \(bu +Microsoft Word .doc format. Microsoft keeps a proprietary hold on +this format. Any software you see that can handle it is likely to +cost money. + +.IP \(bu +RTF + +.IP \(bu + +DXF (AutoCAD) +.IP \(bu + +IOCA (Image Object Content Architecture) +The specification of this format is documented by IBM: +.UR http://publibz.boulder.ibm.com/epubs/pdf/c3168055.pdf + Data Stream and Object Architectures: Image Object Content Architecture Reference +.UE +\&. See above for software that processes this format. + +.IP \(bu +OpenEXR is an HDR format (like +.BR "PFM" (1)\c +\&). +See +.UR http://www.openexr.com + http://www.openexr.com +.UE +\&. + +.IP \(bu +Xv Visual Schnauzer thumbnail image. This is a rather antiquated +format used by the Xv program. In Netpbm circles, it is best known +for the fact that it is very similar to Netpbm formats and uses the +same signature ("P7") as PAM because it was developed as +sort of a fork of the Netpbm format specifications. + +.IP \(bu +YUV 4:2:0, aka YUV 420, and the similar YUV 4:4:4, YUV 4:2:2, +YUV 4:1:1, YUV 4:1:1s, and YUV 4:1:0. Video systems often use this. + +.IP \(bu + +.UR http://en.wikipedia.org/wiki/MJPEG +MJPEG +.UE +\& movie +format. + +.IP \(bu +YUV4MPEG2 is a movie format whose purpose is similar to that of +the Netpbm formats for still images. You use it for manipulating +movies, but not for storing or transmitting them. The only known use +of the format is with +.UR http://mjpeg.sourceforge.net +\fBMJPEGTools\fP +.UE +\&. The programs +\fBpnmtoy4m\fP and \fBy4mtopnm\fP (and predecessors \fBppmtoy4m\fP +and \fBy4mtoppm\fP) in that package convert between a Netpbm stream +and a YUV4MPEG2 stream. As you might guess from the name, YUV4MPEG2 +uses a YUV representation of data, which is more convenient than the +Netpbm formats' RGB representation for working with data that is +ultimately MPEG2. + + + +.UN history +.SH History +.PP +Netpbm has a long history, starting with Jef Poskanzer's Pbmplus +package in 1988. See the +.BR "Netpbm web site" (1)\c +\& +for details. +.PP +The file \fBdoc/HISTORY\fP in the Netpbm source code contains a +detailed change history release by release. + + +.UN author +.SH Author +.PP +Netpbm is based on the Pbmplus package by Jef Poskanzer, first +distributed in 1988 and maintained by him until 1991. But the package +contains work by countless other authors, added since Jef's original +work. In fact, the name is derived from the fact that the work was +contributed by people all over the world via the Internet, when such +collaboration was still novel enough to merit naming the package after +it. +.PP +Bryan Henderson has been maintaining Netpbm since 1999. In +addition to packaging work by others, Bryan has also written a +significant amount of new material for the package. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/index.html +.PP
\ No newline at end of file |