Penguin
Recent Changes
Blame: ppmshadow(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of ppmshadow(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 ppmshadow
2 !!!ppmshadow
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 FILES
8 LIMITATIONS
9 EXIT STATUS
10 SEE ALSO
11 AUTHOR
12 COPYRIGHT
13 ----
14 !!NAME
15
16
17 ppmshadow - add simulated shadows to a portable pixmap image
18 !!SYNOPSIS
19
20
21 __ppmshadow__ [[__-b__ ''blur_size''] [[__-k__]
22 [[__-t__] [[__-x__ ''xoffset''] [[__-y__
23 ''yoffset''] [[__-u__] [[''pnmfile'']
24 !!DESCRIPTION
25
26
27 __ppmshadow__ adds a simulated shadow to an image, giving
28 the appearance that the contents of the image float above
29 the page, casting a diffuse shadow on the background.
30 Shadows can either be black, as cast by opaque objects, or
31 translucent, where the shadow takes on the colour of the
32 object which casts it. You can specify the extent of the
33 shadow and its displacement from the image with command line
34 options.
35 !!OPTIONS
36
37
38 __-b__ ''blur_size''
39
40
41 Sets the distance of the light source from the image. Larger
42 values move the light source closer, casting a more diffuse
43 shadow, while smaller settings move the light further away,
44 yielding a sharper shadow. ''blur_size'' defaults to 11
45 pixels.
46
47
48 __-k__
49
50
51 Keep the intermediate temporary image files. When debugging,
52 these intermediate files provide many clues as to the source
53 of an error. See __FILES__ below for a list of the
54 contents of each file.
55
56
57 __-t__
58
59
60 Consider the non-background material in the image
61 translucent -- it casts shadows of its own colour rather
62 than a black shadow, which is default. This often results in
63 fuzzy, difficult-to-read images but in some circumstances
64 may look better.
65
66
67 __-u__
68
69
70 Print command syntax and a summary of options.
71
72
73 __-x__ ''xoffset''
74
75
76 Specifies the displacement of the light source to the left
77 of the image. Larger settings of __xoffset__ displace the
78 shadow to the right, as would be cast by a light further to
79 the left. If not specified, the horizontal offset is half of
80 ''blur_size'' (above), to the left.
81
82
83 __-y__ ''yoffset''
84
85
86 Specifies the displacement of the light source above the top
87 of the image. Larger settings displace the shadow downward,
88 corresponding to moving the light further above the top of
89 the image. If you don't specify __-y__, the vertical
90 offset defaults to the same as the horizontal offset
91 (above), upward.
92 !!FILES
93
94
95 Input is an anymap named by the ''pnmfile'' command line
96 argument; if you don't specify ''pnmfile'', the input is
97 the Standard Input file.
98
99
100 Output is a always a PPM file, written to Standard
101 Output.
102
103
104 __pnmfile__ creates a number of temporary files as it
105 executes. It creates them in the /tmp directory, with names
106 of the form:
107
108
109 ___PPMshadow__''pid''__-__''N''__.ppm__
110
111
112 where ''pid'' is the process number of the
113 __ppmshadow__ process and ''N'' is a number
114 identifying the file as described below. In normal
115 operation, __ppmshadow__ deletes temporary files as soon
116 as it is done with them and leaves no debris around after it
117 completes. To preserve the intermediate files for debugging,
118 use the __-k__ command line option.
119
120
121 ''N'' in the filename means:
122
123
124 __1__
125
126
127 Positive binary mask
128
129
130 __2__
131
132
133 Convolution kernel for blurring shadow
134
135
136 __3__
137
138
139 Blurred shadow image
140
141
142 __4__
143
144
145 Clipped shadow image, offset as requested
146
147
148 __5__
149
150
151 Blank image with background of source image
152
153
154 __6__
155
156
157 Offset shadow
158
159
160 __7__
161
162
163 Inverse mask file
164
165
166 __8__
167
168
169 Original image times inverse mask
170
171
172 __9__
173
174
175 Generated shadow times positive mask
176
177
178 __10__
179
180
181 Shadow times background colour
182 !!LIMITATIONS
183
184
185 The source image must contain sufficient space on the edges
186 in the direction in which the shadow is cast to contain the
187 shadow -- if it doesn't some of the internal steps may fail.
188 You can usually expand the border of a too-tightly-cropped
189 image with __pnmmargin__ before processing it with
190 __ppmshadow__.
191
192
193 Black pixels and pixels with the same color as the image
194 background don't cast a shadow. If this causes unintentional
195
196
197 The background color of the source image (which is preserved
198 in the output) is deemed to be the color of the pixel at the
199 top left of the input image. If that pixel isn't part of the
200 background, simply add a one-pixel border at the top of the
201 image, generate the shadow image, then delete the border
202 from it.
203
204
205 If something goes wrong along the way, the error messages
206 from the various Netpbm programs __ppmshadow__ calls
207 will, in general, provide little or no clue as to where
208 __ppmshadow__ went astray. In this case, Specify the
209 __-k__ option and examine the intermediate results in the
210 temporary files (which this option causes to be preserved).
211 If you manually run the commands that __ppmshadow__ runs
212 on these files, you can figure out where the problem is. In
213 problem cases where you want to manually tweak the image
214 generation process along the way, you can keep the
215 intermediate files with the __-k__ option, modify them
216 appropriately with an image editor, then recombine them with
217 the steps used by the code in __ppmshadow__. See the
218 __ppmshadow.doc__ document for additional details and
219 examples of the intermediate files.
220
221
222 Shadows are by default black, as cast by opaque material in
223 the image occluding white light. Use the __-t__ option to
224 simulate translucent material, where the shadow takes on the
225 colour of the object that casts it. If the contrast between
226 the image and background is insufficient, the __-t__
227 option may yield unattractive results which resemble simple
228 blurring of the original image.
229
230
231 Because Netpbm used to have a maximum maxval of 255, which
232 meant that the largest convolution kernel __pnmconvol__
233 could use was 11 by 11, __ppmshadow__ includes a horrid,
234 CPU-time-burning kludge which, if a blur of greater than 11
235 is requested, performs an initial convolution with an
236 11__pnmsmooth__ (which is
237 actually a script that calls pnmconvol with a 3
238 __
239
240
241 If you wish to generate an image at high resolution, then
242 scale it to publication size with __pnmscale__ in order
243 to eliminate jagged edges by resampling, it's best to
244 generate the shadow in the original high resolution image,
245 prior to scaling it down in size. If you scale first and
246 then add the shadow, you'll get an unsightly jagged stripe
247 between the edge of material and its shadow, due to
248 resampled pixels intermediate between the image and
249 background obscuring the shadow.
250 !!EXIT STATUS
251
252
253 __ppmshadow__ returns status 0 if processing was
254 completed without errors, and a nonzero Unix error code if
255 an error prevented generation of output. Some errors may
256 result in the script aborting, usually displaying error
257 messages from various Netpbm components it uses, without
258 returning a nonzero error code. When this happens, the
259 output file will be empty, so be sure to test this if you
260 need to know if the program succeeded.
261 !!SEE ALSO
262
263
264 pnm(5), pnmmargin(1), pnmconvol(1),
265 pnmscale(1), pnmsmooth(1),
266 ppm(5)
267 !!AUTHOR
268
269
270 John Walker
271 !!COPYRIGHT
272
273
274 This software is in the public domain. Permission to use,
275 copy, modify, and distribute this software and its
276 documentation for any purpose and without fee is hereby
277 granted, without any conditions or
278 restrictions.
279 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.