.ec _
.ll 76
.ad b
.in 4
.\"====================================================================
.ti -4
1 Language
.ce
GREG2_\ Language Summary

.nf
ARROW       : Draw a list of arrows in User coordinates.
CONVERT     : Converts data in the X,Y buffer in the current projection.
ELLIPSE     : Draws an ellipse in User coordinate.
EXTREMA     : Shows minimum and maximum of the Regular Grid array.
GRID        : Plots a Grid in (A,D) with steps As and Ds (in degrees).
LEVELS      : Sets the contour levels.
MASK        : Masks part of a regular grid map.
MEAN        : Computes statistics on map values.
PERSPECTIVE : Makes a 3-D perspective of the Regular Grid array.
PLOT        : Plots a SIC image variable to the window.
POLYGON     : Defines a polygon for use by MASK and MEAN.
PROJECTION  : Defines a spherical projection.
RANDOM__MAP  : Creates a Regular Grid array from randomly sampled data.
RESAMPLE    : Resamples the Regular Grid array on a different Grid.
RGDATA      : Reads/creates a 2-D map and put it in the Regular Grid array.
RGMAP       : Draws contour lines for the Regular Grid array.
STRIP       : Extracts a strip from the Regular Grid array.
WEDGE       : Draws wedges.
WRITE       : Saves an internal buffer on a file.
.fi
.\"--------------------------------------------------------------------
.ti -4
2 NEWS

See HELP GREG1\ News for information
.\"====================================================================
.ti -4
1 ARROW
.ti +4
[GREG2_\]ARROW Xref Yref Length Angle [Reference]

This command draws one or more arrows at given position, and of given
length, and angle:
.in +4
.ti -2
- Xref and Yref define a reference point (in user coordinates) for the
arrow. The Reference value (5th argument) indicates where this point
lies on the arrow (0 for the start of the arrow, 0.5 for the middle of
the arrow, 1 for the tip of the arrow). Any intermediate value is
valid; default is 0.5.
.ti -2
- Length defines the arrow length, in paper units (cm).
.ti -2
- Angle defines the arrow orientation angle. It is ALWAYS in DEGREES,
TRIGONOMETRIC ORIENTATION.
.in -4
Additionally, the arrow head size can be customized with SET EXPAND.

All the 5 arguments can be scalar explicit values or scalar variable
names: this will draw a single arrow. But the 4 first arguments can
also be array variables: this will draw as many arrows as the arrays
provide values (their size have to be consistant). Mixing scalar and
array variable is possible, e.g.
.nf
  GREG> ARROW Xarray Yarray 1 AngleArray
.fi
will draw a set of arrows at different positions and orientation
angles, but all of same length.

In order to draw arrows defined by a starting point and ending point
coordinates, use commands G\DRAW RELO and G\DRAW ARROW.
.\"====================================================================
.ti -4
1 CONVERT
.ti +4
[GREG2_\]CONVERT A0 D0 [Angle] [/TYPE Ptype] [/UNIT Unit] [/SYSTEM
EQU|GAL [Equinox]] [/VARIABLE Var__X Var__Y]

The command converts coordinates in a given projection and coordinate
system to GREG current ones:

.in +6
.ti -4
* Input:
.ti -2
-_ Coordinates are found in Var__X and Var__Y if the option /VARIABLE
is present, else buffers X and Y are used. Var__X and Var__Y must be
DOUBLE precision, writeable, 1-dimensional arrays. If input projection
type is NONE, values are absolute spherical coordinates. Else they are
offsets from the projection center.
.ti -2
-_ The unit of coordinates can be set with the option /UNIT with the
argument SECOND, MINUTE, DEGREE, or RADIAN. Default is current Greg
angle unit (see HELP G\SET ANGLE__UNIT).
.ti -2
-_ Input coordinate system is set with the option /SYSTEM EQU|GAL
[Equinox]. Default equinox is 2000 if system is Equatorial.
.ti -2
-_ Input projection is defined by CONVERT A0 D0 [Angle] [/TYPE
Ptype]. A0 and D0 are the coordinates of the projection center
(reference of the offset coordinates). They are relevant except for
the NONE projection. Format is degrees in sexagesimal strings (A0 is
hour angle if input system is EQUATORIAL). Angle, if relevant, must be
set in degrees. Supported types can be found with CONVERT /TYPE
?. Default is NONE.

.ti -4
* Output:
.ti -2
-_ Converted coordinates are saved in the input variables
(overwritten). If the current Greg projection is NONE, values are
absolute spherical coordinates. Else they are offsets from the current
Greg projection center.
.ti -2
-_ The unit of output coordinates is always natural units (i.e. the
equivalent of Radians after reprojection).
.ti -2
-_ Output coordinate system is the current Greg one (see SHOW SYSTEM
and HELP SET SYSTEM).
.ti -2
-_ Output projection (center and type) is the current Greg one (see
HELP PROJECTION).
.in -6

There is no provision for "hidden" parts which are treated exactly as
visible ones.
.\"--------------------------------------------------------------------
.ti -4
2 EXAMPLES

* Converting relative coordinates to absolute:
.br

Say one wants to convert the RADIO-projected coordinates (+100,+200)
arcseconds from Eq.2000 center (01:23:45.67,76:54:32.10) to absolute
Eq.2000 coordinates:

.nf
  ! Define input offsets
  define double myx myy
  let myx +100
  let myy +200
  ! Define output system of coordinates
  set system eq 2000
  ! Define output projection. NONE means CONVERT output will be absolute
  ! spherical coordinates
  projection /type none
  ! Convert offsets given their input description
  convert 01:23:45.67 76:54:32.10 /type radio /syste eq 2000 /var myx myy /unit second
  ! Variables are now absolute spherical coordinates (radian unit)
  exa myx myy
  ! Convert from radians to RA-DEC sexagesimal strings
  define char*23 chra chdec
  let chra  myx /sexa h r
  let chdec myy /sexa d r
  exa chra chdec
