PAMCOMP(1)

📦
version 11.13.03 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ pamcomp ✨

bestie. sit down. hydrate. because today we're talking about pamcomp, and it's genuinely one of the most iconic little gremlins in the Netpbm family. it composites — that's fancy speak for overlays — two Netpbm images together. that's it. that's the job. and it does it SO well. 💖

and yes, before you ask: this is the Pamcomp User Manual(1), straight from the General Commands Manual. we're doing the whole thing. no skimming. periodt. 👑

🌈 NAME 🌈

pamcomp — composite (overlay) two Netpbm images together

like. that's literally it. two images go in, one stacked-on-top-of-the-other image comes out. the way that this is such a simple concept and yet so powerful?? obsessed. 😭✨

🦋 SYNOPSIS 🦋

pamcomp

[-align={left | center | right | beyondleft | beyondright}]
[-valign={top | middle | bottom| above | below}] [-xoff=X] [-yoff=Y]
[-alpha=alpha-pgmfile] [-invert] [-opacity=opacity] [-mixtransparency]
[-linear] overlay_file [underlying_file [output_file]]

okay so a few little quality-of-life notes before you run off, because the command line here is kinder than it looks:

  • minimum unique abbreviation of the option is acceptable — meaning you can be lazy (affectionately) and type just enough letters to be unambiguous. iconic behaviour. 💅
  • you may use double hyphens instead of a single hyphen to denote options. so -alpha and --alpha are both valid, no judgement.
  • you may use white space in place of the equals sign to separate an option name from its value. live your truth.

💜 DESCRIPTION 💜

first things first, queen: this program is part of Netpbm(1). yes, that Netpbm. we're in the family. 🫶

pamcomp reads two images and produces a composite image with one of the images overlayed on top of the other — possibly translucently. the images do not need to be the same size, which is such a relief honestly. the inputs and outputs are all Netpbm format image files.

in its simplest use, pamcomp just places the image in the file overlay_file on top of the image in the file underlying_file, blocking out the part of underlying_file beneath it. layering. stacking. cunty. ✨

now, if you add the -alpha option, then pamcomp uses the image in file alpha-pgmfile as a transparency mask, which means it determines the level of transparency of each point in the overlay image. the transparency mask must have the same dimensions as the overlay image — no exceptions bestie, it's not a suggestion. 💀

here's how that plays out:

  • where the transparency mask defines the overlay image to be opaque, the composite output contains only the contents of the overlay image — the underlying image is totally blocked out.
  • where the transparency mask defines the overlay image to be transparent, the composite output contains none of the overlay image — the underlying image shows through completely.
  • where the transparency mask shows a value in between opaque and transparent (that's the translucence zone 🌫️), the composite image contains a mixture of the overlay image and the underlying image, and the level of translucence determines how much of each.

the transparency mask is a PGM file in which a white pixel represents opaqueness and a black pixel transparency. anything in between is translucent. and listen — (like any Netpbm program, pamcomp will see a PBM file as if it is PGM). good to know. noted. 🎀

🧚 a lil plot twist: PAM transparency 🧚

if the overlay image is a PAM image of tuple type RGB_ALPHA or GRAYSCALE_ALPHA, then the overlay image contains transparency information itself, and pamcomp uses it the same way as the transparency mask described above. self-sufficient. independent. main character energy. 💅

and if you supply both an overlay image that has transparency information and a transparency mask, pamcomp multiplies the two opacities to get the opacity of the overlay pixel. math. it's always math. 😭

before Netpbm 10.25 (October 2004), pamcomp did not recognize the transparency information in a PAM image — it just ignored it. 🙈 so people had to make appropriate transparency masks in order to have a non-opaque overlay. and here's the tea: some Netpbm programs that convert from image formats that contain transparency information are not able to create RGB_ALPHA or GRAYSCALE_ALPHA PAM output, so you have to use the old method — extract the transparency information from the original into a separate transparency mask and use that as input to pamcomp. historical. vintage. retro. slay in a grandmother way. 👑

📐 the output, explained 📐

  • the output image is always of the same dimensions as the underlying image. so the underlying image is the canvas and the overlay is the sticker you're slapping on it. 🌸
  • pamcomp uses only parts of the overlay image that fit within the underlying image. anything hanging off the edge? gone. bye. 🦋
  • the output image is a PAM image.
  • its tuples are color, grayscale, or black and white — whichever is the "highest" format between the two input images.
  • the maxval of the output is the least common multiple of the maxvals of the input, up to the maximum possible PAM maxval, 65535.
  • the output has an opacity channel if and only if the underlying image does, and then the opacities are as described under the -mixtransparency option. and before Netpbm 10.56 (September 2011), the output never had an opacity channel. the past was so restrictive, we love growth. 🫶

📍 where do i put the overlay tho 📍

to specify where on the underlying image to place the overlay image, use the -align, -valign, -xoff, and -yoff options. and without these options, the defaults are:

  • default horizontal position: flush left ⬅️
  • default vertical position: flush top ⬆️

the overlay image, in the position you specify, need not fit entirely within the underlying image. pamcomp uses only the parts of the overlay image that appear above the underlying image. and yes — it is possible to specify positioning such that none of the overlay image is over the underlying image, i.e. the overlay is out of frame. 😭 if you do that, pamcomp issues a warning. it's not mad, it's just disappointed.

⚠️ bestie if you're getting a warning and you didn't mean to be out of frame, double-check your -align / -valign / -xoff / -yoff situation. that's the vibe check.

🌈 mixed formats, mixed maxvals 🌈

the overlay and underlying images may be of different formats — like, genuinely, e.g. overlaying a PBM text image over a full color PPM image — and they may have different maxvals. it's giving diversity. it's giving inclusivity. 💖

the output image has the more general of the two input formats, and a maxval that is the least common multiple of the two maxvals — or the maximum maxval allowable by the format, if the LCM is more than that. so the output is basically the two of them holding hands. 🤝

🎀 ARGUMENTS 🎀

okay so the positional arguments. there's three of them and two are optional, which is very generous of the program honestly.

  • overlay_file — the name of the file containing the overlay image. (yes, the original text says "overly image," which is a typo from the netpbm era, but we keep the meaning: it's the overlay. 💅)
  • underlying_file — the name of the file containing the underlying image.

for either of those, you may specify - to indicate Standard Input. and the underlying file defaults to Standard Input. so, like—

🚨 make sure you aren't specifying (or defaulting) Standard Input as both. because then it's just the same input being read twice and it's giving chaos, not in the cute way. 💀

also, heads up: there may be a third input file, identified by an -alphafile option. so technically the input situation can get a little crowded but it's fine, we can handle it, we're built different. 🫶

  • output_file — the name of the file to which pamcomp writes the output, creating or truncating it first. you may specify - to indicate Standard Output, in which case pamcomp does not truncate it.

and here's a fun little historical nugget for you: pamcomp is unusual among Netpbm programs, as a historical accident, in having an output file argument. Netpbm programs normally write to Standard Output only. so pamcomp is the quirky one. the little rebel. we love her for it. 👑

and that's part one, bestie!! the options are coming up next and honestly? they're the best part. don't go anywhere. 💖✨

✨ OPTIONS ✨

So besides the options that literally every libnetpbm program has (and yes bestie, that includes -quiet, check the Common Options if you need a refresher), pamcomp has its own little collection of flags. Obsessed with her honestly. Here they are 💅

  • -align=alignment — picks where the overlay image sits horizontally on top of the underlying image, and the syntax is very HTML-coded of her. left means flush left, center means centered, right means flush right. 🫶

The -xoff option then tweaks this position.

There's also beyondleft, which means just out of frame to the left — like the right edge of the overlay is lined up flush with the left edge of the underlying image. And beyondright means just out of frame to the right. These two alignments are only useful if you add a -xoff option, periodt. (Both these values were added in Netpbm 10.10, October 2002.)

The default is left.

  • -valign=alignment — same energy but vertical: where the overlay sits up-and-down relative to the underlying image, again in that HTML-ish syntax. top means flush top, middle means centered, and bottom means flush bottom. ✨

The -yoff option then tweaks this position.

above means just out of frame to the top — the bottom edge of the overlay is flush with the top edge of the underlying image. below means just out of frame to the bottom. These alignments are useful only if you add a -yoff option. (These two values were added in Netpbm 10.10, October 2002.)

The default is top.

  • -xoff=x — this one messes with the horizontal positioning of the overlay relative to the underlying image, as chosen by the -align option. pamcomp shifts the overlay image from that basic position x pixels to the right, and x can be negative if you want to shift left.

And no, the overlay doesn't have to fit entirely on the underlying image, or even fit at all. pamcomp just uses the parts that lie over the underlying image. 💖

Heads up: before Netpbm 10.10 (October 2002), -xoff was mutually exclusive with -align and always measured from the left edge. Ancient lore fr.
  • -yoff=y — same thing but vertical, modifying the position selected by the -valign option. pamcomp shifts the overlay y pixels downward from that basic position, and y can be negative to shift upward.

Same deal: the overlay need not fit entirely (or at all) on the underlying image, and pamcomp uses only the parts that lie over it.

Before Netpbm 10.10 (October 2002), -xoff (yes, as written) was mutually exclusive with -valign and always measured from the top edge.
  • -alpha=alpha-pgmfile — names the file holding the transparency mask. If you don't specify this option, there's no transparency mask at all, which is the same as a mask that says "totally opaque everywhere." 🎀

You can pass - as the value and the transparency mask will come from Standard Input. But bestie, if you do that, do not specify Standard Input as the source of any other input image. Pick one. 🙈

  • -invert — flips the meaning of the values in the transparency mask, which effectively swaps the roles of the overlay image and the underlying image wherever the two intersect. Iconic. 💅
  • -opacity=opacity — tells pamcomp how opaque the overlay image should be, i.e. how much of the composite image comes from the overlay versus the underlying image. opacity is a floating point number: 1.0 means the overlay is totally opaque, 0.0 means totally transparent. The default is 1.0.

If you specify a transparency mask (the -alpha option), pamcomp uses the product of the opacity indicated by the mask — as modified by the -invert option, as a fraction — and this opacity value. Note the -invert option does not apply to this opacity value. 🫶

As a simple opacity value, it only really makes sense between 0 and 1, inclusive. But pamcomp accepts all values and just does the same arithmetic computation with whatever you give it. An opacity less than zero means the underlay image gets intensified and then the overlay image is "subtracted" from it. An opacity greater than unity means the overlay gets intensified and the underlay subtracted from it. Either way, pamcomp clips the resulting color component intensities so they're nonnegative and don't exceed the output image's maxval. 💀

Sounds unhinged, but it has uses! You can brighten or darken or saturate or desaturate areas of the underlay image. See this description(1) of the technique.

This option was added in Netpbm 10.6 (July 2002). And before Netpbm 10.15 (April 2003), values less than zero or greater than unity were not allowed.

  • -mixtransparency — controls what pamcomp does where both the underlying and overlay images are non-opaque. 🌈

By default, the output image has the same transparency as the underlying image, and the transparency of the underlying image has no effect on the composition of color.

But with this option, pamcomp composes the image using a plastic transparency metaphor: the underlying and overlay images are plastic slides, and the output image is the slide you get when you stack those two up. So the transparency of the output is a combination of the transparency of the inputs, and the transparency of the underlying image affects that image's contribution to the output color. 🦋

Except — unlike the metaphorical slide, a PAM pixel has a color even where it's completely transparent, so pamcomp departs from the metaphor in that case and makes the output color identical to the underlying image.

This option was new in Netpbm 10.56 (September 2011). Before that, the output is always opaque and pamcomp ignores the transparency of the underlying image.

  • -linear — says that the inputs aren't true Netpbm images but rather a light-intensity-proportional variation. This matters only when you mix pixels, using the -opacity option or a transparency mask (the -alpha option).

The transparency mask and -opacity values indicate a fraction of the light intensity of a pixel. But the PNM and PNM-equivalent PAM image formats represent intensities with gamma-adjusted numbers that aren't linearly proportional to intensity. So by default, pamcomp does a calculation on every sample read from its input and every sample written to its output to convert between those gamma-adjusted numbers and internal intensity-proportional numbers. 🧚

Sometimes you're not working with true PNM or PAM images, but a variation where the sample values are directly proportional to intensity. If that's you, use -linear to tell pamcomp this, and it'll skip the conversions.

The conversion takes time. And the difference between intensity-proportional values and gamma-adjusted values may be small enough that you'd barely see a difference if you just pretended the gamma-adjusted values were intensity-proportional anyway. So just to save time — at the expense of some image quality — you can specify -linear even when you have true PPM input and expect true PPM output. 🙈

For the first 13 years of Netpbm's life, until Netpbm 10.20 (January 2004), pamcomp's predecessor pnmcomp always treated PPM samples as intensity-proportional even though they weren't, and got like, barely any complaints. So using -linear as a lil lie is a reasonable thing to do if speed matters to you. ⭐

Another technique to consider: convert your PNM image to the linear variation with pnmgamma, run pamcomp on it and other transformations that like linear PNM, then convert it back to true PNM with pnmgamma -ungamma. pnmgamma is often faster than pamcomp at doing that conversion. 💜

🌸 SEE ALSO 🌸

📜 HISTORY 📜

pamcomp was new in Netpbm 10.21 (March 2004). Its predecessor, pnmcomp, was one of the first programs added to Netpbm when the project went global in 1993. Queen behavior honestly 👑

👑 AUTHOR 👑

Copyright (C) 1992 by David Koblas (koblas@mips.com).

💖 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/pamcomp.html

And that's a wrap bestie!! 🎉 This lil masterpiece is netpbm documentation, dated 13 August 2011, and it's the Pamcomp User Manual(1). Go forth and composite your images, you absolute icon. 💅✨🦋

📦 where this page comes from