PPMSHADOW(1)

✨ NAME ✨

ppmshadow — it adds simulated shadows to a PPM image 💅 (yes bestie, it's giving graphic design is my passion but make it CLI)

Okay so you know that cute floating look where stuff seems to hover above the page and casts a soft lil shadow? That's this program. Let's go 💖

---

🎀 SYNOPSIS 🎀

ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoffset] [ppmfile]

---

🦋 DESCRIPTION 🦋

ppmshadow is part of Netpbm(1), so it's already in your friend group, no worries 🫶

What it does: ppmshadow adds a simulated shadow to an image, making it look like the contents of the image float above the page, casting a diffuse shadow on the background. Shadows can either be black, like an opaque object casts, or translucent, where the shadow takes on the color of the object casting it. You can control the crispness of the shadow and how far it's displaced from the image with command line options. Obsessed tbh ✨

Here's the vibe check on how it sees your image: ppmshadow treats your image as a foreground sitting on a background. The background color is literally whatever color the top left pixel of your image is. The background is all the pixels that are that color, and the foreground is everything else. The shadow it generates is a shadow of the foreground, cast on the background. No cap 💀

The shadow is the same size as the foreground, plus some fringes as determined by the -b option. It gets truncated to fit inside your image. The output image is the same dimensions as the input image.

Pro tip energy: you can use pamcomp to place a foreground image over a background before running ppmshadow on it. And you can use ppmmake to make the background image (which is just an image of a solid color). Iconic combo 🔥

The output has the same dimensions and maxval as the input. Matching, as it should be.