.fi

* Converting offsets from one projection to another:
.br

Say one wants to convert the RADIO-projected offsets (+100,+200)
arcseconds away from Eq.2000 center (01:23:45.67,76:54:32.10) to
GNOMONIC-projected offsets (same projection center):

.nf
  ! Define input offsets
  define double myx myy
  let myx +100
  let myy +200
  ! Define output system of coordinates
  set system eq 2000
  ! Define output projection
  projection 01:23:45.67 76:54:32.10 /type gnomonic
  ! Convert offsets given their input description
  convert 01:23:45.67 76:54:32.10 /type radio /syste eq 2000 /var myx myy /unit second
  ! Variables are now offsets in the new projection (radians)
  exa myx myy
.fi
.\"====================================================================
.ti -4
1 ELLIPSE
.ti +4
[GREG2_\]ELLIPSE Major [Minor [Position__Angle]] [/BOX X Y] [/USER X Y
[code]] [/ARC Theta__min Theta__max] [/FILL [Colour]] [/HATCH [Ipen]
[Angle] [Separ] [Phase]]

This command draws at current pen position (or at position (X,Y) if
option /BOX or /USER is present) an ellipse of given semi-major axis,
semi-minor axis, (default Minor = Major) and Position__Angle (default
0 degrees). This command is useful for plotting beam sizes,
uncertainty ellipses, pie charts, etc.

Major, Minor are in User Coordinates. X and Y are in User Coordinates
(option /USER) or in Physical Units (centimeters from the bottom left
box corner, option /BOX). Major, Minor, X and Y, can be 1-D arrays of
any size, provided the sizes are the same.

The Position__Angle is ALWAYS in DEGREES, TRIGONOMETRIC ORIENTATION,
starting 0 from X>0 half-axis. Trigonometric means it increases from
X>0 half-axis to Y>0 half-axis. As such, orientation can go clockwise
or counter-clockwise depending if the axes are reverted or not, like
e.g. for astronomical plots (X increase to the left). The
Position__Angle can be indifferently an array, a number, or omitted.

The code suboption in the /USER option, if present, can be any of
`SECONDS', `MINUTES', `DEGREES', `RADIANS' (in which case the X and Y
coordinates are taken to be in the corresponding unit) or `ABSOLUTE'
(in which case X and Y are taken as absolute coordinates, usually
exprimed in sexagesimal format). The presence of the code suboption is
valid only if a PROJECTION and a SYSTEM (EQUATORIAL or GALACTIC) are
both defined.

A portion of the ellipse can be drawn by specifying the boundary
angles in option /ARC (in degrees, trigonometric sense from the
position angle). Not compatible with the array mode.

/FILL [Colour] will fill the ellipse(s), with the current pen colour
or with the specified colour (see HELP PEN /COL for possibilities). If
/ARC is also present, the filled area is the corresponding pie part,
not the subtended arc.

/HATCH will fill the ellipse(s) with parallel lines. The pen (default
current), line orientation in degrees (default 45), the separation in
physical units (default 0.25 cm) and phase between 0 and 1 (default 0)
can be customized. In this case the contour(s) are not drawn. If /ARC
is also present, the filled area is the corresponding pie part, not
the subtended arc.
.\"====================================================================
.ti -4
1 EXTREMA
.ti +4
[GREG2_\]EXTREMA [/BLANKING Bval Eval] [/PLOT] [/COMPUTE] [/LOCAL
PLOT|TERMINAL|FileName]

Computes and shows the minimum and maximum values of the Regular Grid
array: shows XMIN,XMAX,YMIN,YMAX,ZMIN,ZMAX. A useful command for
deciding where to set contour levels, or what size to give to the BOX
if you want an exact aspect ratio between two coordinates. The current
blanking value is used, but can be overridden using option /BLANKING.

Option /LOCAL specifies that instead of computing global extrema LOCAL
extrema values should be computed and:
.in +4
.ti -2
- PLOT: written at appropriate places on the plot. This is a very good
way to avoid ambiguities in contour map. A shortest format is used for
writing the values, and the character size controls the label
size. /PLOT is an alias for /LOCAL PLOT.
.ti -2
- TERMINAL: written to the terminal,
.ti -2
- FileName: written to the given file name.
.in -4
These arguments can be combined. If output is TERMINAL and/or file, X
and Y values are offsets in radians.

If option /COMPUTE is not present, the global extrema are only
computed if not already known (from a previous call to EXTREMA, or
from an image header). /COMPUTE forces computation from the data
array. It should be used if for any reason the known extrema are
incorrect (invalid image header, killed bad pixel, change of blanking
value...).
.\"====================================================================
.ti -4
1 GRID
.ti +4
[GREG2_\]GRID [Astep [Dstep]] [/ALTERNATE] [/LABEL]

Plots a grid of meridian and parallels according to the current
projection and system. Astep is the grid step for meridian in degrees
(Default 15), Dstep for Parallels (Default Astep). If one step is 0,
this part of the grid is not plotted. If the /ALTERNATE option is
present, the grid will be a grid in the alternate coordinate system
(Equatorial or Galactic). This does not currently work for projection
type AITOFF and RADIO.

If /LABEL is present, the meridians and parallels will be labeled with
their absolute coordinates.
.\"====================================================================
.ti -4
1 LEVELS
.ti +4
[GREG2_\]LEVELS [Args ...]

LEVELS without arguments will display the contour levels used by
command RGMAP.
The level values can also be found in the array GREG%LEVELS[GREG%NLEVEL]
(not defined if no levels), where GREG%NLEVEL is the number of levels
(0 if no levels).

.ti +4 
[GREG2_\]LEVELS NONE 

reset the level list (and thus GREG%NLEVEL becomes 0).

.ti +4
[GREG2_\]LEVELS C1 C2 TO C3 BY C4 ...

