Help for SARGON

PURPOSE:
SARGON is an interactive program which performs operations on user-specified
areas (polygons) in an image.  SARGON operates on byte or halfword data.

EXECUTION:

Examples for this program are divided into two sections.  First is a
typical SARGON session.  The second section demonstrates the commands with
less attention given to the details of program operation and more to the
commands themselves.

Example #1  (Vertical spacing is used liberally in this example.  This
    spacing will not appear in a real SARGON session.)

TAE> SARGON INP=A OUT=B
COPYING INPUT TO OUTPUT
(There is a delay here, then the input image is displayed.)

SARGON READY
(The "SARGON READY" statement will come up whenever SARGON is 
requesting a new command from the user.  The other possible state is
flagged by the statement "READY FOR TRACKBALL" which indicates that 
SARGON is expecting the user to define a polygon using the trackball; the user
may, however, and often will, input a command in this latter state, too.)

'ZERO 

VERTEX ACQUISITION CYCLE....Hit carriage return TO STORE POINT
			    DOUBLE carriage return STORES LAST POINT
READY FOR TRACKBALL
(ENTER COMMAND OR PRESS RETURN TO DEFINE AREA)

(press RETURN)
(Move trackball and press <CR> for first point.  As you do this for
subsequent points, SARGON will connect the points you've selected with a
line.  DO NOT complete the polygon by selecting your starting point again
at the end; SARGON will complete the polygon for you.  When you're done, push
<CR> twice and SARGON will draw the completing line segment.)

OK ?   (Y OR N)

'Y
(Enter Y to use displayed polygon; N will allow you to respecify the area.)
(SARGON will zero out the specified region and come back with a prompt
for another area.)

READY FOR TRACKBALL
(ENTER COMMAND OR PRESS RETURN TO DEFINE AREA)

LINEAR=(10,100)
(Change lookup table.  We don't want to select any more areas in this
case, so we input a command.  SARGON will continue to accept areas for
the operation until EXIT or some other command is entered.)

SARGON READY
'EXIT
(This shows a return to the SARGON READY state, and we get out of
SARGON with EXIT.)

TAE>

Example #2

The following commands are more to show the functions of SARGON than
anything else; they don't represent a typical or necessarily reasonable
sequence of steps.  Moreover, SARGON output and trackball interaction
is omitted; the user should be able to deduce from the example above 
the actions that SARGON will take for each of these commands.)

GEN A 1000 1000		Generate a test image
SARGON A B		Call SARGON
   .
   .
   .
FIT=(0,32768)           For halfword data only, map 0 to 0 and 32768 to 255.
			This is only used for changing mapping mid-stream;
			SARGON automatically queries for these values at
			the start of the program when the input image is
			in halfword format.  Same as RANGE.
RIGHT=50		Move current window 50 pixels to the right.  
			This will not work - nor make sense - if
			the image already is filling the screen.
			This restriction also applies to the commands
			following.  Also, this and the next three commands
			may be abbreviated using the first letter of the
			command.
LEFT=50			Move current window 50 pixels to the left.
UP=200			Same as above, in up direction.
DOWN=75			Same as above, in down direction.
'HOME			Redisplay image such that pixel 1,1 is at the
			upper-left pixel of the monitor.

MULT=0.5		Multiply the DN of pixels within user-specified
			area by 0.5.
DIVIDE=5.3              Divide the DN of pixels within user-specified 
			area by 5.3 - may be abbreviated DIV.
ADD=180	         	Add 180 to the DN of all pixels within the
			specified area.  Values will top off at 255 as
			applicable.
SUBTRACT=200		Subtract 200 from the DN of all pixels within the
			specified area.  Value will bottom out at 0 as
			applicable.  This command may be abbreviated SUB.
'STATS			Stats will perform stats on the specified area.
			The Average DN, Standard Deviation, Min DN and Max DN
			are calculated.
'ZERO			Zero out the given area.  Same as SETTO=0 below.
SETTO=40		Set DN's within the indicated area to 40.  May
			be abbreviated SET.
'COPY			Copy input image to output file and screen.  Same as
			'RESTORE.  This is essentially the same as starting
			over.

'INTERP			Perform an EXTRAP interpolation over all interior
			points.  (See EXTRAP subroutine documentation.)
MIN=40			Set the minimum DN used in the interpolation
			formula to 40.  The default is -9999.
MAX=240			Set the maximum DN used in the interpolation
			formula to 240.  The default is 32768.
RADIUS=100000		Set the interpolation radius to 100000.  The
			default is 1 million.  (See OPERATION section.)
PERC=85			Specify that 85 percent of the points on the polygon
			border should be used for the interpolation.  The 
			default is 100%.

