diff options
Diffstat (limited to 'upstream/debian-unstable/man5/pam.5')
| -rw-r--r-- | upstream/debian-unstable/man5/pam.5 | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man5/pam.5 b/upstream/debian-unstable/man5/pam.5 new file mode 100644 index 00000000..9e8174a5 --- /dev/null +++ b/upstream/debian-unstable/man5/pam.5 @@ -0,0 +1,331 @@ +\ +.\" 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 "PAM format specification" 5 "27 November 2013" "netpbm documentation" + +.SH NAME +pam - Netpbm common 2-dimensional bitmap format + +.UN general +.SH GENERAL +.PP +The PAM image format is a lowest common denominator 2 dimensional map +format. +.PP +It is designed to be used for any of myriad kinds of graphics, but can +theoretically be used for any kind of data that is arranged as a two +dimensional rectangular array. Actually, from another perspective it +can be seen as a format for data arranged as a three dimensional +array. +.PP +The name "PAM" is an acronym derived from "Portable +Arbitrary Map." This derivation makes more sense if you consider +it in the context of the other Netpbm format names: PBM, PGM, and PPM. +.PP +This format does not define the meaning of the data at any particular +point in the array. It could be red, green, and blue light +intensities such that the array represents a visual image, or it could +be the same red, green, and blue components plus a transparency +component, or it could contain annual rainfalls for places on the +surface of the Earth. Any process that uses the PAM format must +further define the format to specify the meanings of the data. +.PP +A PAM image describes a two dimensional grid of tuples. The tuples are +arranged in rows and columns. The width of the image is the number of +columns. The height of the image is the number of rows. All rows are the +same width and all columns are the same height. The tuples may have any +degree, but all tuples have the same degree. The degree of the tuples is +called the depth of the image. Each member of a tuple is called a sample. A +sample is an unsigned integer which represents a locus along a scale which +starts at zero and ends at a certain maximum value called the maxval. The +maxval is the same for every sample in the image. The two dimensional array +of all the Nth samples of each tuple is called the Nth plane or Nth channel of +the image. +.PP +Though the basic format does not assign any meaning to the tuple values, it +does include an optional string that describes that meaning. The +contents of this string, called the tuple type, are arbitrary from the +point of view of the basic PAM format, but users of the format may assign +meaning to it by convention so they can identify their particular +implementations of the PAM format. Some tuple types are defined as +official subformats of PAM. See +.UR #tupletype +Defined Tuple Types +.UE +\&. + +.UN format_universe +.SH The Confusing Universe of Netpbm Formats +.PP +It is easy to get confused about the relationship between the PAM +format and PBM, PGM, PPM, and PNM. Here is a little enlightenment: +.PP +"PNM" is not really a format. It is a shorthand for the PBM, PGM, +and PPM formats collectively. It is also the name of a group of +library functions that can each handle all three of those formats. +.PP +"PAM" is in fact a fourth format. But it is so general +that you can represent the same information in a PAM image as you can +in a PBM, PGM, or PPM image. And in fact a program that is designed +to read PBM, PGM, or PPM and does so with a recent version of the +Netpbm library will read an equivalent PAM image just fine and the +program will never know the difference. +.PP +To confuse things more, there is a collection of library routines +called the "pam" functions that read and write the PAM +format, but also read and write the PBM, PGM, and PPM formats. They +do this because the latter formats are much older and more popular, so +even a new program must work with them. Having the library handle all +the formats makes it convenient to write programs that use the newer +PAM format as well. + +.UN layout +.SH THE LAYOUT +.PP +A convenient way to read and write the PAM format accurately is via the +.BR "libnetpbm" (1)\c +\& C subroutine library. +.PP +A PAM file consists of a sequence of one or more PAM images. There are +no data, delimiters, or padding before, after, or between images. +.PP +Each PAM image consists of a header followed immediately by a raster. +.PP +Here is an example header: + +.nf + +P7 +WIDTH 227 +HEIGHT 149 +DEPTH 3 +MAXVAL 255 +TUPLTYPE RGB +ENDHDR + + +.fi +.PP +The header begins with the ASCII characters "P7" followed +by newline. This is the magic number. +.PP +Note: \fBxv\fP thumbnail images also start with the "P7" magic number. +(This and PAM were independent extensions to the Netpbm formats). The rest +of the format makes it easy to distinguish PAM from that format, though). +.PP +The header continues with an arbitrary number of lines of ASCII +text. Each line ends with and is delimited by a newline character. +.PP +Each header line consists of zero or more whitespace-delimited +tokens or begins with "#". If it begins with "#" +it is a comment and the rest of this specification does not apply to +it. +.PP +A header line which has zero tokens is valid but has no meaning. +.PP +The type of header line is identified by its first token, which is +8 characters or less: + + +.TP +\fBENDHDR \fP +This is the last line in the header. The header must contain +exactly one of these header lines. + +.TP +\fBHEIGHT \fP +The second token is a decimal number representing the height +of the image (number of rows). The header must contain exactly one +of these header lines. + +.TP +\fBWIDTH\fP +The second token is a decimal number representing the width of the +image (number of columns). The header must contain exactly one of +these header lines. + +.TP +\fBDEPTH\fP +The second token is a decimal number representing the depth of the +image (number of planes or channels). The header must contain exactly +one of these header lines. + +.TP +\fBMAXVAL\fP +The second token is a decimal number representing the maxval of the image. +The header must contain exactly one of these header lines. + +.TP +\fBTUPLTYPE\fP +The header may contain any number of these header lines, including +zero. The rest of the line is part of the tuple type. The rest of +the line is not tokenized, but the tuple type does not include any +white space immediately following \fBTUPLTYPE \fP or at the very end +of the line. It does not include a newline. There must be something +other than white space after the \fBTUPLTYPE\fP token. +.sp +If there are multiple \fBTUPLTYPE\fP header lines, the tuple type +is the concatenation of the values from each of them, separated by a +single blank, in the order in which they appear in the header. If +there are no \fBTUPLTYPE\fP header lines the tuple type is the null +string. + + +.PP +The raster consists of each row of the image, in order from top to bottom, +consecutive with no delimiter of any kind between, before, or after, rows. +.PP +Each row consists of every tuple in the row, in order from left to +right, consecutive with no delimiter of any kind between, before, or +after, tuples. +.PP +Each tuple consists of every sample in the tuple, in order, +consecutive with no delimiter of any kind between, before, or after, +samples. +.PP +Each sample consists of an unsigned integer in pure binary format, +with the most significant byte first. The number of bytes is the +minimum number of bytes required to represent the maxval of the image. +.PP +The character referred to as "newline" herein is the +character known in ASCII as Line Feed or LF. + +.UN limitations +.SH LIMITATIONS +.PP +Height, width, depth, and maxval are at least 1. +.PP +Height, width, and depth have no defined maximum, but processors and +generators of images usually have their own limitations. +.PP +The maxval of an image is never greater than 65535. (The reason it is +limited is to make it easier to build an image processor, in which +intermediate arithmetic values often have to fit within 31 or 32 bits). +There was no specified limitation before October, 2005, but essentially +all implementations have always observed it. + +.UN tupletype +.SH DEFINED TUPLE TYPES +.PP +Some tuple types are defined in this specification to specify +official subformats of PAM for especially popular applications of the +format. Users of the format may also define their own tuple types, +and thus their own subformats. +.PP +Tuple type affects \fIonly\fP the meanings of the samples (which are +unsigned integers) in the tuples of the image. It does not affect how the +samples or tuples are encoded. Tuple type may affect the meaning of a tuple's +position in the array (e.g. it may indicate in a visual image that a tuple +in Row 1 is one at the top of the image rather than the bottom). +.PP +Tuple type never determines how many samples are in a tuple (that is +instead determined by the DEPTH header line). Tuple type could be said to +imply a depth (number of samples per tuple) because certain tuple types are +valid only in combination with certain DEPTH values, but it is good +programming practice to use DEPTH for the depth when decoding the raster and +separately validate that the depth is consistent with the tuple type. Also, +it is good practice to accept a depth that is too great and just ignore the +higher numbered planes. + +.UN visual +.SS PAM Used For Visual Images +.PP +A common use of PAM images is to represent visual images such +as are typically represented by images in the older and more concrete +PBM, PGM, and PPM formats. + +.B Black And White +.PP +A black and white image, such as would alternatively be represented by a +PBM image, has a tuple type of "BLACKANDWHITE". Such a PAM image has a depth +of 1 and maxval 1 where the one sample in each tuple is 0 to represent a black +pixel and 1 to represent a white one. The maxval, height, width, and order of +tuples in the raster bear the obvious relationship to those of the equivalent +PGM image. +.PP +Note that in the PBM format, a sample value of zero means white, but in +PAM, zero means black. + +.B Grayscale +.PP +A grayscale image, such as would alternatively be represented by a PGM +image, has a tuple type of "GRAYSCALE". Such a PAM image has a depth of 1. +The maxval, height, width, and raster bear the obvious relationship to those +of the equivalent PGM image. + +.B Color +.PP +A color image, such as would alternatively be represented by a PPM image, +has a tuple type of "RGB". Such a PAM image has a depth of 3. The maxval, +height, width, and raster bear the obvious relationship to those of the PPM +image. The first plane represents red, the second green, and the third blue. + +.B Transparent +.PP +Each of the visual image formats mentioned above has a variation that +contains transparency information. In that variation, the tuple type +has "_ALPHA" added to it (e.g. "RGB_ALPHA") and one +more plane. The highest numbered plane is the opacity plane (sometimes +called an alpha plane or transparency plane). +.PP +In this kind of image, the color represented by a pixel is actually +a combination of an explicitly specified foreground color and a background +color to be identified later. +.PP +The planes other than the opacity plane describe the foreground +color. A sample in the opacity plane tells how opaque the pixel is, by +telling what fraction of the pixel's light comes from the foreground +color. The rest of the pixel's light comes from the (unspecified) +background color. +.PP +For example, in a GRAYSCALE_ALPHA image, assume Plane 0 indicates +a gray tone 60% of white and Plane 1 indicates opacity 25%. The +foreground color is the 60% gray, and 25% of that contributes to the +ultimate color of the pixel. The other 75% comes from some background +color. So let's assume further that the background color of the pixel +is full white. Then the color of the pixel is 90% of white: 25% of +the foreground 60%, plus 75% of the background 100%. +.PP +The sample value is the opacity fraction just described, as a fraction +of the maxval. Note that it is \fInot\fP gamma-adjusted like the +foreground color samples. + + +.UN internetmediatype +.SH INTERNET MEDIA TYPE +.PP +No Internet Media Type (aka MIME type, content type) for PBM has been +registered with IANA, but the unofficial value +image/x-portable-arbitrarymap is +assigned by this specification, to be consistent with conventional values for +the older Netpbm formats. + +.UN filename +.SH FILE NAME +.PP +The conventional suffix for the name of a PAM file is ".pam". +But this is not required. + + +.UN seealso +.SH SEE ALSO +.BR "Netpbm" (1)\c +\&, +.BR "pbm" (1)\c +\&, +.BR "pgm" (1)\c +\&, +.BR "ppm" (1)\c +\&, +.BR "pnm" (1)\c +\&, +.BR "libnetpbm" (1)\c +\& +.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/pam.html +.PP
\ No newline at end of file |