{ "content": [ { "type": "text", "text": "# pamlookup (man)\n\n## NAME\n\npamlookup - map an image to a new image by using it as indices into a table\n\n## SYNOPSIS\n\npamlookup -lookupfile=lookupfile [-byplane] -missingcolor=color [-fit] indexfile\nAll options can be abbreviated to their shortest unique prefix. You may use two hyphens in‐\nstead of one. You may separate an option name and its value with white space instead of an\nequals sign.\n\n## DESCRIPTION\n\nThis program is part of Netpbm(1).\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (4 subsections)\n- **OPTIONS** (4 subsections)\n- **EXAMPLES** (2 subsections)\n- **SEE ALSO**\n- **HISTORY**\n- **DOCUMENT SOURCE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "pamlookup", "section": "", "mode": "man", "summary": "pamlookup - map an image to a new image by using it as indices into a table", "synopsis": "pamlookup -lookupfile=lookupfile [-byplane] -missingcolor=color [-fit] indexfile\nAll options can be abbreviated to their shortest unique prefix. You may use two hyphens in‐\nstead of one. You may separate an option name and its value with white space instead of an\nequals sign.", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "", "long": null, "arg": null, "description": "lookupfile names the file that contains the PAM or PNM image that is the lookup table. This option is mandatory." }, { "flag": "", "long": null, "arg": null, "description": "This options selects by plane indexing. The default is whole tuple indexing. This option was new in Netpbm 10.72 (September 2015). Before that, there is no by plane indexing." }, { "flag": "", "long": null, "arg": null, "description": "This option is meaningful only if the lookup image (and therefore the output) is a PNM image. color specifies the color that is to go in the output wherever the index from the input is not present in the lookup table (not present means the index exceeds the dimensions of the lookup image -- e.g. index is 100 but the lookup image is a 50 x 1 PPM). If you don't specify this option or -fit, pamlookup uses the value from the top left corner of the lookup image whenever an index exceeds the dimensions of the lookup im‐ age. Specify the color (color) as described for the \u001b]8;;libnetpbmimage.html#colorname\u001b\\argument of the pnmparsecolor() li‐ brary routine\u001b]8;;\u001b\\ . Another way to deal with a too-small lookup image is to use the -fit option. This option has no effect if you also specify -fit or -byplane." }, { "flag": "", "long": null, "arg": null, "description": "present in the index image, per the index image's maxval. For example, if your index image has a single plane and a maxval of 255 and your lookup image is 1 row of 10 columns, pamlookup stretches your lookup image to 255 columns before doing the lookups. pamlookup does the stretching (or shrinking) with the pamscale(1) program. When you use -fit, pamlookup never fails or warns you because of invalid lookup image dimensions, and the -missingcolor option has no effect. -fit has no effect when you specify -byplane. pamlookup always has the behavior re‐ quested by -fit when it does by plane indexing." } ], "examples": [ "Say you have a set of rainfall data in a single plane PAM image. The rows and columns of the", "PAM indicate latitude and longitude. The sample values are the annual rainfall in (whole)", "centimeters. The highest rainfall value in the image is 199 centimeters. The image is in", "the file rainfall.pam.", "You want to produce a PPM rainfall map with green for the wettest places, red for the driest,", "and other colors in between.", "First, compose a lookup table image, probably with a graphical editor and the image blown way", "up so you can work with individual pixels. The image must have a single row and 200 columns.", "Make the leftmost pixel red and the rightmost pixel green and choose appropriate colors in", "between. Call it colorkey.ppm.", "pamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm", "Now lets say you're too lazy to type in 200 color values and nobody really cares about the", "places that have more than 99 centimeters of annual rainfall. In that case, just make col‐", "orkey.ppm 100 columns wide and do this:", "pamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \\", ">rainfallmap.ppm", "Now if there are areas that get more than 100 centimeters of rainfall, they will just show up", "black in the output.", "Say you want to compare two PBM (black and white) images visually. Each consists of black", "foreground pixels on a white background. You want to create an image that contains back‐", "ground where both images contain background and foreground where both images contain fore‐", "ground. But where Image 1 has a foreground pixel and Image 2 does not, you want red in the", "output; where Image 2 has a foreground pixel and Image 1 does not, you want green.", "First, we create a single image that contains the information from both input PBMs:", "pamstack image1.pbm image2.pbm >bothimages.pam", "Note that this image has 1 of 4 possible tuple values at each location: (0,0), (0,1), (1,0),", "or (1,1).", "Now, we create a lookup table that we can index with those 4 values:", "ppmmake white 1 1 >white.ppm", "ppmmake black 1 1 >black.ppm", "ppmmake red 1 1 >red.ppm", "ppmmake green 1 1 >green.ppm", "pamcat -leftright black.ppm red.ppm >blackred.ppm", "pamcat -leftright green.ppm white.ppm >greenwhite.ppm", "pamcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm", "Finally, we look up the indices from our index in our lookup table and produce the output:", "pamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm" ], "see_also": [ { "name": "pamunlookup", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pamunlookup/1/json" }, { "name": "pnmremap", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnmremap/1/json" }, { "name": "ppmmake", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/ppmmake/1/json" }, { "name": "pamcat", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pamcat/1/json" }, { "name": "pamstack", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pamstack/1/json" }, { "name": "pnm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pnm/1/json" }, { "name": "pam", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pam/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 3, "subsections": [] }, { "name": "SYNOPSIS", "lines": 7, "subsections": [] }, { "name": "DESCRIPTION", "lines": 38, "subsections": [ { "name": "The Lookup Table Image", "lines": 36 }, { "name": "Example - Whole Tuple Indexing", "lines": 31 }, { "name": "Example - By Plane Indexing", "lines": 19 }, { "name": "Miscellaneous", "lines": 12 } ] }, { "name": "OPTIONS", "lines": 5, "subsections": [ { "name": "-lookupfile=_", "lines": 4 }, { "name": "-byplane", "lines": 6 }, { "name": "-missingcolor=_", "lines": 18 }, { "name": "-fit", "lines": 14 } ] }, { "name": "EXAMPLES", "lines": 1, "subsections": [ { "name": "Example: rainfall map", "lines": 28 }, { "name": "Example: graphical diff", "lines": 32 } ] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] }, { "name": "HISTORY", "lines": 2, "subsections": [] }, { "name": "DOCUMENT SOURCE", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "pamlookup - map an image to a new image by using it as indices into a table\n\n", "subsections": [] }, "SYNOPSIS": { "content": "pamlookup -lookupfile=lookupfile [-byplane] -missingcolor=color [-fit] indexfile\n\nAll options can be abbreviated to their shortest unique prefix. You may use two hyphens in‐\nstead of one. You may separate an option name and its value with white space instead of an\nequals sign.\n\n", "subsections": [] }, "DESCRIPTION": { "content": "This program is part of Netpbm(1).\n\npamlookup takes a two dimensional array of indices and a lookup table as input. For each po‐\nsition in the index array, it looks up the index in the lookup table and places the result of\nthe lookup in the output image.\n\nThere are two ways of indexing the lookup table: whole tuple and by plane. The -byplane op‐\ntion controls which pamlookup does.\n\nIn the simplest form of whole tuple indexing, each index in the index array is a single whole\nnumber and the lookup table associates a whole tuple with each possible whole number index.\nSo for example, the index array might have at Row 2, Column 9 the value 23. The lookup table\nmight associate the tuple (1,2,3) with the value 23. In that case, the output image contains\nthe tuple (1,2,3) at Row 2, Column 9.\n\nIn a more complex form of whole tuple indexing, each index in the index array is an ordered\npair of whole numbers and the lookup table associates a whole tuple with each possible or‐\ndered pair index. Modifying the example above, the index value could be (23, 5) instead of\n23.\n\nWith whole tuple indexing, the output thus has the same width and height as the index image,\nand tuple depth and type and maxval are determined by the lookup table.\n\nWith whole tuple indexing, if the index image has depth 1, its sample values are single whole\nnumber indices. If the index image has depth greater than 1, its tuples are ordered pair in‐\ndices composed of the first and second sample in the tuple.\n\nIn by-plane indexing, the index image contains whole number indices. Each sample in the in‐\ndex image is an index. The lookup table maps each whole number index to another whole num‐\nber. pamlookup looks up the sample at each row, column, and plane in the index image in the\nlookup table and uses the resulting whole number as the sample value for the same row, col‐\numn, and plane in the output.\n\nWith by-plane indexing, the output thus has the same dimensions as the index image an the\nsame maxval as the lookup image.\n\n\n", "subsections": [ { "name": "The Lookup Table Image", "content": "The lookup table is a PAM or PNM image. If the index image contains whole number indices,\nthe lookup image is a single row and the index is a column number. The lookup result is the\nvalue of the tuple or pixel at the indicated column in the one row in the lookup table. If\nthe index image contains ordered pair indices, the first element of the ordered pair is a row\nnumber and the second element of the ordered pair is a column number. The lookup result is\nthe value of the tuple or pixel at the indicated row and column in the lookup table.\n\nThe width of the lookup image should normally be the maxval of the index image plus one, so\nthat each possible index sample value corresponds to one entry in the lookup table. There\nare two ways pamlookup deals with a lookup image that does not have such a width:\n\n\n\n• Scale the lookup image to the required width. pamlookup always does this with by\nplane indexing, and with whole tuple indexing, does it when you specify -fit.\n\n\n• Use a default value for indices that exceed the width of the lookup image and ignore\nlookup image columns beyond the maxval of the index image. pamlookup does this with\nwhole tuple indexing when you don't specify -fit.\n\nYou specify the default value with a -missingcolor option; it defaults to the value\nfrom the top left corner of the lookup image.\n\n\nWith ordered pair indexes (which implies whole tuple indexing), the same rule applies to the\nheight of the index image as to the width.\n\nThe mandatory -lookupfile option identifies the file containing the lookup table image. -\nmeans Standard Input. It won't work if both the index image file and lookup table file are\nStandard Input.\n\nYou can use ppmmake and pamcat to create a lookup table file.\n\n\n" }, { "name": "Example - Whole Tuple Indexing", "content": "Here is an example of pamlookup's function with whole tuple indexing (-byplane not speci‐\nfied).\n\nConsider an index image consisting of a 3x2x1 PAM as follows:\n\n0 1 0\n2 2 2\n\nand a lookup table consisting of a 3x1 PPM image as follows:\n\nred yellow beige\n\nThe lookup table above says Index 0 corresponds to the color red, Index 1 corresponds to yel‐\nlow, and Index 2 corresponds to beige. The output of pamlookup is the following PPM image:\n\nred yellow red\nbeige beige beige\n\nNow let's look at an example of the more complex case where the indices are ordered pairs of\nwhole numbers instead of whole numbers. Our index image will be this 3x2x2 PAM image:\n\n(0,0) (0,1) (0,0)\n(1,1) (1,0) (0,0)\n\nOur lookup table for the example will be this two dimensional PPM:\n\nred yellow red\nblack green red\n\n\n" }, { "name": "Example - By Plane Indexing", "content": "Here is an example of pamlookup's function with by plane tuple indexing (-byplane specified).\n\nConsider an index image consisting of a 3x2x3 PAM as follows:\n\n(0,0,0) (1,0,0) (2,0,0)\n(2,2,0) (2,0,2) (2,0,0)\n\nand a lookup table consisting of a 3x1x1 PAM image with maxval 7 as follows:\n\n3 4 7\n\nThe lookup table above says Index 0 corresponds to the sample value 3, Index 1 corresponds to\n4, and Index 2 corresponds to 7. The output of pamlookup is the following 3x2x3 PAM image:\n\n(3,3,3) (4,3,3) (7,3,3)\n(7,7,3) (7,3,7) (7,3,3)\n\n\n" }, { "name": "Miscellaneous", "content": "The indexfile argument identifies the file containing the index PAM or PNM image. - means\nStandard Input. It won't work if both the index image file and lookup table file are Stan‐\ndard Input.\n\nThe output image goes to Standard Output.\n\nIf you want to use two separate 1-plane images as indices (so that your output reflects the\ncombination of both inputs), use pamstack to combine the two into one two-plane image (and\nuse a 2-dimensional lookup table image).\n\n\n" } ] }, "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\\ ), pamlookup recognizes the following command line options:\n\n\n", "subsections": [ { "name": "-lookupfile=_", "content": "lookupfile names the file that contains the PAM or PNM image that is the lookup table.\nThis option is mandatory.\n\n" }, { "name": "-byplane", "content": "This options selects by plane indexing. The default is whole tuple indexing.\n\nThis option was new in Netpbm 10.72 (September 2015). Before that, there is no by\nplane indexing.\n\n" }, { "name": "-missingcolor=_", "content": "This option is meaningful only if the lookup image (and therefore the output) is a PNM\nimage. color specifies the color that is to go in the output wherever the index from\nthe input is not present in the lookup table (not present means the index exceeds the\ndimensions of the lookup image -- e.g. index is 100 but the lookup image is a 50 x 1\nPPM).\n\nIf you don't specify this option or -fit, pamlookup uses the value from the top left\ncorner of the lookup image whenever an index exceeds the dimensions of the lookup im‐\nage.\n\nSpecify the color (color) as described for the \u001b]8;;libnetpbmimage.html#colorname\u001b\\argument of the pnmparsecolor() li‐\nbrary routine\u001b]8;;\u001b\\ .\n\nAnother way to deal with a too-small lookup image is to use the -fit option.\n\nThis option has no effect if you also specify -fit or -byplane.\n\n" }, { "name": "-fit", "content": "present in the index image, per the index image's maxval. For example, if your index\nimage has a single plane and a maxval of 255 and your lookup image is 1 row of 10\ncolumns, pamlookup stretches your lookup image to 255 columns before doing the\nlookups. pamlookup does the stretching (or shrinking) with the pamscale(1) program.\n\nWhen you use -fit, pamlookup never fails or warns you because of invalid lookup image\ndimensions, and the -missingcolor option has no effect.\n\n-fit has no effect when you specify -byplane. pamlookup always has the behavior re‐\nquested by -fit when it does by plane indexing.\n\n\n\n" } ] }, "EXAMPLES": { "content": "", "subsections": [ { "name": "Example: rainfall map", "content": "Say you have a set of rainfall data in a single plane PAM image. The rows and columns of the\nPAM indicate latitude and longitude. The sample values are the annual rainfall in (whole)\ncentimeters. The highest rainfall value in the image is 199 centimeters. The image is in\nthe file rainfall.pam.\n\nYou want to produce a PPM rainfall map with green for the wettest places, red for the driest,\nand other colors in between.\n\nFirst, compose a lookup table image, probably with a graphical editor and the image blown way\nup so you can work with individual pixels. The image must have a single row and 200 columns.\nMake the leftmost pixel red and the rightmost pixel green and choose appropriate colors in\nbetween. Call it colorkey.ppm.\n\npamlookup rainfall.pam -lookupfile=colorkey.ppm >rainfallmap.ppm\n\n\nNow lets say you're too lazy to type in 200 color values and nobody really cares about the\nplaces that have more than 99 centimeters of annual rainfall. In that case, just make col‐\norkey.ppm 100 columns wide and do this:\n\npamlookup rainfall.ppm -lookupfile=colorkey.ppm -missingcolor=black \\\n>rainfallmap.ppm\n\n\nNow if there are areas that get more than 100 centimeters of rainfall, they will just show up\nblack in the output.\n\n" }, { "name": "Example: graphical diff", "content": "Say you want to compare two PBM (black and white) images visually. Each consists of black\nforeground pixels on a white background. You want to create an image that contains back‐\nground where both images contain background and foreground where both images contain fore‐\nground. But where Image 1 has a foreground pixel and Image 2 does not, you want red in the\noutput; where Image 2 has a foreground pixel and Image 1 does not, you want green.\n\nFirst, we create a single image that contains the information from both input PBMs:\n\npamstack image1.pbm image2.pbm >bothimages.pam\n\n\nNote that this image has 1 of 4 possible tuple values at each location: (0,0), (0,1), (1,0),\nor (1,1).\n\nNow, we create a lookup table that we can index with those 4 values:\n\nppmmake white 1 1 >white.ppm\nppmmake black 1 1 >black.ppm\nppmmake red 1 1 >red.ppm\nppmmake green 1 1 >green.ppm\npamcat -leftright black.ppm red.ppm >blackred.ppm\npamcat -leftright green.ppm white.ppm >greenwhite.ppm\npamcat -topbottom blackred.ppm greenwhite.ppm >lookup.ppm\n\n\nFinally, we look up the indices from our index in our lookup table and produce the output:\n\npamlookup bothimages.ppm -lookupfile=lookup.ppm >imagediff.ppm\n\n\n\n" } ] }, "SEE ALSO": { "content": "pamunlookup(1), pnmremap(1), ppmmake(1), pamcat(1), pamstack(1), pnm(1), pam(1)\n\n\n", "subsections": [] }, "HISTORY": { "content": "pamlookup was new in Netpbm 10.13 (December 2002).\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/pamlookup.html\n\nnetpbm documentation 25 July 2015 Pamlookup User Manual(1)", "subsections": [] } } } }