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 CFORM.  The program will work on 3-dimensional (cube)
files (unless they are in BIP format), but no magnification or compression is
allowed in the third dimension;  the same operation is performed on each band.

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.

OPIC will normally have the same data format as IPIC.  Use the OFORM parameter
to change the output format.

SIZE performs  bilinear interpolation to magnify or compress the image.
The 'NOIN keyword may be used to suppress interpolation.  See sections on image
magnification and reduction below.

OPERATION:

The size of the output image is specified in one of two ways:

(1) Explicitly specifying it with the NL and NS parameters:

        SIZE  INP  OUT  NL=500  NS=500
    or  SIZE  INP  OUT  SIZE=(1,1,500,500)

(2) Specifying a magnification or compression (zoom) factor:

        SIZE  INP  OUT  ZOOM=3		! 3x magnification
        SIZE  INP  OUT  ZOOM=-2         ! 2x compression
    or  SIZE  INP  OUT  ZOOM=0.5        ! 2x compression

The ZOOM factor can be a floating point value.
A negative ZOOM results in image compression.  I.e. ZOOM= -2.5 is the
same as ZOOM=0.4

Note the if both NL,NS ans ZOOM are specified, the ZOOM parameter will
determine the magnification/compression factor and NL,NS will determine the
size of the output image.

Independent zooms may be specified in the line (vertical) and sample
(horizontal) directions:

        SIZE  INP  OUT  LZOOM=2  SZOOM=3
        SIZE  INP  OUT  LZOOM=3  SZOOM=-2

As the last example implies, the image may be magnified in one direction
and compressed in the other.

The AREA parameter may be used to restrict processing to an area of the
input image.  For example:

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

The output data format may be different from the input format (see OFORM
keyword).  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 the 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 program XVD.  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 does not override the corresponding NL and/or 
NS values in the VICAR SIZE field.  If a value of NL or NS is specified that 
is smaller than ZOOM*(input NL or NS), then the image will be truncated in
that dimension.  If greater, then a blank area will be appended on the
bottom or right edge, respectively.

The IOFFSET parameter may be used to start the output image at a (line,sample)
coordinate other than (1,1).  Let the input image be:

                           1  2  3
                           2  3  4
                           3  4  5

then
		SIZE  INP  OUT  NL=8  NS=8  ZOOM=2  IOFFSET=(2,2)  'NOIN

will result in the following:

                    0  0  0  0  0  0  0  0
                    0  1  1  2  2  3  3  0
                    0  1  1  2  2  3  3  0
                    0  2  2  3  3  4  4  0
                    0  2  2  3  3  4  4  0
                    0  3  3  4  4  5  5  0
                    0  3  3  4  4  5  5  0
                    0  0  0  0  0  0  0  0

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.

UPDATING OF MAP PROJECTION LABEL INFORMATION:

If the input image has map projection labels, the projection information
will be updated to reflect changes in the geometry as a result of size
changes and image offsets (see AREA and IOFFSET parameters).  A new map
projection history label is added and the map projection property label
is updated.

If the map projection is POINT PERSPECTIVE, the following label items are
recomputed:

    FOCAL_PLANE_SCALE
    OPT_AXIS_INTERCEPT_LINE
    OPT_AXIS_INTERCEPT_SAMPLE
    PLANET_CENTER_LINE
    PLANET_CENTER_SAMPLE

For all other projections, the following label items are recomputed:

    LINE_PROJECTION_OFFSET
    SAMPLE_PROJECTION_OFFSET
    MAP_SCALE
    MAP_RESOLUTION

If either MAP_SCALE or MAP_RESOLUTION is missing from the input projection
label, it is computed from the other using the relationship: 

                      PI
     MAP_RESOLUTION = --- * A_AXIS_RADIUS/MAP_SCALE
                      180

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 20,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.


PROGRAM HISTORY:

Written by: Gary Yagi, 26 January 1976
Cognizant programmer: Gary Yagi
Revision history:
    Jan 04  lwk  Added support for 3-D (cube) files;  removed Magellan option
                 (which will live on as pgm. SIZEMGN)
 18 Dec 03  DLR   INCREASED BUFFER SIZES TO ALLOW LINES UP TO 100000.
                  FIXED PDF.
 29 May 03  AXC  Fixed ABEND when LZOOM is specified but not SZOOM.
                 (AR-108538)
		 Initialized a character buffer. (AR-104344) 
 22 Aug 00  GMY  Fix bug when ZOOM not specified and NL is same as input.
                 (AR 104590)
 24 Apr 00  GMY  Fix bug when ZOOM, NL, NS are specified for case where
                 NL,NS specifies output is to be same size as input.
 07 Dec 99  GMY  (Day of infamy)  Major reorganization of code and
                 rewritting of test script.  Fixed IOFFSET problem for
                 interpolation case.  When updating map projection labels,
                 if resolution or scale is missing, it is computed from the
                 other.