Sets the contour levels to be C1, C2, C2+C4, C2+2*C4, ..C3, and so on,
using the same list format as SIC\ command FOR. The contour levels are
used to make contour plots of the Regular Grid array using command
RGMAP. Up to 40 contours can be given at a time. Note that it is more
efficient to use a single RGMAP command with many levels than many
RGMAP commands with a single level each.

.ti +4
[GREG2_\]LEVELS EXPO Step [Linear Scale]

Sets the contour levels in a semi-exponential scale. Linear is the
number of linear levels: levels from -Linear*Step to -Step by Step
and Step to Linear*Step by Step are regularly spaced. Above Linear*Step,
the next contour level is Scale times larger than the previous one.
The defaults are Step=1, Linear=3 and Scale=sqrt(2).

.\"====================================================================
.ti -4
1 MASK
.ti +4
[GREG2_\]MASK [IN|OUT] [/BLANKING Bval]

masks all pixels of the Regular Grid array lying inside (if argument
is IN) or outside (if argument is OUT or by DEFAULT) the current
polygon (see command POLYGON) by attributing them a blanking
value. This value is defined by command SET_ BLANKING, or specified
using the option /BLANKING_ Bval.
.\"====================================================================
.ti -4
1 MEAN
.ti +4
[GREG2_\]MEAN [/CLIP Nsigma]

computes crude statistics on the part of the Regular Grid array lying
inside the current polygon. Blanking values as defined in
SET_ BLANKING are ignored. The results are displayed (some of them
according to the current ANGLE__UNIT), and stored in the variables:
.br
- POLY%NPIX (number of non-blanked pixels in the polygon),
.br
- POLY%MIN
.br
- POLY%MAX
.br
- POLY%AREA (area of the non-blanked pixels),
.br
- POLY%SUM (integrated intensity),
.br
- POLY%RMS.

If option /CLIP is present, iterative kappa sigma rejection is used to
reject outlier pixels.
.\"====================================================================
.ti -4
1 PERSPECTIVE
.ti +4
[GREG2_\]PERSPECTIVE [Altitude Azimuth] [/FACTOR Fv Ov] [/LOWER]
[/LINES] [/STEP Nsx Nsy] [/AXES Xmin Xmax Ymin Ymax] [/CENTER]
[/VERTICAL Vmin Vmax]

Makes a parallel projective view of the Regular Grid array, with
hidden lines removed. If /LINES option is present, lines along a
single axis are plotted. Altitude and Azimuth are the values of the
corresponding viewing angles in Degrees. Default values are 30 and 45
at the beginning, and then the last values given. The upper part is
drawn, unless the /LOWER option is present.

Automatic scaling to match approximately the current box is used, but
it is only a rough guess and may fail if extrema of the Regular Grid
occurs near the edges. Fine tuning of the plot scale can be obtained
using the /FACTOR option. It controls scaling of the Regular Grid
values by the factor Fv (default 1) and an offset Ov which is in
physical units along the Y direction of the plot.

The Regular Grid array is plotted according to the orientation implied
by command LIMITS, but the whole array is plotted. The /STEP option
may be used to indicate to take only 1 pixel over Nsx ones for the X
axis (resp. Nsy and Y). The /AXES option plots (X,Y) axes. The
/VERTICAL option controls the max, min of plotted perspective and
plots a Z axis. The /CENTER option centers the perspective. BLANKED
PIXELS are forced to the minimum value of the map, or the Vmin value
when the /VERTICAL option is in use.
.\"====================================================================
.ti -4
1 PLOT
.ti +4
[GREG2_\]PLOT [Varname] [/SCALING Type Low__cut High__cut] [/BLANKING
Bval Eval] [/POSITION Posx1 Posx2 Posy1 Posy2] [/BOUNDARIES Userx1
Userx2 Usery1 Usery2] [/VISIBLE]

PLOT will put a pixel image (pixels contained in the variable Varname)
inside the current BOX. Varname is a 2-D SIC variable name that
defaults to the RG variable if omitted. Subsets like A[4] where A is a
3-D sic variable are not yet allowed. How to create and handle images
in programs calling the GREG2_\ language (including GREG) is described
in the subtopic IMAGE__HOWTO.

This command is normally used in the following sequence:
.nf

Greg> SET BOX LOCATION Gx1 Gx2 Gy1 Gy2  ! Define box position
Greg> RGDATA Varname /VARIABLE          ! Put image in the RG variable,
                                        ! read associated header variables
Greg> LIMITS /RGDATA                    ! Computes associated limits
Greg> PLOT                              ! Plot the array in the box
Greg> BOX                               ! Draws the box
.fi
.\"--------------------------------------------------------------------
.ti -4
2 IMAGE__HOWTO

There exist a number of ways to get pixels into GREG2_\:
.in +4
.ti -2
-_ Read the X, Y, Z values of a Z=f(X,Y) "image", use RGDATA (if X and
Y define a regularly sampled grid) or RANDOM (if X and Y are "random
points") to make a Regular Grid Map (see HELP GREG1_\COLUMN,
GREG2_\RGDATA and GREG2_\RANDOM)
.ti -2
-_ Read a RGDATA-format file with the RGDATA command (see topic RGDATA)
.ti -2
-_ Define a 2-D SIC variable and fill it with values, or connect a SIC
variable with an existing GILDAS DATA FORMAT (GDF) image (see
HELP_ SIC_\DEFINE), or use the SIC_\ACCEPT command to read
formatted/unformatted streams of values and put them in a SIC 2-D
variable (see HELP_ SIC_\ACCEPT). Then give this 2-D variable to the
internal image buffer by the RGDATA_ Varname_ /VARIABLE command.
.ti -2
-_ The command GREG3_\IMAGE connects directly an existing 2, 3 or 4-D
GILDAS DATA FORMAT image in the GREG image buffer. See
HELP_ GREG3_\IMAGE for details.
.in -4

