This page describes, in Unix manual page style, a Perl program available for downloading from this site which adds simulated shadows to bitmap images, such as those in the title of this page. To use the program you must have Perl (version 4.0, patch level 36 or later) and the PBMplus or Netpbm raster image toolkit installed on your machine. This program makes extensive use of Unix facilities; it is improbable in the extreme that it will work on non-Unix systems without extensive modifications. An accompanying document explains how it works.
pnmshadow – add simulated shadows to portable pixmap images
pnmshadow [ -b blur_size ] [ -k ] [ -t ] [ -x xoffset ] [ -y yoffset ] [ -u ] [ pnmfile ]
pnmshadow adds a simulated shadow to a raster image, giving the appearance that the contents of the image float above the page, casting a diffuse shadow on the background. Shadows can either be black, as cast by opaque objects, or translucent, where the shadow takes on the colour of the object which casts it. The extent of the shadow and its displacement from the image can be specified by command line options.
Input is an anymap named by the pnmfile command line argument; if no pnmfile is specified, input is read from standard input. Output is a PPM file, written on standard output.
A number of temporary files are created during the execution of pnmshadow. All temporary files are created in the current directory (which must therefore be writable), and have names of the form:
_PNMshadowpid-N.ppm
where pid is replaced by the process number of the program running this script and N is a number identifying the file as given below. In normal operation, all temporary files are deleted as soon as they are no longer needed and no debris is left around after pnmshadow is done. To preserve the intermediate files for debugging, use the -k option on the command line.
You can always delete any temporary files left around with:
rm _PNMshadow*.ppm
| N | Contents of Temporary File |
|---|---|
| 1 | Positive binary mask |
| 2 | Convolution kernel for blurring shadow |
| 3 | Blurred shadow image |
| 4 | Clipped shadow image, offset as requested |
| 5 | Blank image with background of source image |
| 6 | Offset shadow |
| 7 | Inverse mask file |
| 8 | Original image times inverse mask |
| 9 | Generated shadow times positive mask |
| 10 | Shadow times background colour |
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 pnmshadow.
Black pixels and pixels with the same colour as the image background don't cast a shadow. If this causes unintentional “holes” in the shadow, fill the offending areas with a colour 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.
The background colour of the source image (which is preserved in the output) is deemed to be the colour 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 PBMplus components will, in general, provide little or no clue as to where pnmshadow went astray. Specifying the -k option, then examining the intermediate results in the temporary files this causes to be preserved can usually, in conjunction with examining the commands in this script, point to a fix. 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 this script. See the How it Works document for additional details and examples of the intermediate files.
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 colour 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.
Unless PBMplus is built with the PGM_BIGGRAYS option (which most people don't use, since it causes PGM and PPM files to be written in the much larger and slower ASCII format rather than raw binary), the largest convolution kernel pnmconvol can use is 11 by 11, since the offset, encoded as the maxval of the kernel file, cannot exceed 255. To allow more diffuse shadows without requiring PGM_BIGGRAYS, pnmshadow includes a horrid, CPU-time-burning kludge which, if a blur of greater than 11 is requested, performs an initial convolution with an 11×11 kernel, then calls pnmsmooth (which is actually a script that calls pnmconvol with a 3×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.
If you wish to generate an image at high resolution, then scale it to publication size with pnmscale 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.
pnm(5), pnmmargin(1), pnmconvol(1), pnmscale(1), pnmsmooth(1), ppm(5)
pnmshadow returns status 0 if processing was completed without errors, and a nonzero Unix error code if an error prevented generation of output. Some errors may result in the script aborting, usually displaying error messages from various PBMplus components it uses, without returning a nonzero error code. When this happens, the output file will be void, so this may be tested if it is necessary to detect such errors.
Two documents are available which describe, in detail, how pnmshadow generates normal black shadows and the optional translucent shadows created by the -t option.
This software is utterly and absolutely unsupported. You are entirely on your own in using this program. If PBMplus or Perl is incorrectly installed or you're using an obsolete version, you will doubtless encounter errors which will require patience and experience with both PBMplus and Perl programming to resolve. Every attempt has been made to permit pnmshadow to be used as a black box, but if the box pops open and gears and springs fly out on your watch, I can't provide any assistance in setting things right.
Download pnmshadow.tar.gz (gzipped TAR archive)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. This software is provided “as is” without express or implied warranty.