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}
15 cols rows
16 |
17 -reduce reduction_factor
18 |
19 [-xsize=cols | -width=cols | -xscale=factor]
20 [-ysize=rows | -height=rows | -yscale=factor]
21 |
22 -pixels n
23 ]
24 [
25 -nomix
26 |
27 -filter=functionName [-window=functionName]
28 ]
29 [-linear]
30 [-reportonly]
31 [-verbose]
32 [pnmfile]
34 Minimum unique abbreviation of option is acceptable. You may use dou‐
38 ble hyphens instead of single hyphen to denote options. You may use
39 white space in place of the equals sign to separate an option name from
40 its value.
41
44 This program is part of Netpbm(1).
45 pamscale scales a Netpbm image by a specified factor, or scales indi‐
47 vidually horizontally and vertically by specified factors.
48 You can either enlarge (scale factor > 1) or reduce (scale factor < 1).
50 pamscale works on multi-image streams, scaling each one independently.
52 But before Netpbm 10.49 (December 2009), it scales only the first image
53 and ignores the rest of the stream.
54 The Scale Factors
57 The options -width, -height, -xsize, -ysize, -xscale, -yscale, -xyfit,
58 -xyfill, -reduce, and -pixels control the amount of scaling. For back‐
59 ward compatibility, there are also -xysize and the scale_factor argu‐
60 ment, but you shouldn't use those.
61 -width and -height specify the width and height in pixels you want the
63 resulting image to be. See below for rules when you specify one and
64 not the other.
65 -xsize and -ysize are synonyms for -width and -height, respectively.
67 -xscale and -yscale tell the factor by which you want the width and
69 height of the image to change from source to result (e.g. -xscale 2
70 means you want to double the width; -xscale .5 means you want to halve
71 it). See below for rules when you specify one and not the other.
72 When you specify an absolute size or scale factor for both dimensions,
74 pamscale scales each dimension independently without consideration of
75 the aspect ratio.
76 If you specify one dimension as a pixel size and don't specify the
78 other dimension, pamscale scales the unspecified dimension to preserve
79 the aspect ratio.
80 If you specify one dimension as a scale factor and don't specify the
82 other dimension, pamscale leaves the unspecified dimension unchanged
83 from the input.
84 If you specify the scale_factor parameter instead of dimension options,
86 that is the scale factor for both dimensions. It is equivalent to -xs‐
87 cale=scale_factor -yscale=scale_factor.
88 Specifying the -reduce reduction_factor option is equivalent to speci‐
90 fying the scale_factor parameter, where scale_factor is the reciprocal
91 of reduction_factor.
92 -xyfit specifies a bounding box. pamscale scales the input image to
94 the largest size that fits within the box, while preserving its aspect
95 ratio. -xysize is a synonym for this. Before Netpbm 10.20 (January
96 2004), -xyfit did not exist, but -xysize did.
97 -xyfill is similar, but pamscale scales the input image to the smallest
99 size that completely fills the box, while preserving its aspect ratio.
100 This option has existed since Netpbm 10.20 (January 2004).
101 -pixels specifies a maximum total number of output pixels. pamscale
103 scales the image down to that number of pixels. If the input image is
104 already no more than that many pixels, pamscale just copies it as out‐
105 put; pamscale does not scale up with -pixels.
106 If you enlarge by a factor of 3 or more, you should probably add a pn‐
108 msmooth step; otherwise, you can see the original pixels in the result‐
109 ing image.
110 -reportonly
112 The option -reportonly causes pamscale not to scale the image, but in‐
114 stead to report to Standard Output what scaling the options and the in‐
115 put image dimensions indicate. For example, if you specify
116 -xyfill 100 100 -reportonly
117 and the input image is 500 x 400, pamscale tells you that this means
119 scaling by .25 to end up with a 125 x 100 image.
120 You can use this information with other programs, such as pamscale‐
122 fixed, that don't have as rich facilities as pamscale for choosing
123 scale factors.
124 The output is intended to be convenient for machine processing. In the
126 example above, it would be
127 500 400 0.250000 0.250000 125 100
130 The output is a single line of text per input image, with blank-sepa‐
134 rated tokens as follows.
135 • input width in pixels, decimal unsigned integer
139 • input height in pixels, decimal unsigned integer
141 • horizontal scale factor, floating point decimal, unsigned
143 • vertical scale factor, floating point decimal, unsigned
145 • output width in pixels, decimal unsigned integer
147 • output height in pixels, decimal unsigned integer
149 -reportonly was new in Netpbm 10.86 (March 2019).
152 Usage Notes
156 A useful application of pamscale is to blur an image. Scale it down
157 (without -nomix) to discard some information, then scale it back up us‐
158 ing pamstretch.
159 Or scale it back up with pamscale and create a "pixelized" image, which
161 is sort of a computer-age version of blurring.
162 Transparency
166 pamscale understands transparency and properly mixes pixels considering
167 the pixels' transparency.
168 Proper mixing does not mean just mixing the transparency value and the
170 color component values separately. In a PAM image, a pixel which is
171 not opaque represents a color that contains light of the foreground
172 color indicated explicitly in the PAM and light of a background color
173 to be named later. But the numerical scale of a color component sample
174 in a PAM is as if the pixel is opaque. So a pixel that is supposed to
175 contain half-strength red light for the foreground plus some light from
176 the background has a red color sample that says full red and a trans‐
177 parency sample that says 50% opaque. In order to mix pixels, you have
178 to first convert the color sample values to numbers that represent
179 amount of light directly (i.e. multiply by the opaqueness) and after
180 mixing, convert back (divide by the opaqueness).
181 Input And Output Image Types
184 pamscale produces output of the same type (and tuple type if the type
185 is PAM) as the input, except if the input is PBM. In that case, the
186 output is PGM with maxval 255. The purpose of this is to allow mean‐
187 ingful pixel mixing. Note that there is no equivalent exception when
188 the input is PAM. If the PAM input tuple type is BLACKANDWHITE, the
189 PAM output tuple type is also BLACKANDWHITE, and you get no meaningful
190 pixel mixing.
191 If you want PBM output with PBM input, use pamditherbw to convert pam‐
193 scale's output to PBM. Also consider pbmreduce.
194 pamscale's function is essentially undefined for PAM input images that
196 are not of tuple type RGB, GRAYSCALE, BLACKANDWHITE, or the _ALPHA
197 variations of those. (By standard Netpbm backward compatibility, this
198 includes PBM, PGM, and PPM images).
199 You might think it would have an obvious effect on other tuple types,
201 but remember that the aforementioned tuple types have gamma-adjusted
202 sample values, and pamscale uses that fact in its calculations. And it
203 treats a transparency plane different from any other plane.
204 pamscale does not simply reject unrecognized tuple types because
206 there's a possibility that just by coincidence you can get useful func‐
207 tion out of it with some other tuple type and the right combination of
208 options (consider -linear in particular).
209 Methods Of Scaling
213 There are numerous ways to scale an image. pamscale implements a bunch
214 of them; you select among them with invocation options.
215 Pixel Mixing
217 Pamscale's default method is pixel mixing. To understand this, imagine
219 the source image as composed of square tiles. Each tile is a pixel and
220 has uniform color. The tiles are all the same size. Now take a trans‐
221 parent sheet the size of the target image, marked with a square grid of
222 tiles the same size. Stretch or compress the source image to the size
223 of the sheet and lay the sheet over the source.
224 Each cell in the overlay grid stands for a pixel of the target image.
226 For example, if you are scaling a 100x200 image up by 1.5, the source
227 image is 100 x 200 tiles, and the transparent sheet is marked off in
228 150 x 300 cells.
229 Each cell covers parts of multiple tiles. To make the target image,
231 just color in each cell with the color which is the average of the col‐
232 ors the cell covers -- weighted by the amount of that color it covers.
233 A cell in our example might cover 4/9 of a blue tile, 2/9 of a red
234 tile, 2/9 of a green tile, and 1/9 of a white tile. So the target
235 pixel would be somewhat unsaturated blue.
236 When you are scaling up or down by an integer, the results are simple.
238 When scaling up, pixels get duplicated. When scaling down, pixels get
239 thrown away. In either case, the colors in the target image are a sub‐
240 set of those in the source image.
241 When the scale factor is weirder than that, the target image can have
243 colors that didn't exist in the original. For example, a red pixel
244 next to a white pixel in the source might become a red pixel, a pink
245 pixel, and a white pixel in the target.
246 This method tends to replicate what the human eye does as it moves
248 closer to or further away from an image. It also tends to replicate
249 what the human eye sees, when far enough away to make the pixelization
250 disappear, if an image is not made of pixels and simply stretches or
251 shrinks.
252 Discrete Sampling
254 Discrete sampling is basically the same thing as pixel mixing except
256 that, in the model described above, instead of averaging the colors of
257 the tiles the cell covers, you pick the one color that covers the most
258 area.
259 The result you see is that when you enlarge an image, pixels get dupli‐
261 cated and when you reduce an image, some pixels get discarded.
262 The advantage of this is that you end up with an image made from the
264 same color palette as the original. Sometimes that's important.
265 The disadvantage is that it distorts the picture. If you scale up by
267 1.5 horizontally, for example, the even numbered input pixels are dou‐
268 bled in the output and the odd numbered ones are copied singly. If you
269 have a bunch of one pixel wide lines in the source, you may find that
270 some of them stretch to 2 pixels, others remain 1 pixel when you en‐
271 large. When you reduce, you may find that some of the lines disappear
272 completely.
273 You select discrete sampling with pamscale's -nomix option.
275 Actually, -nomix doesn't do exactly what I described above. It does
277 the scaling in two passes - first horizontal, then vertical. This can
278 produce slightly different results.
279 There is one common case in which one often finds it burdensome to have
281 pamscale make up colors that weren't there originally: Where one is
282 working with an image format such as GIF that has a limited number of
283 possible colors per image. If you take a GIF with 256 colors, convert
284 it to PPM, scale by .625, and convert back to GIF, you will probably
285 find that the reduced image has way more than 256 colors, and therefore
286 cannot be converted to GIF. One way to solve this problem is to do the
287 reduction with discrete sampling instead of pixel mixing. Probably a
288 better way is to do the pixel mixing, but then color quantize the re‐
289 sult with pnmquant before converting to GIF.
290 When the scale factor is an integer (which means you're scaling up),
292 discrete sampling and pixel mixing are identical -- output pixels are
293 always just N copies of the input pixels. In this case, though, con‐
294 sider using pamstretch instead of pamscale to get the added pixels in‐
295 terpolated instead of just copied and thereby get a smoother enlarge‐
296 ment.
297 pamscale's discrete sampling is faster than pixel mixing, but pamen‐
299 large is faster still. pamenlarge works only on integer enlargements.
300 discrete sampling (-nomix) was new in Netpbm 9.24 (January 2002).
302 Resampling
305 Resampling assumes that the source image is a discrete sampling of some
307 original continuous image. That is, it assumes there is some non-pix‐
308 elized original image and each pixel of the source image is simply the
309 color of that image at a particular point. Those points, naturally,
310 are the intersections of a square grid.
311 The idea of resampling is just to compute that original image, then
313 sample it at a different frequency (a grid of a different scale).
314 The problem, of course, is that sampling necessarily throws away the
316 information you need to rebuild the original image. So we have to make
317 a bunch of assumptions about the makeup of the original image.
318 You tell pamscale to use the resampling method by specifying the -fil‐
320 ter option. The value of this option is the name of a function, from
321 the set listed below.
322 To explain resampling, we are going to talk about a simple one dimen‐
324 sional scaling -- scaling a single row of grayscale pixels horizon‐
325 tally. If you can understand that, you can easily understand how to do
326 a whole image: Scale each of the rows of the image, then scale each of
327 the resulting columns. And scale each of the color component planes
328 separately.
329 As a first step in resampling, pamscale converts the source image,
331 which is a set of discrete pixel values, into a continuous step func‐
332 tion. A step function is a function whose graph is a staircase-y
333 thing.
334 Now, we convolve the step function with a proper scaling of the filter
336 function that you identified with -filter. If you don't know what the
337 mathematical concept of convolution (convolving) is, you are officially
338 lost. You cannot understand this explanation. The result of this con‐
339 volution is the imaginary original continuous image we've been talking
340 about.
341 Finally, we make target pixels by picking values from that function.
343 To understand what is going on, we use Fourier analysis:
345 The idea is that the only difference between our step function and the
347 original continuous function (remember that we constructed the step
348 function from the source image, which is itself a sampling of the orig‐
349 inal continuous function) is that the step function has a bunch of high
350 frequency Fourier components added. If we could chop out all the
351 higher frequency components of the step function, and know that they're
352 all higher than any frequency in the original function, we'd have the
353 original function back.
354 The resampling method assumes that the original function was sampled at
356 a high enough frequency to form a perfect sampling. A perfect sampling
357 is one from which you can recover exactly the original continuous func‐
358 tion. The Nyquist theorem says that as long as your sample rate is at
359 least twice the highest frequency in your original function, the sam‐
360 pling is perfect. So we assume that the image is a sampling of some‐
361 thing whose highest frequency is half the sample rate (pixel resolu‐
362 tion) or less. Given that, our filtering does in fact recover the
363 original continuous image from the samples (pixels).
364 To chop out all the components above a certain frequency, we just mul‐
366 tiply the Fourier transform of the step function by a rectangle func‐
367 tion.
368 We could find the Fourier transform of the step function, multiply it
370 by a rectangle function, and then Fourier transform the result back,
371 but there's an easier way. Mathematicians tell us that multiplying in
372 the frequency domain is equivalent to convolving in the time domain.
373 That means multiplying the Fourier transform of F by a rectangle func‐
374 tion R is the same as convolving F with the Fourier transform of R.
375 It's a lot better to take the Fourier transform of R, and build it into
376 pamscale than to have pamscale take the Fourier transform of the input
377 image dynamically.
378 That leaves only one question: What is the Fourier transform of a rec‐
380 tangle function? Answer: sinc. Recall from math that sinc is defined
381 as sinc(x) = sin(PI*x)/PI*x.
382 Hence, when you specify -filter=sinc, you are effectively passing the
384 step function of the source image through a low pass frequency filter
385 and recovering a good approximation of the original continuous image.
386 Refiltering
388 There's another twist: If you simply sample the reconstructed original
390 continuous image at the new sample rate, and that new sample rate isn't
391 at least twice the highest frequency in the original continuous image,
392 you won't get a perfect sampling. In fact, you'll get something with
393 ugly aliasing in it. Note that this can't be a problem when you're
394 scaling up (increasing the sample rate), because the fact that the old
395 sample rate was above the Nyquist level means so is the new one. But
396 when scaling down, it's a problem. Obviously, you have to give up im‐
397 age quality when scaling down, but aliasing is not the best way to do
398 it. It's better just to remove high frequency components from the
399 original continuous image before sampling, and then get a perfect sam‐
400 pling of that.
401 Therefore, pamscale filters out frequencies above half the new sample
403 rate before picking the new samples.
404 Approximations
406 Unfortunately, pamscale doesn't do the convolution precisely. Instead
408 of evaluating the filter function at every point, it samples it -- as‐
409 sumes that it doesn't change any more often than the step function
410 does. pamscale could actually do the true integration fairly easily.
411 Since the filter functions are built into the program, the integrals of
412 them could be too. Maybe someday it will.
413 There is one more complication with the Fourier analysis. sinc has
415 nonzero values on out to infinity and minus infinity. That makes it
416 hard to compute a convolution with it. So instead, there are filter
417 functions that approximate sinc but are nonzero only within a manage‐
418 able range. To get those, you multiply the sinc function by a window
419 function, which you select with the -window option. The same holds for
420 other filter functions that go on forever like sinc. By default, for a
421 filter that needs a window function, the window function is the Black‐
422 man function. Hanning, Hamming, and Kaiser are alternatives.
423 Filter Functions Besides Sinc
425 The math described above works only with sinc as the filter function.
427 pamscale offers many other filter functions, though. Some of these ap‐
428 proximate sinc and are faster to compute. For most of them, I have no
429 idea of the mathematical explanation for them, but people do find they
430 give pleasing results. They may not be based on resampling at all, but
431 just exploit the convolution that is coincidentally part of a resam‐
432 pling calculation.
433 For some filter functions, you can tell just by looking at the convolu‐
435 tion how they vary the resampling process from the perfect one based on
436 sinc:
437 The impulse filter assumes that the original continuous image is in
439 fact a step function -- the very one we computed as the first step in
440 the resampling. This is mathematically equivalent to the discrete sam‐
441 pling method.
442 The box (rectangle) filter assumes the original image is a piecewise
444 linear function. Its graph just looks like straight lines connecting
445 the pixel values. This is mathematically equivalent to the pixel mix‐
446 ing method (but mixing brightness, not light intensity, so like pam‐
447 scale -linear) when scaling down, and interpolation (ala pamstretch)
448 when scaling up.
449 Gamma
451 pamscale assumes the underlying continuous function is a function of
453 brightness (as opposed to light intensity), and therefore does all this
454 math using the gamma-adjusted numbers found in a PNM or PAM image. The
455 -linear option is not available with resampling (it causes pamscale to
456 fail), because it wouldn't be useful enough to justify the implementa‐
457 tion effort.
458 Resampling (-filter) was new in Netpbm 10.20 (January 2004).
460 The filter and window functions
462 Here is a list of the function names you can specify for the -filter or
464 -windowoption. For most of them, you're on your own to figure out just
465 what the function is and what kind of scaling it does. These are com‐
466 mon functions from mathematics. Note that some of these make sense
467 only as filter functions and some make sense only as window funcions.
468 point The graph of this is a single point at X=0, Y=1.
472 box The graph of this is a rectangle sitting on the X axis and cen‐
475 tered on the Y axis with height 1 and base 1.
476 triangle
479 The graph of this is an isosceles triangle sitting on the X axis
480 and centered on the Y axis with height 1 and base 2.
481 quadratic
484 cubic
486 catrom
488 mitchell
490 gauss
492 sinc
494 bessel
496 hanning
498 hamming
500 blackman
502 kaiser
504 normal
506 hermite
508 lanczos
510 Not documented
511 Linear vs Gamma-adjusted
516 The pixel mixing scaling method described above involves intensities of
517 pixels (more precisely, it involves individual intensities of primary
518 color components of pixels). But the PNM and PNM-equivalent PAM image
519 formats represent intensities with gamma-adjusted numbers that are not
520 linearly proportional to intensity. So pamscale, by default, performs
521 a calculation on each sample read from its input and each sample writ‐
522 ten to its output to convert between these gamma-adjusted numbers and
523 internal intensity-proportional numbers.
524 Sometimes you are not working with true PNM or PAM images, but rather a
526 variation in which the sample values are in fact directly proportional
527 to intensity. If so, use the -linear option to tell pamscale this.
528 pamscale then will skip the conversions.
529 The conversion takes time. In one experiment, it increased by a factor
531 of 10 the time required to reduce an image. And the difference between
532 intensity-proportional values and gamma-adjusted values may be small
533 enough that you would barely see a difference in the result if you just
534 pretended that the gamma-adjusted values were in fact intensity-propor‐
535 tional. So just to save time, at the expense of some image quality,
536 you can specify -linear even when you have true PPM input and expect
537 true PPM output.
538 For the first 13 years of Netpbm's life, until Netpbm 10.20 (January
540 2004), pamscale's predecessor pnmscale always treated the PPM samples
541 as intensity-proportional even though they were not, and drew few com‐
542 plaints. So using -linear as a lie is a reasonable thing to do if
543 speed is important to you. But if speed is important, you also should
544 consider the -nomix option and pnmscalefixed.
545 Another technique to consider is to convert your PNM image to the lin‐
547 ear variation with pnmgamma, run pamscale on it and other transforma‐
548 tions that like linear PNM, and then convert it back to true PNM with
549 pnmgamma -ungamma. pnmgamma is often faster than pamscale in doing the
550 conversion.
551 With -nomix, -linear has no effect. That's because pamscale does not
553 concern itself with the meaning of the sample values in this method;
554 pamscale just copies numbers from its input to its output.
555 Precision
559 pamscale uses floating point arithmetic internally. There is a speed
560 cost associated with this. For some images, you can get the acceptable
561 results (in fact, sometimes identical results) faster with pnmscale‐
562 fixed, which uses fixed point arithmetic. pnmscalefixed may, however,
563 distort your image a little. See the pnmscalefixed user manual for a
564 complete discussion of the difference.
565
568 In addition to the options common to all programs based on libnetpbm
569 (most notably -quiet, see
570 Common Options ⟨index.html#commonoptions⟩ ), pamscale recognizes the
571 following command line options:
572 -width
577 -height
579 -xsize
581 -ysize
583 -xscale
585 -yscale
587 -xyfit
589 -xyfill
591 -reduce
593 -pixels
595 -xysize
597 These options determine the horizontal and vertical scale fac‐
598 tors.
599 See The Scale Factors ⟨#scalefactor⟩ .
601 -reportonly
604 This causes pamscale not to scale the image, but instead to
605 report to Standard Output what scaling the options and the in‐
606 put image
607 dimensions indicate.
608 See -reportonly ⟨#reportonly⟩ .
610 -nomix
613 This option selects discrete sampling ⟨#sampling⟩ as the
614 method of scaling ⟨#methods⟩ .
616 -filter=functionName
619 This option selects resampling ⟨#resampling⟩ as the
620 method of scaling ⟨#methods⟩ .
622 -window=functionName
625 This option selects a window function to modify the filter
626 function
627 specified with -filter.
628 See Resampling ⟨#resampling⟩ .
630 -verbose
633 This option causes pamscale to issue messages to Standard Er‐
634 ror about
635 the scaling.
636
642 pnmscalefixed(1), pamstretch(1), pamstretch-gen(1), pamditherbw(1),
643 pbmreduce(1), pbmpscale(1), pamenlarge(1), pnmsmooth(1), pamcut(1), pn‐
644 mgamma(1), pnmscale(1), pnm(1), pam(1)
645
648 pamscale was new in Netpbm 10.20 (January 2004). It was adapted from,
649 and obsoleted, pnmscale. pamscale's primary difference from pnmscale
650 is that it handles the PAM format and uses the "pam" facilities of the
651 Netpbm programming library. But it also added the resampling class of
652 scaling method. Furthermore, it properly does its pixel mixing arith‐
653 metic (by default) using intensity-proportional values instead of the
654 gamma-adjusted values the pnmscale uses. To get the old pnmscale
655 arithmetic, you can specify the -linear option.
656 The intensity proportional stuff came out of suggestions by Adam M
658 Costello in January 2004.
659 The resampling algorithms are mostly taken from code contributed by
661 Michael Reinelt in December 2003.
662 The version of pnmscale from which pamscale was derived, itself evolved
664 out of the original Pbmplus version of pnmscale by Jef Poskanzer (1989,
665 1991). But none of that original code remains.
666
668 This manual page was generated by the Netpbm tool 'makeman' from HTML
669 source. The master documentation is at
670 http://netpbm.sourceforge.net/doc/pamscale.html
672netpbm documentation 29 June 2020 Pamscale User Manual(0)