Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PGM Format Specification(5)   File Formats Manual  PGM Format Specification(5)

       pgm - Netpbm grayscale image format

       This program is part of Netpbm(1).

       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 be-
       cause it's easier than reading this specification).

       A PGM image represents a	 grayscale  graphic  image.   There  are  many
       pseudo-PGM  formats  in use where everything is as specified herein ex-
       cept 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.

       The name	"PGM" is an acronym derived from "Portable Gray	Map."

       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.

       The  format  definition	is as follows.	You can	use the	libnetpbm(3) C
       subroutine library to conveniently and accurately  read	and  interpret
       the format.

       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.

       Each PGM	image consists of the following:

       o      A	"magic number" for identifying the file	type.  A  pgm  image's
	      magic number is the two characters "P5".

       o      Whitespace (blanks, TABs,	CRs, LFs).

       o      A	width, formatted as ASCII characters in	decimal.

       o      Whitespace.

       o      A	height,	again in ASCII decimal.

       o      Whitespace.

       o      The  maximum  gray value (Maxval), again in ASCII	decimal.  Must
	      be less than 65536, and more than	zero.

       o      A	single whitespace character (usually a newline).

       o      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 signifi-
	      cant byte	is first.

	      A	row of an image	is horizontal.	A  column  is  vertical.   The
	      pixels in	the image are square and contiguous.

	      Each gray	value is a number proportional to the intensity	of the
	      pixel, adjusted by the ITU-R Recommendation BT.709 gamma	trans-
	      fer  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.

	      BT.709's range of	channel	values (16-240)	is irrelevant to PGM.

	      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.  pnmgamma takes such a PGM	variant	as in-
	      put and produces a true PGM as output.

	      Another popular variation	from PGM is to	substitute  the	 newer
	      sRGB transfer function for the BT.709 one.  You can use pnmgamma
	      to convert between this variation	and true PGM.

	      In the transparency mask variation from PGM,  the	 value	repre-
	      sents  opaqueness.  It is	proportional to	the fraction of	inten-
	      sity 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 be-
	      tween,  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.

       Strings starting	with "#" may be	comments, the same as with PBM(5).

       Note that you can use pamdepth to convert between a the format  with  1
       byte per	gray value and the one with 2 bytes per	gray value.

       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).

   Plain PGM
       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 pbm(5) for  some
       commentary  on  how plain and raw formats relate	to one another and how
       to use them.

       The difference in the plain format is:


	      There is exactly one image in a file.


	      The magic	number is P2 instead of	P5.


	      Each pixel in the	raster is represented as an ASCII decimal num-
	      ber (of arbitrary	size).


	      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.


	      No line should be	longer than 70 characters.

       Here is an example of a small image in the plain	PGM format.

       # feep.pgm
       24 7
       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

       There is	a newline character at the end of each of these	lines.

       Programs	 that  read  this format should	be as lenient as possible, ac-
       cepting anything	that looks remotely like a PGM.

       No Internet Media Type (aka MIME	type, content type) for	PGM  has  been
       registered with IANA, but the value image/x-portable-graymap is conven-

       Note that the PNM Internet Media	Type image/x-portable-anymap also  ap-

       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

       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 sam-
       ple.  Old programs may depend on	this.

       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.

       pnm(5), pbm(5), ppm(5), pam(5),	libnetpbm(3),  programs	 that  process

       Copyright (C) 1989, 1991	by Jef Poskanzer.

       This  manual  page was generated	by the Netpbm tool 'makeman' from HTML
       source.	The master documentation is at

netpbm documentation		09 October 2016	   PGM Format Specification(5)


Want to link to this manual page? Use this URL:

home | help