pamscale man page on CentOS

Man page or keyword search:  
man Server   8420 pages
apropos Keyword Search (all sections)
Output format
CentOS logo
[printable version]

Pamscale User Manual(0)				       Pamscale User Manual(0)

NAME
       pamscale - scale a Netpbm image

SYNOPSIS
	  pamscale
	     [
		scale_factor
		|
		{-xyfit | -xyfill | -xysize} cols rows
		|
		-reduce reduction_factor
		|
		[-xsize=cols | -width=cols | -xscale=factor]
		[-ysize=rows | -height=rows | -yscale=factor]
		|
		-pixels n
	     ]
	     [
		[-verbose]
		[
		   -nomix
		   |
		   -filter=functionName [-window=functionName]
		]
		[-linear]
	     }
	     [pnmfile]

       Minimum	unique abbreviation of option is acceptable.  You may use dou‐
       ble hyphens instead of single hyphen to denote options.	 You  may  use
       white space in place of the equals sign to separate an option name from
       its value.

DESCRIPTION
       This program is part of Netpbm(1).

       pamscale scales a Netpbm image by a specified factor, or	 scales	 indi‐
       vidually horizontally and vertically by specified factors.

       You can either enlarge (scale factor > 1) or reduce (scale factor < 1).

   The Scale Factors
       When  you specify an absolute size or scale factor for both dimensions,
       pamscale scales each dimension independently without  consideration  of
       the aspect ratio.

       If  you	specify	 one  dimension	 as a pixel size and don't specify the
       other dimension, pamscale scales the unspecified dimension to  preserve
       the aspect ratio.

       If  you	specify	 one dimension as a scale factor and don't specify the
       other dimension, pamscale leaves the  unspecified  dimension  unchanged
       from the input.

       If you specify the scale_factor parameter instead of dimension options,
       that is the scale factor for both  dimensions.	It  is	equivalent  to
       -xscale=scale_factor -yscale=scale_factor.

       Specifying  the -reduce reduction_factor option is equivalent to speci‐
       fying the scale_factor  parameter, where scale_factor is the reciprocal
       of reduction_factor.

       -xyfit  specifies  a  bounding box.  pamscale scales the input image to
       the largest size that fits within the box, while preserving its	aspect
       ratio.	-xysize	 is  a synonym for this.  Before Netpbm 10.20 (January
       2004), -xyfit did not exist, but -xysize did.

       -xyfill is similar, but pamscale scales the input image to the smallest
       size  that completely fills the box, while preserving its aspect ratio.
       This option has existed since Netpbm 10.20 (January 2004).

       -pixels specifies a maximum total number of  output  pixels.   pamscale
       scales  the image down to that number of pixels.	 If the input image is
       already no more than that many pixels, pamscale just copies it as  out‐
       put; pamscale does not scale up with -pixels.

       If  you	enlarge	 by  a	factor of 3 or more, you should probably add a
       pnmsmooth step; otherwise, you can  see	the  original  pixels  in  the
       resulting image.

   Usage Notes
       A  useful  application  of pamscale is to blur an image.	 Scale it down
       (without -nomix) to discard some information, then  scale  it  back  up
       using pamstretch.

       Or scale it back up with pamscale and create a 'pixelized' image, which
       is sort of a computer-age version of blurring.

   Transparency
       pamscale understands transparency and properly mixes pixels considering
       the pixels' transparency.

       Proper  mixing does not mean just mixing the transparency value and the
       color component values separately.  In a PAM image, a  pixel  which  is
       not  opaque  represents	a  color that contains light of the foreground
       color indicated explicitly in the PAM and light of a  background	 color
       to be named later.  But the numerical scale of a color component sample
       in a PAM is as if the pixel is opaque.  So a pixel that is supposed  to
       contain half-strength red light for the foreground plus some light from
       the background has a red color sample that says full red and  a	trans‐
       parency	sample that says 50% opaque.  In order to mix pixels, you have
       to first convert the color sample  values  to  numbers  that  represent
       amount  of  light  directly (i.e. multiply by the opaqueness) and after
       mixing, convert back (divide by the opaqueness).

   Input And Output Image Types
       pamscale produces output of the same type (and tuple type if  the  type
       is  PAM)	 as  the input, except if the input is PBM.  In that case, the
       output is PGM with maxval 255.  The purpose of this is to  allow	 mean‐
       ingful  pixel  mixing.  Note that there is no equivalent exception when
       the input is PAM.  If the PAM input tuple type  is  BLACKANDWHITE,  the
       PAM  output tuple type is also BLACKANDWHITE, and you get no meaningful
       pixel mixing.

       If you want PBM output with PBM input, use pamditherbw to convert  pam‐
       scale's output to PBM.  Also consider pbmreduce.

       pamscale's  function is essentially undefined for PAM input images that
       are not of tuple type RGB,  GRAYSCALE,  BLACKANDWHITE,  or  the	_ALPHA
       variations  of those.  (By standard Netpbm backward compatibility, this
       includes PBM, PGM, and PPM images).

       You might think it would have an obvious effect on other	 tuple	types,
       but  remember  that  the aforementioned tuple types have gamma-adjusted
       sample values, and pamscale uses that fact in its calculations.	And it
       treats a transparency plane different from any other plane.

       pamscale	 does  not  simply  reject  unrecognized  tuple	 types because
       there's a possibility that just by coincidence you can get useful func‐
       tion  out of it with some other tuple type and the right combination of
       options (consider -linear in particular).

   Methods Of Scaling
       There are numerous ways to scale an image.  pamscale implements a bunch
       of them; you select among them with invocation options.

       Pixel Mixing

       Pamscale's default method is pixel mixing.  To understand this, imagine
       the source image as composed of square tiles.  Each tile is a pixel and
       has uniform color.  The tiles are all the same size.  Now lay over that
       a transparent sheet of the same size, marked  off  in  a	 square	 grid.
       Each  cell  in  the  grid  stands for a pixel of the target image.  For
       example, if you are scaling a 100x200 image up by 1.5, the source image
       is  100	x  200 tiles, and the transparent sheet is marked off in 150 x
       300 cells.

       Each cell covers parts of multiple tiles.  To make  the	target	image,
       just color in each cell with the color which is the average of the col‐
       ors the cell covers -- weighted by the amount of that color it  covers.
       A  cell	in  our	 example  might cover 4/9 of a blue tile, 2/9 of a red
       tile, 2/9 of a green tile, and 1/9 of a	white  tile.   So  the	target
       pixel would be somewhat unsaturated blue.

       When  you are scaling up or down by an integer, the results are simple.
       When scaling up, pixels get duplicated.	When scaling down, pixels  get
       thrown away.  In either case, the colors in the target image are a sub‐
       set of those in the source image.

       When the scale factor is weirder than that, the target image  can  have
       colors  that  didn't  exist  in the original.  For example, a red pixel
       next to a white pixel in the source might become a red  pixel,  a  pink
       pixel, and a white pixel in the target.

       This  method  tends  to	replicate  what the human eye does as it moves
       closer to or further away from an image.	 It also  tends	 to  replicate
       what  the human eye sees, when far enough away to make the pixelization
       disappear, if an image is not made of pixels and	 simply	 stretches  or
       shrinks.

       Discrete Sampling

       Discrete	 sampling  is  basically the same thing as pixel mixing except
       that, in the model described above, instead of averaging the colors  of
       the  tiles the cell covers, you pick the one color that covers the most
       area.

       The result you see is that when you enlarge an image, pixels get dupli‐
       cated and when you reduce an image, some pixels get discarded.

       The  advantage  of  this is that you end up with an image made from the
       same color palette as the original.  Sometimes that's important.

       The disadvantage is that it distorts the picture.  If you scale	up  by
       1.5  horizontally, for example, the even numbered input pixels are dou‐
       bled in the output and the odd numbered ones are copied singly.	If you
       have  a	bunch of one pixel wide lines in the source, you may find that
       some of them stretch to 2  pixels,  others  remain  1  pixel  when  you
       enlarge.	  When	you reduce, you may find that some of the lines disap‐
       pear completely.

       You select discrete sampling with pamscale's -nomix option.

       Actually, -nomix doesn't do exactly what I described  above.   It  does
       the  scaling in two passes - first horizontal, then vertical.  This can
       produce slightly different results.

       There is one common case in which one often finds it burdensome to have
       pamscale	 make  up  colors  that weren't there originally: Where one is
       working with an image format such as GIF that has a limited  number  of
       possible	 colors per image.  If you take a GIF with 256 colors, convert
       it to PPM, scale by .625, and convert back to GIF,  you	will  probably
       find that the reduced image has way more than 256 colors, and therefore
       cannot be converted to GIF.  One way to solve this problem is to do the
       reduction  with	discrete sampling instead of pixel mixing.  Probably a
       better way is to do the pixel  mixing,  but  then  color	 quantize  the
       result with pnmquant before converting to GIF.

       When  the  scale	 factor is an integer (which means you're scaling up),
       discrete sampling and pixel mixing are identical -- output  pixels  are
       always  just  N copies of the input pixels.  In this case, though, con‐
       sider using pamstretch instead of pamscale  to  get  the	 added	pixels
       interpolated instead of just copied and thereby get a smoother enlarge‐
       ment.

       pamscale's discrete sampling is faster than pixel  mixing,  but	pamen‐
       large is faster still.  pamenlarge works only on integer enlargements.

       discrete sampling (-nomix) was new in Netpbm 9.24 (January 2002).

       Resampling

       Resampling assumes that the source image is a discrete sampling of some
       original continuous image.  That is, it assumes there is some  non-pix‐
       elized  original image and each pixel of the source image is simply the
       color of that image at a particular point.   Those  points,  naturally,
       are the intersections of a square grid.

       The  idea  of  resampling  is just to compute that original image, then
       sample it at a different frequency (a grid of a different scale).

       The problem, of course, is that sampling necessarily  throws  away  the
       information you need to rebuild the original image.  So we have to make
       a bunch of assumptions about the makeup of the original image.

       You tell pamscale to use the resampling method by specifying the	 -fil‐
       ter  option.   The value of this option is the name of a function, from
       the set listed below.

       To explain resampling, we are going to talk about a simple  one	dimen‐
       sional  scaling	--  scaling  a single row of grayscale pixels horizon‐
       tally.  If you can understand that, you can easily understand how to do
       a  whole image: Scale each of the rows of the image, then scale each of
       the resulting columns.  And scale each of the  color  component	planes
       separately.

       As  a  first  step  in  resampling, pamscale converts the source image,
       which is a set of discrete pixel values, into a continuous  step	 func‐
       tion.   A  step	function  is  a	 function whose graph is a staircase-y
       thing.

       Now, we convolve the step function with a proper scaling of the	filter
       function	 that you identified with -filter.  If you don't know what the
       mathematical concept of convolution (convolving) is, you are officially
       lost.  You cannot understand this explanation.  The result of this con‐
       volution is the imaginary original continuous image we've been  talking
       about.

       Finally, we make target pixels by picking values from that function.

       To understand what is going on, we use Fourier analysis:

       The  idea is that the only difference between our step function and the
       original continuous function (remember that  we	constructed  the  step
       function from the source image, which is itself a sampling of the orig‐
       inal continuous function) is that the step function has a bunch of high
       frequency  Fourier  components  added.	If  we	could chop out all the
       higher frequency components of the step function, and know that they're
       all  higher  than any frequency in the original function, we'd have the
       original function back.

       The resampling method assumes that the original function was sampled at
       a high enough frequency to form a perfect sampling.  A perfect sampling
       is one from which you can recover exactly the original continuous func‐
       tion.   The Nyquist theorem says that as long as your sample rate is at
       least twice the highest frequency in your original function,  the  sam‐
       pling  is  perfect.  So we assume that the image is a sampling of some‐
       thing whose highest frequency is half the sample	 rate  (pixel  resolu‐
       tion)  or  less.	  Given	 that,	our filtering does in fact recover the
       original continuous image from the samples (pixels).

       To chop out all the components above a certain frequency, we just  mul‐
       tiply  the  Fourier transform of the step function by a rectangle func‐
       tion.

       We could find the Fourier transform of the step function,  multiply  it
       by  a  rectangle	 function, and then Fourier transform the result back,
       but there's an easier way.  Mathematicians tell us that multiplying  in
       the  frequency  domain  is equivalent to convolving in the time domain.
       That means multiplying the Fourier transform of F by a rectangle	 func‐
       tion  R	is  the	 same as convolving F with the Fourier transform of R.
       It's a lot better to take the Fourier transform of R, and build it into
       pamscale	 than to have pamscale take the Fourier transform of the input
       image dynamically.

       That leaves only one question:  What is the Fourier transform of a rec‐
       tangle  function?  Answer: sinc.	 Recall from math that sinc is defined
       as sinc(x) = sin(PI*x)/PI*x.

       Hence, when you specify -filter=sinc, you are effectively  passing  the
       step  function  of the source image through a low pass frequency filter
       and recovering a good approximation of the original continuous image.

       Refiltering

       There's another twist: If you simply sample the reconstructed  original
       continuous image at the new sample rate, and that new sample rate isn't
       at least twice the highest frequency in the original continuous	image,
       you  won't  get a perfect sampling.  In fact, you'll get something with
       ugly aliasing in it.  Note that this can't be  a	 problem  when	you're
       scaling	up (increasing the sample rate), because the fact that the old
       sample rate was above the Nyquist level means so is the new  one.   But
       when  scaling  down,  it's  a  problem.	Obviously, you have to give up
       image quality when scaling down, but aliasing is not the best way to do
       it.   It's  better  just	 to  remove high frequency components from the
       original continuous image before sampling, and then get a perfect  sam‐
       pling of that.

       Therefore,  pamscale  filters out frequencies above half the new sample
       rate before picking the new samples.

       Approximations

       Unfortunately, pamscale doesn't do the convolution precisely.   Instead
       of  evaluating  the  filter  function  at every point, it samples it --
       assumes that it doesn't change any more often than  the	step  function
       does.   pamscale	 could actually do the true integration fairly easily.
       Since the filter functions are built into the program, the integrals of
       them could be too.  Maybe someday it will.

       There  is  one  more  complication with the Fourier analysis.  sinc has
       nonzero values on out to infinity and minus infinity.   That  makes  it
       hard  to	 compute  a convolution with it.  So instead, there are filter
       functions that approximate sinc but are nonzero only within  a  manage‐
       able  range.   To get those, you multiply the sinc function by a window
       function, which you select with the -window option.  The same holds for
       other filter functions that go on forever like sinc.  By default, for a
       filter that needs a window function, the window function is the	Black‐
       man function.

       Filter Functions Besides Sinc

       The  math  described above works only with sinc as the filter function.
       pamscale offers many other filter functions,  though.   Some  of	 these
       approximate  sinc  and are faster to compute.  For most of them, I have
       no idea of the mathematical explanation for them, but  people  do  find
       they  give  pleasing  results.	They may not be based on resampling at
       all, but just exploit the convolution that is coincidentally part of  a
       resampling calculation.

       For some filter functions, you can tell just by looking at the convolu‐
       tion how they vary the resampling process from the perfect one based on
       sinc:

       The  impulse  filter  assumes  that the original continuous image is in
       fact a step function -- the very one we computed as the first  step  in
       the resampling.	This is mathematically equivalent to the discrete sam‐
       pling method.

       The box (rectangle) filter assumes the original image  is  a  piecewise
       linear  function.   Its graph just looks like straight lines connecting
       the pixel values.  This is mathematically equivalent to the pixel  mix‐
       ing  method  (but  mixing brightness, not light intensity, so like pam‐
       scale -linear) when scaling down, and  interpolation  (ala  pamstretch)
       when scaling up.

       Gamma

       pamscale	 assumes  the  underlying continuous function is a function of
       brightness (as opposed to light intensity), and therefore does all this
       math using the gamma-adjusted numbers found in a PNM or PAM image.  The
       -linear option is not available with resampling (it causes pamscale  to
       fail),  because it wouldn't be useful enough to justify the implementa‐
       tion effort.

       Resampling (-filter) was new in Netpbm 10.20 (January 2004).

       The filter functions

       Here is a list of the function names you can specify  for  the  -filter
       option.	 For  most of them, you're on your own to figure out just what
       the function is and what kind of scaling it  does.   These  are	common
       functions from mathematics.

       point  The graph of this is a single point at X=0, Y=1.

       box    The  graph of this is a rectangle sitting on the X axis and cen‐
	      tered on the Y axis with height 1 and base 1.

       triangle
	      The graph of this is an isosceles triangle sitting on the X axis
	      and centered on the Y axis with height 1 and base 2.

       quadratic

       cubic

       catrom

       mitchell

       gauss

       sinc

       bessel

       hanning

       hamming

       blackman

       kaiser

       normal

       hermite

       lanczos
	      Not documented

   Linear vs Gamma-adjusted
       The pixel mixing scaling method described above involves intensities of
       pixels (more precisely, it involves individual intensities  of  primary
       color  components of pixels).  But the PNM and PNM-equivalent PAM image
       formats represent intensities with gamma-adjusted numbers that are  not
       linearly	 proportional to intensity.  So pamscale, by default, performs
       a calculation on each sample read from its input and each sample	 writ‐
       ten  to	its output to convert between these gamma-adjusted numbers and
       internal intensity-proportional numbers.

       Sometimes you are not working with true PNM or PAM images, but rather a
       variation  in which the sample values are in fact directly proportional
       to intensity.  If so, use the -linear option  to	 tell  pamscale	 this.
       pamscale then will skip the conversions.

       The  conversion	takes  time.  In one experiment, it increased the time
       required to reduce an image by a factor	of  10.	  And  the  difference
       between	intensity-proportional values and gamma-adjusted values may be
       small enough that you would barely see a difference in  the  result  if
       you  just  pretended that the gamma-adjusted values were in fact inten‐
       sity-proportional.  So just to save time, at the expense of some	 image
       quality,	 you can specify -linear even when you have true PPM input and
       expect true PPM output.

       For the first 13 years of Netpbm's life, until  Netpbm  10.20  (January
       2004),  pamscale's  predecessor pnmscale always treated the PPM samples
       as intensity-proportional even though they were not, and drew few  com‐
       plaints.	  So  using  -linear  as  a lie is a reasonable thing to do if
       speed is important to you.  But if speed is important, you also	should
       consider the -nomix option and pnmscalefixed.

       Another	technique to consider is to convert your PNM image to the lin‐
       ear variation with pnmgamma, run pamscale on it and  other  transforma‐
       tions  that  like linear PNM, and then convert it back to true PNM with
       pnmgamma -ungamma.  pnmgamma is often faster than pamscale in doing the
       conversion.

       With  -nomix,  -linear has no effect.  That's because pamscale does not
       concern itself with the meaning of the sample values  in	 this  method;
       pamscale just copies numbers from its input to its output.

   Precision
       pamscale	 uses  floating point arithmetic internally.  There is a speed
       cost associated with this.  For some images, you can get the acceptable
       results	(in  fact,  sometimes identical results) faster with pnmscale‐
       fixed, which uses fixed point arithmetic.  pnmscalefixed may,  however,
       distort	your  image a little.  See the pnmscalefixed user manual for a
       complete discussion of the difference.

SEE ALSO
       pnmscalefixed(1), pamstretch(1),	 pamditherbw(1),  pbmreduce(1),	 pbmp‐
       scale(1),  pamenlarge(1),  pnmsmooth(1),	 pamcut(1),  pnmgamma(1), pnm‐
       scale(1), pnm(1), pam(1)

HISTORY
       pamscale was new in Netpbm 10.20 (January 2004).	 It was adapted	 from,
       and  obsoleted,	pnmscale.  pamscale's primary difference from pnmscale
       is that it handles the PAM format and uses the "pam" facilities of  the
       Netpbm  programming library.  But it also added the resampling class of
       scaling method.	Furthermore, it properly does its pixel mixing	arith‐
       metic  (by  default) using intensity-proportional values instead of the
       gamma-adjusted values the pnmscale  uses.   To  get  the	 old  pnmscale
       arithmetic, you can specify the -linear option.

       The  intensity  proportional  stuff  came  out of suggestions by Adam M
       Costello in January 2004.

       The resampling algorithms are mostly taken  from	 code  contributed  by
       Michael Reinelt in December 2003.

       The version of pnmscale from which pamscale was derived, itself evolved
       out of the original Pbmplus version of pnmscale by Jef Poskanzer (1989,
       1991).  But none of that original code remains.

netpbm documentation	       18 February 2005	       Pamscale User Manual(0)
[top]

List of man pages available for CentOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net