1Ppmshadow User Manual(0) Ppmshadow User Manual(0)
2
6 ppmshadow - add simulated shadows to a PPM image
7
10 ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoffset] [ppmfile]
11
15 This program is part of Netpbm(1).
16 ppmshadow adds a simulated shadow to an image, giving the appearance
18 that the contents of the image float above the page, casting a diffuse
19 shadow on the background. Shadows can either be black, as cast by
20 opaque objects, or translucent, where the shadow takes on the color of
21 the object which casts it. You can specify the crispness of the shadow
22 and its displacement from the image with command line options.
23 ppmshadow sees your image as a foreground on a background. The back‐
25 ground color is whatever color the top left pixel of your image is.
26 The background is all the pixels that are that color and the foreground
27 is everything else. The shadow that ppmshadow generates is a shadow of
28 the foreground, cast on the background.
29 The shadow is the same size as the foreground, plus some fringes as
31 determined by the -b option. It is truncated to fit in your image.
32 The output image is the same dimensions as the input image.
33 You can use pamcomp to place a foreground image over a background
35 before running ppmshadow on it. You can use ppmmake to make the back‐
36 ground image (just an image of a solid color).
37 The output has the same dimensions and maxval as the input.
39 The blurring to make the fringes of the shadow will not have a desir‐
41 able effect if the color depth (maxval) of the image is too low -- you
42 need a high maxval to get all the shades needed to create a smooth gra‐
43 dient. So if your input has low maxval (including most notably if the
44 input is PBM, which means its maxval is 1), run it through pamdepth to
45 raise its maxval. 255 is usually a good choice.
46 Input is a PPM file named by the ppmfile command line argument; if you
48 don't specify ppmfile, the input is Standard Input.
49 The output is a PPM file, written to Standard Output.
51
55 ppmshadow recognizes the following command line options:
56 -b blur_size
60 Sets the distance of the light source from the image. Larger
61 values move the light source closer, casting a more diffuse
62 shadow, while smaller settings move the light further away,
63 yielding a sharper shadow. blur_size is the number of pixels of
64 fringe there is on the shadow, beyond where the shadow would be
65 if there were no blurring.
66 The default is 11 pixels.
68 Note that this option controls only the fringing effect of mov‐
70 ing the light source closer to the object. It does not make the
71 shadow grow or shrink as would happpen in the real world if you
72 moved a point light source closer to and further from an object.
73 -k Keep the intermediate temporary image files. When debugging,
76 these intermediate files provide many clues as to the source of
77 an error. See below ⟨#tempfiles⟩ for a list of the contents of
78 each file.
79 -t Consider the non-background material in the image translucent --
82 it casts shadows of its own color rather than a black shadow,
83 which is default. This often results in fuzzy, difficult-to-
84 read images but in some circumstances may look better.
85 -x xoffset
88 Specifies the displacement of the light source to the left of
89 the image. Larger settings of xoffset displace the shadow to
90 the right, as would be cast by a light further to the left. If
91 not specified, the horizontal offset is half of blur_size
92 (above), to the left.
93 -y yoffset
96 Specifies the displacement of the light source above the top of
97 the image. Larger settings displace the shadow downward, corre‐
98 sponding to moving the light further above the top of the image.
99 If you don't specify -y, the vertical offset defaults to the
100 same as the horizontal offset (above), upward.
101 ppmshadow does not recognize the options common to all programs based
105 on libnetpbm (See
106 Common Options ⟨index.html#commonoptions⟩ .) However, the -version
107 option works.
108
111 The source image must contain sufficient space on the edges in the
112 direction in which the shadow is cast to contain the shadow -- if it
113 doesn't some of the internal steps may fail. You can usually expand
114 the border of a too-tightly-cropped image with pnmmargin before pro‐
115 cessing it with ppmshadow.
116 Black pixels and pixels with the same color as the image background
118 don't cast a shadow. If this causes unintentional "holes" in the
119 shadow, fill the offending areas with a color which differs from black
120 or the background by RGB values of 1, which will be imperceptible to
121 the viewer. Since the comparison is exact, the modified areas will now
122 cast shadows.
123 The background color of the source image (which is preserved in the
125 output) is deemed to be the color of the pixel at the top left of the
126 input image. If that pixel isn't part of the background, simply add a
127 one-pixel border at the top of the image, generate the shadow image,
128 then delete the border from it.
129 If something goes wrong along the way, the error messages from the var‐
131 ious Netpbm programs ppmshadow calls will, in general, provide little
132 or no clue as to where ppmshadow went astray. In this case, Specify
133 the -k option and examine the intermediate results in the temporary
134 files (which this option causes to be preserved). If you manually run
135 the commands that ppmshadow runs on these files, you can figure out
136 where the problem is. In problem cases where you want to manually
137 tweak the image generation process along the way, you can keep the
138 intermediate files with the -k option, modify them appropriately with
139 an image editor, then recombine them with the steps used by the code in
140 ppmshadow.
141 Shadows are by default black, as cast by opaque material in the image
143 occluding white light. Use the -t option to simulate translucent mate‐
144 rial, where the shadow takes on the color of the object that casts it.
145 If the contrast between the image and background is insufficient, the
146 -t option may yield unattractive results which resemble simple blurring
147 of the original image.
148 Because Netpbm used to have a maximum maxval of 255, which meant that
150 the largest convolution kernel pnmconvol could use was 11 by 11,
151 ppmshadow includes a horrid, CPU-time-burning kludge which, if a blur
152 of greater than 11 is requested, performs an initial convolution with
153 an 11 x 11 kernel, then calls pnmsmooth (which is itself a program that
154 calls pnmconvol with a 3 x 3 kernel) as many times as the requested
155 blur exceeds 11. It's ugly, but it gets the job done on those rare
156 occasions where you need a blur greater than 11.
157 If you wish to generate an image at high resolution, then scale it to
159 publication size with pamscale in order to eliminate jagged edges by
160 resampling, it's best to generate the shadow in the original high reso‐
161 lution image, prior to scaling it down in size. If you scale first and
162 then add the shadow, you'll get an unsightly jagged stripe between the
163 edge of material and its shadow, due to resampled pixels intermediate
164 between the image and background obscuring the shadow.
165
168 ppmshadow returns status 0 if processing was completed without errors,
169 and a nonzero Unix error code if an error prevented generation of out‐
170 put. Some errors may result in the script aborting, usually displaying
171 error messages from various Netpbm components it uses, without return‐
172 ing a nonzero error code. When this happens, the output file will be
173 empty, so be sure to test this if you need to know if the program suc‐
174 ceeded.
175
178 ppmshadow creates a number of temporary files as it executes. It cre‐
179 ates a new directory for them in the directory named by the TMPDIR
180 environment variable, defaulting to /tmp if it is not set.
181 In normal operation, ppmshadow finds a unique name for the temporary
183 directory and deletes each temporary file as soon as it is done with it
184 and leaves no debris around after it completes. To preserve the inter‐
185 mediate files for debugging, use the -k command line option. In that
186 case, the directory name is ppmshadowpid, where pid is the process ID
187 of the ppmshadow process, and the program fails if ppmshadow cannot
188 create that directory because the name is already in use.
189 The temporary files are:
191 infile.ppm
195 A copy of the input.
196 background.ppm
199 Blank image with background of source image
200 bgmask.ppm
203 Positive binary mask
204 convkernel.ppm
207 Convolution kernel for blurring shadow
208 blurredlackshad.ppm
211 Blurred shadow image before coloring
212 blurred.ppm
215 Blurred, colored shadow image
216 shadow.ppm
219 Clipped shadow image, offset as requested
220 shadback.ppm
223 Generated shadow times positive mask
224
230 pnm(1), pnmmargin(1), pnmconvol(1), pamscale(1), pnmsmooth(1), ppm(1)
231
234 John Walker http://www.fourmilab.ch ⟨http://www.fourmilab.ch⟩ August
235 8, 1997
236
239 This software is in the public domain. Permission to use, copy, mod‐
240 ify, and distribute this software and its documentation for any purpose
241 and without fee is hereby granted, without any conditions or restric‐
242 tions.
243
245 This manual page was generated by the Netpbm tool 'makeman' from HTML
246 source. The master documentation is at
247 http://netpbm.sourceforge.net/doc/ppmshadow.html
249netpbm documentation 24 June 2017 Ppmshadow User Manual(0)