Debian Codegraph @

upstream/debian-unstable/man1/ppmshadow.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Ppmshadow User Manual" 1 "24 June 2017" "netpbm documentation"
7
8 .SH NAME
9 ppmshadow - add simulated shadows to a PPM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBppmshadow\fP
15 [\fB-b\fP \fIblur_size\fP]
16 [\fB-k\fP]
17 [\fB-t\fP]
18 [\fB-x\fP \fIxoffset\fP]
19 [\fB-y\fP \fIyoffset\fP]
20 [\fIppmfile\fP]
21
22
23 .UN description
24 .SH DESCRIPTION
25 .PP
26 This program is part of
27 .BR "Netpbm" (1)\c
28 \&.
29 .PP
30 \fBppmshadow\fP adds a simulated shadow to an image, giving the
31 appearance that the contents of the image float above the page,
32 casting a diffuse shadow on the background. Shadows can either be
33 black, as cast by opaque objects, or translucent, where the shadow
34 takes on the color of the object which casts it. You can specify the
35 crispness of the shadow and its displacement from the image with command
36 line options.
37 .PP
38 \fBppmshadow\fP sees your image as a foreground on a background.
39 The background color is whatever color the top left pixel of your image is.
40 The background is all the pixels that are that color and the foreground
41 is everything else. The shadow that \fBppmshadow\fP generates is a
42 shadow of the foreground, cast on the background.
43 .PP
44 The shadow is the same size as the foreground, plus some fringes
45 as determined by the \fB-b\fP option. It is truncated to fit in your
46 image. The output image is the same dimensions as the input image.
47 .PP
48 You can use \fBpamcomp\fP to place a foreground image over a background
49 before running \fBppmshadow\fP on it. You can use \fBppmmake\fP to make
50 the background image (just an image of a solid color).
51 .PP
52 The output has the same dimensions and maxval as the input.
53 .PP
54 The blurring to make the fringes of the shadow will not have a desirable
55 effect if the color depth (maxval) of the image is too low -- you need a high
56 maxval to get all the shades needed to create a smooth gradient. So if your
57 input has low maxval (including most notably if the input is PBM, which means
58 its maxval is 1), run it through \fBpamdepth\fP to raise its maxval. 255 is
59 usually a good choice.
60 .PP
61 Input is a PPM file named by the \fIppmfile\fP command line argument; if
62 you don't specify \fIppmfile\fP, the input is Standard Input.
63 .PP
64 The output is a PPM file, written to Standard Output.
65
66
67 .UN options
68 .SH OPTIONS
69
70 \fBppmshadow\fP recognizes the following command line options:
71
72
73 .TP
74 \fB-b\fP \fIblur_size\fP
75 Sets the distance of the light source from the image. Larger values
76 move the light source closer, casting a more diffuse shadow, while
77 smaller settings move the light further away, yielding a sharper
78 shadow. \fIblur_size\fP is the number of pixels of fringe there is
79 on the shadow, beyond where the shadow would be if there were no
80 blurring.
81 .sp
82 The default is 11 pixels.
83 .sp
84 Note that this option controls only the fringing effect of moving
85 the light source closer to the object. It does not make the shadow
86 grow or shrink as would happpen in the real world if you moved a point
87 light source closer to and further from an object.
88
89 .TP
90 \fB-k\fP
91 Keep the intermediate temporary image files. When debugging, these
92 intermediate files provide many clues as to the source of an error.
93 See
94 .UR #tempfiles
95 below
96 .UE
97 \& for a list of the contents of each file.
98
99 .TP
100 \fB-t\fP
101 Consider the non-background material in the image translucent -- it
102 casts shadows of its own color rather than a black shadow, which is
103 default. This often results in fuzzy, difficult-to-read images but in
104 some circumstances may look better.
105
106 .TP
107 \fB-x\fP\fI xoffset\fP
108 Specifies the displacement of the light source to the left of the
109 image. Larger settings of \fBxoffset\fP displace the shadow to the
110 right, as would be cast by a light further to the left. If not
111 specified, the horizontal offset is half of \fIblur_size \fP (above),
112 to the left.
113
114 .TP
115 \fB-y\fP\fI yoffset\fP
116 Specifies the displacement of the light source above the top of
117 the image. Larger settings displace the shadow downward,
118 corresponding to moving the light further above the top of the image.
119 If you don't specify \fB-y\fP, the vertical offset defaults to the
120 same as the horizontal offset (above), upward.
121
122
123 .PP
124 \fBppmshadow\fP does not recognize the options common to all
125 programs based on libnetpbm (See
126 .UR index.html#commonoptions
127 Common Options
128 .UE
129 \&.) However, the \fB-version\fP option works.
130
131 .UN limitations
132 .SH LIMITATIONS
133 .PP
134 The source image must contain sufficient space on the edges in the
135 direction in which the shadow is cast to contain the shadow -- if it
136 doesn't some of the internal steps may fail. You can usually expand
137 the border of a too-tightly-cropped image with \fBpnmmargin\fP before
138 processing it with \fBppmshadow\fP.
139 .PP
140 Black pixels and pixels with the same color as the image
141 background don't cast a shadow. If this causes unintentional
142 "holes" in the shadow, fill the offending areas with a color
143 which differs from black or the background by RGB values of 1, which
144 will be imperceptible to the viewer. Since the comparison is exact,
145 the modified areas will now cast shadows.
146 .PP
147 The background color of the source image (which is preserved in
148 the output) is deemed to be the color of the pixel at the top left of
149 the input image. If that pixel isn't part of the background, simply
150 add a one-pixel border at the top of the image, generate the shadow
151 image, then delete the border from it.
152 .PP
153 If something goes wrong along the way, the error messages from the
154 various Netpbm programs \fBppmshadow\fP calls will, in general,
155 provide little or no clue as to where \fBppmshadow\fP went astray.
156 In this case, Specify the \fB-k\fP option and examine the
157 intermediate results in the temporary files (which this option causes
158 to be preserved). If you manually run the commands that
159 \fBppmshadow\fP runs on these files, you can figure out where the
160 problem is. In problem cases where you want to manually tweak the
161 image generation process along the way, you can keep the intermediate
162 files with the \fB-k \fP option, modify them appropriately with an
163 image editor, then recombine them with the steps used by the code in
164 \fBppmshadow\fP.
165 .PP
166 Shadows are by default black, as cast by opaque material in the
167 image occluding white light. Use the \fB-t\fP option to simulate
168 translucent material, where the shadow takes on the color of the
169 object that casts it. If the contrast between the image and
170 background is insufficient, the \fB-t\fP option may yield
171 unattractive results which resemble simple blurring of the original
172 image.
173 .PP
174 Because Netpbm used to have a maximum maxval of 255, which meant
175 that the largest convolution kernel \fBpnmconvol\fP could use was 11
176 by 11, \fBppmshadow\fP includes a horrid, CPU-time-burning kludge
177 which, if a blur of greater than 11 is requested, performs an initial
178 convolution with an 11 x 11 kernel, then calls \fBpnmsmooth\fP
179 (which is itself a program that calls \fBpnmconvol\fP with a 3 x 3
180 kernel) as many times as the requested blur exceeds 11. It's ugly,
181 but it gets the job done on those rare occasions where you need a blur
182 greater than 11.
183 .PP
184 If you wish to generate an image at high resolution, then scale it
185 to publication size with \fBpamscale\fP in order to eliminate jagged
186 edges by resampling, it's best to generate the shadow in the original
187 high resolution image, prior to scaling it down in size. If you scale
188 first and then add the shadow, you'll get an unsightly jagged stripe
189 between the edge of material and its shadow, due to resampled pixels
190 intermediate between the image and background obscuring the shadow.
191
192 .UN exitstatus
193 .SH EXIT STATUS
194
195 \fBppmshadow\fP returns status 0 if processing was completed without
196 errors, and a nonzero Unix error code if an error prevented generation
197 of output. Some errors may result in the script aborting, usually
198 displaying error messages from various Netpbm components it uses,
199 without returning a nonzero error code. When this happens, the output
200 file will be empty, so be sure to test this if you need to know if the
201 program succeeded.
202
203 .UN tempfiles
204 .SH TEMPORARY FILES
205 .PP
206 \fBppmshadow\fP creates a number of temporary files as it executes. It
207 creates a new directory for them in the directory named by the
208 \fBTMPDIR\fP environment variable, defaulting to \fB/tmp\fP if it is not
209 set.
210 .PP
211 In normal operation, \fBppmshadow\fP finds a unique name for the
212 temporary directory and deletes each temporary file as
213 soon as it is done with it and leaves no debris around after it
214 completes. To preserve the intermediate files for debugging, use the
215 \fB-k\fP command line option. In that case, the directory name is
216 \fBppmshadow\fP\fIpid\fP, where \fIpid\fP is the process ID of
217 the \fBppmshadow\fP process, and the program fails if \fBppmshadow\fP cannot
218 create that directory because the name is already in use.
219 .PP
220 The temporary files are:
221
222
223 .TP
224 \fBinfile.ppm\fP
225 A copy of the input.
226
227 .TP
228 \fBbackground.ppm\fP
229 Blank image with background of source image
230
231 .TP
232 \fBbgmask.ppm\fP
233 Positive binary mask
234
235 .TP
236 \fBconvkernel.ppm\fP
237 Convolution kernel for blurring shadow
238
239 .TP
240 \fBblurredlackshad.ppm\fP
241 Blurred shadow image before coloring
242
243 .TP
244 \fBblurred.ppm\fP
245 Blurred, colored shadow image
246
247 .TP
248 \fBshadow.ppm\fP
249 Clipped shadow image, offset as requested
250
251 .TP
252 \fBshadback.ppm\fP
253 Generated shadow times positive mask
254
255
256
257
258 .UN seealso
259 .SH SEE ALSO
260 .BR "pnm" (1)\c
261 \&,
262 .BR "pnmmargin" (1)\c
263 \&,
264 .BR "pnmconvol" (1)\c
265 \&,
266 .BR "pamscale" (1)\c
267 \&,
268 .BR "pnmsmooth" (1)\c
269 \&,
270 .BR "ppm" (1)\c
271 \&
272
273 .UN author
274 .SH AUTHOR
275
276 John Walker
277 .UR http://www.fourmilab.ch
278 http://www.fourmilab.ch
279 .UE
280 \& August
281 8, 1997
282
283 .UN copyright
284 .SH COPYRIGHT
285 This software is in the public domain. Permission to use, copy,
286 modify, and distribute this software and its documentation for any
287 purpose and without fee is hereby granted, without any conditions or
288 restrictions.
289 .SH DOCUMENT SOURCE
290 This manual page was generated by the Netpbm tool 'makeman' from HTML
291 source. The master documentation is at
292 .IP
293 .B http://netpbm.sourceforge.net/doc/ppmshadow.html
294 .PP