FITS files can also be loaded in Greg:
.in +4
.ti -2
-_ Use the VECTOR_\FITS command to convert a FITS image to a GDF (Gildas
Data Format) image that will be directly readable afterwards.
.ti -2
-_ "on-the-fly" automatic conversion from FITS to GDF format for
GREG3_\IMAGE command.
.ti -2
-_ avoid disk-to-disk conversion by loading the FITS directly in memory
with the command SIC_\DEFINE_ IMAGE.
.in -4
See each command HELP for details.
.\"--------------------------------------------------------------------
.ti -4
2 /BLANKING
.ti +4
[GREG2_\]PLOT /BLANKING Bval Eval

Blanking value (Bval) and tolerance (Eval). Default values are those
defined by SET_ BLANKING command.
.\"--------------------------------------------------------------------
.ti -4
2 /BOUNDARIES
.ti +4
[GREG2_\]PLOT /BOUNDARIES Userx1 Userx2 Usery1 Usery2

User coordinates corresponding to the image boundary. The default is
those of the plotted image (when the image has any), or the current
user limits if not.
.\"--------------------------------------------------------------------
.ti -4
2 /POSITION
.ti +4
[GREG2_\]PLOT /POSITION Posx1 Posx2 Posy1 Posy2

Box location in physical units (default is the current GreG box
location).
.\"--------------------------------------------------------------------
.ti -4
2 /SCALING
.ti +4
[GREG2_\]PLOT /SCALING Type [Low__cut High__cut]

Defines the type of transfer function to be used. Type can be LINear,
natural LOGarithmic, or EQUalization. The Low__cut and High__cut are
the lowest and highest represented values respectively. The default
"cuts" are the image extrema. The current cuts are stored in the
variable array CURIMA%SCALE. The current scaling (as an integer code)
is stored in the variable CURIMA%SCALING.

The LOG transfer function computes the logarithm of the pixel values.
There can be negative pixel values as long as the low and high cuts
remain positive. If one or two cuts are negative or null, they will be
implicitly replaced with a better suited positive value (lowest
positive or highest positive value depending on the cut).

The EQUalization scaling tries its best to put the same number of
pixels in each slot of the color table, thus increasing immensely the
visibility of low-contrast images. This scaling mode has problem (and
warns user) when a large number of pixels have exactly the same value
(i.e., no contrast at all). Beware that most "real" images are
obtained with receivers working with a small number (11 to 16) of
bits, thus restricting the range of available Real numbers in the
data.

The SIC variables CURIMA%EQUAL%NLEV, CURIMA%EQUAL%LEV and
CURIMA%EQUAL%HIST contain the number of different levels computed in
EQUALIZATION mode, the values of these levels, and the number of
pixels in each level, respectively. Useful to know which contour
levels to draw, and necessary for the WEDGE command.
.\"--------------------------------------------------------------------
.ti -4
2 /VISIBLE
.ti +4
[GREG2_\]PLOT /VISIBLE

Specify that the image is to be always drawn, even when totally masked
by an overlapping image. This allows special features like movies when
the plot content is drawn or redrawn, although the "movie" speed
depends on the computer power.
.\"--------------------------------------------------------------------
.ti -4
2 RGB
.ti +4
PLOT [3D__Var] [/SCALING LIN|LOG|EQU [Rlcut Rhcut Glcut Ghcut Blcut
Bhcut]]
.ti +4
PLOT [3D__Var] [/SCALING LUPTON [Beta]]

THIS FEATURE IS CURRENTLY EXPERIMENTAL. Calling sequence, option
names, and behavior are subject to changes in the future.

If the RG buffer (or the named variable, if any) is a 3D cube with 3
planes, the command will plot it as a RGB image (R for 1st plane, G
for 2nd plane, B for 3rd plane).

The extrema are always (re)evaluated for each plane individually. That
is, global cube extrema and RG%MIN and RG%MAX (if available) are
ignored.

The default is to display the whole extrema ranges with linear
scaling. This can be overridden with the option /SCALING, giving a
custom scaling and cuts for each plane. Lupton scaling (combining each
planes in a non-independent way) is available; Beta factor defaults to
3 but can be customized.
.\"====================================================================
.ti -4
1 POLYGON
.ti +4
[GREG2_\]POLYGON [(File)Name] [/VARIABLE]
.ti +4
[GREG2_\]POLYGON [/PLOT] [/FILL [Colour]] [/HATCH [Ipen] [Angle]
[Separ] [Phase]]
.ti +4
[GREG2_\]POLYGON [(File)Name] /RESET

The first syntax defines the polygon either from:
.in +4
.ti -4
CURSOR
.br
If no argument and no option, the interactive cursor is invoked to
define the polygon summits. Type any key to go to next summit, C to
correct the last one, D to delete it, and type E to end the polygon
definition. The last polygon side will then appear. The polygon
definition may be aborted by typing Q. For graphical displays, you may
use the mouse buttons for the commands. The left mouse button draws a
vertex, the middle mouse button deletes the last vertex, and the right
mouse button ends the polygon definition. After the use of the cursor,
the polygon plot is stored in the GTV metacode in a segment named
POLYGON. You can delete it with the command CLEAR SEGMENT.
.ti -4
FILE
.br
If a file name is given as argument, the cursor is not called. The
summit coordinates are read from the named ASCII file (X in column 1,
Y in column 2).
.ti -4
VARIABLE
.br
If a SIC variable name is given with the /VARIABLE option, the summit
coordinates are read either from a variable array of the form:
     VAR[NXY,2]  Real or Double
.br
or a structure of the form (i.e. same as output):
.br
     VAR%NXY         Integer or Long
     VAR%X[VAR%NXY]  Real or Double
     VAR%Y[VAR%NXY]  Real or Double
.in -4
Whereever they come from (cursor, file, or variable), the polygon
values are stored internally; they can be printed with the command
GREG2_\WRITE_ POLYGON, and they correspond to the variables POLY%NXY
(number of vertices), POLY%X and POLY%Y (the corresponding
coordinates). The currently defined POLYGON is used by the commands
MEAN and MASK.