Now listen: the blurring that makes the fringes of the shadow will not have a desirable effect if the color depth (maxval) of the image is too low — you need a high maxval to get all the shades required for a smooth gradient. So if your input has a low maxval (and especially if it's PBM, meaning its maxval is 1, girl help), run it through pamdepth to raise that maxval. 255 is usually a good choice. Trust 🎀

Input is a PPM file named by the ppmfile command line argument; if you don't specify ppmfile, the input is Standard Input.

The output is a PPM file, written to Standard Output. Periodt.

---

💅 OPTIONS 💅

ppmshadow recognizes the following command line options:

• -b blur_size — Sets the distance of the light source from the image. Larger values move the light source closer, casting a more diffuse shadow, while smaller settings move the light further away, giving you a sharper shadow. blur_size is the number of pixels of fringe on the shadow, beyond where the shadow would be if there were no blurring.

The default is 11 pixels.

Caveat bestie: this option controls only the fringing effect of moving the light source closer to the object. It does not make the shadow grow or shrink the way it would in the real world if you moved a point light source closer to and further from an object. iykyk

• -k — Keep the intermediate temporary image files. When debugging, these intermediate files provide many clues as to the source of an error. See below for a list of the contents of each file. (Detective mode 🔍)
• -t — Consider the non-background material in the image translucent — it casts shadows of its own color rather than a black shadow, which is the default. This often results in fuzzy, difficult-to-read images 🙈 but in some circumstances it may look better. Your call.
• -x xoffset — Specifies the displacement of the light source to the left of the image. Larger settings of xoffset displace the shadow to the right, as would be cast by a light further to the left. If not specified, the horizontal offset is half of blur_size (above), to the left.
• -y yoffset — Specifies the displacement of the light source above the top of the image. Larger settings displace the shadow downward, corresponding to moving the light further above the top of the image. If you don't specify -y, the vertical offset defaults to the same as the horizontal offset (above), upward.

ppmshadow does not recognize the options common to all programs based on libnetpbm (See Common Options). However, the -version option works. At least we have that 💖

---

😭 LIMITATIONS 😭

Okay, real talk time, bestie — here's where things get picky:

• The source image must contain sufficient space on the edges in the direction in which the shadow is cast to contain the shadow — if it doesn't, some of the internal steps may fail. You can usually expand the border of a too-tightly-cropped image with pnmmargin before processing it with ppmshadow. Give it room to breathe ✨
• Black pixels and pixels with the same color as the image background don't cast a shadow. If this causes unintentional "holes" in the shadow, fill the offending areas with a color which differs from black or the background by RGB values of 1, which will be imperceptible to the viewer. Since the comparison is exact, the modified areas will now cast shadows. Sneaky but it works 💅
• The background color of the source image (which is preserved in the output) is deemed to be the color of the pixel at the top left of the input image. If that pixel isn't part of the background, simply add a one-pixel border at the top of the image, generate the shadow image, then delete the border from it.
• If something goes wrong along the way, the error messages from the various Netpbm programs ppmshadow calls will, in general, provide little or no clue as to where ppmshadow went astray 😭 In this case, specify the -k option and examine the intermediate results in the temporary files (which this option causes to be preserved). If you manually run the commands that ppmshadow runs on these files, you can figure out where the problem is. In problem cases where you want to manually tweak the image generation process along the way, you can keep the intermediate files with the -k option, modify them appropriately with an image editor, then recombine them with the steps used by the code in ppmshadow. DIY era 🛠️
• Shadows are by default black, as cast by opaque material in the image occluding white light. Use the -t option to simulate translucent material, where the shadow takes on the color of the object that casts it. If the contrast between the image and background is insufficient, the -t option may yield unattractive results which resemble simple blurring of the original image. Not the serve you were hoping for 💀
• Because Netpbm used to have a maximum maxval of 255, which meant that the largest convolution kernel pnmconvol could use was 11 by 11, ppmshadow includes a horrid, CPU-time-burning kludge which, if a blur of greater than 11 is requested, performs an initial convolution with an 11 x 11 kernel, then calls pnmsmooth (which is itself a program that calls pnmconvol with a 3 x 3 kernel) as many times as the requested blur exceeds 11. It's ugly, but it gets the job done on those rare occasions where you need a blur greater than 11. Respect the hustle honestly 👑
• If you wish to generate an image at high resolution, then scale it to publication size with pamscale in order to eliminate jagged edges by resampling, it's best to generate the shadow in the original high resolution image, prior to scaling it down in size. If you scale first and then add the shadow, you'll get an unsightly jagged stripe between the edge of material and its shadow, due to resampled pixels intermediate between the image and background obscuring the shadow. Learn from our pain 🦋

---

⭐ EXIT STATUS ⭐

ppmshadow returns status 0 if processing was completed without errors, and a nonzero Unix error code if an error prevented generation of output.

But heads up: some errors may result in the script aborting, usually displaying error messages from various Netpbm components it uses, without returning a nonzero error code. When this happens, the output file will be empty, so be sure to test this if you need to know if the program succeeded. Don't let an empty file gaslight you 🙈

---

🌸 TEMPORARY FILES 🌸

ppmshadow creates a number of temporary files as it executes. It creates a new directory for them in the directory named by the TMPDIR environment variable, defaulting to /tmp if it is not set.

In normal operation, ppmshadow finds a unique name for the temporary directory and deletes each temporary file as soon as it is done with it, and leaves no debris around after it completes. Clean girl aesthetic ✨

To preserve the intermediate files for debugging, use the -k command line option. In that case, the directory name is ppmshadowpid, where pid is the process ID of the ppmshadow process, and the program fails if ppmshadow cannot create that directory because the name is already in use.

The temporary files are:

• infile.ppm — A copy of the input.
• background.ppm — Blank image with background of source image
• bgmask.ppm — Positive binary mask
• convkernel.ppm — Convolution kernel for blurring shadow
• blurredlackshad.ppm — Blurred shadow image before coloring
• blurred.ppm — Blurred, colored shadow image
• shadow.ppm — Clipped shadow image, offset as requested
• shadback.ppm — Generated shadow times positive mask

---

🌈 SEE ALSO 🌈

pnm(1), pnmmargin(1), pnmconvol(1), pamscale(1), pnmsmooth(1), ppm(1)

---

👑 AUTHOR 👑

John Walker http://www.fourmilab.ch — August 8, 1997 🎂

---

💜 COPYRIGHT 💜

This software is in the public domain. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions.

---

🧚 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/ppmshadow.html

---

And that's the whole page bestie! This one's from the netpbm documentation, dated 24 June 2017 (the Ppmshadow User Manual(1) era, vintage but still slaying 💖). Go forth and cast some shadows ✨🦋🎀