{ "content": [ { "type": "text", "text": "# pnmgamma (man)\n\n## NAME\n\npnmgamma - perform gamma adjustment on a PNM image\n\n## SYNOPSIS\n\npnmgamma {\n-bt709tolinear |\n-lineartobt709 |\n-bt709tosrgb |\n-srgbtobt709 } [-gamma=float] [-rgamma=float] [-ggamma=float] [-bgamma=float]\n[pnmfile]\npnmgamma [\n-bt709ramp |\n-srgbramp ] [-ungamma] [{gamma | redgamma greengamma bluegamma} [pnmfile]]\n\n## DESCRIPTION\n\nThis program is part of Netpbm(1).\n\n## TLDR\n\n> Perform gamma correction on PNM images.\n\n- Convert the image from BT.709 luminance to radiance or sRGB luminance:\n `pnmgamma -{{bt709tolinear|bt709tosrgb}} {{path/to/image.pnm}} > {{path/to/output.pnm}}`\n- Convert the image from radiance or sRGB luminance to BT.709 luminance:\n `pnmgamma -{{lineartobt709|srgbtobt709}} {{path/to/image.pnm}} > {{path/to/output.pnm}}`\n- Specify the gamma value used for the gamma transfer function:\n `pnmgamma {{-ga|-gamma}} {{value}} {{path/to/image.pnm}} > {{path/to/output.pnm}}`\n- Specify the gamma value used for the gamma transfer function per color component:\n `pnmgamma {{-rg|-rgamma}} {{value}} {{-gg|-ggamma}} {{value}} {{-bg|-bgamma}} {{value}} {{path/to/image.pnm}} > {{path/to/output.pnm}}`\n\n*Source: tldr-pages*\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **PARAMETERS**\n- **OPTIONS** (13 subsections)\n- **SEE ALSO**\n- **AUTHOR**\n- **DOCUMENT SOURCE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "pnmgamma", "section": "", "mode": "man", "summary": "pnmgamma - perform gamma adjustment on a PNM image", "synopsis": "pnmgamma {\n-bt709tolinear |\n-lineartobt709 |\n-bt709tosrgb |\n-srgbtobt709 } [-gamma=float] [-rgamma=float] [-ggamma=float] [-bgamma=float]\n[pnmfile]\npnmgamma [\n-bt709ramp |\n-srgbramp ] [-ungamma] [{gamma | redgamma greengamma bluegamma} [pnmfile]]", "tldr_summary": "Perform gamma correction on PNM images.", "tldr_examples": [ { "description": "Convert the image from BT.709 luminance to radiance or sRGB luminance", "command": "pnmgamma -{{bt709tolinear|bt709tosrgb}} {{path/to/image.pnm}} > {{path/to/output.pnm}}" }, { "description": "Convert the image from radiance or sRGB luminance to BT.709 luminance", "command": "pnmgamma -{{lineartobt709|srgbtobt709}} {{path/to/image.pnm}} > {{path/to/output.pnm}}" }, { "description": "Specify the gamma value used for the gamma transfer function", "command": "pnmgamma {{-ga|-gamma}} {{value}} {{path/to/image.pnm}} > {{path/to/output.pnm}}" }, { "description": "Specify the gamma value used for the gamma transfer function per color component", "command": "pnmgamma {{-rg|-rgamma}} {{value}} {{-gg|-ggamma}} {{value}} {{-bg|-bgamma}} {{value}} {{path/to/image.pnm}} > {{path/to/output.pnm}}" } ], "tldr_source": "official", "flags": [ { "flag": "", "long": null, "arg": null, "description": "Convert the image from BT.709 luminance to radiance. I.e. convert from true PPM or PGM to a radiance-linear variation that can be used with certain tools that need it. This option was new in Netpbm 10.32 (February 2006)." }, { "flag": "", "long": null, "arg": null, "description": "Convert the image from radiance to BT.709 luminance. I.e. convert to true PPM or PGM from a radiance-linear variation. You get true BT.709 (ergo true PPM or PGM) only if you use the default gamma value (i.e. don't specify -gamma, etc.). This option was new in Netpbm 10.32 (February 2006)." }, { "flag": "", "long": null, "arg": null, "description": "Convert the image from BT.709 luminance to SRGB luminance. I.e. convert from true PPM or PGM to an SRGB-based variation that is required by certain tools and display de‐ vices. You get true SRGB only if you use the default gamma value (i.e. don't specify -gamma, etc.). This option was new in Netpbm 10.32 (February 2006)." }, { "flag": "", "long": null, "arg": null, "description": "Convert the image from SRGB luminance to BT.709 luminance. I.e. convert to true PPM or PGM from an SRGB-based variation. This option was new in Netpbm 10.32 (February 2006)." }, { "flag": "", "long": null, "arg": null, "description": "Same as -lineartobt709, but using the old syntax. This option was renamed in Netpbm 10.32 (February 2006). Before that, its name is -cieramp." }, { "flag": "", "long": null, "arg": null, "description": "This is an obsolete synonym for -bt709ramp. The name of this option comes from a former belief that this was a standard of CIE (International Commission On Illumination), but it now (August 2005) looks like it never was." }, { "flag": "", "long": null, "arg": null, "description": "Convert the image from radiance to SRGB luminance. Note that it is true SRGB only if you use the default gamma value (i.e. don't specify any gamma parameters). This is an old syntax option. There is no equivalent in the new syntax because it re‐ ally shouldn't be a function of pnmgamma at all. It exists solely for backward com‐ patibility. The reason it shouldn't exist is that the way to do this conversion con‐ sistent with the Netpbm philosophy is do a -lineartobt709 followed by a -bt709tosrgb. It's exactly analogous to the way you have to convert from PNG to TIFF by doing a png‐ topam followed by a pnmtotiff. The -srgbramp option actually dates to before there was a standard definition of what the sample values of a Netpbm image measure, and pn‐ mgamma considered radiance-linear to be the proper intermediate format." }, { "flag": "", "long": null, "arg": null, "description": "Apply the inverse of the specified transfer function (i.e. go from gamma-adjusted lu‐ minance to radiance). This is valid only with -bt709ramp (aka -cieramp), -srgbramp, and the default exponen‐ tial transfer function." }, { "flag": "", "long": null, "arg": null, "description": "This specifies the gamma value to use in the transfer function. All of the transfer functions involve an exponent, and the gamma value is that exponent. The standards specify a particular gamma value. If you use anything else, you are varying from the standard. The default is the standard value. For the simple exponential transfer function (which is not a standard), the default is 2.2. In the -bt709tosrgb and -srgbtobt709 conversions there are two exponents. -gamma af‐ fects the \"to\" function; the \"from\" function always uses the standard gamma value. If you specify one of the component-specific options (-rgamma, etc.), that overrides the -gamma value. With the -bt709ramp (aka -cieramp), -srgbramp, or the default exponential transfer function, you can't actually use this option, but you specify the same thing with \u001b]8;;#parameters\u001b\\parameters.\u001b]8;;\u001b\\ This option was new in Netpbm 10.32 (February 2006)." }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "" }, { "flag": "", "long": null, "arg": null, "description": "These options are just like -gamma, except they specify the value for a particular one of the color components. If you don't specify this option for a particular color component, the default is the -gamma value (or -gamma's default if you didn't specify that either). With the -bt709ramp (aka -cieramp), -srgbramp, or the default exponential transfer function, you can't actually use this option, but you specify the same thing with \u001b]8;;#parameters\u001b\\parameters.\u001b]8;;\u001b\\ This option was new in Netpbm 10.32 (February 2006)." }, { "flag": "", "long": null, "arg": null, "description": "This is the maxval of the output image. By default, the maxval of the output is the same as that of the input. Because the transformation is not linear, you need a greater maxval in the output in order not to lose any information from the input. For example, if you convert to ra‐ diance-linear sample values with -ungamma -bt709ramp and default gamma value, and your maxval is 255 on both input and output, 3 different input sample values all generate output sample value 254. In order to have a different output sample value for each input sample value, you would need an output maxval at least 3 times the input maxval. This option was new in Netpbm 10.32 (February 2006). Before that, you can achieve the same result by increasing the maxval of the input or decreasing the maxval of the out‐ put using pamdepth. WHAT IS GAMMA? A good explanation of gamma is in Charles Poynton's Gamma FAQ at http://www.poynton.com/Gam‐ maFAQ.html\" (1) and Color FAQ at http://www.poynton.com/ColorFAQ.html\" (1). In brief: The simplest way to code an image is by using sample values that are directly pro‐ portional to the radiance of the color components. Radiance is a physical quantification based on the amount of power in the light; it is easily measurable in a laboratory, but does not take into account what the light looks like to a person. It wastes the sample space be‐ cause the human eye can't discern differences between low-radiance colors as well as it can between high-radiance colors. So instead, we pass the radiance values through a transfer function that makes it so that changing a sample value by 1 causes the same level of per‐ ceived color change anywhere in the sample range. We store those resulting values in the im‐ age file. That transfer function is called the gamma transfer function and the transforma‐ tion is called gamma adjusting. The gamma-adjusted value, proportional to subjective brightness, are known as the luminance of the pixel. There is no precise objective way to measure luminance, since it's psychological. Also, per‐ ception of brightness varies according to a variety of factors, including the surrounding in which an image is viewed. Therefore, there is not just one gamma transfer function. Virtually all image formats, either specified or de facto, use gamma-adjusted values for their sample values. What's really nice about gamma is that by coincidence, the inverse function that you have to do to convert the gamma-adjusted values back to radiance is done automatically by CRTs. You just apply a voltage to the CRT's electron gun that is proportional to the gamma-adjusted sample value, and the radiance of the light that comes out of the screen is close to the ra‐ diance value you had before you applied the gamma transfer function! And when you consider that computer video devices usually want you to store in video memory a value proportional to the signal voltage you want to go to the monitor, which the monitor turns into a proportional drive voltage on the electron gun, it is really convenient to work with gamma-adjusted sample values." } ], "examples": [], "see_also": [ { "name": "pnm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnm/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 3, "subsections": [] }, { "name": "SYNOPSIS", "lines": 14, "subsections": [] }, { "name": "DESCRIPTION", "lines": 40, "subsections": [] }, { "name": "PARAMETERS", "lines": 15, "subsections": [] }, { "name": "OPTIONS", "lines": 6, "subsections": [ { "name": "-bt709tolinear", "lines": 6 }, { "name": "-lineartobt709", "lines": 9 }, { "name": "-bt709tosrgb", "lines": 10 }, { "name": "-srgbtobt709", "lines": 6 }, { "name": "-bt709ramp", "lines": 6 }, { "name": "-cieramp", "lines": 7 }, { "name": "-srgbramp", "lines": 13 }, { "name": "-ungamma", "lines": 7 }, { "name": "-gamma=_", "lines": 22 }, { "name": "-rgamma=_", "lines": 1 }, { "name": "-ggamma=_", "lines": 1 }, { "name": "-bgamma=_", "lines": 13 }, { "name": "-maxval=_", "lines": 54 } ] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "DOCUMENT SOURCE", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "pnmgamma - perform gamma adjustment on a PNM image\n\n", "subsections": [] }, "SYNOPSIS": { "content": "pnmgamma {\n-bt709tolinear |\n-lineartobt709 |\n-bt709tosrgb |\n-srgbtobt709 } [-gamma=float] [-rgamma=float] [-ggamma=float] [-bgamma=float]\n\n[pnmfile]\n\npnmgamma [\n-bt709ramp |\n-srgbramp ] [-ungamma] [{gamma | redgamma greengamma bluegamma} [pnmfile]]\n\n\n", "subsections": [] }, "DESCRIPTION": { "content": "This program is part of Netpbm(1).\n\nPnmgamma performs gamma adjustment on pseudo-PNM images.\n\nThe PPM format specification specifies that certain sample values in a file represent certain\nlight intensities in an image. In particular, they specify that the sample values are di‐\nrectly proportional to luminance as defined by ITU-R Recommendation BT.709. BT.709 luminance\nas a function of radiance is a power function modified with a linear ramp near black.\n\nHowever, people sometimes work with approximations of PPM and PGM where the sample values\nrepresent intensity in different ways:\n\nIn one common variation, the sample value is directly proportional to radiance (often called\n\"linear intensity\").\n\nAnother popular variation is to make the samples proportional to luminance as defined by the\nInternational Electrotechnical Commission (IEC) SRGB standard. The SRGB gamma transfer func‐\ntion is like the BT.709 one except with different constants in it.\n\nNote that SRGB is often spelled \"sRGB\". In this document, we use standard English typogra‐\nphy, though, which doesn't allow for that kind of capitalization.\n\npnmgamma allows you to manipulate the gamma transfer function, thus working with and/or cre‐\nating pseudo-PPM files that are useful for various things.\n\nFor example, if you feed a true PPM to pnmgamma -bt709tolinear , you get as output a file\nwhich is PPM in every respect except that the sample values are radiances. If you feed such\na file to pnmgamma -linearto709, you get back a true PPM.\n\nThe situation for PGM images is analogous. And pnmgamma treats PBM images as PGM images.\n\nWhen you feed a radiance-proportional pseudo-PPM image to a display program that expects a\ntrue PPM, the display appears darker than it should, so pnmgamma has the effect of lightening\nthe image. When you feed a true PPM to a display program that expects radiance-proportional\nsample values, and therefore does a gamma adjustment of its own on them, the display appears\nlighter than it should, so pnmgamma with a gamma value less than one (the multiplicative in‐\nverse of whatever gamma value the display program uses) has the effect of darkening the im‐\nage.\n\n", "subsections": [] }, "PARAMETERS": { "content": "The form of the parameters depends on whether you're using the old syntax or the new syntax.\nWith the old syntax, the parameters are a mixture of gamma values and the input file name.\nWith the new syntax, the only parameter is the input file name and you specify gamma values\nwith option.\n\nYou use the old syntax if you specify -bt709ramp (or its synonym -cieramp) or -srgramp or if\nyou don't specify any transfer function at all (and thus default to a simple exponential).\nOtherwise, you use the new syntax.\n\nWith the old syntax, you may specify a single gamma value or 3 separate gamma values (red,\ngreen, and blue) or no gamma values. In any case, the meanings of those parameters is the\nsame as the more modern -gamma, -rgamma, -ggamma, and -bgamma options described below.\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\\ ), pnmgamma recognizes the following command line options:\n\n\n\n", "subsections": [ { "name": "-bt709tolinear", "content": "Convert the image from BT.709 luminance to radiance. I.e. convert from true PPM or\nPGM to a radiance-linear variation that can be used with certain tools that need it.\n\nThis option was new in Netpbm 10.32 (February 2006).\n\n" }, { "name": "-lineartobt709", "content": "Convert the image from radiance to BT.709 luminance. I.e. convert to true PPM or PGM\nfrom a radiance-linear variation.\n\nYou get true BT.709 (ergo true PPM or PGM) only if you use the default gamma value\n(i.e. don't specify -gamma, etc.).\n\nThis option was new in Netpbm 10.32 (February 2006).\n\n" }, { "name": "-bt709tosrgb", "content": "Convert the image from BT.709 luminance to SRGB luminance. I.e. convert from true PPM\nor PGM to an SRGB-based variation that is required by certain tools and display de‐\nvices.\n\nYou get true SRGB only if you use the default gamma value (i.e. don't specify -gamma,\netc.).\n\nThis option was new in Netpbm 10.32 (February 2006).\n\n" }, { "name": "-srgbtobt709", "content": "Convert the image from SRGB luminance to BT.709 luminance. I.e. convert to true PPM\nor PGM from an SRGB-based variation.\n\nThis option was new in Netpbm 10.32 (February 2006).\n\n" }, { "name": "-bt709ramp", "content": "Same as -lineartobt709, but using the old syntax.\n\nThis option was renamed in Netpbm 10.32 (February 2006). Before that, its name is\n-cieramp.\n\n" }, { "name": "-cieramp", "content": "This is an obsolete synonym for -bt709ramp.\n\nThe name of this option comes from a former belief that this was a standard of CIE\n(International Commission On Illumination), but it now (August 2005) looks like it\nnever was.\n\n" }, { "name": "-srgbramp", "content": "Convert the image from radiance to SRGB luminance. Note that it is true SRGB only if\nyou use the default gamma value (i.e. don't specify any gamma parameters).\n\nThis is an old syntax option. There is no equivalent in the new syntax because it re‐\nally shouldn't be a function of pnmgamma at all. It exists solely for backward com‐\npatibility. The reason it shouldn't exist is that the way to do this conversion con‐\nsistent with the Netpbm philosophy is do a -lineartobt709 followed by a -bt709tosrgb.\nIt's exactly analogous to the way you have to convert from PNG to TIFF by doing a png‐\ntopam followed by a pnmtotiff. The -srgbramp option actually dates to before there\nwas a standard definition of what the sample values of a Netpbm image measure, and pn‐\nmgamma considered radiance-linear to be the proper intermediate format.\n\n" }, { "name": "-ungamma", "content": "Apply the inverse of the specified transfer function (i.e. go from gamma-adjusted lu‐\nminance to radiance).\n\nThis is valid only with -bt709ramp (aka -cieramp), -srgbramp, and the default exponen‐\ntial transfer function.\n\n" }, { "name": "-gamma=_", "content": "This specifies the gamma value to use in the transfer function. All of the transfer\nfunctions involve an exponent, and the gamma value is that exponent.\n\nThe standards specify a particular gamma value. If you use anything else, you are\nvarying from the standard.\n\nThe default is the standard value. For the simple exponential transfer function\n(which is not a standard), the default is 2.2.\n\nIn the -bt709tosrgb and -srgbtobt709 conversions there are two exponents. -gamma af‐\nfects the \"to\" function; the \"from\" function always uses the standard gamma value.\n\nIf you specify one of the component-specific options (-rgamma, etc.), that overrides\nthe -gamma value.\n\nWith the -bt709ramp (aka -cieramp), -srgbramp, or the default exponential transfer\nfunction, you can't actually use this option, but you specify the same thing with\n\u001b]8;;#parameters\u001b\\parameters.\u001b]8;;\u001b\\\n\nThis option was new in Netpbm 10.32 (February 2006).\n\n" }, { "name": "-rgamma=_", "content": "" }, { "name": "-ggamma=_", "content": "" }, { "name": "-bgamma=_", "content": "These options are just like -gamma, except they specify the value for a particular one\nof the color components.\n\nIf you don't specify this option for a particular color component, the default is the\n-gamma value (or -gamma's default if you didn't specify that either).\n\nWith the -bt709ramp (aka -cieramp), -srgbramp, or the default exponential transfer\nfunction, you can't actually use this option, but you specify the same thing with\n\u001b]8;;#parameters\u001b\\parameters.\u001b]8;;\u001b\\\n\nThis option was new in Netpbm 10.32 (February 2006).\n\n" }, { "name": "-maxval=_", "content": "This is the maxval of the output image. By default, the maxval of the output is the\nsame as that of the input.\n\nBecause the transformation is not linear, you need a greater maxval in the output in\norder not to lose any information from the input. For example, if you convert to ra‐\ndiance-linear sample values with -ungamma -bt709ramp and default gamma value, and your\nmaxval is 255 on both input and output, 3 different input sample values all generate\noutput sample value 254. In order to have a different output sample value for each\ninput sample value, you would need an output maxval at least 3 times the input maxval.\n\nThis option was new in Netpbm 10.32 (February 2006). Before that, you can achieve the\nsame result by increasing the maxval of the input or decreasing the maxval of the out‐\nput using pamdepth.\n\n\n\n\nWHAT IS GAMMA?\nA good explanation of gamma is in Charles Poynton's Gamma FAQ at http://www.poynton.com/Gam‐\nmaFAQ.html\" (1) and Color FAQ at http://www.poynton.com/ColorFAQ.html\" (1).\n\nIn brief: The simplest way to code an image is by using sample values that are directly pro‐\nportional to the radiance of the color components. Radiance is a physical quantification\nbased on the amount of power in the light; it is easily measurable in a laboratory, but does\nnot take into account what the light looks like to a person. It wastes the sample space be‐\ncause the human eye can't discern differences between low-radiance colors as well as it can\nbetween high-radiance colors. So instead, we pass the radiance values through a transfer\nfunction that makes it so that changing a sample value by 1 causes the same level of per‐\nceived color change anywhere in the sample range. We store those resulting values in the im‐\nage file. That transfer function is called the gamma transfer function and the transforma‐\ntion is called gamma adjusting.\n\nThe gamma-adjusted value, proportional to subjective brightness, are known as the luminance\nof the pixel.\n\nThere is no precise objective way to measure luminance, since it's psychological. Also, per‐\nception of brightness varies according to a variety of factors, including the surrounding in\nwhich an image is viewed. Therefore, there is not just one gamma transfer function.\n\nVirtually all image formats, either specified or de facto, use gamma-adjusted values for\ntheir sample values.\n\nWhat's really nice about gamma is that by coincidence, the inverse function that you have to\ndo to convert the gamma-adjusted values back to radiance is done automatically by CRTs. You\njust apply a voltage to the CRT's electron gun that is proportional to the gamma-adjusted\nsample value, and the radiance of the light that comes out of the screen is close to the ra‐\ndiance value you had before you applied the gamma transfer function!\n\nAnd when you consider that computer video devices usually want you to store in video memory a\nvalue proportional to the signal voltage you want to go to the monitor, which the monitor\nturns into a proportional drive voltage on the electron gun, it is really convenient to work\nwith gamma-adjusted sample values.\n\n" } ] }, "SEE ALSO": { "content": "pnm(1)\n\n", "subsections": [] }, "AUTHOR": { "content": "Copyright (C) 1991 by Bill Davidson and Jef Poskanzer.\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/pnmgamma.html\n\nnetpbm documentation 30 June 2007 Pnmgamma User Manual(1)", "subsections": [] } } } }