{ "mode": "man", "parameter": "pngtopam", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pngtopam/1/json", "generated": "2026-08-09T20:36:49Z", "synopsis": "pngtopam [-verbose] [-alphapam | -alpha | -mix] [-background=color] [-gamma=value]\n[-text=filename] [-time] [-byrow] [pngfile]\nMinimum unique abbreviation of option is acceptable. You may use double hyphens instead of\nsingle hyphen to denote options. You may use white space in place of the equals sign to sep‐\narate an option name from its value.", "sections": { "NAME": { "content": "pngtopam - convert a PNG image into a Netpbm image\n\n", "subsections": [] }, "SYNOPSIS": { "content": "pngtopam [-verbose] [-alphapam | -alpha | -mix] [-background=color] [-gamma=value]\n[-text=filename] [-time] [-byrow] [pngfile]\n\nMinimum unique abbreviation of option is acceptable. You may use double hyphens instead of\nsingle hyphen to denote options. You may use white space in place of the equals sign to sep‐\narate an option name from its value.\n\n", "subsections": [] }, "DESCRIPTION": { "content": "This program is part of Netpbm(1).\n\npngtopam reads a PNG image (Portable Network Graphics) as input and produces a Netpbm image\nas output. The type of the output file depends on the input file - if it's black & white,\npngtopam creates a PBM file. If it's grayscale, pngtopam creates a PGM file. Otherwise, it\ncreates a PPM file. Except that with the -alphapam option, it always creates a PAM file.\nThat file has tuple type GRAYSCALEALPHA or RGBALPHA depending on whether the input has\ncolor or not.\n\nTo convert in the other direction, use pamtopng or pnmtopng. The former is the more modern\nof the two and can recognize transparency information in a PAM file, as you might generate\nwith pngtopam -alphapam. It has existed only since June 2015. The latter has more features,\nbut probably not ones that matter in the modern world.\n\n\n", "subsections": [] }, "OPTIONS": { "content": "In addition to the options common to all programs based on libnetpbm (most notably -quiet,\nsee \u001b]8;;index.html#commonoptions\u001b\\ Common Options\u001b]8;;\u001b\\ ), pngtopam recognizes the following command line options:\n\n\n", "subsections": [ { "name": "-verbose", "content": "Display various information about the input PNG image and the conversion process.\n\nIf you want even more information about the PNG image, use pngcheck (not part of\nNetpbm).\n\n" }, { "name": "-alphapam", "content": "Produce a single output image containing the main image (foreground) and the trans‐\nparency channel or transparency mask. This image is in the PAM format with tuple type\nof either GRAYSCALEALPHA (which has a depth of 2 channels) or RGBALPHA (which has a\ndepth of 4 channels).\n\nYou can specify only one of -alphapam, -alpha, and -mix. With none of them, pngtopam\nproduces an image of the foreground of the input image and discards transparency in‐\nformation.\n\nThis option was new in Netpbm 10.44 (September 2008).\n\n" }, { "name": "-alpha", "content": "ther a PBM file or a PGM file, depending on whether different levels of transparency\nappear.\n\npngtopam discards the main image (the foreground).\n\nYou can specify only one of -alphapam, -alpha, and -mix. With none of them, pngtopam\nproduces an image of the foreground of the input image and discards transparency in‐\nformation.\n\n" }, { "name": "-mix", "content": "The background color is determined by the bKGD chunk in the PNG, except that you can\noverride it with -background. If the PNG has no bKGD chunk and you don't specify\n-background, the background color is white.\n\nYou can specify only one of -alphapam, -alpha, and -mix. With none of them, pngtopam\nproduces an image of the foreground of the input image and discards transparency in‐\nformation.\n\n" }, { "name": "-background=_", "content": "This option specifies the background color with which to mix the image when you spec‐\nify -mix.\n\ncolor is as described for the \u001b]8;;libnetpbmimage.html#colorname\u001b\\argument of the pnmparsecolor() library routine\u001b]8;;\u001b\\ .\n\nExamples:\n\n\n\n• -background=rgb:01/ff/80\n\n• -background=rgbi:1/255/128\n\n\nIf you don't specify -background, the background color is what is specified in the PNG\nimage, and if the PNG doesn't specify anything, white.\n\nYou cannot specify -background unless you also specify -mix. Before Netpbm 10.27\n(March 2005), you could specify -background without -mix and it was just ignored.\n(This caused a usability problem).\n\n\n" }, { "name": "-gamma=_", "content": "This option causes pngtopam to respect the image gamma information in the PNG file\n(from the gAMA chunk). Probably by historical accident, pngtopam ignores that infor‐\nmation by default, assuming the image uses the same gamma transformation as a Netpbm\nimage, so the output image has different colors than the PNG file actually represents\nif the PNG doesn't actually do that. (However, it is rare for a PNG file to use a\ngamma transformation different from what the Netpbm formats specify, or if it does, to\nspecify with a gAMA chuck what that is).\n\nBut when you do specify -gamma, you get a rather strange additional function, probably\na historical mistake: pngtopam incorporates the specified screen gamma value into the\noutput pixels, so that the samples in the Netpbm output deviate from the Netpbm format\nspecifications and are appropriate raw intensity values to send to the display. This\nfunction essentially just exercises the ability of the PNG library to make gamma cor‐\nrections to the pixels as it reads them from the PNG file to produce values appropri‐\nate for sending to a certain display in certain viewing conditions. It's a strange\nfunction because it has nothing to do with PNG and because in Netpbm, the normal way\nto make gamma corrections appropriate for sending to a ceratin display in certain\nviewing conditions is with the program pngtopam, applied to the normal output of png‐\ntopam.\n\nIf you specify -gamma, but the PNG image does not specify what gamma transformation it\nuses (there is no gAMA chunk), pngtopam assumes a simple power transformation with an\nimage gamma of 1.0. That is probably not not the actual image gamma; it is much more\nlikely to be .45.\n\nBecause the gammas of uncompensated monitors are around 2.6, which results in an im‐\nage-gamma of 0.45, some typical situations are: when the image-gamma is 0.45 (use\n-verbose to check) and the picture is too light, your system is gamma-corrected, so\nconvert with \"-gamma 1.0\". When no gAMA chunk is present or the image-gamma is 1.0,\nuse 2.2 to make the picture lighter and 0.45 to make the picture darker.\n\nOne oddity to be aware of when using -gamma on an image with transparency: The PNG im‐\nage specifies that a certain color is transparent, i.e. every pixel in the image of\nthat color is transparent. But pngtopam interprets this as applying to the gamma-cor‐\nrected space, and there may be less precision in that space than in the original,\nwhich means multiple uncorrected colors map to the same corrected color. So imagine\nthat the image contains 3 shades of white (gray) and specifies that one of them is\ntransparent. After gamma correction, those three shades are indistinguishable, so\npngtopam considers pixels of all three shades to be transparent.\n\n\n" }, { "name": "-text=_", "content": "Writes the tEXt and zTXt chunks to a file, in a format as described in the pnmtopng\nuser manual. These chunks contain text comments or annotations.\n\n" }, { "name": "-time", "content": "" }, { "name": "-byrow", "content": "fail.\n\npngtopam has two ways to do the conversion from PNG to PAM, using respectively two fa‐\ncilities of the PNG library:\n\n\n\n\nWhole Image\nDecode the entire image into memory at once, using pngreadimage(), then convert to\nPAM and output row by row.\n\n\nRow By Row\nRead, convert, and output one row at a time using pngreadrow().\n\n\n\nWhole Image is generally preferable because the PNG library does more of the work,\nwhich means it understands more of the PNG format possibilities now and in the future.\nAlso, if the PNG is interlaced, pngtopam does not know how to assemble the rows in the\nright order.\n\nRow By Row uses far less memory, which means with large images, it can run in environ‐\nments where Whole Image cannot and may also run faster. And because Netpbm code does\nmore of the work, it's possible that it can be more flexible or at least give better\ndiagnostic information if there's something wrong with the PNG.\n\nThe Netpbm native code may do something correctly that the PNG library does incor‐\nrectly, or vice versa.\n\nIn Netpbm, we stress function over performance, so by default pngtopam uses Whole Im‐\nage. You can select Row By Row with -byrow if you want the speed or resource require‐\nment improvement.\n\n-byrow was new in Netpbm 10.54 (March 2011).\n\n\n" }, { "name": "-orientraw", "content": "A TIFF stream contains raster data which can be arranged in the stream various ways.\nMost commonly, it is arranged by rows, with the top row first, and the pixels left to\nright within each row, but many other orientations are possible.\n\nThe common orientation is the same on the Netpbm formats use, so tifftopnm can do its\njobs quite efficiently when the TIFF raster is oriented that way.\n\nBut if the TIFF raster is oriented any other way, it can take a considerable amount of\nprocessing for tifftopnm to convert it to Netpbm format.\n\n\n\n" } ] }, "SEE ALSO": { "content": "pamtopng(1), pnmtopng(1), pngtopnm(1), ptot, pnmgamma(1), pnm(1)\n\nFor information on the PNG format, see \u001b]8;;http://schaik.com/png\u001b\\http://schaik.com/png\u001b]8;;\u001b\\ .\n\n", "subsections": [] }, "NOTE": { "content": "A PNG image contains a lot of information that can't be represented in Netpbm formats.\nTherefore, you lose information when you convert to another format with \"pngtopam | pnm‐\ntoxxx\". If there is a specialized converter that converts directly to the other format, e.g.\nptot to convert from PNG to TIFF, you'll get better results using that.\n\n", "subsections": [] }, "LIMITATIONS": { "content": "There could be an option to include PNG comment chunks in the output image as PNM comments\ninstead of putting them in a separate file.\n\nThe program could be much faster, with a bit of code optimizing. As with any Netpbm program,\nspeed always takes a back seat to quick present and future development.\n\n", "subsections": [] }, "HISTORY": { "content": "pngtopam was new in Netpbm 10.44, as a replacement for pngtopnm. The main improvement over\npngtopnm was that it could generate a PAM image with a transparency channel, whereas with\npngtopnm, you would have to extract the transparency channel as a separate file, in a sepa‐\nrate run.\n\npngtopnm was new in Netpbm 8.1 (March 2000), the first big change to the package in Netpbm's\nrenaissance. It and pnmtopng were simply copied from the pnmtopng package\" (1) by Greg\nRoelofs. Those were based on simpler reference applications by Alexander Lehmann\n and Willem van Schaik and distributed with their\nPNG library.\n\nNearly all of the code has changed since it was copied from the pnmtopng package, most of it\njust to improve maintainability.\n\n\n", "subsections": [] }, "AUTHORS": { "content": "Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.\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/pngtopam.html\n\nnetpbm documentation 22 July 2008 Pngtopam User Manual(1)", "subsections": [] } }, "summary": "pngtopam - convert a PNG image into a Netpbm image", "flags": [ { "flag": "", "long": null, "arg": null, "description": "Display various information about the input PNG image and the conversion process. If you want even more information about the PNG image, use pngcheck (not part of Netpbm)." }, { "flag": "", "long": null, "arg": null, "description": "Produce a single output image containing the main image (foreground) and the trans‐ parency channel or transparency mask. This image is in the PAM format with tuple type of either GRAYSCALEALPHA (which has a depth of 2 channels) or RGBALPHA (which has a depth of 4 channels). You can specify only one of -alphapam, -alpha, and -mix. With none of them, pngtopam produces an image of the foreground of the input image and discards transparency in‐ formation. This option was new in Netpbm 10.44 (September 2008)." }, { "flag": "", "long": null, "arg": null, "description": "ther a PBM file or a PGM file, depending on whether different levels of transparency appear. pngtopam discards the main image (the foreground). You can specify only one of -alphapam, -alpha, and -mix. With none of them, pngtopam produces an image of the foreground of the input image and discards transparency in‐ formation." }, { "flag": "", "long": null, "arg": null, "description": "The background color is determined by the bKGD chunk in the PNG, except that you can override it with -background. If the PNG has no bKGD chunk and you don't specify -background, the background color is white. You can specify only one of -alphapam, -alpha, and -mix. With none of them, pngtopam produces an image of the foreground of the input image and discards transparency in‐ formation." }, { "flag": "", "long": null, "arg": null, "description": "This option specifies the background color with which to mix the image when you spec‐ ify -mix. color is as described for the \u001b]8;;libnetpbmimage.html#colorname\u001b\\argument of the pnmparsecolor() library routine\u001b]8;;\u001b\\ . Examples: • -background=rgb:01/ff/80 • -background=rgbi:1/255/128 If you don't specify -background, the background color is what is specified in the PNG image, and if the PNG doesn't specify anything, white. You cannot specify -background unless you also specify -mix. Before Netpbm 10.27 (March 2005), you could specify -background without -mix and it was just ignored. (This caused a usability problem)." }, { "flag": "", "long": null, "arg": null, "description": "This option causes pngtopam to respect the image gamma information in the PNG file (from the gAMA chunk). Probably by historical accident, pngtopam ignores that infor‐ mation by default, assuming the image uses the same gamma transformation as a Netpbm image, so the output image has different colors than the PNG file actually represents if the PNG doesn't actually do that. (However, it is rare for a PNG file to use a gamma transformation different from what the Netpbm formats specify, or if it does, to specify with a gAMA chuck what that is). But when you do specify -gamma, you get a rather strange additional function, probably a historical mistake: pngtopam incorporates the specified screen gamma value into the output pixels, so that the samples in the Netpbm output deviate from the Netpbm format specifications and are appropriate raw intensity values to send to the display. This function essentially just exercises the ability of the PNG library to make gamma cor‐ rections to the pixels as it reads them from the PNG file to produce values appropri‐ ate for sending to a certain display in certain viewing conditions. It's a strange function because it has nothing to do with PNG and because in Netpbm, the normal way to make gamma corrections appropriate for sending to a ceratin display in certain viewing conditions is with the program pngtopam, applied to the normal output of png‐ topam. If you specify -gamma, but the PNG image does not specify what gamma transformation it uses (there is no gAMA chunk), pngtopam assumes a simple power transformation with an image gamma of 1.0. That is probably not not the actual image gamma; it is much more likely to be .45. Because the gammas of uncompensated monitors are around 2.6, which results in an im‐ age-gamma of 0.45, some typical situations are: when the image-gamma is 0.45 (use -verbose to check) and the picture is too light, your system is gamma-corrected, so convert with \"-gamma 1.0\". When no gAMA chunk is present or the image-gamma is 1.0, use 2.2 to make the picture lighter and 0.45 to make the picture darker. One oddity to be aware of when using -gamma on an image with transparency: The PNG im‐ age specifies that a certain color is transparent, i.e. every pixel in the image of that color is transparent. But pngtopam interprets this as applying to the gamma-cor‐ rected space, and there may be less precision in that space than in the original, which means multiple uncorrected colors map to the same corrected color. So imagine that the image contains 3 shades of white (gray) and specifies that one of them is transparent. After gamma correction, those three shades are indistinguishable, so pngtopam considers pixels of all three shades to be transparent." }, { "flag": "", "long": null, "arg": null, "description": "Writes the tEXt and zTXt chunks to a file, in a format as described in the pnmtopng user manual. These chunks contain text comments or annotations." }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "fail. pngtopam has two ways to do the conversion from PNG to PAM, using respectively two fa‐ cilities of the PNG library: Whole Image Decode the entire image into memory at once, using pngreadimage(), then convert to PAM and output row by row. Row By Row Read, convert, and output one row at a time using pngreadrow(). Whole Image is generally preferable because the PNG library does more of the work, which means it understands more of the PNG format possibilities now and in the future. Also, if the PNG is interlaced, pngtopam does not know how to assemble the rows in the right order. Row By Row uses far less memory, which means with large images, it can run in environ‐ ments where Whole Image cannot and may also run faster. And because Netpbm code does more of the work, it's possible that it can be more flexible or at least give better diagnostic information if there's something wrong with the PNG. The Netpbm native code may do something correctly that the PNG library does incor‐ rectly, or vice versa. In Netpbm, we stress function over performance, so by default pngtopam uses Whole Im‐ age. You can select Row By Row with -byrow if you want the speed or resource require‐ ment improvement. -byrow was new in Netpbm 10.54 (March 2011)." }, { "flag": "", "long": null, "arg": null, "description": "A TIFF stream contains raster data which can be arranged in the stream various ways. Most commonly, it is arranged by rows, with the top row first, and the pixels left to right within each row, but many other orientations are possible. The common orientation is the same on the Netpbm formats use, so tifftopnm can do its jobs quite efficiently when the TIFF raster is oriented that way. But if the TIFF raster is oriented any other way, it can take a considerable amount of processing for tifftopnm to convert it to Netpbm format." } ], "examples": [], "see_also": [ { "name": "pamtopng", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pamtopng/1/json" }, { "name": "pnmtopng", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnmtopng/1/json" }, { "name": "pngtopnm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pngtopnm/1/json" }, { "name": "pnmgamma", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnmgamma/1/json" }, { "name": "pnm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnm/1/json" } ], "tldr": { "source": "official", "description": "Convert a PNG image to a Netpbm image.", "examples": [ { "description": "Convert the specified PNG image to a Netpbm image", "command": "pngtopam {{path/to/image.png}} > {{path/to/output.pam}}" }, { "description": "Create an output image that includes both the main image and transparency mask of the input image", "command": "pngtopam -alphapam {{path/to/image.png}} > {{path/to/output.pam}}" }, { "description": "Replace transparent pixels by the specified color", "command": "pngtopam {{-m|-mix}} {{-ba|-background}} {{color}} {{path/to/image.png}} > {{path/to/output.pam}}" }, { "description": "Write tEXt chunks found in the input image to the specified text file", "command": "pngtopam {{-te|-text}} {{path/to/file.txt}} {{path/to/image.png}} > {{path/to/output.pam}}" } ] } }