The polygon loaded by the command can be directly or later plotted
with the following options:
.in +4
.ti -4
/FILL [Colour]
.br
the polygon is color-filled with the current pen colour or with the
specified colour (see HELP PEN /COL for possibilities),
.ti -4
/HATCH [Ipen] [Angle] [Separ] [Phase]
.br
the polygon is filled with parallel hatch lines with the specified pen
(default current), with the given angle in degrees (default 45),
separation in physical units (default 0.25 cm), and phase from 0 to 1
to displace the lines by this fraction of the separation from a fixed
reference (default 0).
.ti -4
/PLOT
.br
the polygon contours are drawn with the current pen,
.in -4
For a color-filled and/or hatched and/or contoured polygon, these
three options can be combined; they will be executed in the above
order.

Finally, the third syntax with the /RESET option allows to undefine
the POLY% variable and free the internal buffers.
.\"====================================================================
.ti -4
1 PROJECTION
.ti +4
[GREG2_\]PROJECTION [A0 D0 [Angle]] [/TYPE Ptype]

Define a projection of the (celestial) sphere from point of (A0,D0),
(which are Longitude and Latitude respectively) of the specified
type. Angle is the angle between the Y axis and the North pole. The
previous values are kept if no argument is specified. All angles are
in degrees, except if the SYSTEM is EQUATORIAL in which case A0 is the
right ascension and must be specified in hours. Formats like
-dd:mm:ss.s or hh:mm.mmm in sexagesimal notation up to the point field
are allowed. After the point, decimal values are assumed.

When a projection is active, the User coordinates are assumed to be
projected coordinates of the sphere, and hence in the case of small
field of view where distortion are negligible, correspond to angular
offsets MEASURED IN RADIANS. The field of view of the projection is
defined by command LIMITS.

The TYPE can be
.in +16
.ti -14
NONE_ _ _ _ _ _ _ _ _ _ Disables the projection system. User
coordinates then loose their interpretation in terms of projected
coordinates. The ANGLE__UNIT is then totally ignored.

.ti -14
CARTESIAN_ _ _ _ _ Cartesian projection with linear coordinates in
both directions, with a possible projection angle.

.ti -14
GNOMONIC_ _ _ _ _ _ Radial projection on the tangent plane. Being
R and P the (angular) polar coordinates from the projection point
(tangent point), the projected coordinates are given by X =
Tan(R).Sin(P) and Y = Tan(R).Cos(P) .

.ti -14
ORTHOGRAPHIC_ _ View from infinity. X = Sin(R).Sin(P) and Y =
Sin(R).Cos(P)

.ti -14
AZIMUTHAL_ _ _ _ _ Spherical offsets from the projection center.
X = R.Sin(P) and Y = R.Cos(P).

.ti -14
STEREOGRAPHIC_ Uses Tan(R/2) instead of Tan(R), and is thus less
distorted than the Gnomonic projection. This is an inversion from the
opposite pole.

