diff options
Diffstat (limited to 'upstream/mageia-cauldron/man5/pgm.5')
| -rw-r--r-- | upstream/mageia-cauldron/man5/pgm.5 | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man5/pgm.5 b/upstream/mageia-cauldron/man5/pgm.5 new file mode 100644 index 00000000..78a5373d --- /dev/null +++ b/upstream/mageia-cauldron/man5/pgm.5 @@ -0,0 +1,247 @@ +\ +.\" 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 "PGM Format Specification" 5 "09 October 2016" "netpbm documentation" + +.SH NAME + +pgm - Netpbm grayscale image format + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +The PGM format is a lowest common denominator grayscale file format. +It is designed to be extremely easy to learn and write programs for. +(It's so simple that most people will simply reverse engineer it +because it's easier than reading this specification). +.PP +A PGM image represents a grayscale graphic image. There are many +pseudo-PGM formats in use where everything is as specified herein except +for the meaning of individual pixel values. For most purposes, a PGM +image can just be thought of an array of arbitrary integers, and all the +programs in the world that think they're processing a grayscale image +can easily be tricked into processing something else. +.PP +The name "PGM" is an acronym derived from "Portable Gray Map." +.PP +One official variant of PGM is the transparency mask. A transparency +mask in Netpbm is represented by a PGM image, except that in place of +pixel intensities, there are opaqueness values. See below. + +.UN format +.SH THE FORMAT +.PP +The format definition is as follows. You can use the +.BR "libnetpbm" (1)\c +\& C subroutine library to conveniently +and accurately read and interpret the format. +.PP +A PGM file consists of a sequence of one or more PGM images. There are +no data, delimiters, or padding before, after, or between images. +.PP +Each PGM image consists of the following: + + + +.IP \(bu +A "magic number" for identifying the file type. +A pgm image's magic number is the two characters "P5". + +.IP \(bu +Whitespace (blanks, TABs, CRs, LFs). + +.IP \(bu +A width, formatted as ASCII characters in decimal. + +.IP \(bu +Whitespace. + +.IP \(bu +A height, again in ASCII decimal. + +.IP \(bu +Whitespace. + +.IP \(bu +The maximum gray value (Maxval), again in ASCII decimal. Must be less +than 65536, and more than zero. + +.IP \(bu +A single whitespace character (usually a newline). + +.IP \(bu +A raster of Height rows, in order from top to bottom. Each row +consists of Width gray values, in order from left to right. Each gray +value is a number from 0 through Maxval, with 0 being black and Maxval +being white. Each gray value is represented in pure binary by either +1 or 2 bytes. If the Maxval is less than 256, it is 1 byte. +Otherwise, it is 2 bytes. The most significant byte is first. +.sp +A row of an image is horizontal. A column is vertical. The pixels +in the image are square and contiguous. +.sp +Each gray value is a number proportional to the intensity of the +pixel, adjusted by the ITU-R Recommendation BT.709 gamma transfer +function. (That transfer function specifies a gamma number of 2.2 and +has a linear section for small intensities). A value of zero is +therefore black. A value of Maxval represents CIE D65 white and the +most intense value in the image and any other image to which the image +might be compared. +.sp +BT.709's range of channel values (16-240) is irrelevant to PGM. +.sp +Note that a common variation from the PGM format is to have the +gray value be "linear," i.e. as specified above except +without the gamma adjustment. \fBpnmgamma\fP takes such a PGM +variant as input and produces a true PGM as output. +.sp +Another popular variation from PGM is to substitute the newer sRGB transfer +function for the BT.709 one. You can use \fBpnmgamma\fP to convert between +this variation and true PGM. +.sp +In the transparency mask variation from PGM, the value represents +opaqueness. It is proportional to the fraction of intensity of a +pixel that would show in place of an underlying pixel. So what +normally means white represents total opaqueness and what normally +means black represents total transparency. In between, you would +compute the intensity of a composite pixel of an "under" and +"over" pixel as under * (1-(alpha/alpha_maxval)) + over * +(alpha/alpha_maxval). Note that there is no gamma transfer function +in the transparency mask. + + +.PP +Strings starting with "#" may be comments, the same as +with +.BR "PBM" (1)\c +\&. +.PP +Note that you can use \fBpamdepth\fP to convert between a the +format with 1 byte per gray value and the one with 2 bytes per gray +value. +.PP +All characters referred to herein are encoded in ASCII. +"newline" refers to the character known in ASCII as Line +Feed or LF. A "white space" character is space, CR, LF, +TAB, VT, or FF (I.e. what the ANSI standard C isspace() function +calls white space). + +.UN plainpgm +.SS Plain PGM +.PP +There is actually another version of the PGM format that is fairly +rare: "plain" PGM format. The format above, which generally +considered the normal one, is known as the "raw" PGM format. +See +.BR "pbm" (1)\c +\& for some commentary on how plain +and raw formats relate to one another and how to use them. +.PP +The difference in the plain format is: + + +.IP \(bu + +There is exactly one image in a file. +.IP \(bu + +The magic number is P2 instead of P5. +.IP \(bu + +Each pixel in the raster is represented as an ASCII decimal number +(of arbitrary size). +.IP \(bu + +Each pixel in the raster has white space before and after it. There must +be at least one character of white space between any two pixels, but there +is no maximum. +.IP \(bu + +No line should be longer than 70 characters. + +.PP +Here is an example of a small image in the plain PGM format. + +.nf +P2 +# feep.pgm +24 7 +15 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0 3 3 3 3 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 15 15 15 0 +0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 15 0 +0 3 3 3 0 0 0 7 7 7 0 0 0 11 11 11 0 0 0 15 15 15 15 0 +0 3 0 0 0 0 0 7 0 0 0 0 0 11 0 0 0 0 0 15 0 0 0 0 +0 3 0 0 0 0 0 7 7 7 7 0 0 11 11 11 11 0 0 15 0 0 0 0 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 + +.fi +.PP +There is a newline character at the end of each of these lines. +.PP +Programs that read this format should be as lenient as possible, +accepting anything that looks remotely like a PGM. + + +.UN internetmediatype +.SH INTERNET MEDIA TYPE +.PP +No Internet Media Type (aka MIME type, content type) for PGM has been +registered with IANA, but the value \f(CWimage/x-portable-graymap\fP +is conventional. +.PP +Note that the PNM Internet Media Type \f(CWimage/x-portable-anymap\fP +also applies. + + +.UN filename +.SH FILE NAME +.PP +There are no requirements on the name of a PGM file, but the convention is +to use the suffix ".pgm". "pnm" is also conventional, for +cases where distinguishing between the particular subformats of PNM is not +convenient. + + +.UN compatibility +.SH COMPATIBILITY +.PP +Before April 2000, a raw format PGM file could not have a maxval greater +than 255. Hence, it could not have more than one byte per sample. Old +programs may depend on this. +.PP +Before July 2000, there could be at most one image in a PGM file. As +a result, most tools to process PGM files ignore (and don't read) any +data after the first image. + +.UN seealso +.SH SEE ALSO +.BR "pnm" (1)\c +\&, +.BR "pbm" (1)\c +\&, +.BR "ppm" (1)\c +\&, +.BR "pam" (1)\c +\&, +.BR "libnetpbm" (1)\c +\&, +.BR "programs that process PGM" (1)\c +\&, + +.UN author +.SH AUTHOR + +Copyright (C) 1989, 1991 by Jef Poskanzer. +.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/pgm.html +.PP
\ No newline at end of file |