Help for SIZE

PURPOSE:
SIZE is a VICAR applications program which may be used to magnify or compress
the size of an image and/or change its aspect ratio.  The program may also
be used to re-scale the input DN values and to change the data format
(e.g. byte-to-halfword).  Note, however, that if image size or aspect ratio
manipulation is not required, these latter two operations are more efficiently
accomplished via program C.

EXECUTION STATEMENT:

      SIZE  INP=IPIC  OUT=OPIC  user-parameters...

where IPIC is the input image and OPIC is the output image.  IPIC and OPIC
may be in byte, halfword (16-bit integer), fullword (32-bit integer), or
floating point (REAL*4) data format.  IPIC and OPIC may have different data
formats.
OPERATION:

The input data format is determined from the input picture label.  The output
data format may be specified via the keyword OFORM.  If not specified, OPIC
will be output in the same data format as IPIC.

The magnification or compression (zoom) factor is specified via the VICAR
size field or by the ZOOM, LZOOM, or SZOOM parameters (see below).  
The zoom factor(s) is inserted as annotation in the output picture label.
The AREA parameter may be used to restrict processing to an area of the
input image.  For example:

		SIZE  IDS  OPIC  ZOOM=-3  AREA=(10,10,100,100)
is equivalent to
		COPY  IPIC  IDS  (10,10,100,100)
		SIZE  IDS  OPIC  ZOOM=-3

SIZE performs its own interpolation (i.e. GEOM, et al, are not fetched).
Since it treats a special case of geometric transformation, the resulting
simplified algorithm is faster than the more general algorithm in GEOM.
See sections on image magnification and reduction below.
If the output data format is different from the input format, data format
conversion is performed.  The image DNs may be optionally rescaled at this
point via parameter SCALE.  Note that rescaling may be necessary when
converting to a smaller data format (e.g. halfword-to-byte).  If a sample
value is outside to range of the output format (e.g. 0 to 255 DN for byte
data), the output DN will be truncated.  The output DN range may be
further limited via the LIMITS parameter.
SPECIFYING THE SIZE OF THE OUTPUT IMAGE:

The size of the output image is specified either by entering the number of
lines and samples in the VICAR size field, or by specifying a magnification
or compression factor via the ZOOM, LZOOM, or SZOOM parameters:

Ex:  Enlarging a 3x3 image to a 9x9 image can be achieved in the
     following equivalent ways:
		SIZE  A  B  SIZE=(1,1,9,9)
        or      SIZE  A  B  NL=9  NS=9
	or	SIZE  A  B  ZOOM=3
        or      SIZE  A  B  LZOOM=3  SZOOM=3

If the output image size is specified by entering the number of lines and
samples, then the ZOOM factor is determined by computing the ratio between
the output and input picture dimensions.  Independent ZOOM factors are
computed in the line and sample dimensions, and may result in a change in
the image aspect ratio:

	z1=NLO/NLI		z2=NSO/NSI

where the input image size is NLI x NSI and the output image size is NLO x NSO.
The computations are performed in floating point, so that the output picture
size is not necessarily a multiple of the input picture size (i.e. z1 and
z2 are floating-point numbers).

The ZOOM factors may be specified via the ZOOM parameter,
		    ZOOM=z
where z1=z2=z, or independently via the LZOOM and SZOOM parameters:
		LZOOM=z1  SZOOM=z2

When the zoom factor is an integer, it is identical in function to the ZOOM
option in programs VIDS or IDX.  If z is positive, the input picture size
is multiplied by z.  If z is negative, the picture size is divided by -z.
Note that z=-2 is equivalent to z=0.5.

Specification of a zoom factor overrides the corresponding NL and/or NS values
in the VICAR SIZE field.  If a zoom factor is not specified the output picture
size defaults to the corresponding NL and/or NS value in the SIZE field.

IMAGE MAGNIFICATION:

The following example illustrates how image magnification is treated. Let
the input picture A be a 3x3 image as follows:

			       2  5  8
			A  =   5  8 11
			       8 11 14

The statement
		SIZE  A  B  SIZE=(1,1,9,9)  'NOIN
	or	SIZE  A  B  ZOOM=3  'NOIN

will produce a 9x9 output image B by replicating each input sample into a
3x3 pixel area:

		       2  2  2  5  5  5  8  8  8
		       2  2  2  5  5  5  8  8  8
		       2  2  2  5  5  5  8  8  8
		       5  5  5  8  8  8 11 11 11
		B  =   5  5  5  8  8  8 11 11 11
		       5  5  5  8  8  8 11 11 11
		       8  8  8 11 11 11 14 14 14
		       8  8  8 11 11 11 14 14 14
		       8  8  8 11 11 11 14 14 14
The statement
		SIZE  A  B  SIZE=(1,1,9,9)  ZOOM=3