.ti -14
LAMBERT_ _ _ _ _ _ _ Equal area projection. Projected distance is
2*Sin(R)/Sqrt(2*(1+Cos(R)).

.ti -14
AITOFF_ _ _ _ _ _ _ _ Equal area projection. Angle and D0 are
ignored.

.ti -14
RADIO_ _ _ _ _ _ _ _ _ The standard radio astronomy single dish
mapping "projection", in which X_ =_ (A-A0).COS(D) and Y_ =_ D-D0. The
Angle is obviously ignored.

.ti -14

SFL_ _ _ _ _ _ _ _ _ _ _ Sanson-Flamsteed projection, similar to the
RADIO projection with one exception: X_ =_ (A-A0).COS(D-D0) and Y_ =_
D-D0. Beware that an Euler rotation of the celestial sphere is
necessary as an additional step, i.e. (A0,D0) and (A,D) here are not
the absolute celestial coordinates (see Calabretta & Greisen 2002).

.ti -14
MOLLWEIDE_ _ _ _ _ Equal area projection. Angle and D0 are
ignored. The projection trades accuracy of angle and shape for
accuracy of proportions in area, and as such is used where that
property is needed, such as maps depicting global distributions.

.ti -14
NCP_ _ _ _ _ _ _ _ _ _ _ North Celestial Pole. Projection to a plane
perpendicular to the pole. Used by the WSRT.
.in -16
.\"====================================================================
.ti -4
1 RANDOM__MAP
.ti +4
[GREG2_\]RANDOM__MAP [Arg1 [Arg2]] [/NEIGHBOURS Nb] [/TRIANGLES]
[/EXTRAPOLATE] [/BLANKING Bval] [/VARIABLES Vx Vy Vz] [/SKIP
[TRIANGULATION] [INTERPOLATION]]

This command is a general purpose interpolation task which uses data
from the X, Y and Z arrays (or those specified in option /VARIABLES)
to fill in a Regular Grid array representing the same surface Z=f(X,Y)
by an interpolation process.  X, Y and Z are arrays defined by the
COLUMN command (see HELP_ COLUMN). It triangulates the data for
interpolation. If a triangulation already exists, and only the Z array
has been changed, RANDOM__MAP does not make a new triangulation.

Often, the user-provided Z=f(X,Y) surface is REGULARLY SAMPLED, even
if NOT COMPLETELY SAMPLED. In this case, it is recommended to use directly the
RGDATA command to create a Regular-grid map, since RANDOM is known to
perform awkwardly with regularly sampled data.

The interpolated grid can be defined by the arguments. If Arg1 is
"RGMAP", the interpolated grid will be exactly coincident with the
current Regular Grid array, else Arg1 and Arg2 are used to indicate
the number of pixels in X and Y directions and Arg2 = Arg1 if not
specified. If no argument is specified, the previous grid (if any) is
reused (see also subtopic /SKIP).

Note that several hypothesis are made about the geometry of triangles
in the plot page space (hence the geometry may be changed by changing
the LIMIT or the BOX__LOCATION). You should thus use limits which
gives a reasonable representation of what are the neighbours of a
given data point. Moreover, this is an interpolation process. Hence if
the basic sampling theory is not respected by your choice of input
data points and output grid, spurious oscillations may occur in the
resulting grid.
.\"--------------------------------------------------------------------
.ti -4
2 /BLANKING
.ti +4
[GREG2_\]RANDOM__MAP /BLANKING Bval

Specify the value Bval to be attributed for pixels lying outside the
convex hull of triangles. The default value is that defined in the SET
BLANKING command. This switch is mandatory if no default blanking
value is preset and no extrapolation required.
.\"--------------------------------------------------------------------
.ti -4
2 /EXTRAPOLATE
.ti +4
[GREG2_\]RANDOM__MAP /EXTRAPOLATE

Control whether extrapolation outside the convex hull of the triangles
is to be done or not. The default is not, i.e. the command fills with
the blanking value the exterior of the convex hull. Beware that
extrapolation is always hazardous.
.\"--------------------------------------------------------------------
.ti -4
2 /NEIGHBOURS
.ti +4
[GREG2_\]RANDOM__MAP /NEIGHBOURS Nb

The argument Nb changes the number of points influencing the
interpolated values. Default is 4 and values up to 8 may be used in
some cases. Caution, it slows down the program, and may enhance
oscillations in some cases.
.\"--------------------------------------------------------------------
.ti -4
2 /SKIP
.ti +4
[GREG2_\]RANDOM__MAP /SKIP [TRIANGULATION] [INTERPOLATION]

The option /SKIP will avoid recomputing the triangulation and/or
interpolation, in order to save time e.g. on large maps. Those
optimizations are under the responsibility of the user, who should
know if the context (e.g. variables) has changed or not. The command
can not guess it by itself.

.in +4
.ti -2
-_ /SKIP TRIANGULATION can be used if the triangulation has already
been done. The triangulation depends on the x and y values, which can
come from the X and Y buffers or /VARIABLES Vx Vy, but also on the
current plot limits.
.ti -2
-_ /SKIP INTERPOLATION can be used if gridding (interpolating) has
already been done. It depends on the z values, which can come from the
Z buffer or /VARIABLES Vz. It also depends on the triangulation.
.in -4

Note that the command may not honor the skip request if it detects
that the context has changed. This is true e.g. at first call of the
command.
.\"--------------------------------------------------------------------
.ti -4
2 /TRIANGLES
.ti +4
[GREG2_\]RANDOM__MAP /TRIANGLES

Plot the triangles selected by the program for interpolation. A single
graphic segment will contain all triangles.
.\"--------------------------------------------------------------------
.ti -4
2 /VARIABLES 
.ti +4
[GREG2_\]RANDOM__MAP /VARIABLES Vx Vy Vz

Use variables Vx Vy Vz instead of the default X,Y,Z buffer to compute
the map.
.\"====================================================================
.ti -4
1 RESAMPLE
.ti +4
[GREG2_\]RESAMPLE Nx Ny [/X Xref Xval Xinc] [/Y Yref Yval Yinc]
[/BLANKING Bval]

This command resamples (by bilinear interpolation) the current regular
grid array on a different grid. The number of pixels of the new grid
must be specified. Unless the user specifies an explicit conversion
formula in the /X and /Y options, the program adjusts it to match the
current Regular Grid array. A blanking value MUST BE specified (either
by default in SET_ BLANKING or using the option /BLANKING) because no
extrapolation is performed. For the same reason, any output pixel's
value that would be interpolated from at least one input blanked
pixel, is itself blanked.
.\"====================================================================
.ti -4
1 RGDATA
.ti +4
[GREG2_\]RGDATA [Name|Array__X_ Array__Y_ Array__Z] [/SUBSET NXmin
NYmin NXmax NYmax] [/VARIABLE] [/FORMAT Fmt [code]] [/INCREMENT IncX
IncY] [/BLANKING Bval]

This command optionally creates, then loads a two-dimensional map into
the Regular Grid array (to be contoured by RGMAP, plotted by PLOT...).
This is THE basic command needed for subsequent 2-dimensional
treatment. "Regular Grid" means that data is internally stored as a
two-dimensional array, thus lies on a Regularly sampled Grid. The
user-provided "pixel values" may come from various "descriptions" of
such regularly sampled (but possibly uncompletely sampled) data:
.in +4
.ti -2
 1)_ Three 1-dimensional arrays, say, X Y and Z, that contain Z=f(X,Y)
at regular intervals in X and Y.
.ti -2
 2)_ A preexisting internal 2-D array (possibly a section of a 3D or 4D
array).
.ti -2
 3)_ An external, specially formatted, file.
.in -4
For data NOT REGULARLY ("randomly") sampled, use the
GREG2_\RANDOM__MAP command instead. The Regular Grid buffer can be
saved in a file with the command GREG2_\WRITE.

Once defined, the Regular Grid description and data are available
under the SIC variables:
.br
.in +4
.ti -2
- RG: the data array e.g. RG[1,1]
.ti -2
- RG%NX: dimension along X
.ti -2
- RG%XREF, RG%XVAL, RG%XINC: X axis conversion
.ti -2
- RG%NY: dimension along Y
.ti -2
- RG%YREF, RG%YVAL, RG%YINC: Y axis conversion
.ti -2
- RG%MIN, RG%XMIN, RG%YMIN: minimum value and position
.ti -2
- RG%MAX, RG%XMAX, RG%YMAX: maximum value and position
.in -4

The following command syntax is used to deduce which "description" is
provided:

.in +4
.ti -2
-_ With 0 or 3 arguments, RGDATA will try to assemble Z=f(X,Y) either
from the X,Y and Z arrays (as defined by command COLUMN) or from
"Array__X Array__Y Array__Z", that should be 1D SIC variables
previously created. The option /INCREMENT is used to force the X and Y
sampling interval to (IncX,IncY) in case of roundoff errors. Defining
twice the same pixel is an error. If a blanking value is currently
defined, non-sampled pixels will be attributed this value, which is
overriden by the Bval value of the /BLANKING option. Note that, if a
blanking value is currently defined, pixels for which X or Y are in
the blanking range are themselves blanked.

