Ppmshadow User Manual(1) General Commands Manual Ppmshadow User Manual(1)
NAME
ppmshadow - add simulated shadows to a PPM image
SYNOPSIS
ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoffset] [ppmfile]
DESCRIPTION
This program is part of Netpbm(1).
ppmshadow adds a simulated shadow to an 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 color of
the object which casts it. You can specify the crispness of the shadow
and its displacement from the image with command line options.
ppmshadow sees your image as a foreground on a background. The back-
ground color is 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 that ppmshadow generates is a shadow of the
foreground, cast on the background.
The shadow is the same size as the foreground, plus some fringes as de-
termined by the -b option. It is truncated to fit in your image. The
output image is the same dimensions as the input image.
You can use pamcomp to place a foreground image over a background before
running ppmshadow on it. You can use ppmmake to make the background im-
age (just an image of a solid color).
The output has the same dimensions and maxval as the input.
The blurring to make 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 needed to create a smooth gradient.
So if your input has low maxval (including most notably if the input is
PBM, which means its maxval is 1), run it through pamdepth to raise its
maxval. 255 is usually a good choice.
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.
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,
yielding a sharper shadow. blur_size is the number of pixels of
fringe there is on the shadow, beyond where the shadow would be
if there were no blurring.
The default is 11 pixels.
Note that 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 as would happpen in the real world if you
moved a point light source closer to and further from an object.
-k Keep the intermediate temporary image files. When debugging,
these intermediate files provide many clues as to the source of
an error. See ]8;;#tempfiles\below]8;;\ for a list of the contents of each file.
-t Consider the non-background material in the image translucent --
it casts shadows of its own color rather than a black shadow,
which is default. This often results in fuzzy, difficult-to-read
images but in some circumstances may look better.
-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, corre-
sponding 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 ]8;;index.html#commonoptions\ Common Options]8;;\ .) However, the -version option works.
LIMITATIONS
The source image must contain sufficient space on the edges in the di-
rection 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.
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.
The background color of the source image (which is preserved in the out-
put) 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 vari-
ous 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 edi-
tor, then recombine them with the steps used by the code in ppmshadow.
Shadows are by default black, as cast by opaque material in the image
occluding white light. Use the -t option to simulate translucent mater-
ial, 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.
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 ex-
ceeds 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 pamscale in order to eliminate jagged edges by re-
sampling, it's best to generate the shadow in the original high resolu-
tion 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.
EXIT STATUS
ppmshadow returns status 0 if processing was completed without errors,
and a nonzero Unix error code if an error prevented generation of out-
put. 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.
TEMPORARY FILES
ppmshadow creates a number of temporary files as it executes. It cre-
ates a new directory for them in the directory named by the TMPDIR envi-
ronment variable, defaulting to /tmp if it is not set.
In normal operation, ppmshadow finds a unique name for the temporary di-
rectory and deletes each temporary file as soon as it is done with it
and leaves no debris around after it completes. To preserve the inter-
mediate 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 ]8;;http://www.fourmilab.ch\http://www.fourmilab.ch]8;;\ 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
netpbm documentation 24 June 2017 Ppmshadow User Manual(1)
Generated by dwww version 1.16 on Tue Dec 16 06:36:42 CET 2025.