will produce a 9x9 output image by interpolating between the four nearest
neighbors and extrapolating around the picture borders.

		       0  1  2  3  4  5  6  7  8
		       1  2  3  4  5  6  7  8  9
		       2  3  4  5  6  7  8  9 10
		       3  4  5  6  7  8  9 10 11
		B  =   4  5  6  7  8  9 10 11 12
		       5  6  7  8  9 10 11 12 13
		       6  7  8  9 10 11 12 13 14
		       7  8  9 10 11 12 13 14 15
		       8  9 10 11 12 13 14 15 16

As in the no-interpolation case above, each input sample has been "blown up"
to fill a 3x3 area.  However, because interpolation is performed, the input
sample values equal the output sample values only at the geometric centers
of these 3x3 areas.

Note that the magnified image output by SIZE differs slightly from what one
might obtain using GEOM, MGEOM, or GEOMA. The user may find it instructive
to attempt to achieve an identical result as the example above by using GEOM
or GEOMA.

IMAGE COMPRESSION:

Image compression is treated as the functional inverse of image magnification.
Unless the keyword 'NOIN is specified, the compression is performed via area
averaging.  To illustrate, let picture B be the 9x9 image of our previous
example:

		       0  1  2  3  4  5  6  7  8
		       1  2  3  4  5  6  7  8  9
		       2  3  4  5  6  7  8  9 10
		       3  4  5  6  7  8  9 10 11
		B  =   4  5  6  7  8  9 10 11 12
		       5  6  7  8  9 10 11 12 13
		       6  7  8  9 10 11 12 13 14
		       7  8  9 10 11 12 13 14 15
		       8  9 10 11 12 13 14 15 16
The statement:
		SIZE  B  C  ZOOM=-3

will cause each output pixel to be computed by averaging a 3x3 area of
the input image.  For example, output pixel (1,1) = (0+1+2+1+2+3+2+3+4)/9
The resulting output image C will be identical to our original input image A:

			       2  5  8
			C  =   5  8 11
			       8 11 14

The area averaging operation is extended to non-itegral zoom factors by
assigning fractional weights to samples around the area margins, and unit
weights to interior samples. The output sample is then the weighted samples
divided by the sum of their weights.
If the keyword 'NOIN is specified,

		SIZE  IPIC  OPIC  ZOOM=-N  'NOIN

then no pixel interpolation is performed.  The output image is generated
by selecting every Nth image line from IPIC, and every Nth pixel of each of
these lines, begining with pixel (1,1).  Note that when the output picture
is several times smaller than the input picture, most of the samples in the
input image are ignored in the generation of the output image.

  To illustrate, let picture B be
the 9x9 image of our previous example:

		       0  1  2  3  4  5  6  7  8
		       1  2  3  4  5  6  7  8  9
		       2  3  4  5  6  7  8  9 10
		       3  4  5  6  7  8  9 10 11
		B  =   4  5  6  7  8  9 10 11 12
		       5  6  7  8  9 10 11 12 13
		       6  7  8  9 10 11 12 13 14
		       7  8  9 10 11 12 13 14 15
		       8  9 10 11 12 13 14 15 16

The statements:
		SIZE  B  C  ZOOM=-3  'NOIN
		SIZE  B  D  ZOOM=-3  'NOIN  AREA=(2,2,8,8)

will generate 3x3 output images C and D of the form:

		0  3  6		       2  5  8
	 C  =	3  6  9		D  =   5  8 11
		6  9 12		       8 11 14

Note the use of the AREA parameter to begin the resampling at a point other
than pixel (1,1).

The input image may be compressed by a non-integral zoom factor r:

		SIZE  IPIC  OPIC  ZOOM=r  'NOIN

where r is a floating point number between 0 and 1.  Each output sample is
generated by determining where it comes from in the input image and selecting
the sample closest to this point.

EXAMPLES:

Let the input image be a 100 x 100 byte picture. The following equivalent
statements will magnify the input image by a factor of 2.5:

		SIZE  A  B  SIZE=(1,1,250,250)
		SIZE  A  B  ZOOM=2.5

To blow up a 50x50 area from the center of the picture by a factor of 4:

		SIZE  A  B  ZOOM=4  AREA=(26,26,50,50)

To average all the lines of an image together, use

		SIZE  A  B  NL=1

The following equivalent statements magnify the line direction by 2 and
shrinks the sample direction by 2:

		SIZE  A  B  SIZE=(1,1,200,50)
		SIZE  A  B  LZOOM=2  SZOOM=-2

PROGRAM RESTRICTIONS:

Both IPIC and OPIC may be up to 70,000 pixels in width (sample size) and of
arbitrary length (line or vertical dimension).

The input image may be on tape or disk.  However, the output image must be on
random-access disk storage.

PARAMETERS: