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