19 Aug 99 -ems - fixed bug that was giving invalid values around the edges
		of the output image
  9jul98   -lwk- changed printout of zoom factor for integer reduction from
		"ZOOM -N" to "ZOOM 1/N"
 24jun98   -lwk- corrected MAP_RESOLUTION update:  it should be multiplied
		by ZOOM, but pgm was dividing!
 21 MAY 98  BAM   INCREASED BUFFER SIZES TO ALLOW LINES UP TO 50000.
                  FIXED PDF.
 04 Feb 98  GMY  Changed SAMP from I*2 to I*4 to fix bug when NS > 32767
  3dec97   -lwk- changed ENTRY's to SUBROUTINE to avoid Alpha compiler bug
 04 Sep 97  lwk   corrected computation of effect of zoom on MP line/samp 
		items, since only (0.5,0.5) is fixed in zoom.
 06 Jul 97  lwk   added IOFFSET parameter
 26 Jun 95 - SMC  FR 89394: Undo FR 89272/89275, because it caused problems.
                            and fixed it another way
 14 Jun 95 - SMC  FR 89272: fixed ABEND when LZOOM=-2 on odd number line images
                  FR 89275: fixed image output so that LZOOM=-2 will begin
                            processing on the first line instead of the second
 12sep95 -lwk- corrected the scaling of the LINE/SAMP_PROJECTION_OFFSET
		label items:  these are defined with respect to (1,1),
		not (0,0)!
 28 Apr 95  FFM   Fix FR 82982:
                  1. Fixed dcl delete statement in test pdf.
                  2. Corrected error in test #2 about m.dat.
                  3. Removed a test case in test #7 which needs too
                     much disk space.
                  4. Fixed an error in xvmessage in routine GETSIZE.
                     So it will not print out a blank line or a line 
                     has meaningless infor on ANDES.
                     
 25 Oct 94  FFM   Fix FR 85697:
                  1. Add keyword DEBUG to print the informational message
                     for routine mp_label_read.
                  2. enlarge buffer to handle output image up to 50,000 
                     samples. If larger than 50,000 samples, SIZE will 
                     abend with a message to inform user the cause of the
                     abend.
 16 Nov 93  FFM   ported to unix. The major changes are :
                  1. modify XV,XL routines
                  2. change int, byte equivalence to INT2BYTE, BYTE2INT,
                     add "include fortport" to all related subroutines
                  3. change logical*1 to byte (if pixel)
                  4. divide real*4 EPS/1.e-6/ into real*4, and data statement
                  5. change hex number to integer in data statement
                  6. change mvl to mvlc, add to addv
                  7. make optional arguments to required arguments for addv,
                     mvlc, and mve
                  8. change QPRINT to XVMESSAGE
                  9. remove /LIST from include statement
                 10. add all include files to imake file
                 11. remove "implicit statement" from slookup include file
                 12. create common/c3/iunit, so iunit will pass to subroutine 
                     sread properly, because SGI doesn't default value to 0.
                 13. add new MP interface
                 14. modify test pdf to be automated for VAX, SUNOS, & SGI.

 09 Nov 91  lwk   update map labels if present
 26 Nov 89  GMY   Fix bug in VOLTS option (max index=2249)
 26 Nov 89  GMY   Added VOLTS keyword.  Program now uses size field to
		  determine size of LOOKUP tables.
 11 Feb 89  GMY   Fixed image compression with no interpolation algorithm
                    to agree with documentation (start with pixel 1,1).
 22 DEC 88  GMY   MGN lookup table resolution increased 10x.
                  Added SMGN1 to handle ZOOM=-3 as special case.
 22 NOV 88  GMY   Major code modification and reorganization:
		  ...Consolidated Magellan option to subroutines SMGN
	          ...and MGNSIZEINIT.  LOOKUP now a separate keyword.
		  ...Added fullword and REAL*4 capability.
		  ...Rewrote help file.
 22 JAN 88  AXW   Changed keyword OFORM from 'MAGELLAN' to 'LOOKUP'.
 26 JAN 87  AXW   Added fullword capability and translation tables
                      for the Magellan project.  Specified by the
                      SIZE.PDF file keyword OFORM='MAGELLAN'.
                      Code modifications are marked by '! AXW'.
  1 JAN 85  FFM   CONVERTED SUBROUTINE INTRP,INTRPV,IOUT,SHRINK,
                      SHRINZ FROM FORTRAN TO ASSEMBLY LANGUAGE
  4 SEP 84  SP    DELETED FORMAT PARAMETER (ALWAYS USING FORMAT 
                      FROM LABEL.)
  4 SEP 84  SP    ADDED STATEMENT TO CHANGE SZOOM=-1 TO SZOOM=1.
  4 SEP 84  SP    CONVERTED TO USE VICAR2 CALLS (XVREAD...)
  4 SEP 84  SP    DOUBLED BUFFER SIZES TO ALLOW LINES UP TO 20000.
 11 JUL 84  HBD   FIX BUG IN SHRINK AND SHRINZ
 18 NOV 83  HBD   DELETED STACKA AND RESTRUCTURED CODE
                      MADE VAX COMPATIBLE

PARAMETERS: