1Pamscale User Manual(0) Pamscale User Manual(0)
2
6 pamscale - scale a Netpbm image
7
9 pamscale
10 [
11 scale_factor
12 |
13 {-xyfit | -xyfill | -xysize} cols rows
14 |
15 -reduce reduction_factor
16 |
17 [-xsize=cols | -width=cols | -xscale=factor]
18 [-ysize=rows | -height=rows | -yscale=factor]
19 |
20 -pixels n
21 ]
22 [
23 [-verbose]
24 [
25 -nomix
26 |
27 -filter=functionName [-window=functionName]
28 ]
29 [-linear]
30 }
31 [pnmfile]
32
36 This program is part of Netpbm(1).
37 pamscale scales a Netpbm image by a specified factor, or scales indi‐
39 vidually horizontally and vertically by specified factors.
40 You can either enlarge (scale factor > 1) or reduce (scale factor < 1).
42 Minimum unique abbreviation of option is acceptable. You may use dou‐
44 ble hyphens instead of single hyphen to denote options. You may use
45 white space in place of the equals sign to separate an option name from
46 its value.
47 The Scale Factors
50 When you specify an absolute size or scale factor for both dimensions,
51 pamscale scales each dimension independently without consideration of
52 the aspect ratio.
53 If you specify one dimension as a pixel size and don't specify the
55 other dimension, pamscale scales the unspecified dimension to preserve
56 the aspect ratio.
57 If you specify one dimension as a scale factor and don't specify the
59 other dimension, pamscale leaves the unspecified dimension unchanged
60 from the input.
61 If you specify the scale_factor parameter instead of dimension options,
63 that is the scale factor for both dimensions. It is equivalent to
64 -xscale=scale_factor -yscale=scale_factor.
65 Specifying the -reduce reduction_factor option is equivalent to speci‐
67 fying the scale_factor parameter, where scale_factor is the reciprocal
68 of reduction_factor.
69 -xyfit specifies a bounding box. pamscale scales the input image to
71 the largest size that fits within the box, while preserving its aspect
72 ratio. -xysize is a synonym for this. Before Netpbm 10.20 (January
73 2004), -xyfit did not exist, but -xysize did.
74 -xyfill is similar, but pamscale scales the input image to the smallest
76 size that completely fills the box, while preserving its aspect ratio.
77 This option has existed since Netpbm 10.20 (January 2004).
78 -pixels specifies a maximum total number of output pixels. pamscale
80 scales the image down to that number of pixels. If the input image is
81 already no more than that many pixels, pamscale just copies it as out‐
82 put; pamscale does not scale up with -pixels.
83 If you enlarge by a factor of 3 or more, you should probably add a
85 pnmsmooth step; otherwise, you can see the original pixels in the
86 resulting image.
87 Usage Notes
91 A useful application of pamscale is to blur an image. Scale it down
92 (without -nomix) to discard some information, then scale it back up
93 using pamstretch.
94 Or scale it back up with pamscale and create a 'pixelized' image, which
96 is sort of a computer-age version of blurring.
97 Transparency
101 pamscale understands transparency and properly mixes pixels considering
102 the pixels' transparency.
103 Proper mixing does not mean just mixing the transparency value and the
105 color component values separately. In a PAM image, a pixel which is
106 not opaque represents a color that contains light of the foreground
107 color indicated explicitly in the PAM and light of a background color
108 to be named later. But the numerical scale of a color component sample
109 in a PAM is as if the pixel is opaque. So a pixel that is supposed to
110 contain half-strength red light for the foreground plus some light from
111 the background has a red color sample that says full red and a trans‐
112 parency sample that says 50% opaque. In order to mix pixels, you have
113 to first convert the color sample values to numbers that represent
114 amount of light directly (i.e. multiply by the opaqueness) and after
115 mixing, convert back (divide by the opaqueness).
116 Input And Output Image Types
119 pamscale produces output of the same type (and tuple type if the type
120 is PAM) as the input, except if the input is PBM. In that case, the
121 output is PGM with maxval 255. The purpose of this is to allow mean‐
122 ingful pixel mixing. Note that there is no equivalent exception when
123 the input is PAM. If the PAM input tuple type is BLACKANDWHITE, the
124 PAM output tuple type is also BLACKANDWHITE, and you get no meaningful
125 pixel mixing.
126 If you want PBM output with PBM input, use pamditherbw to convert pam‐
128 scale's output to PBM. Also consider pbmreduce.
129 pamscale's function is essentially undefined for PAM input images that
131 are not of tuple type RGB, GRAYSCALE, BLACKANDWHITE, or the _ALPHA
132 variations of those. (By standard Netpbm backward compatibility, this
133 includes PBM, PGM, and PPM images).
134 You might think it would have an obvious effect on other tuple types,
136 but remember that the aforementioned tuple types have gamma-adjusted
137 sample values, and pamscale uses that fact in its calculations. And it
138 treats a transparency plane different from any other plane.
139 pamscale does not simply reject unrecognized tuple types because
141 there's a possibility that just by coincidence you can get useful func‐
142 tion out of it with some other tuple type and the right combination of
143 options (consider -linear in particular).
144 Methods Of Scaling
148 There are numerous ways to scale an image. pamscale implements a bunch
149 of them; you select among them with invocation options.
150 Pixel Mixing
152 Pamscale's default method is pixel mixing. To understand this, imagine
154 the source image as composed of square tiles. Each tile is a pixel and
155 has uniform color. The tiles are all the same size. Now lay over that
156 a transparent sheet of the same size, marked off in a square grid.
157 Each cell in the grid stands for a pixel of the target image. For
158 example, if you are scaling a 100x200 image up by 1.5, the source image
159 is 100 x 200 tiles, and the transparent sheet is marked off in 150 x
160 300 cells.
161 Each cell covers parts of multiple tiles. To make the target image,
163 just color in each cell with the color which is the average of the col‐
164 ors the cell covers -- weighted by the amount of that color it covers.
165 A cell in our example might cover 4/9 of a blue tile, 2/9 of a red
166 tile, 2/9 of a green tile, and 1/9 of a white tile. So the target
167 pixel would be somewhat unsaturated blue.
168 When you are scaling up or down by an integer, the results are simple.
170 When scaling up, pixels get duplicated. When scaling down, pixels get
171 thrown away. In either case, the colors in the target image are a sub‐
172 set of those in the source image.
173 When the scale factor is weirder than that, the target image can have
175 colors that didn't exist in the original. For example, a red pixel
176 next to a white pixel in the source might become a red pixel, a pink
177 pixel, and a white pixel in the target.
178 This method tends to replicate what the human eye does as it moves
180 closer to or further away from an image. It also tends to replicate
181 what the human eye sees, when far enough away to make the pixelization
182 disappear, if an image is not made of pixels and simply stretches or
183 shrinks.
184 Discrete Sampling
186 Discrete sampling is basically the same thing as pixel mixing except
188 that, in the model described above, instead of averaging the colors of
189 the tiles the cell covers, you pick the one color that covers the most
190 area.
191 The result you see is that when you enlarge an image, pixels get dupli‐
193 cated and when you reduce an image, some pixels get discarded.
194 The advantage of this is that you end up with an image made from the
196 same color palette as the original. Sometimes that's important.
197 The disadvantage is that it distorts the picture. If you scale up by
199 1.5 horizontally, for example, the even numbered input pixels are dou‐
200 bled in the output and the odd numbered ones are copied singly. If you
201 have a bunch of one pixel wide lines in the source, you may find that
202 some of them stretch to 2 pixels, others remain 1 pixel when you
203 enlarge. When you reduce, you may find that some of the lines disap‐
204 pear completely.
205 You select discrete sampling with pamscale's -nomix option.
207 Actually, -nomix doesn't do exactly what I described above. It does
209 the scaling in two passes - first horizontal, then vertical. This can
210 produce slightly different results.
211 There is one common case in which one often finds it burdensome to have
213 pamscale make up colors that weren't there originally: Where one is
214 working with an image format such as GIF that has a limited number of
215 possible colors per image. If you take a GIF with 256 colors, convert
216 it to PPM, scale by .625, and convert back to GIF, you will probably
217 find that the reduced image has way more than 256 colors, and therefore
218 cannot be converted to GIF. One way to solve this problem is to do the
219 reduction with discrete sampling instead of pixel mixing. Probably a
220 better way is to do the pixel mixing, but then color quantize the
221 result with pnmquant before converting to GIF.
222 When the scale factor is an integer (which means you're scaling up),
224 discrete sampling and pixel mixing are identical -- output pixels are
225 always just N copies of the input pixels. In this case, though, con‐
226 sider using pamstretch instead of pamscale to get the added pixels
227 interpolated instead of just copied and thereby get a smoother enlarge‐
228 ment.
229 pamscale's discrete sampling is faster than pixel mixing, but pamen‐
231 large is faster still. pamenlarge works only on integer enlargements.
232 discrete sampling (-nomix) was new in Netpbm 9.24 (January 2002).
234 Resampling
237 Resampling assumes that the source image is a discrete sampling of some
239 original continuous image. That is, it assumes there is some non-pix‐
240 elized original image and each pixel of the source image is simply the
241 color of that image at a particular point. Those points, naturally,
242 are the intersections of a square grid.
243 The idea of resampling is just to compute that original image, then
245 sample it at a different frequency (a grid of a different scale).
246 The problem, of course, is that sampling necessarily throws away the
248 information you need to rebuild the original image. So we have to make
249 a bunch of assumptions about the makeup of the original image.
250 You tell pamscale to use the resampling method by specifying the -fil‐
252 ter option. The value of this option is the name of a function, from
253 the set listed below.
254 To explain resampling, we are going to talk about a simple one dimen‐
256 sional scaling -- scaling a single row of grayscale pixels horizon‐
257 tally. If you can understand that, you can easily understand how to do
258 a whole image: Scale each of the rows of the image, then scale each of
259 the resulting columns. And scale each of the color component planes
260 separately.
261 As a first step in resampling, pamscale converts the source image,
263 which is a set of discrete pixel values, into a continuous step func‐
264 tion. A step function is a function whose graph is a staircase-y
265 thing.
266 Now, we convolve the step function with a proper scaling of the filter
268 function that you identified with -filter. If you don't know what the
269 mathematical concept of convolution (convolving) is, you are officially
270 lost. You cannot understand this explanation. The result of this con‐
271 volution is the imaginary original continuous image we've been talking
272 about.
273 Finally, we make target pixels by picking values from that function.
275 To understand what is going on, we use Fourier analysis:
277 The idea is that the only difference between our step function and the
279 original continuous function (remember that we constructed the step
280 function from the source image, which is itself a sampling of the orig‐
281 inal continuous function) is that the step function has a bunch of high
282 frequency Fourier components added. If we could chop out all the
283 higher frequency components of the step function, and know that they're
284 all higher than any frequency in the original function, we'd have the
285 original function back.
286 The resampling method assumes that the original function was sampled at
288 a high enough frequency to form a perfect sampling. A perfect sampling
289 is one from which you can recover exactly the original continuous func‐
290 tion. The Nyquist theorem says that as long as your sample rate is at
291 least twice the highest frequency in your original function, the sam‐
292 pling is perfect. So we assume that the image is a sampling of some‐
293 thing whose highest frequency is half the sample rate (pixel resolu‐
294 tion) or less. Given that, our filtering does in fact recover the
295 original continuous image from the samples (pixels).
296 To chop out all the components above a certain frequency, we just mul‐
298 tiply the Fourier transform of the step function by a rectangle func‐
299 tion.
300 We could find the Fourier transform of the step function, multiply it
302 by a rectangle function, and then Fourier transform the result back,
303 but there's an easier way. Mathematicians tell us that multiplying in
304 the frequency domain is equivalent to convolving in the time domain.
305 That means multiplying the Fourier transform of F by a rectangle func‐
306 tion R is the same as convolving F with the Fourier transform of R.
307 It's a lot better to take the Fourier transform of R, and build it into
308 pamscale than to have pamscale take the Fourier transform of the input
309 image dynamically.
310 That leaves only one question: What is the Fourier transform of a rec‐
312 tangle function? Answer: sinc. Recall from math that sinc is defined
313 as sinc(x) = sin(PI*x)/PI*x.
314 Hence, when you specify -filter=sinc, you are effectively passing the
316 step function of the source image through a low pass frequency filter
317 and recovering a good approximation of the original continuous image.
318 Refiltering
320 There's another twist: If you simply sample the reconstructed original
322 continuous image at the new sample rate, and that new sample rate isn't
323 at least twice the highest frequency in the original continuous image,
324 you won't get a perfect sampling. In fact, you'll get something with
325 ugly aliasing in it. Note that this can't be a problem when you're
326 scaling up (increasing the sample rate), because the fact that the old
327 sample rate was above the Nyquist level means so is the new one. But
328 when scaling down, it's a problem. Obviously, you have to give up
329 image quality when scaling down, but aliasing is not the best way to do
330 it. It's better just to remove high frequency components from the
331 original continuous image before sampling, and then get a perfect sam‐
332 pling of that.
333 Therefore, pamscale filters out frequencies above half the new sample
335 rate before picking the new samples.
336 Approximations
338 Unfortunately, pamscale doesn't do the convolution precisely. Instead
340 of evaluating the filter function at every point, it samples it --
341 assumes that it doesn't change any more often than the step function
342 does. pamscale could actually do the true integration fairly easily.
343 Since the filter functions are built into the program, the integrals of
344 them could be too. Maybe someday it will.
345 There is one more complication with the Fourier analysis. sinc has
347 nonzero values on out to infinity and minus infinity. That makes it
348 hard to compute a convolution with it. So instead, there are filter
349 functions that approximate sinc but are nonzero only within a manage‐
350 able range. To get those, you multiply the sinc function by a window
351 function, which you select with the -window option. The same holds for
352 other filter functions that go on forever like sinc. By default, for a
353 filter that needs a window function, the window function is the Black‐
354 man function.
355 Filter Functions Besides Sinc
357 The math described above works only with sinc as the filter function.
359 pamscale offers many other filter functions, though. Some of these
360 approximate sinc and are faster to compute. For most of them, I have
361 no idea of the mathematical explanation for them, but people do find
362 they give pleasing results. They may not be based on resampling at
363 all, but just exploit the convolution that is coincidentally part of a
364 resampling calculation.
365 For some filter functions, you can tell just by looking at the convolu‐
367 tion how they vary the resampling process from the perfect one based on
368 sinc:
369 The impulse filter assumes that the original continuous image is in
371 fact a step function -- the very one we computed as the first step in
372 the resampling. This is mathematically equivalent to the discrete sam‐
373 pling method.
374 The box (rectangle) filter assumes the original image is a piecewise
376 linear function. Its graph just looks like straight lines connecting
377 the pixel values. This is mathematically equivalent to the pixel mix‐
378 ing method (but mixing brightness, not light intensity, so like pam‐
379 scale -linear) when scaling down, and interpolation (ala pamstretch)
380 when scaling up.
381 Gamma
383 pamscale assumes the underlying continuous function is a function of
385 brightness (as opposed to light intensity), and therefore does all this
386 math using the gamma-adjusted numbers found in a PNM or PAM image. The
387 -linear option is not available with resampling (it causes pamscale to
388 fail), because it wouldn't be useful enough to justify the implementa‐
389 tion effort.
390 Resampling (-filter) was new in Netpbm 10.20 (January 2004).
392 The filter functions
394 Here is a list of the function names you can specify for the -filter
396 option. For most of them, you're on your own to figure out just what
397 the function is and what kind of scaling it does. These are common
398 functions from mathematics.
399 point The graph of this is a single point at X=0, Y=1.
403 box The graph of this is a rectangle sitting on the X axis and cen‐
406 tered on the Y axis with height 1 and base 1.
407 triangle
410 The graph of this is an isosceles triangle sitting on the X axis
411 and centered on the Y axis with height 1 and base 2.
412 quadratic
415 cubic
417 catrom
419 mitchell
421 gauss
423 sinc
425 bessel
427 hanning
429 hamming
431 blackman
433 kaiser
435 normal
437 hermite
439 lanczos
441 Not documented
442 Linear vs Gamma-adjusted
447 The pixel mixing scaling method described above involves intensities of
448 pixels (more precisely, it involves individual intensities of primary
449 color components of pixels). But the PNM and PNM-equivalent PAM image
450 formats represent intensities with gamma-adjusted numbers that are not
451 linearly proportional to intensity. So pamscale, by default, performs
452 a calculation on each sample read from its input and each sample writ‐
453 ten to its output to convert between these gamma-adjusted numbers and
454 internal intensity-proportional numbers.
455 Sometimes you are not working with true PNM or PAM images, but rather a
457 variation in which the sample values are in fact directly proportional
458 to intensity. If so, use the -linear option to tell pamscale this.
459 pamscale then will skip the conversions.
460 The conversion takes time. In one experiment, it increased the time
462 required to reduce an image by a factor of 10. And the difference
463 between intensity-proportional values and gamma-adjusted values may be
464 small enough that you would barely see a difference in the result if
465 you just pretended that the gamma-adjusted values were in fact inten‐
466 sity-proportional. So just to save time, at the expense of some image
467 quality, you can specify -linear even when you have true PPM input and
468 expect true PPM output.
469 For the first 13 years of Netpbm's life, until Netpbm 10.20 (January
471 2004), pamscale's predecessor pnmscale always treated the PPM samples
472 as intensity-proportional even though they were not, and drew few com‐
473 plaints. So using -linear as a lie is a reasonable thing to do if
474 speed is important to you. But if speed is important, you also should
475 consider the -nomix option and pnmscalefixed.
476 Another technique to consider is to convert your PNM image to the lin‐
478 ear variation with pnmgamma, run pamscale on it and other transforma‐
479 tions that like linear PNM, and then convert it back to true PNM with
480 pnmgamma -ungamma. pnmgamma is often faster than pamscale in doing the
481 conversion.
482 With -nomix, -linear has no effect. That's because pamscale does not
484 concern itself with the meaning of the sample values in this method;
485 pamscale just copies numbers from its input to its output.
486 Precision
490 pamscale uses floating point arithmetic internally. There is a speed
491 cost associated with this. For some images, you can get the acceptable
492 results (in fact, sometimes identical results) faster with pnmscale‐
493 fixed, which uses fixed point arithmetic. pnmscalefixed may, however,
494 distort your image a little. See the pnmscalefixed user manual for a
495 complete discussion of the difference.
496
499 pnmscalefixed(1), pamstretch(1), pamditherbw(1), pbmreduce(1), pbmp‐
500 scale(1), pamenlarge(1), pnmsmooth(1), pamcut(1), pnmgamma(1), pnm‐
501 scale(1), pnm(1), pam(1)
502
505 pamscale was new in Netpbm 10.20 (January 2004). It was adapted from,
506 and obsoleted, pnmscale. pamscale's primary difference from pnmscale
507 is that it handles the PAM format and uses the "pam" facilities of the
508 Netpbm programming library. But it also added the resampling class of
509 scaling method. Furthermore, it properly does its pixel mixing arith‐
510 metic (by default) using intensity-proportional values instead of the
511 gamma-adjusted values the pnmscale uses. To get the old pnmscale
512 arithmetic, you can specify the -linear option.
513 The intensity proportional stuff came out of suggestions by Adam M
515 Costello in January 2004.
516 The resampling algorithms are mostly taken from code contributed by
518 Michael Reinelt in December 2003.
519 The version of pnmscale from which pamscale was derived, itself evolved
521 out of the original Pbmplus version of pnmscale by Jef Poskanzer (1989,
522 1991). But none of that original code remains.
523netpbm documentation 18 February 2005 Pamscale User Manual(0)