{ "content": [ { "type": "text", "text": "# Netpbm (man)\n\n## NAME\n\nnetpbm - netpbm library overview\n\n## Sections\n\n- **NAME**\n- **Overview Of Netpbm**\n- **Table Of Contents**\n- **The Netpbm Programs** (6 subsections)\n- **The Netpbm Formats** (2 subsections)\n- **The Netpbm Library**\n- **Memory Usage**\n- **Companion Software** (1 subsections)\n- **Other Graphics Software** (8 subsections)\n- **Other Graphics Formats**\n- **History**\n- **Author**\n- **DOCUMENT SOURCE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Netpbm", "section": "", "mode": "man", "summary": "netpbm - netpbm library overview", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 3, "subsections": [] }, { "name": "Overview Of Netpbm", "lines": 12, "subsections": [] }, { "name": "Table Of Contents", "lines": 114, "subsections": [] }, { "name": "The Netpbm Programs", "lines": 15, "subsections": [ { "name": "Common Options", "lines": 9 }, { "name": "-quiet", "lines": 6 }, { "name": "-version", "lines": 7 }, { "name": "-plain", "lines": 12 }, { "name": "Directory", "lines": 6 }, { "name": "How To Use The Programs", "lines": 45 } ] }, { "name": "The Netpbm Formats", "lines": 51, "subsections": [ { "name": "Implied Format Conversion", "lines": 31 }, { "name": "Netpbm and Transparency", "lines": 26 } ] }, { "name": "The Netpbm Library", "lines": 37, "subsections": [] }, { "name": "Memory Usage", "lines": 122, "subsections": [] }, { "name": "Companion Software", "lines": 1, "subsections": [ { "name": "PHP-NetPBM", "lines": 10 } ] }, { "name": "Other Graphics Software", "lines": 4, "subsections": [ { "name": "Command Line Programs", "lines": 8 }, { "name": "Image Viewers", "lines": 28 }, { "name": "Image Capturers", "lines": 9 }, { "name": "Visual Graphics Software", "lines": 19 }, { "name": "Programming Tools", "lines": 25 }, { "name": "Tools For Specific Graphics Formats", "lines": 57 }, { "name": "Document/Graphics Software", "lines": 53 }, { "name": "Other", "lines": 25 } ] }, { "name": "Other Graphics Formats", "lines": 136, "subsections": [] }, { "name": "History", "lines": 8, "subsections": [] }, { "name": "Author", "lines": 9, "subsections": [] }, { "name": "DOCUMENT SOURCE", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "netpbm - netpbm library overview\n\n", "subsections": [] }, "Overview Of Netpbm": { "content": "Netpbm is a package of graphics programs and a programming library.\n\nThere are over 330 separate programs in the package, most of which have \"pbm\", \"pgm\", \"ppm\",\n\"pam\", or \"pnm\" in their names. For example, pamscale(1) and giftopnm(1).\n\nFor example, you might use pamscale to shrink an image by 10%. Or use pamcomp to overlay one\nimage on top of another. Or use pbmtext to create an image of text. Or reduce the number of\ncolors in an image with pnmquant.\n\nNetpbm is an open source software package, distributed via the \u001b]8;;http://sourceforge.net/projects/netpbm\u001b\\Sourceforge netpbm project\u001b]8;;\u001b\\ .\n\n", "subsections": [] }, "Table Of Contents": { "content": "•\n\n\u001b]8;;#overview\u001b\\Overview Of Netpbm\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#formats\u001b\\The Netpbm Formats\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#impconv\u001b\\Implied Format Conversion\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#transparency\u001b\\Netpbm and Transparency\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#programs\u001b\\The Netpbm Programs\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#commonoptions\u001b\\Common Options\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#directory\u001b\\Directory\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#prognotes\u001b\\How To Use The Programs\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#libnetpbm\u001b\\The Netpbm Library\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#config\u001b\\netpbm-config\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#memoryusage\u001b\\Memory Usage\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#cpuusage\u001b\\CPU Usage\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#netpbmforgimp\u001b\\Netpbm For Gimp\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#companion\u001b\\Companion Software\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#phpnetpbm\u001b\\PHP-NetPBM\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#othersoftware\u001b\\Other Graphics Software\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#viewers\u001b\\Image Viewers\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#capturers\u001b\\Image Capturers\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#visual\u001b\\Visual Graphics Software\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#programmingtools\u001b\\Programming Tools\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#toolsforformats\u001b\\Tools For Specific Graphics Formats\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#document\u001b\\Document/Graphics Software\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#otherothersoftware\u001b\\Other\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;#otherfmt\u001b\\Other Graphics Formats\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#history\u001b\\History\u001b]8;;\u001b\\\n\n•\n\n\u001b]8;;#author\u001b\\Author\u001b]8;;\u001b\\\n\n\n", "subsections": [] }, "The Netpbm Programs": { "content": "The Netpbm programs are generally useful run by a person from a command shell, but are also\ndesigned to be used by programs. A common characteristic of Netpbm programs is that they are\nsimple, fundamental building blocks. They are most powerful when stacked in pipelines.\nNetpbm programs do not use graphical user interfaces and do not seek input from a user. The\nonly programs that display graphics at all are the very primitive display programs pamx and\nppmsvgalib, and they don't do anything but that.\n\nEach of these programs has its own manual, as linked in the directory below.\n\nThe Netpbm programs can read and write files greater than 2 GiB wherever the underlying sys‐\ntem can. There may be exceptions where the programs use external libraries (The JPEG li‐\nbrary, etc.) to access files and the external library does not have large file capability.\nBefore Netpbm 10.15 (April 2003), no Netpbm program could read a file that large.\n\n", "subsections": [ { "name": "Common Options", "content": "There are a few options that are present on all programs that are based on the Netpbm li‐\nbrary, including virtually all Netpbm programs. These are not mentioned in the individual\nmanuals for the programs.\n\nYou can use two hyphens instead of one on these options if you like.\n\n\n\n" }, { "name": "-quiet", "content": "Suppress all informational messages that would otherwise be issued to Standard Error.\n(To be precise, this only works to the extent that the program in question implements\nthe Netpbm convention of issuing all informational messages via the pmmessage() ser‐\nvice of the Netpbm library).\n\n" }, { "name": "-version", "content": "Instead of doing anything else, report the version of the libnetpbm library linked\nwith the program (it may have been linked statically into the program, or dynamically\nlinked at run time). Normally, the Netpbm programs and the library are installed at\nthe same time, so this tells you the version of the program and all the other Netpbm\nfiles it uses as well.\n\n" }, { "name": "-plain", "content": "\"ascii\") version of the format, as opposed to the \"raw\" (aka \"binary\") version.\n\nNote that the other Netpbm format, PAM, does not have plain and raw versions, so this\noption has no effect on a program that generates PAM output.\n\nThis option was introduced in Netpbm 10.10 (October 2002). From Netpbm 10.32 (Febru‐\nary 2006) through Netpbm 10.62 (March 2013), the option is invalid with a program that\ngenerates PAM output (instead of ignoring the option, the program fails).\n\n\n\n" }, { "name": "Directory", "content": "Here is a complete list of all the Netpbm programs (with links to their manuals):\n\nNetpbm program directory(1)\n\n\n" }, { "name": "How To Use The Programs", "content": "As a collection of primitive tools, the power of Netpbm is multiplied by the power of all the\nother unix tools you can use with them. These notes remind you of some of the more useful\nways to do this. Often, when people want to add high level functions to the Netpbm tools,\nthey have overlooked some existing tool that, in combination with Netpbm, already does it.\n\nOften, you need to apply some conversion or edit to a whole bunch of files.\n\nAs a rule, Netpbm programs take one input file and produce one output file, usually on Stan‐\ndard Output. This is for flexibility, since you so often have to pipeline many tools to‐\ngether.\n\nHere is an example of a shell command to convert all your of PNG files (named *.png) to JPEG\nfiles named *.jpg:\nfor i in *.png; do pngtopam $i | ppmtojpeg >`basename $i .png`.jpg; done\n\n\nOr you might just generate a stream of individual shell commands, one per file, with awk or\nperl. Here's how to brighten 30 YUV images that make up one second of a movie, keeping the\nimages in the same files:\n\nls *.yuv\n| perl -ne 'chomp;\nprint yuvtoppm $ | pambrighten -value +100 | ppmtoyuv >tmp$$.yuv;\nmv tmp$$.yuv $\n'\n| sh\n\n\nThe tools find (with the -exec option) and xargs are also useful for simple manipulation of\ngroups of files.\n\nSome shells' \"process substitution\" facility can help where a non-Netpbm program expects you\nto identify a disk file for input and you want it to use the result of a Netpbm manipulation.\nSay the hypothetical program printcmyk takes the filename of a Tiff CMYK file as input and\nwhat you have is a PNG file abc.png.\n\nTry:\nprintcmyk <({ pngtopam abc.png | pnmtotiffcmyk ; })\n\n\nIt works in the other direction too, if you have a program that makes you name its output\nfile and you want the output to go through a Netpbm tool.\n\n\n" } ] }, "The Netpbm Formats": { "content": "All of the programs work with a set of graphics formats called the \"netpbm\" formats. Specif‐\nically, these formats are pbm(1), pgm(1), ppm(1), and pam(1).\n\nThe first three of these are sometimes known generically as \"pnm\".\n\nMany of the Netpbm programs convert from a Netpbm format to another format or vice versa.\nThis is so you can use the Netpbm programs to work on graphics of any format. It is also\ncommon to use a combination of Netpbm programs to convert from one non-Netpbm format to an‐\nother non-Netpbm format. Netpbm has converters for about 100 graphics formats, and as a\npackage Netpbm lets you do more graphics format conversions than any other computer graphics\nfacility.\n\nThe Netpbm formats are all raster formats, i.e. they describe an image as a matrix of rows\nand columns of pixels. In the PBM format, the pixels are black and white. In the PGM for‐\nmat, pixels are shades of gray. In the PPM format, the pixels are in full color. The PAM\nformat is more sophisticated. A replacement for all three of the other formats, it can rep‐\nresent matrices of general data including but not limited to black and white, grayscale, and\ncolor images.\n\nPrograms designed to work with PBM images have \"pbm\" in their names. Programs designed to\nwork with PGM, PPM, and PAM images similarly have \"pgm\", \"ppm\", and \"pam\" in their names.\n\nAll Netpbm programs designed to read PGM images see PBM images as if they were PGM too. All\nNetpbm programs designed to read PPM images see PGM and PBM images as if they were PPM. See\n\u001b]8;;#impconv\u001b\\ Implied Format Conversion\u001b]8;;\u001b\\ .\n\nPrograms that have \"pnm\" in their names read PBM, PGM, and PPM but unlike \"ppm\" programs,\nthey distinguish between those formats and their function depends on the format. For exam‐\nple, pnmtopng(1) creates a black and white PNG output image if its input is PBM or PGM, but a\ncolor PNG output image if its input is PPM. And pnmrotate produces an output image of the\nsame format as the input. A hypothetical ppmrotate program would also read all three PNM in‐\nput formats, but would see them all as PPM and would always generate PPM output.\n\nPrograms that have \"pam\" in their names read all the Netpbm formats: PBM, PGM, PPM, and PAM.\nThey sometimes treat them all as if they are PAM, using an implied conversion, but often they\nrecognize the individual formats and behave accordingly, like a \"pnm\" program does. See \u001b]8;;#impconv\u001b\\Im‐\nplied Format Conversion\u001b]8;;\u001b\\ .\n\nFinally, there are subformats of PAM that are equivalent to PBM, PGM, and PPM respectively,\nand Netpbm programs designed to read PBM, PGM, and/or PPM see those PAM images as if they\nwere the former. For example, ppmhist can analyze a PAM image of tuple type RGB (i.e. a\ncolor image) as if it were PPM.\n\nIf it seems wasteful to you to have three separate PNM formats, be aware that there is a\nhistorical reason for it. In the beginning, there were only PBMs. PGMs came later, and then\nPPMs. Much later came PAM, which realizes the possibility of having just one aggregate for‐\nmat.\n\nThe formats are described in the specifications of pbm(1), pgm(1), ppm(1), and pam(1).\n\n", "subsections": [ { "name": "Implied Format Conversion", "content": "A program that uses the PGM library subroutines to read an image can read a PBM image as well\nas a PGM image. The program sees the PBM image as if it were the equivalent PGM image, with\na maxval of 255. note: This sometimes confuses people who are looking at the formats at a\nlower layer than they ought to be because a zero value in a PBM raster means white, while a\nzero value in a PGM raster means black.\n\nA program that uses the PPM library subroutines to read an image can read a PGM image as well\nas a PPM image and a PBM image as well as a PGM image. The program sees the PBM or PGM image\nas if it were the equivalent PPM image, with a maxval of 255 in the PBM case and the same\nmaxval as the PGM in the PGM case.\n\nA program that uses the PAM library subroutines to read an image can read a PBM, PGM, or PPM\nimage as well as a PAM image. The program sees a PBM image as if it were the equivalent PAM\nimage with tuple type BLACKANDWHITE. It sees a PGM image as if it were the equivalent PAM\nimage with tuple type GRAYSCALE. It sees a PPM image as if it were the equivalent PAM image\nwith tuple type RGB. But the program actually can see deeper if it wants to. It can tell\nexactly which format the input was and may respond accordingly. For example, a PAM program\ntypically produces output in the same format as its input.\n\nA program that uses the PGM library subroutines to read an image can read a PAM image as well\na PGM image, if the PAM is a grayscale or black and white visual image. That canonically\nmeans the PAM has a depth of 1 and a tuple type of GRAYSCALE or BLACKANDWHITE, but most\nNetpbm programs are fairly liberal and will take any PAM at all, ignoring all but the first\nplane.\n\nThere is a similar implied conversion for PPM library subroutines reading PAM. There is\nnothing similar for PBM, so if you need for a PBM program to read a PAM image, run it through\npamtopnm.\n\n\n" }, { "name": "Netpbm and Transparency", "content": "In many graphics formats, there's a means of indicating that certain parts of the image are\nwholly or partially transparent, meaning that if it were displayed \"over\" another image, the\nother image would show through there. Netpbm formats deliberately omit that capability,\nsince their purpose is to be extremely simple.\n\nIn Netpbm, you handle transparency via a transparency mask in a separate (slightly redefined)\nPGM image. In this pseudo-PGM, what would normally be a pixel's intensity is instead an\nopaqueness value. See pgm(1). pamcomp(1) is an example of a program that uses a PGM trans‐\nparency mask.\n\nAnother means of representing transparency information has recently developed in Netpbm, us‐\ning PAM images. In spite of the argument given above that Netpbm formats should be too sim‐\nple to have transparency information built in, it turns out to be extremely inconvenient to\nhave to carry the transparency information around separately. This is primarily because Unix\nshells don't provide easy ways to have networks of pipelines. You get one input and one out‐\nput from each program in a pipeline. So you'd like to have both the color information and\nthe transparency information for an image in the same pipe at the same time.\n\nFor that reason, some new (and recently renovated) Netpbm programs recognize and generate a\nPAM image with tuple type RGBALPHA or GRAYSCALEALPHA, which contains a plane for the trans‐\nparency information. See the PAM specification(1).\n\n\n\n\n" } ] }, "The Netpbm Library": { "content": "The Netpbm programming library, libnetpbm(1), makes it easy to write programs that manipulate\ngraphic images. Its main function is to read and write files in the Netpbm formats, and be‐\ncause the Netpbm package contains converters for all the popular graphics formats, if your\nprogram reads and writes the Netpbm formats, you can use it with any formats.\n\nBut the library also contain some utility functions, such as character drawing and RGB/YCrCb\nconversion.\n\nThe library has the conventional C linkage. Virtually all programs in the Netpbm package are\nbased on the Netpbm library.\n\n\n\nnetpbm-config\nIn a standard installation of Netpbm, there is a program named netpbm-config in the regular\nprogram search path. We don't consider this a Netpbm program -- it's just an ancillary part\nof a Netpbm installation. This program tells you information about the Netpbm installation,\nand is intended to be run by other programs that interface with Netpbm. In fact, netpbm-con‐\nfig is really a configuration file, like those you typically see in the /etc/ directory of a\nUnix system.\n\nExample:\n$netpbm-config --datadir\n/usr/local/netpbm/data\n\n\nIf you write a program that needs to access a Netpbm data file, it can use such a shell com‐\nmand to find out where the Netpbm data files are.\n\nnetpbm-config is the only file that must be installed in a standard directory (it must be in\na directory that is in the default program search path). You can use netpbm-config as a\nbootstrap to find all the other Netpbm files.\n\nThere is no detailed documentation of netpbm-config. If you're in a position to use it, you\nshould have no trouble reading the file itself to figure out how to use it.\n\n", "subsections": [] }, "Memory Usage": { "content": "An important characteristic that varies among graphics software is how much memory it uses,\nand how. Does it read an entire image into memory, work on it there, then write it out all\nat once? Does it read one and write one pixel at a time? In Netpbm, it differs from one\nprogram to the next, but there are some generalizations we can make.\n\nMost Netpbm programs keep one row of pixels at a time in memory. Such a program reads a row\nfrom an input file, processes it, then writes a row to an output file. Some programs execute\nalgorithms that can't work like that, so they keep a small window of rows in memory. Others\nmust keep the entire image in memory. If you think of what job the program does, you can\nprobably guess which one it does.\n\nWhen Netpbm keeps a pixel in memory, it normally uses a lot more space for it than it occu‐\npies in the Netpbm image file format.\n\nThe older programs (most of Netpbm) use 12 bytes per pixel. This is true even for a PBM im‐\nage, for which it only really takes one bit to totally describe the pixel. Netpbm does this\nexpansion to make implementing the programs easier -- it uses the same format regardless of\nthe type of image.\n\nNewer programs use the \"pam\" family of library functions internally, which use memory a lit‐\ntle differently. These functions are designed to handle generic tuples with a variable num‐\nbers of planes, so no fixed size per-tuple storage is possible. A program of this type uses\n4 bytes per sample (a tuple is composed of samples), plus a pointer (4-8 bytes) per tuple.\nIn a graphic image, a tuple is a pixel. So an ordinary color image takes 16-20 bytes per\npixel.\n\nWhen considering memory usage, it is important to remember that memory and disk storage are\nequivalent in two ways:\n\n\n\n• Memory is often virtual, backed by swap space on disk storage. So accessing memory\nmay mean doing disk I/O.\n\n\n• Files are usually cached and buffered, so that accessing a disk file may just mean ac‐\ncessing memory.\n\n\nThis means that the consequences of whether a program works from the image file or from a\nmemory copy are not straightforward.\n\nNote that an image takes a lot less space in a Netpbm format file, and therefore in an oper‐\nating system's file cache, than in Netpbm's in-memory format. In non-Netpbm image formats,\nthe data is even smaller. So reading through an input file multiple times instead of keeping\na copy in regular memory can be the best use of memory, and many Netpbm programs do that.\nBut some files can't be read multiple times. In particular, you can't rewind and re-read a\npipe, and a pipe is often the input for a Netpbm program. Netpbm programs that re-read files\ndetect such input files and read them into a temporary file, then read that temporary file\nmultiple times.\n\nA few Netpbm programs use an in-memory format that is just one bit per pixel. These are pro‐\ngrams that convert between PBM and a format that has a raster format very much like PBM's.\nIn this case, it would actually make the program more complicated (in addition to much\nslower) to use Netpbm's generic 12 byte or 8 byte pixel representation.\n\nBy the way, the old axiom that memory is way faster than disk is not necessarily true. On\nsmall systems, it typically is true, but on a system with a large network of disks, espe‐\ncially with striping, it is quite easy for the disk storage to be capable of supplying data\nfaster than the CPU can use it.\n\n\nCPU Usage\nPeople sometimes wonder what CPU facilities Netpbm programs and the Netpbm programming li‐\nbrary use. The programs never depend on particular features existing (assuming they're com‐\npiled properly), but the speed and cost of running a program varies depending upon the CPU\nfeatures.\n\nNote that when you download a binary that someone else compiled, even though it appears to be\ncompiled properly for your machine, it may be compiled improperly for that machine if it is\nold, because the person who compiled it may have chosen to exploit features of newer CPUs in\nthe line. For example, an x86 program may be compiled to use instructions that are present\non an 80486, but not on an 80386. You would probably not know this until you run the program\nand it crashes.\n\nBut the default build options almost always build binaries that are as backward compatible\nwith old CPUs as possible. An exception is a build for a 64 bit x86 CPU. While the builder\ncould build a program that runs on a 32 bit x86, it does not do so by default. A default\nbuild builds a program will not run on an older 32-bit-only x86 CPU.\n\nOne common build option is to use MMX/SSE operands with x86 CPUs. Those are not available on\nolder x86 CPUs. The builder by default does not generate code that uses MMX/SSE when build‐\ning for 32 bit x86 CPUs, but does when building for 64 bit x86.\n\nOne area of particular importance is floating point arithmetic. The Netpbm image formats are\nbased on integers, and Netpbm arithmetic is done with integers where possible. But there is\none significant area that is floating point: programs that must deal with light intensity.\nThe Netpbm formats use integers that are proportional to brightness, and brightness is expo‐\nnentially related to light intensity. The programs have to keep the intermediate intensity\nvalues in floating point in order not to lose precision. And the conversion (gamma function)\nbetween the two is heavy-duty floating point arithmetic.\n\nPrograms that mix pixels together have to combine light intensity, so they do heavy floating\npoint. Three of the most popular Netpbm programs do that: pamscale(1) (shrink/expand an im‐\nage), pamcomp(1) (overlay an image over another one), and pamditherbw(1) (Make a black and\nwhite image that approximates a grayscale image).\n\nThe Netpbm image formats use 16 bit integers. The Netpbm code uses \"unsigned int\" size inte‐\ngers to work with them.\n\n\n\nNetpbm For Gimp\nThe Gimp is a visual image editor for Unix and X, so it does the kinds of things that Netpbm\ndoes, but interactively in a user-friendly way. The Gimp knows a variety of graphics file\nformats and image transformations, but you can extend it with plugins.\n\nA particularly easy way to write a Gimp plugin is to write a Netpbm program (remember that a\nfundamental mission of Netpbm is make writing image manipulation programs easy) and then use\n\u001b]8;;http://netpbm2gimp.sourceforge.net/\u001b\\netpbm2gimp\u001b]8;;\u001b\\ to compile that same source code into a Gimp plugin.\n\nYou can turn a program that converts from a certain graphics file format to Netpbm format\ninto a Gimp load plugin. Likewise, you can turn a program that converts to a certain graph‐\nics format from Netpbm format into a Gimp store plugin. Finally, a program that transforms\nimages in Netpbm format can become a process plugin.\n\nAnd the netpbm2gimp project has already packaged for you a few hundred of the Netpbm programs\nas Gimp plugins. With this package you can, for example, edit an image in any of the arcane\ngraphics file formats that Netpbm understands but no other image editor in existence does.\n\n\n", "subsections": [] }, "Companion Software": { "content": "", "subsections": [ { "name": "PHP-NetPBM", "content": "If you're using Netpbm to do graphics for a website, you can invoke the Netpbm programs from\na PHP script. To make this even easier, check out \u001b]8;;http://sourceforge.net/projects/phpnetpbm\u001b\\PHP-NetPBM\u001b]8;;\u001b\\ , a PHP class that interacts\nwith Netpbm. Its main goal is to decrease the pain of using Netpbm when working with images\nin various formats. It includes macro commands to perform manipulations on many files.\n\nI can't actually recommend PHP-NetPBM. I spent some time staring at it and was unable to\nmake sense of it. Some documentation is in fractured English and other is in an unusual\ncharacter set. But a PHP expert might be able to figure it out and get some use out of it.\n\n" } ] }, "Other Graphics Software": { "content": "Netpbm contains primitive building blocks. It certainly is not a complete graphics software\nlibrary.\n\n", "subsections": [ { "name": "Command Line Programs", "content": "ImageMagick does many of the same things - mainly the more popular ones - that Netpbm does,\nincluding conversion between popular formats and basic editing. convert, mogrify, montage,\nand animate are popular programs from the ImageMagick package. ImageMagick runs on Unix,\nWindows, Windows NT, Macintosh, and VMS.\n\nImageMagick also contains the program display, which is a \u001b]8;;#viewers\u001b\\viewer\u001b]8;;\u001b\\ and \u001b]8;;#visual\u001b\\visual editor\u001b]8;;\u001b\\ .\n\n" }, { "name": "Image Viewers", "content": "The first thing you will want to make use of any of these tools is a viewer. (On GNU/Linux,\nyou can use Netpbm's pamx or ppmsvgalib in a pinch, but it is pretty limiting). zgv is a\ngood full service viewer to use on a GNU/Linux system with the SVGALIB graphics display dri‐\nver library. You can find zgv at \u001b]8;;ftp://ftp.ibiblio.org/pub/Linux/apps/graphics/viewers/svga\u001b\\ftp://ftp.ibiblio.org/pub/Linux/apps/graphics/viewers/svga\u001b]8;;\u001b\\\n.\n\nzgv even has a feature in it wherein you can visually crop an image and write an output file\nof the cropped image using pamcut(1).\n\nSee the -s option to zgv.\n\nFor the X inclined, there is also xzgv.\n\nxwud (X Window Undump) is a classic application program in the X Window System that displays\nan image in an X window. It takes the special X Window Dump format as input; you can use\nNetpbm's pnmtoxwd(1) to create it. You're probably better off just using Netpbm's pamx(1).\n\nxloadimage and its extension xli are also common ways to display a graphic image in X.\n\ngqview is a more modern X-based image viewer.\n\nqiv is a small, very fast viewer for X.\n\nTo play mpeg movies, such as produced by ppmtompeg, try mplayer(1) or \u001b]8;;http://sourceforge.net/projects/xine\u001b\\xine\u001b]8;;\u001b\\ .\n\nSee \u001b]8;;ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers/X\u001b\\ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers/X\u001b]8;;\u001b\\ .\n\n" }, { "name": "Image Capturers", "content": "xwd (X Window Dump), a classic application program in the X Window System, captures the con‐\ntents of an X window, in its own special image format, called X Window Dump File. You can\nuse Netpbm's xwdtopnm(1) to turn it into something more useful.\n\n\u001b]8;;http://www.rcdrummond.net/fbdump/\u001b\\fbdump\u001b]8;;\u001b\\ Capturers the current contents of a video display on the local computer and generates\na PPM image of it. It works with Linux framebuffer devices.\n\n\n" }, { "name": "Visual Graphics Software", "content": "Visual graphics software is modern point-and-click software that displays an image and lets\nyou work on it and see the results as you go. This is fundamentally different from what\nNetpbm programs do.\n\nxv is a very old and very popular simple image editor in the Unix world. It does not have\nmuch in the way of current support, or maintenance, though.\n\nGimp is a visual image editor for Unix and the X Window System, in the same category as the\nmore famous, less capable, and much more expensive Adobe Photoshop, etc. for Windows. See\n\u001b]8;;http://www.gimp.org\u001b\\http://www.gimp.org\u001b]8;;\u001b\\ . And you can add most of Netpbm's function to Gimp using \u001b]8;;http://netpbm2gimp.sourceforge.net/\u001b\\Netpbm2gimp\u001b]8;;\u001b\\ .\n\nImageMagick contains the program display, which is another visual image editor. It has fewer\nfunctions than Gimp. This program uses the X Window System. The package also contains \u001b]8;;#othercmdline\u001b\\com‐\nmand line\u001b]8;;\u001b\\ graphics programs.\n\nElectric Eyes, kuickshow, and gthumb are also visual editors for the X/Window system, and\nKView and gwenview are specifically for KDE.\n\n" }, { "name": "Programming Tools", "content": "If you're writing a program in C to draw and manipulate images, check out \u001b]8;;https://github.com/libgd/libgd\u001b\\gd\u001b]8;;\u001b\\ . Netpbm con‐\ntains a C library for drawing images (libnetpbm's \"ppmd\" routines), but it is not as capable\nor documented as gd. There are wrapper libraries available for Perl, PHP, and other lan‐\nguage.\n\nYou can easily run any Netpbm program from a C program with the pmsystem function from the\nNetpbm programming library, but that is less efficient than gd functions that do the same\nthing.\n\n\u001b]8;;http://cairographics.org/\u001b\\Cairo\u001b]8;;\u001b\\ is similar.\n\nIlib is a C subroutine library with functions for adding text to an image (as you might do at\na higher level with pbmtext, pamcomp, etc.). It works with Netpbm input and output. Find it\nat \u001b]8;;http://www.k5n.us/Ilib.php\u001b\\k5n.us\u001b]8;;\u001b\\ . Netpbm also includes character drawing functions in the libnetpbm(1) library,\nbut they do not have as fancy font capabilities (see ppmdraw(1) for an example of use of the\nNetpbm character drawing functions).\n\n\u001b]8;;http://www.pango.org/\u001b\\Pango\u001b]8;;\u001b\\ is another text rendering library, with an emphasis on internationalization.\n\nPango and Cairo complement each other and work well together.\n\nGD is a library of graphics routines that is part of PHP. It has a subset of Netpbm's func‐\ntions and has been found to resize images more slowly and with less quality.\n\n" }, { "name": "Tools For Specific Graphics Formats", "content": "mencode, which is part of the mplayer(1) package, creates movie files. It's like a much more\nadvanced version of ppmtompeg(1), without the Netpbm building block simplicity.\n\n\u001b]8;;http://mjpeg.sourceforge.net\u001b\\MJPEGTools\u001b]8;;\u001b\\ is software for dealing with the MJPEG movie format.\n\nTo create an animated GIF, or extract a frame from one, use gifsicle. gifsicle converts be‐\ntween animated GIF and still GIF, and you can use pamtogif and giftopnm to connect up to all\nthe Netpbm utilities. See \u001b]8;;http://www.lcdf.org/gifsicle\u001b\\http://www.lcdf.org/gifsicle\u001b]8;;\u001b\\ .\n\nTo convert an image of text to text (optical character recognition - OCR), use gocr (think of\nit as an inverse of pbmtext). See \u001b]8;;http://jocr.sourceforge.net/\u001b\\http://jocr.sourceforge.net/\u001b]8;;\u001b\\ .\n\n\u001b]8;;http://schaik.com/pngsuite\u001b\\http://schaik.com/pngsuite\u001b]8;;\u001b\\ contains a PNG test suite -- a whole bunch of PNG images ex‐\nploiting the various features of the PNG format.\n\nOther versions of Netpbm's pnmtopng/pngtopam are at http://www.schaik.com/png/pnmtopng.html\"\n(1).\n\nThe version in Netpbm was actually based on that package a long time ago, and you can expect\nto find better exploitation of the PNG format, especially recent enhancements, in that pack‐\nage. It may be a little less consistent with the Netpbm project and less exploitive of re‐\ncent Netpbm format enhancements, though.\n\n\u001b]8;;http://pngwriter.sourceforge.net\u001b\\pngwriter\u001b]8;;\u001b\\ is a C++ library for creating PNG images. With it, you plot an image pixel by\npixel. You can also render text with the FreeType2 library.\n\njpegtran Does some of the same transformations as Netpbm is famous for, but does them specif‐\nically on JPEG files and does them without loss of information. By contrast, if you were to\nuse Netpbm, you would first decompress the JPEG image to Netpbm format, then transform the\nimage, then compress it back to JPEG format. In that recompression, you lose a little image\ninformation because JPEG is a lossy compression. Of course, only a few kinds of lossless\ntransformation are possible. jpegtran comes with the Independent JPEG Group's (\n\u001b]8;;http://www.ijg.org\u001b\\http://www.ijg.org)\u001b]8;;\u001b\\ JPEG library.\n\nSome tools to deal with EXIF files (see also Netpbm's jpegtopnm(1) and pnmtojpeg(1)):\n\nTo dump (interpret) an EXIF header: Exifdump (( \u001b]8;;http://www.math.u-psud.fr/~bousch/exifdump.py\u001b\\http://www.math.u-psud.fr/~bousch/exif‐\ndump.py)\u001b]8;;\u001b\\ ) or \u001b]8;;http://www.sentex.net/~mwandel/jhead\u001b\\Jhead\u001b]8;;\u001b\\ .\n\nA Python EXIF library and dumper: \u001b]8;;http://pyexif.sourceforge.net.\u001b\\http://pyexif.sourceforge.net.\u001b]8;;\u001b\\\n\nHere's some software to work with IOCA (Image Object Content Architecture): \u001b]8;;http://www.forminnovation.com\u001b\\ImageToolbox\u001b]8;;\u001b\\\n($2500, demo available). This can convert from TIFF -> IOCA and back again.\n\n\u001b]8;;https://ameri-imager.software.informer.com/\u001b\\Ameri-Imager\u001b]8;;\u001b\\ is an image and video editor. ($40 Windows only).\n\npnm2ppa converts to HP's \"Winprinter\" format (for HP 710, 720, 820, 1000, etc). It is a su‐\nperset of Netpbm's pbmtoppa and handles, notably, color. However, it is more of a printer\ndriver than a Netpbm-style primitive graphics building block. See \u001b]8;;http://sourceforge.net/projects/pnm2ppa\u001b\\The Pnm2ppa /Sourceforge\nProject\u001b]8;;\u001b\\\n\nDjVuLibre is a package of software for using the DjVu format. It includes viewers, browser\nplugins, decoders, simple encoders, and utilities. The encoders and decoders can convert be‐\ntween DjVu and PNM. See \u001b]8;;http://djvu.sourceforge.net/\u001b\\ the DjVu website.\u001b]8;;\u001b\\\n\n\n" }, { "name": "Document/Graphics Software", "content": "There is a large class of software that does document processing, and that is somewhat re‐\nlated to graphics because documents contain graphics and a page of a document is for many\npurposes a graphic image. Because of this slight intersection with graphics, I cover docu‐\nment processing software here briefly, but it is for the most part beyond the scope of this\ndocument.\n\nFirst, we look at where Netpbm meets document processing. pstopnm converts from Postscript\nand PDF to PNM. It effectively renders the document into images of printed pages. pstopnm\nis nothing but a convenient wrapper for \u001b]8;;http://www.ghostscript.com/\u001b\\Ghostscript\u001b]8;;\u001b\\ , and in particular Netpbm-format device\ndrivers that are part of it. pnmtops and pbmtoepsi convert a PNM image to a Postscript pro‐\ngram for printing the image. But to really use PDF and Postscript files, you generally need\nmore complex document processing software.\n\nAdobe invented Postscript and PDF and products from Adobe are for many purposes the quintes‐\nsential Postscript and PDF tools.\n\nAdobe's free Acrobat Reader displays PDF and converts to Postscript. The Acrobat Reader for\nunix has a program name of \"acroread\" and the -toPostScript option (also see the -level2 op‐\ntion) is useful.\n\nOther software from Adobe, available for purchase, interprets and creates Postscript and PDF\nfiles. \"Distill\" is a program that converts Postscript to PDF.\n\n\u001b]8;;http://www.foolabs.com/xpdf/\u001b\\xpdf\u001b]8;;\u001b\\ also reads PDF files.\n\nGSview, ghostview, gv, ggv, and kghostview are some other viewers for Postscript and PDF\nfiles.\n\nThe program ps2pdf, part of Ghostscript, converts from Postscript to PDF.\n\nbmpp(1) converts from Netpbm and other formats to PDF.\n\n\nTwo packages that produce more kinds of Encapsulated Postscript than the Netpbm programs, in‐\ncluding compressed kinds, are bmpp(1) and \u001b]8;;http://imgtops.sourceforge.net/\u001b\\imgtops\u001b]8;;\u001b\\ .\n\ndvips converts from DVI format to Postscript. DVI is the format that Tex produces. Netpbm\ncan convert from Postscript to PNM. Thus, you can use these in combination to work with\nTex/Latex documents graphically.\n\n\u001b]8;;http://wvware.sourceforge.net\u001b\\wvware\u001b]8;;\u001b\\ converts a Microsoft Word document (.doc file) to various other formats. While the\nweb page doesn't seem to mention it, it reportedly can extract an embedded image in a Word\ndocument as a PNG.\n\n\u001b]8;;http://www.verypdf.com/artprint\u001b\\Document Printer\u001b]8;;\u001b\\ converts various print document formats (Microsoft Word, PDF, HTML, etc.)\nto various graphic image formats. ($38, Windows only).\n\nLatex2html converts Latex document source to HTML document source. Part of that involves\ngraphics, and Latex2html uses Netpbm tools for some of that. But Latex2html through its his‐\ntory has had some rather esoteric codependencies with Netpbm. Older Latex2html doesn't work\nwith current Netpbm. Latex2html-99.2beta8 works, though.\n\n" }, { "name": "Other", "content": "The file program looks at a file and tells you what kind of file it is. It recognizes most\nof the graphics formats with which Netpbm deals, so it is pretty handy for graphics work.\nNetpbm's anytopnm(1) program depends on file. See \u001b]8;;ftp://ftp.astron.com/pub/file\u001b\\ftp://ftp.astron.com/pub/file\u001b]8;;\u001b\\ .\n\nThe Utah Raster Toolkit from the Geometric Design And Computation group in the Department of\nComputer Science at University of Utah serves a lot of the same purpose as Netpbm, but with‐\nout the emphasis on format conversions. This package is based on the RLE format, which you\ncan convert to and from the Netpbm formats.\n\nIvtools is a suite of free X Window System drawing editors for Postscript, Tex, and web\ngraphics production, as well as an embeddable and extendable vector graphic shell. It uses\nthe Netpbm facilities. See \u001b]8;;http://www.ivtools.org\u001b\\http://www.ivtools.org\u001b]8;;\u001b\\ .\n\nChisato Yamauchi has written a free c/Fortran graphic library:\n\u001b]8;;http://www.ir.isas.jaxa.jp/~cyamauch/eggxprocall/\u001b\\EGGX/ProCall\u001b]8;;\u001b\\ . He says he tried to write the ultimate easy-to-use graphic kit for X. It is\nfor drawing upon an X11 window, but for storage, it outputs PPM. He suggests Netpbm to con‐\nvert to other formats.\n\nThe program morph morphs one image into another. It uses Targa format images, but you can\nuse tgatoppm and ppmtotga to deal with that format. You have to use the graphical (X/Tk)\nXmorph to create the mesh files that you must feed to morph. morph is part of the Xmorph\npackage. See \u001b]8;;http://xmorph.sourceforge.net/\u001b\\http://xmorph.sourceforge.net/\u001b]8;;\u001b\\ .\n\n\n" } ] }, "Other Graphics Formats": { "content": "People never seem to tire of inventing new graphics formats, often completely redundant with\npre-existing ones. Netpbm cannot keep up with them. Here is a list of a few that we know\nNetpbm does not handle (yet).\n\nVarious commercial Windows software handles dozens of formats that Netpbm does not, espe‐\ncially formats typically used with Windows programs. ImageMagick is probably the most used\nfree image format converter and it also handles lots of formats Netpbm does not.\n\n\n\n\n• WebP was announced by Google in October 2010 as a more compressed replacement for JFIF\n(aka JPEG) on the web.\n\n\n• JPEG-LS is similar to JFIF (aka JPEG) except that it is capable of representing all\nthe information in any raster image, so you could convert from, say, PNM, without los‐\ning any information. CharLS is a programming library for JPEG-LS.\n\n\n\n• Lossless JPEG is a similarly lossless variation of JPEG. It predates every other\nlossless JPEG variation, but had only brief interest. You can find code for encoding\nand decoding Lossless JPEG on \u001b]8;;https://github.com/thorfdbg/libjpeg\u001b\\GitHub\u001b]8;;\u001b\\ .\n\n\n• JPEG XR offers greater dynamic range, a wider range of colors, and more efficient com‐\npression than JFIF (aka JPEG). Windows and Internet Explorer understand this format,\nstarting with Windows 7 and Internet Explorer 9, along with many other programs. This\nformat was previously known as Windows Media Photo and HD Photo.\n\n\n• Direct Draw Surface (DDS)is the de facto standard wrapper format for S3 texture com‐\npression, as used in all modern realtime graphics applications. Besides Windows-based\ntools, there is a Gimp plugin for this format.\n\n\n• DjVu is a web-centric format and software platform for distributing documents and im‐\nages. Promoters say it is a good replacement for PDF, PS, TIFF, JFIF(JPEG), and GIF\nfor distributing scanned documents, digital documents, or high-resolution pictures,\nbecause it downloads faster, displays and renders faster, looks nicer on a screen, and\nconsumes less client resources than competing formats.\n\nFor more information, see \u001b]8;;http://djvu.sourceforge.net/\u001b\\ the DjVu website.\u001b]8;;\u001b\\\n\n\n•\n\n\u001b]8;;http://www.web3d.org/x3d/specifications/vrml\u001b\\VRML (Virtual Reality Modelling Language)\u001b]8;;\u001b\\\n\n\n•\n\nCALS (originated by US Department Of Defense, favored by architects). It is described\nin this 1997 listing of graphics formats: \u001b]8;;http://www.faqs.org/faqs/graphics/fileformats-faq/part3/\u001b\\ http://www.faqs.org/faqs/graphics/filefor‐\nmats-faq/part3/\u001b]8;;\u001b\\ . CALS has at times been an abbreviation of various things, all of\nwhich appear to be essentially the same format, but possibly slightly different:\n\n\n\n• Computer Aided Logistics Support\n\n• Computer Aided Acquisition and Logistics Support\n\n• Continuous Acquisition and Life-cycle Support\n\n• Commerce At Light Speed\n\n\n\nThe US Navy publishes \u001b]8;;https://www.navsea.navy.mil/Home/Warfare-Centers/NSWC-Carderock/Resources/Technical-Information-Systems/IETMs/Specifications-Standards/CALS-Standards/\u001b\\specs\u001b]8;;\u001b\\ for it.\n\n\n•\n\narray formats dx, general, netcdf, CDF, hdf, cm\n\n•\n\nCGM+\n\n\n• HDR formats OpenEXR, SGI TIFF LogLuv, floating point TIFF, Radiance RGBE\n\n\n• Windows Meta File (.WMF). Libwmf converts from WMF to things like Latex, PDF, PNG.\nSome of these can be input to Netpbm.\n\n\n• Microsoft Word .doc format. Microsoft keeps a proprietary hold on this format. Any\nsoftware you see that can handle it is likely to cost money.\n\n\n• RTF\n\n\n•\n\nDXF (AutoCAD)\n\n•\n\nIOCA (Image Object Content Architecture) The specification of this format is docu‐\nmented by IBM: \u001b]8;;http://publibz.boulder.ibm.com/epubs/pdf/c3168055.pdf\u001b\\ Data Stream and Object Architectures: Image Object Content Architec‐\nture Reference\u001b]8;;\u001b\\ . See above for software that processes this format.\n\n\n• OpenEXR is an HDR format (like PFM(1)). See \u001b]8;;http://www.openexr.com\u001b\\ http://www.openexr.com\u001b]8;;\u001b\\ .\n\n\n• Xv Visual Schnauzer thumbnail image. This is a rather antiquated format used by the\nXv program. In Netpbm circles, it is best known for the fact that it is very similar\nto Netpbm formats and uses the same signature (\"P7\") as PAM because it was developed\nas sort of a fork of the Netpbm format specifications.\n\n\n• 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,\nand YUV 4:1:0. Video systems often use this.\n\n\n•\n\n\u001b]8;;http://en.wikipedia.org/wiki/MJPEG\u001b\\MJPEG\u001b]8;;\u001b\\ movie format.\n\n\n• YUV4MPEG2 is a movie format whose purpose is similar to that of the Netpbm formats for\nstill images. You use it for manipulating movies, but not for storing or transmitting\nthem. The only known use of the format is with \u001b]8;;http://mjpeg.sourceforge.net\u001b\\MJPEGTools\u001b]8;;\u001b\\ . The programs pnmtoy4m\nand y4mtopnm (and predecessors ppmtoy4m and y4mtoppm) in that package convert between\na Netpbm stream and a YUV4MPEG2 stream. As you might guess from the name, YUV4MPEG2\nuses a YUV representation of data, which is more convenient than the Netpbm formats'\nRGB representation for working with data that is ultimately MPEG2.\n\n\n\n", "subsections": [] }, "History": { "content": "Netpbm has a long history, starting with Jef Poskanzer's Pbmplus package in 1988. See the\nNetpbm web site(1) for details.\n\nThe file doc/HISTORY in the Netpbm source code contains a detailed change history release by\nrelease.\n\n\n", "subsections": [] }, "Author": { "content": "Netpbm is based on the Pbmplus package by Jef Poskanzer, first distributed in 1988 and main‐\ntained by him until 1991. But the package contains work by countless other authors, added\nsince Jef's original work. In fact, the name is derived from the fact that the work was con‐\ntributed by people all over the world via the Internet, when such collaboration was still\nnovel enough to merit naming the package after it.\n\nBryan Henderson has been maintaining Netpbm since 1999. In addition to packaging work by\nothers, Bryan has also written a significant amount of new material for the package.\n", "subsections": [] }, "DOCUMENT SOURCE": { "content": "This manual page was generated by the Netpbm tool 'makeman' from HTML source. The master\ndocumentation is at\n\nhttp://netpbm.sourceforge.net/doc/index.html\n\nnetpbm documentation 08 August 2020 User manual for Netpbm(1)", "subsections": [] } } } }