Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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]
	     }
	     [-reportonly]
	     [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).

       pamscale	 work  on multi-image streams, scaling each one	independently.
       But before Netpbm 10.49 (December 2009),	it scales only the first image
       and ignores the rest of the stream.

   The Scale Factors
       The  options -width, -height, -xsize, -ysize, -xscale, -yscale, -xyfit,
       -xyfill,	-reduce, and -pixels control the amount	of scaling.  For back-
       ward  compatibility,  there  is also -xysize and	the scale_factor argu-
       ment, but you shouldn't use those.

       -width and -height specify the width and	height in pixels you want  the
       resulting  image	 to  be.  See below for	rules when you specify one and
       not the other.

       -xsize and -ysize are synonyms for -width and -height, respectively.

       -xscale and -yscale tell	the factor by which you	 want  the  width  and
       height  of  the	image to change	from source to result (e.g.  -xscale 2
       means you want to double	the width; -xscale .5 means you	want to	 halve
       it).  See below for rules when you specify one and not the other.

       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 -xs-
       cale=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 pn-
       msmooth step; otherwise,	you can	see the	original pixels	in the result-
       ing image.

       -reportonly

       The  option -reportonly causes pamscale not to scale the	image, but in-
       stead to	report to Standard Output what scaling the options and the in-
       put image dimensions indicate.  For example, if you specify
	   -xyfill 100 100 -reportonly
       and  the	 input	image is 500 x 400, pamscale tells you that this means
       scaling by .25 to end up	with a 125 x 100 image.

       The output is intended to be convenient for machine processing.	In the
       example above, it would be

	   500 400 0.250000 0.250000 125 100

       The  output  is a single	line of	text per input image, with blank-sepa-
       rated tokens as follows.

       o      input width in pixels, decimal unsigned integer

       o      input height in pixels, decimal unsigned integer

       o      horizontal scale factor, floating	point decimal, unsigned

       o      vertical scale factor, floating point decimal, unsigned

       o      output width in pixels, decimal unsigned integer

       o      output height in pixels, decimal unsigned	integer

       -reportonly was new in Netpbm 10.86 (March 2019).

   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 us-
       ing 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 take a	trans-
       parent sheet the	size of	the target image, marked with a	square grid of
       tiles the same size.  Stretch or	compress the source image to the  size
       of the sheet and	lay the	sheet over the source.

       Each  cell  in the overlay 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  en-
       large.	When you reduce, you may find that some	of the lines disappear
       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  re-
       sult 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  in-
       terpolated  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 im-
       age 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	-- as-
       sumes 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.  Hanning, Hamming,	and Kaiser are alternatives.

       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 ap-
       proximate  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	resam-
       pling 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 and window functions

       Here is a list of the function names you	can specify for	the -filter or
       -windowoption.  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  com-
       mon  functions  from  mathematics.   Note that some of these make sense
       only as filter functions	and some make sense only as window funcions.

       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 by a	factor
       of 10 the time required to reduce an image.  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 intensity-propor-
       tional.	 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(5), pam(5)

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.

DOCUMENT SOURCE
       This manual page	was generated by the Netpbm tool 'makeman'  from  HTML
       source.	The master documentation is at

	      http://netpbm.sourceforge.net/doc/pamscale.html

netpbm documentation		03 January 2019	       Pamscale	User Manual(0)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY | DOCUMENT SOURCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pamscale&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help