1Ppmshadow User Manual(0)                              Ppmshadow User Manual(0)
2
3
4

NAME

6       ppmshadow - add simulated shadows to a PPM image
7
8

SYNOPSIS

10       ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoffset] [ppmfile]
11
12
13

DESCRIPTION

15       This program is part of Netpbm(1).
16
17       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
24       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
30       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
34       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
38       The output has the same dimensions and maxval as the input.
39
40       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
47       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
50       The output is a PPM file, written to Standard Output.
51
52
53

OPTIONS

55       ppmshadow recognizes the following command line options:
56
57
58
59       -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
67              The default is 11 pixels.
68
69              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
74
75       -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
80
81       -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
86
87       -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
94
95       -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
102
103
104       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
109

LIMITATIONS

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
117       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
124       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
130       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
142       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
149       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
158       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
166

EXIT STATUS

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
176

TEMPORARY FILES

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
182       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
190       The temporary files are:
191
192
193
194       infile.ppm
195              A copy of the input.
196
197
198       background.ppm
199              Blank image with background of source image
200
201
202       bgmask.ppm
203              Positive binary mask
204
205
206       convkernel.ppm
207              Convolution kernel for blurring shadow
208
209
210       blurredlackshad.ppm
211              Blurred shadow image before coloring
212
213
214       blurred.ppm
215              Blurred, colored shadow image
216
217
218       shadow.ppm
219              Clipped shadow image, offset as requested
220
221
222       shadback.ppm
223              Generated shadow times positive mask
224
225
226
227
228

SEE ALSO

230       pnm(1), pnmmargin(1), pnmconvol(1), pamscale(1), pnmsmooth(1), ppm(1)
231
232

AUTHOR

234       John  Walker  http://www.fourmilab.chhttp://www.fourmilab.ch⟩  August
235       8, 1997
236
237
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

DOCUMENT SOURCE

245       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
246       source.  The master documentation is at
247
248              http://netpbm.sourceforge.net/doc/ppmshadow.html
249
250netpbm documentation             24 June 2017         Ppmshadow User Manual(0)
Impressum