.ti -2
- With ONE argument (Name) following the command, Name is taken as the
name of an existing SIC 2D variable if option /VARIABLE is present.
Otherwise, Name is a specially formatted file (see
HELP_ RGDATA_ FILE__FORMAT) from which the Regular Grid array must be
read in.
.in -4

A rectangular subset of the array defined by the pixel coordinates of
the Bottom Left Corner and Top Right Corner can be selected thanks to
the /SUBSET option.
.\"--------------------------------------------------------------------
.ti -4
2 FILE__FORMAT
.ti +4

The format for the input file consits of a four line header as such:
.nf
1st line : NX XREF XVAL XINC
2nd line : (any comment for first axis, could be blank)
3rd line : NY YREF YVAL YINC
4th line : (any comment for 2nd axis, could be blank)
.fi
followed by the data (NX times NY pixel values) in a format which can
be specified with the /FORMAT option when the default 10z8 is not
used.
.br
NX is the number of pixels in the 1st dimension of the map (on the "X
axis"), XREF the index of the pixel for which the actual X abscissa
value is XVAL, the increment between two pixels being XINC, and the
same for the y axis. Thus, the abcissa X of the pixel 'I' is just
X=(I-XREF)*XINC+XVAL
.br
This format is very simple-minded (so that any inexperienced
programmer can use it in less than 5 minutes), but highly non
efficient in I/O processing. A more elaborate data format ("IMAGES"),
specially suited for astronomical applications and large maps is
available through GREG3_\ language (command GREG3_\IMAGE), or directly
using SIC variables (command SIC_\DEFINE) and the /VARIABLE option of
this command. One should read once its data in RGDATA format in GreG,
then convert it for future use in IMAGE format with the command
GREG2\WRITE IMAGE filename.

See also the IMAGE__HOWTO subtopic of the GREG2_\PLOT command.
.\"--------------------------------------------------------------------
.ti -4
2 /FORMAT
.ti +4

The /FORMAT option governs how the data part (pixel values) of the
RGDATA file must be read by GreG. Fmt is a valid fortran format
(default is 10z8, the minimal way to encode real*4 data). code may be
BY, R4, R8, I4 or I2, depending if the data written in the file are
BYtes, Real4, Real8, Integer4 or Integer2. (The values in the GreG map
will always be Reals*4 after the read is done).
.\"====================================================================
.ti -4
1 RGMAP
.ti +4
[GREG2_\]RGMAP [Quiet|Fast|chunksize] [/PERCENT P1] [/ABSOLUTE A1]
[/BLANKING Bval Eval] [/GREY COLOUR N] [/KEEP File__Name [Blank]]
[/PENS [Pos Neg]] [/ONLY POSITIVE|NEGATIVE]

Draws (or fills) isocontours of the Regular Grid array. The RG is an
internal 2D "map" created/loaded by various commands (RGDATA,
RANDOM__MAP, RESAMPLE, IMAGE), or loaded by a calling program. The
levels are those specified by command LEVELS, but may be affected by a
scaling factor by option /PERCENT or /ABSOLUTE.

This command is normally used in the following sequence:
.nf
Greg> SET BOX LOCATION Gx1 Gx2 Gy1 Gy2  ! Define box position
Greg> RGDATA (options...)               ! Put image in the RG variable,
                                        ! read associated header variables
Greg> LIMITS /RGDATA                    ! Computes associated limits
Greg> PLOT                              ! Plot the array in the box
Greg> BOX                               ! Draws the box
Greg> LEVELS 0.1 to 0.9 by 0.1          ! define contour levels
Greg> RGMAP /PERCENT 1                  ! Draw contour levels  (in this
                                        ! case, as percentage of peak)
.fi

The "Quiet" mode does contouring silently. For "Fast" and "chunksize"
modifiers, see subtopic MEMORY__OPTIONS.
.\"--------------------------------------------------------------------
.ti -4
2 MEMORY__OPTIONS
.ti +4

The program normally allocates less that 1/5 of the total number of
pixels in the map to store the contour segments, and warns the user
when that limit is reached. Besides, contouring may be slow on large
maps. The modifier "Fast" cuts the map in smaller "chunks" and
performs contouring on those submaps, without the 1/5 above
limitation.

The Contour-filling mode (/GREY) can consume (temporary) a large
amount of memory, so is always performed on subsets of the image
("chunks") when the image size is greater than a system-dependent
limit (256*256 on UNIX systems). When the contours are too involved,
an internal limit can nevertheless be reached. One can then retry the
contour-filling by specifying a smaller "Chunksize" (in pixels). For
example, to force contour-filling on subsets of 64 "lines" of a
512x512 pixel image, type RGMAP_ 64*512_ /GREY
.\"--------------------------------------------------------------------
.ti -4
2 /ABSOLUTE
.ti +4
[GREG2_\]RGMAP /ABSOLUTE A1

Contour levels are multiples of A1, e.g. for LEVELS 1 2 3, the contour
used will be A1 2*A1 3*A1.
.\"--------------------------------------------------------------------
.ti -4
2 /BLANKING
.ti +4
[GREG2_\]RGMAP /BLANKING Bval Eval

Override the current blanking value as defined by command
SET_ BLANKING. Contours are not drawn in pixels touching pixels with
value V so that ABS(V-Bval)_ <=_ Eval. This is extremely useful for
regular grids only partially filled as often occur in astronomy.
.\"--------------------------------------------------------------------
.ti -4
2 /GREY
.ti +4
[GREG2_\]RGMAP /GREY [start [step] [background]]

On graphic displays with area filling capabilities, fills contours
with up to 16 different color pens (but the number of contours is not
limited to 16). These pen colors may be changed in the same manner as
for the pixels colors (see HELP LUT_ /PEN). "start" (default 0) and
"step" (default 1) may be used to change the exploration of the 16-pen
palette. "background" is the number of a color used to fill the map
before contour-filling, thus providing a user-defined background for
the contour-filled map.

In case of Filling problems, see the subtopic MEMORY__OPTIONS of this
HELP.
.\"--------------------------------------------------------------------
.ti -4
2 /KEEP
.ti +4
[GREG2_\]RGMAP /KEEP File__Name [Blank]

Will keep a formatted copy of the coordinates of the contour points in
the specified file. This file can later be used as an input file for
COLUMN. X coordinates are in column 1 and Y coordinates in column
2. The Blank value is written as a separator value for later
CONNECT_ /BLANKING Blank. Blank defaults to the SET_ BLANKING value if
it exists, else Blank is mandatory.
.\"--------------------------------------------------------------------
.ti -4
2 /ONLY
.ti +4
[GREG2_\]RGMAP /GREY /ONLY POSITIVE|NEGATIVE

Apply the filling capabilities provided by the /GREY option only
to positive or negative contours for better clarity.

.\"--------------------------------------------------------------------
.ti -4
2 /PENS
.ti +4
[GREG2_\]RGMAP /PENS [Pos Neg]

Selects the pens for positive and negative contours. Three modes of
operation are possible :
.in +4
.ti -2
-_ Without option /PENS, positive contour levels use pen 0 and
negative contour levels use pen 15. Positive means that the value
given in command LEVELS is positive, not the final contour level value
which is affected by a possibly negative factor.
.ti -2
-_ With option /PENS, all contours use the current pen.
.ti -2
-_ With /PENS_ Pos_ Neg, positive contours use pen number Pos and
negative contours use pen number Neg.
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 /PERCENT
.ti +4
[GREG2_\]RGMAP /PERCENT P1

Computes M=MAX(ABS(min),ABS(max)) of the data to be contoured. Contour
levels selected with LEVELS are multiples of P1 percent of M. E.g. if
P1 = 10 and LEVELS 1 2 5 9, the contour levels are 10, 20, 50 and 90%
of the peak value.

From the above rule you can deduce the absolute level values with the
following commands:
.nf
    DEFINE REAL ABSLEVELS /LIKE GREG%LEVELS
    LET ABSLEVELS MAX(ABS(RGMIN),ABS(RGMAX))*P1*GREG%LEVELS/100
    EXA ABSLEVELS
.fi
.\"====================================================================
.ti -4
1 STRIP
.ti +4
[GREG2_\]STRIP [X1 Y1 X2 Y2]

Will extract from the current Regular Grid array a strip going through
points (X1,Y1) and (X2,Y2) in User coordinates. If no arguments are
present, it will call the cursor to set the two points.  Although the
end points need not be on the map boundaries, STRIP will always
produce a full strip across the map.

For strip parallel to the X or Y map axis, the nearest pixel is used
to fill the values. For any other strip orientation, if the tangent of
the angle is less than (NY-1)/(NX-1) (i.e. if you scan the X map axis
faster than the Y map axis), the number of resulting points on the
strip profile will be NX and the user coordinates along the strip will
be the map X coordinate. For each pixel, interpolation along the Y
axis is done using the three nearby Y pixels. A similar situation with
X replacing Y occurs if the angle is larger.

The map user coordinates are put into the X buffer, and map values
into the Y buffer. The strip can then be plotted using CONNECT, but
remember to set decent limits before.
.\"====================================================================
.ti -4
1 WEDGE
.ti +4
[GREG2_\]WEDGE [Top|Bottom|Left|Right [Size]] [/SCALING Lin|Log|Equ
Min Max] [/LEVEL [Label] ]

Will plot a WEDGE along the current BOX. WEDGES are used after a PLOT
command to show the relationship between pixel hues and image values.

The default position is Right, i.e., on the right side of the box, but
the other location and size modifiers are self-explanatory. The
SCALING defaults to the current scaling of the last image PLOTted, but
can be changed (as in command PLOT) with the /SCALING option.

The /LEVEL option will draw levels (as defined by the LEVEL command)
at their appropriate location on the wedge. The modifier Label will
label the wedge axis with the level values. This is the default (i.e.,
some levels should be defined) for the EQUALIZATION Mode, for which
the relationship between pixel hues and image values is strongly
non-linear.
.\"====================================================================
.ti -4
1 WRITE
.ti +4
[GREG2_\]WRITE Item File__Name
.ti +4
[GREG2_\]WRITE COLUMN File__Name [OLD|NEW [Format]] /TABLE [X Nx] [Y
Ny] [Z Nz]

This command is used to save some GreG internal buffers on an output
file for later processing. The item specifies what is to be saved, and
the format of saving, and can be :
.in +4

.ti -2
POLYGON
.br
Save the current polygon in a formatted way on two columns easily
readable by command COLUMN or POLYGON later. The default extension
is .POL

.ti -2
RGDATA
.br
Save the current Regular Grid array on a RGDATA-like output file (to
preserve the result of a masking, or of a random mapping
interpolation). See also HELP RGDATA FILE__FORMAT. The default
extension is .DAT

.ti -2
IMAGE
.br
Same as above but use the more efficient and complete IMAGE data
format of GILDAS. The default extension is .GDF

.ti -2
COLUMN (no option)
.br
Save the current X Y Z buffers on a formatted output file (after a
SORT or a STRIP for example). The default extension is .DAT

.ti -2
COLUMN /TABLE
.br
Save the X Y Z buffers but on column Nx, Ny, Nz of the specified
output table (Gildas Data Format). A new table is created if argument
NEW is specified, otherwise the table must already exists (default
OLD). The format of NEW tables can be specified as a 4th argument in
REAL (default), DOUBLE or INTEGER. The OLD tables may be expanded if
any of Nx, Ny or Nz exceed the table column number ; exact match on
the number of lines is required. The tables can be read by command
COLUMN_ /TABLE.
.in -4
.\"====================================================================
.ti -4
1 ENDOFHELP