LINEAR=(150,200)    	Apply linear stretch to the display lookup table.
			Same as STRETCH.
CIRC=10			Command given at vertex acquisition level. It will
			gather points at a radius of 10 from the cursor
			location and perform specified function on interior
			points.
'RAW			Remove any applied stretch.
'OFF			Turn image display off.
'ON			Turn image display back on.

'DBUG			Produce debug print.
'EXIT			Exit SARGON.  Equivalent to 'END.

'RCUR			Rcur will read and report the cursor position for the
			display and picture.
PCUR=(10,10)		Pcur will position the cursor according to picture
			coordinates given.
@FILE.EXT		Will execute commands found in file.ext where
			ext is any file extension.  Default ext is ".sar"
			so one could get away with just typing @file
			instead of @file.sar

RESTRICTIONS:
1) The maximum number of vertices is 24.
2) Polygon sides may not cross.
3) Maximum line length is 10000 bytes.
4) Maximum number of line segments to be interpolated for in any one polygon
   is 2000.
5) Maximum number of exterior points will be truncated at 4000.
6) Program is extremely picky about the data type passed to commands.  Be
   sure that you specify reals when it wants reals, and ints when it wants
   ints.

OPERATION:
SARGON first copies the input to the output so that all operations (with
the exception of COPY/RESTORE) will operate only on the output dataset.
It will always display the output dataset.

Whenever any of the keywords MULT, SUBT, ADD, DIVI, ZERO, COPY, SET, STATS, or
INTE (or their aliases) is specified, the Vertex Acquisition Cycle is
entered.

Each vertex of the polygon of interest is defined by trackball.  For each
push of the carriage return key within the Cycle, the current
location of the trackball is stored as a vertex.  A double carriage return
defines the last vertex.  The user should not repeat vertices; the program
will close the polygon automatically.  Or the circle mode may be used to
acquire vertices.  The command 'CIRC radius' would be used to invoke it
where 'radius' is an integer value.

The program will prompt the user to either accept or reject the polygon
drawn on the display.  If accepted, the output dataset is updated and the
appropriate lines are redisplayed.  The program is then ready for more
vertices and reports "READY FOR TRACKBALL."  Any parameter input will
exit the Cycle, winding up in "SARGON READY".

For interpolation, the points immediately exterior to the polygon are
collected.  Those exterior points with MIN <= DN <= MAX will be saved
for use.  If PERC is not 100, these exterior points will be randomly
weeded out until the proper percent remains.  These final points are then
fed to EXTRAP which interpolates.  For each point being interpolated for,
only exterior points within a radius of RADI will be used in the 
formula.  The use of RADI and PERC greatly determine the speed of the
algorithm for large areas.  (See EXTRAP document.)

MIN and MAX are important for painless interpolation.  For example, if
a large dark gore is to be removed, one can set MIN above the gore's
DN.  Then if one side of the polygon accidentally crosses into the gore,
the interpolation formula will ignore the border points collected from
within the gore.

One last thing to note.  Within the session one can execute a command
file similar to that found in IDX.  In order to do this, the "@" followed
by a file name must be given. (I.E. @commands - This will search for a
file by the name of "commands.sar" and execute it's contents.)  .SAR is
the default extension, otherwise the full file specification must be given.
HISTORY:

  WRITTEN BY:  Charles Avis, 1 March 1982
  REVISIONS:
  1984-05-11 Charlie Avis - converted to Vax
  1985-07-12 John Reimer - converted to Vicar2
  1986-01-31 Helen DeRueda - bug fixes, added parameters STATS, PCUR,
                             RCUR, CIRC.
  1989-02-20 Tom Greer - Upgraded to R2LIB.  Wrote test plan, fixed
                         bugs in OPRATE for ADD, SUB, MULT, DIV.  
                         Fixed bug in SORTX.  Fixed bug in STRETCH.
  1992-07-13 Florance Moss - Added IHBUF in routine OPRATE to avoid access
                             violation caused by DN out of range. (FR 66642)
                             To test the FR, do the following commands :
                             GEN A 512 512 LINC=256 SINC=256 'HALF
                             SARGON A B
                             RANGE -32768 32767
                             ADD 20000.
                             Use track ball to select an area in the bright 
                             DN
  1993-12-10 D.D. Knight - Application made portable.
  1996-04-12 O.A. Montoya  - Bug fixes in OPRATE for ADD, SUB..., FR89204.
                             Modified sargon.imake file to run on UNIX.
  2018-03-27 W.L. Bunch - Removed IMPLICIT declarations. Fixed big/little
                          endian bug (inserted in 1984?). Added test script
                          and example output.                                 

  COGNIZANT PROGRAMMER:  Tom Greer

PARAMETERS: