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

FreeBSD Manual Pages

  
 
  

home | help
Pnmtopng User Manual(0)				       Pnmtopng	User Manual(0)

NAME
       pnmtopng	- convert a PNM	image to PNG

SYNOPSIS
       pnmtopng	[-verbose] [-downscale]	[-interlace] [-alpha=file] [-transpar-
       ent=[=]color] [-background=color] [-palette=palettefile]	[-gamma=value]
       [-hist] [-text=file] [-ztxt=file] [-rgb='wx wy
	 rx  ry	 gx  gy	bx by']	[-size='x y unit'] [-srgbintent=intent]	[-mod-
       time='[yy]yy-mm-dd
	 hh:mm:ss'] [-nofilter]	[-sub] [-up] [-avg] [-paeth]  [-compression=n]
       [-comp_mem_level=n]	      [-comp_strategy={huffman_only|filtered}]
       [-comp_method=deflated]	 [-comp_window_bits=n]	 [-comp_buffer_size=n]
       [-force]	[-libversion] [pnmfile]

OPTION USAGE
       Obsolete	options:

       [-filter	n]

       Options available only in older versions:

       [-chroma	wx wy rx ry gx gy bx by] [-phys	x y unit] [-time [yy]yy-mm-dd
	 hh:mm:ss]

       Minimum	unique abbreviation of option is acceptable.  You may use dou-
       ble hyphens instead of single hyphen to denote options.	 You  may  use
       white space in place of the equals sign to separate an option name from
       its value.

DESCRIPTION
       This program is part of Netpbm(1).

       pnmtopng	reads a	PNM image as input and produces	a PNG image as output.

       Color component values in PNG files are either eight  or	 sixteen  bits
       wide,  so  pnmtopng will	automatically scale colors to have a maxval of
       255 or 65535.

       For a grayscale image, pnmtopng produces	a PNG bit depth	1, 2, 4, 8  or
       16.   When the input image has a	small maxval, the output PNG image has
       a correspondingly small bit depth.  But in mapping the  PNM  maxval  to
       the  PNG	 maxval	 (which	is by definition the maximum value that	can be
       represented in the number of bits), a fair amount of distortion happens
       with  these low maxvals.	 For example, with a PNM maxval	of 5 and a PNG
       maxval of 7, the	input sample 2 becomes the output sample 3.  The input
       brightness  is  2/5  =  .40,  while the output brightness is 3/7	= .43.
       Note that this is not a problem if you view the maxval as a  precision,
       because	in  .4	and  .43 are identical within the precision implied by
       maxval 5.  Indeed, if you convert this PNG back to a maxval 5 PGM,  the
       pixel's	value  will  again be 2, exactly as it was originally.	But if
       you need	precisely the same colors in the output	PNG as	in  the	 input
       PNM,  make sure your input PNM has a maxval which is a power of two mi-
       nus one.	 If you	can't do that, then convert it with pamdepth to	 some-
       thing  with  a  large  maxval that is a power of	two minus one (255 and
       65535 are good choices) to minimize the error.

OPTIONS
       pnmtopng	changed	in Netpbm 10.30	(October 2005)	to  use	 the  standard
       Netpbm  command line syntax.  Before that, you could not	use double hy-
       phens to	denote an option and could not use an equal sign  to  separate
       an  option name from its	value.	And the	options	had to come before the
       non-option program arguments.

       Furthermore, the	options	-chroma, -phys,	and  -time  were  replaced  by
       -rgb,  -size,  and -modtime, respectively.  The only difference,	taking
       -phys/-size as an example, is that -phys	takes multiple	program	 argu-
       ments  as the option argument, whereas -size takes a single program ar-
       gument which is composed	of multiple words.  E.g.  The old  shell  com-
       mand

	  pnmtopng -phys 800 800 0 input.pnm >output.png

       is equivalent to	the new	shell command

	  pnmtopng -size "800 800 0" input.pnm >output.png

       If  you're  writing  a program that needs to work with both new and old
       pnmtopng, have it first try with	the new	syntax,	and if it  fails  with
       "unrecognized option," fall back	to the old syntax.

       -verbose
	      This  causes pnmtopng to display information about the format of
	      the output file.

       -downscale
	      This enables pnmtopng to scale maxvalues of more then  65535  to
	      16  bits.	Since this means loss of image data, pnmtopng does not
	      do it by default.

       -interlace
	      This causes the PNG file to be interlaced, in Adam7 format.  The
	      interlaced  format is one	in which the raster data starts	with a
	      low-resolution representation of the entire image, then  contin-
	      ues  with	additional information for the entire image, then even
	      more information,	etc.  In Adam7 in particular, there are	 seven
	      such passes of the whole image.  This is useful when you are re-
	      ceiving the image	over a slow communication line as  someone  is
	      waiting  to  see	it.   The simplest thing to do in that case is
	      wait for the entire image	to arrive  and	then  display  it  in-
	      stantly,	but  then  the user is wasting time staring at a blank
	      space until the whole image arrives.  With the standard  non-in-
	      terlaced	format,	 the  data  arrives row-by-row starting	at the
	      top, so the displayer could display each row of the image	as  it
	      arrives and gradually paint down to the bottom.  But with	an in-
	      terlaced image, the displayer can	start by showing a low-resolu-
	      tion version of the image, then gradually	improve	the display as
	      more data	arrives.

       -alpha=filename
	      This specifies the transparency (alpha) channel  of  the	image.
	      You  supply the transparency channel as a	standard PGM transpar-
	      ency mask	(see the PGM(5)	specification.	pnmtopng does not nec-
	      essarily	represents the transparency information	as a transpar-
	      ency channel in the PNG format.  If it can represent the	trans-
	      parency information through a palette, it	will do	so in order to
	      make a smaller PNG file.	pnmtopng even sorts the	palette	so  it
	      can  omit	 the  opaque  colors from the transparency part	of the
	      palette and save space for the palette.

       -transparent=color
	      pnmtopng marks the specified color as transparent	in the PNG im-
	      age.

	      Specify  the  color (color) as described for the argument	of the
	      pnm_parsecolor()		       library		       routine
	      <libnetpbm_image.html#colorname>	.   E.g.  red or rgb:ff/00/0d.
	      If the color you specify is not present in the  image,  pnmtopng
	      selects  instead	the  color in the image	that is	closest	to the
	      one you specify.	Closeness is measured as a Cartesian  distance
	      between  colors  in  RGB space.  If multiple colors are equidis-
	      tant, pnmtopng chooses one of them arbitrarily.

	      However, if you prefix your color	specification with "=",	e.g.

				  -transparent =red

	       only the	exact color you	specify	will be	transparent.  If  that
	      color  does  not appear in the image, there will be no transpar-
	      ency.  pnmtopng issues an	information message when this  is  the
	      case.

       -background=color
	      Causes  pnmtopng	to  create a background	color chunk in the PNG
	      output which can be used for subsequent transparency channel  or
	      transparent  color  conversions.	 Specify color the same	as for
	      -transparent.

       -palette=palettefile
	      This option specifies a palette to use in	the  PNG.   It	forces
	      pnmtopng	to create the paletted (colormapped) variety of	PNG --
	      if that isn't possible, pnmtopng	fails.	 If  the  palette  you
	      specify  doesn't	contain	 exactly the colors in the image, pnm-
	      topng fails.   Since  pnmtopng  will  automatically  generate  a
	      paletted PNG, with a correct palette, when appropriate, the only
	      reason you would specify the -palette option is if you  care  in
	      what  order  the	colors appear in the palette.  The PNG palette
	      has colors in the	same order as the palette you specify.

	      You specify the palette by naming	a PPM file that	has one	 pixel
	      for each color in	the palette.

	      Alternatively,  consider	the  case  that	have a palette and you
	      want to make sure	your PNG contains only colors  from  the  pal-
	      ette,  approximating  if necessary.  You don't care what indexes
	      the PNG uses internally for the colors (i.e. the	order  of  the
	      PNG  palette).  In this case, you	don't need -palette.  Pass the
	      Netpbm input  image  and	your  palette  PPM  through  pnmremap.
	      Though  you  might  think	 it would, using -palette in this case
	      wouldn't even save pnmtopng any work.

       -gamma=value
	      Causes pnmtopng to create	a gAMA chunk.  This information	 helps
	      describe	how  the  color	values in the PNG must be interpreted.
	      Without the gAMA chunk, whatever interprets  the	PNG  must  get
	      this information separately (or just assume something standard).
	      If your input is a true PPM or PGM  image,  you  should  specify
	      -gamma=.52.   But	sometimes people generate images which are os-
	      tensibly PPM except the image uses a  different  gamma  transfer
	      function	than the one specified for PPM.	 A common case of this
	      is when the image	is created by  simple  hardware	 that  doesn't
	      have  digital computational ability.  Also, some simple programs
	      that generate images from	scratch	do it with a gamma transfer in
	      which the	gamma value is 1.0.

       -hist  Use  this	 parameter  to	create a chunk that specifies the fre-
	      quency (or histogram) of the colors in the image.

       -text=filename
	      This option lets you include arbitrary text strings in  the  PNG
	      output, as tEXt chunks.

	      filename is the name of a	file that contains your	text strings.

	      The  output contains a distinct tEXt chunk for each entry	in the
	      file.

	      Here is an example of a text string file:

		   Title	   PNG file
		   Author	   John	Doe
		   Description	   how to include a text chunk
				      PNG file
		   "Creation Date" 2015-may-11
		   Software	   pamtopng

	      The file is divided into entries,	each entry comprising consecu-
	      tive  lines  of  text.  The first	line of	an entry starts	in the
	      first column (i.e. the first column is not white space) and  ev-
	      ery  other  line has white space in the first column.  The first
	      entry starts in the first	line, so it is not valid for the first
	      line of the file to have white space in its first	column.

	      The  first  word in an entry is the key of the text string (e.g.
	      'Title').	 It begins in column one of the	line and continues  up
	      to,  but not including, the first	delimiter character or the end
	      of the line, whichever is	first.	You can	 enclose  the  key  in
	      double  quotes  in  which	 case the key can consists of multiple
	      words.  The quotes are not part of the key.  The text string per
	      se  begins  after	the key	and any	delimiter characters after it,
	      plus the text in subsequent continuation lines.

	      There is no limit	on the length of a file	line or	entry  or  key
	      or text string.  There is	no limit on the	number of entries.

       -ztxt=filename
	      The  same	 as -text, except the text string is compressed	in the
	      PNG output.  pnmtopng uses zTXt chunks instead of	a tEXt chunks,
	      unless the key for the text string starts	with 'A' or 'T'.  This
	      odd exception exists for backward	compatibility; we  don't  know
	      why  the	program	 was originally	designed this way, except that
	      the distinction was meant	to roughly identify the	keys  'Author'
	      and 'Title'.

       -rgb=chroma_list
	      This  option specifies how red, green, and blue component	values
	      of a pixel specify a particular color, by	telling	the chromatic-
	      ities  of	 those	3  primary illuminants and of white (i.e. full
	      strength of all three).

	      The chroma_list value is a blank-separated list  of  8  floating
	      point  decimal numbers.  The CIE-1931 X and Y chromaticities (in
	      that order) of each of white, red, green,	and blue, in that  or-
	      der.

	      This information goes into the PNG's cHRM	chunk.

	      In  a  shell  command, make sure you use quotation marks so that
	      the blanks in chroma_list	don't make the shell see multiple com-
	      mand arguments.

	      This  option  was	 new  in  Netpbm 10.30 (October	2005).	Before
	      that, the	option -chroma does the	same thing, but	with  slightly
	      different	syntax.

       -size="x	y unit"
	      This option determines the aspect	ratio of the individual	pixels
	      of your image as well as the physical resolution of it.

	      unit is either 0 or 1.  When it is 1, the	option	specifies  the
	      physical resolution of the image in pixels per meter.  For exam-
	      ple, -size="10000	15000 1" means that when someone displays  the
	      image,  he should	make it	so that	10,000 pixels horizontally oc-
	      cupy 1 meter and 15,000 pixels vertically	occupy one meter.  And
	      even  if	he doesn't take	this advice on the overall size	of the
	      displayed	image, he should at least make it so that  each	 pixel
	      displays as 1.5 times as high as wide.

	      When  unit  is  0, that means there is no	advice on the absolute
	      physical resolution; just	on the ratio of	horizontal to vertical
	      physical resolution.

	      This information goes into the PNG's pHYS	chunk.

	      When you don't specify -size, pnmtopng creates the image with no
	      pHYS chunk, which	means square pixels of no absolute resolution.

	      This option was new in  Netpbm  10.30  (October  2005).	Before
	      that,  the  option  -phys	does the same thing, but with slightly
	      different	syntax.

       -srgbintent=intent
	      This asserts that	the input is a pseudo-Netpbm image  that  uses
	      an  sRGB	color space (unlike true Netpbm) and indicates how you
	      intend for the colors to be rendered.  It	causes pnmtopng	to in-
	      clude an sRGB chunk in the PNG image that	specifies that intent,
	      so see the PNG documentation for more information	on  what  this
	      really means.

	      intent is	one of:

       o      perceptual

       o      relativecolorimetric

       o      saturation

       o      absolutecolorimetric

	      This  option  was	new in Netpbm 10.71 (June 2015).  Before that,
	      pnmtopng never generates an sRGB chunk.

       -modtime="[yy]yy-mm-dd hh:mm:ss"
	      This option allows you to	specify	the modification time value to
	      be placed	in the PNG output.  You	can specify the	year parameter
	      either as	a two digit or four digit value.

	      This option was new in  Netpbm  10.30  (October  2005).	Before
	      that,  the  option  -time	does the same thing, but with slightly
	      different	syntax.

       -filter=n
	      This option is obsolete.	Before Netpbm 10.22 (April 2004), this
	      was the only way to specify a row	filter.	 It specifies a	single
	      type of row filter, by number, that pnmtopng must	 use  on  each
	      row.

	      Use -nofilter, -sub, -up,	-avg, and -paeth in current Netpbm.

       -nofilter

       -sub

       -up

       -avg

       -paeth Each  of	these  options permits pnmtopng	to use one type	of row
	      filter.  pnmtopng	chooses	whichever of the permitted filters  it
	      finds  to	 be optimal.  If you specify none of these options, it
	      is the same as specifying	all of them -- pnmtopng	uses  any  row
	      filter type it finds optimal.

	      These  options  were new with Netpbm 10.22 (April	2004).	Before
	      that, you	could use the -filter option to	specify	one  permitted
	      row  filter  type.   The default,	when you specify no filter op-
	      tions, was the same.

       -compression=n
	      This option sets set the compression level of the	zlib  compres-
	      sion.   Select a level from 0 for	no compression (maximum	speed)
	      to 9 for maximum compression (minimum speed).

	      The default is the default of the	zlib library.

       -comp_mem_level=n
	      This option sets the memory usage	level of the zlib compression.
	      Select  a	 level	from  1	 for minimum memory usage (and minimum
	      speed) to	9 for maximum memory usage (and	speed).

	      The default is the default of the	zlib library.

	      This option was new in Netpbm 10.30 (October 2005).

       -comp_strategy={huffman_only|filtered}
	      This options sets	the compression	strategy of the	zlib  compres-
	      sion.   See  Zlib	 documentation	for  information on what these
	      strategies are.

	      The default is the default of the	zlib library.

	      This option was new in Netpbm 10.30 (October 2005).

       -comp_method=deflated
	      This option does nothing.	 It is here for	mathematical complete-
	      ness  and	 for possible forward compatibility.  It theoretically
	      selects the compression method of	the zlib compression, but  the
	      Z	 library  knows	 only  one method today, so there's nothing to
	      choose.

	      The default is the default of the	zlib library.

	      This option was new in Netpbm 10.30 (October 2005).

       -comp_window_bits=N
	      This option tells	how big	a window the  zlib  compression	 algo-
	      rithm  uses.   The  value	 is the	base 2 logarithm of the	window
	      size in bytes, so	8 means	256 bytes.  The	value must be  from  8
	      to 15 (i.e. 256 bytes to 32K).

	      See Zlib documentation for details on what this window size is.

	      The default is the default of the	zlib library.

	      This option was new in Netpbm 10.30 (October 2005).

       -comp_buffer_size=N
	      This  option  determines	in  what size pieces pnmtopng does the
	      zlib compression.	 One compressed	piece goes in each IDAT	 chunk
	      in  the  PNG.   So  the bigger this value, the fewer IDAT	chunks
	      your PNG will have.  Theoretically, this makes the  PNG  smaller
	      because  1)  you	have  less per-IDAT-chunk overhead, and	2) the
	      compression algorithm has	more data to work with.	 But in	 real-
	      ity,  the	difference will	probably not be	noticeable above about
	      8K, which	is the default.

	      The value	n is the size of the compressed	piece (i.e.  the  com-
	      pression buffer) in bytes.

	      This option was new in Netpbm 10.30 (October 2005).

       -force When  you	 specify this, pnmtopng	limits its optimizations.  The
	      resulting	PNG output is as similar to the	Netpbm input as	possi-
	      ble.   For  example, the PNG output will not be paletted and the
	      transparency channel will	be represented as a full  transparency
	      channel  even  if	the information	could be represented more suc-
	      cinctly with a transparency chunk.

       -libversion
	      This option causes pnmtopng to display version information about
	      itself  and the libraries	it uses, in addition to	all its	normal
	      function.	 Do not	confuse	this with  the	Netpbm	common	option
	      -version,	 which	causes the program to display version informa-
	      tion about the Netpbm library and	do nothing else.

	      You can't	really use this	option in a program that invokes  pnm-
	      topng  and  needs	to know	which version it is.  Its function has
	      changed too much over the	history	of pnmtopng.   The  option  is
	      good only	for human eyes.

SEE ALSO
       pngtopam(1), pamtopng(1), pnmremap(1), pnmgamma(1), pnm(5)

       For   information   on	the   PNG  format,  see	 http://schaik.com/png
       <http://schaik.com/png> .

AUTHOR
       Copyright (C) 1995-1997 by Alexander Lehmann and	Willem van Schaik.

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

	      http://netpbm.sourceforge.net/doc/pnmtopng.html

netpbm documentation		 13 March 2019	       Pnmtopng	User Manual(0)

NAME | SYNOPSIS | OPTION USAGE | DESCRIPTION | OPTIONS | SEE ALSO | AUTHOR | DOCUMENT SOURCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pnmtopng&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help