.ec _
.ll 80
.ad b
.in 4
.ti -4
1 Language
.nf
  DISPLAY_\ Language summary

The DISPLAY_\ Language contains commands to display data cubes and results
in a flexible, interactively controlled or scripted way. Available commands:

CATALOG       : Define the spectral line catalog to identify transitions
COLOR         : Control the color LUT to highlight the Zero level
COMPARE       : Visually compare 2 data cubes 
FIND          : Search for spectral lines in the specified range
LOAD          : Read a file in the DATA area for further display
EXPLORE       : Explore a data cube: make a plot of spectra around a 2-D map
EXTRACT       : Extract a subset from a data cube
INSPECT__3D    : Visualize any data cube by cuts along 3 main directions
POPUP         : Enlarge one panel of a display
SET 	      : Set some IMAGER or GreG parameter
SHOW          : Display (in a plane by plane plot) any data cube or
                other results from the IMAGER program.
SLICE         : Extract a Slice of the specified data cube
SPECTRUM      : Compute integrated spectrum from data cube
STATISTIC     : Compute Statistics on specified data
VIEW          : Show (in a comprehensive plot) any data cube
.fi

Commands EXPLORE, INSPECT__3D, SHOW and VIEW remember and share the same 
input data for their display (e.g. SHOW CLEAN, followed by EXPLORE will
work as EXPLORE CLEAN).

.!======================================================================  
.ti -4
1 CATALOG
.ti +4 
[DISPLAY_\]CATALOG [?|NONE|FileName [.. [FileNameN]] [/SORT OutFile [Interval]

Define or list the current catalog(s) for spectral line identification. 
With argument NONE, the active catalogs are discarded.
With no argument or argument ?, the command will just list the names of the current catalog(s).

A catalog is a file in the "Astro" GILDAS format, as used in programs
ASTRO or CLASS in the GILDAS suite, or in  the LINEDB_\ data format
(which requires Python binding).  

There can be only ONE Astro catalog connected at a time, and it is exclusive
of any LINEDB data bases. On the opposite, there may be several
LINDEB data bases specified by the CATALOG command.

At initialization, IMAGER search for $HOME/imager.linedb as default
catalog, then gag__data:imager.linedb if not found. If the specified
catalog does not exist, IMAGER falls back to the gag__data:molecules.dat
Astro-format catalog.

Caution: although direct use of the LINEDB_\USE command is also 
possible to define the LINEDB catalog(s), this is not recommended 
as it may result with possible conflicts with an Astro catalog.

.ti -4 
2 /SORT
.ti +4
[DISPLAY_\]CATALOG InputCatalog /SORT OutputCatalog [Interval]

Sort a InputCatalog in Astro format, and place the sorted result
in OutputCatalog, in Astro CSV format. Duplicate entries are removed,
as well as spectral lines from the same molecule separated by less
than Interval (in MHz) if specified. The later facility allows to 
avoid handling separately hyperfine components of the same transition
that are too close together.


.ti -4
2 Default
.ti +4

With Python binding (which is normally provided), a default catalog 
can be created (in the local directory) by executing once
.br
  @ gag__data:imager-linedb.sic 
.br
This may take a while, and even get stuck occasionally because it
performs network access to remote databases. You can later copy 
this catalog to your $HOME. See HELP LINEDB_\ to add or remove
species from such catalogs. 

Without Python binding, IMAGER provides a default Astro catalog
in gag__data:molecules.dat.
.ti -4
2 Astro
.ti +4

The ASTRO catalog format is one of the two following ones:

A comma separated value file, including the frequency, 
the species name, and the transition name, e.g.:
.ti +4
  150E3; MOLE; TRANSITION;

A list-directed file, with the same information, e.g.:
.ti +4
  150E3 'MOLE' 'TRANSITION'

Lines beginning with an exclamation mark are considered as comments.
The first line **MUST** be a comment line (or just start by a ;)
That line may specify the unit of Frequencies in the catalog (Hz, kHz, MHz, GHz). 
If no recognized unit is found in this line, frequencies are assumed to be in MHz.

A default catalog (with no implied warranty) is given in gag__data:molecules.dat.

.ti -4
2 Linedb_\
.ti +4

The LINEDB catalog format is a more flexible facility, which can also
holds additional information.  On-line spectral databases (JPL and
CDMS) are directly useable as LINEDB catalogs, although access can
be long in this case. 

Scripts named gag__data:*-linedb.sic are availables as examples
to construct local data bases from the on-line ones. Beware that
the on-line databases sometimes change their naming conventions, so
that identifying a given species by name can be tricky.

In 2020, access to CDMS was unreliable. It has improved since.
Access to JPL is operational, but frequencies are not as up-to-date as in CDMS.

Local files in the JPL ".cat" format can be used, but as of Jan-2020,
the Einstein coefficients are wrong. They also require a "partfunc.cat"
in the following format (given here for HN-15-C as an example)
.nf
species HN-15-C 28006
temperatures 300. 225. 150. 75. 37.5 18.75 9.375
qpart 141.06 105.9 70.797 35.514 17.23 9.135 4.746
.fi
The tag number (28006 here) must match that of the ".cat" file.

.ti -4
2 LINEDB%ENERGY

Maximum energy of the upper state of the selected transitions, in K.
This applies only to LINEDB data bases.


.!========================================================================
.ti -4
1 COLOR
.ti +4

  [DISPLAY_\]COLOR HueRange [HueZero HueExtent]
  
Select a color Look-up-Table so that the color at value Zero is given
by HueZero (in range [0,360[), and the overall HUE extent is HueExtent 
(which can be larger than 360).
HueRange (in the same units) indicate a part of the LUT
which  becomes progressively whiter (less saturation, HueRange < 0) or 
darker (less intensity, HueRange > 0) around the colour HueZero.

Such LUTs allow to outline the Signal-containing regions compared
to the noise level, either in bright (HueRange < 0) or dark (HueRange > 0)
modes.

.!========================================================================
.ti -4
1 COMPARE 
.ti +4
[DISPLAY_\]COMPARE [LeftSet RightSet] Mode [/DIRECTORY NameTree]

Visually compare two data cubes or two maps side by side.
See HELP COMPARE CUBE  and HELP COMPARE MAPS for details.

.ti -4
2 /DIRECTORY
.ti +4
[DISPLAY_\]COMPARE LeftSet RightSet /DIRECTORY NameTree

  Display the graphics under the user specified <NameTree "graphic tree", 
instead of the usual <GREG tree. The tree is created if needed, cleared
and activated.

A few names should not be used:  VSIDE, POPUP, CCT because they are
already used by some specific plotting routine.

.ti -4
2 CUBE
.ti +4
[DISPLAY_\]COMPARE LeftCube RightCube

Create a "view-like" (see HELP VIEW) display to compare side-by-side
two data cubes. LeftCube should be 3-D SIC image variable, as RightCube.

The display is divided in 3 columns:
.br
- The left column contains the integrated intensity image (bottom) and
current channel (top) for the LeftCube
.br 
- The right column contains the same information for the RightCube

The middle column has 4 panels, from top to bottom
.br
- Spectrum of current pixel of RightCube
.br 
- Spectrum of current pixel of LeftCube
.br
- Integrated spectrum of RightCube
.br
- Integrate spectrum of LeftCube

The yellow area on the integrated spectra indicates over which velocity
range the integrated maps are computed.  The integrated spectra are
computed over the region displayed in the integrated intensity maps (default
is whole displayed area).

The green lines on the current spectra indicate the current displayed channel.
They may correspond to the same velocity (R or RightClick / spacebar with 
cursor in the spectra) or different ones (I -- for Independent -- with 
cursor in the spectra). 

.ti -4
2 MAPS
.ti +4
[DISPLAY_\]COMPARE [LeftMap RightMap] [Mode]

Compare side by side two 2-D datasets. The LeftMap defines the way both are
displayed (sizes, contour levels, color scale). If neither is specified,
just re-display the last ones. 

Mode is an optional keyword that indicates which data set controls the size
(unless SIZE is non zero) and data range (unless SCALE is specified). 
Allowed keywords are
.nf
LEFT    Size and data range taken from LeftMap
RIGHT   Size and data range taken from RightMap
JOINT   Data range taken as the union of the Left and Right ranges
EACH    Data range taken for each map.
.fi
For JOINT and EACH, the size is the union of sizes.

The maps can be planes of data cubes. For example
.ti +8
COMPARE CLEAN[2] CLEAN[16]
.br
will display side by side channel 2 and channel 16 of the CLEAN cube.

.ti -4
2 WARNING
.ti +4

By default, COMPARE only considers relative positions with respect to the 
reference position of each cube/map.  This allows to compare two different 
objects if needed.

However, for MAP comparisons, if BOX__LIMITS specifies absolute coordinates,
each map will be displayed according to these common box limits.

.ti -4
2 Restrictions
.ti +4

The following restrictions currently applies :
.nf
- There is no mode with Absolute position matching for CUBEs.
- when using the Zoom capability, COMPARE preserves a square area
- the I (--Independent--) mode only works on RightCube
- Slice (S key) and Extract (X key) do not work 
.fi

.!========================================================================
.ti -4
1 EXPLORE
.ti +4
[DISPLAY_\]EXPLORE  [DataCube] [/ADD Cx Cy [Box]] [/NOPAUSE]
[/DIRECTORY NameTree]

Create a plot with a 2-D map in the middle, and up to 8 spectra
around it. 

DataCube is the name of an internal 3-D buffer, SIC variable or
data file. The 2-D map will be either a channel of this 3-D data set,
or a velocity integrated map obtained from it. It will displayed
at the center of the plot. If not present, argument DataCube keeps its
previous value.

Spectra can be displayed around, with arrows showing their position
in the map, either interactively (when the /NOPAUSE option is not
present), or manually through the /ADD option. In interactive mode,
the user can press S to extract and display the spectrum from
any place in the 2-D map.

EXPLORE ?  will list the control variables for this command. The
usual SIZE and CENTER control the 2-D map size, RANGE controls the
velocity range, and SCALE the spectral flux range.

.ti -4
2 /ADD
.ti +4
[DISPLAY_\]EXPLORE  /ADD Cx Cy [Box]

Add the spectrum coming from positin Cx Cy (in arcsec) in the specified
Box number. The Box number indicates the placement as in a numeric
keypad layout. Box 5 (the center) is reserved for the 2-D map.

If Box is not present, the spectrum is placed in the most plausible
position according to the coordinates (Cx,Cy).


.ti -4
2 /DIRECTORY
.ti +4
[DISPLAY_\]EXPLORE DataCube /DIRECTORY NameTree

  Display the graphics under the user specified <NameTree "graphic tree", 
instead of the usual <GREG tree. The tree is created if needed, cleared
if it already exists.

Using different "graphic trees" allows the user
to simultaneously display (same or different) data in different ways,
as each tree inherits a specific window.

A few names should not be used:  VSIDE, POPUP, CCT because they are
already used by some specific plotting routine.


.ti -4
2 /NOPAUSE
.ti +4
[DISPLAY_\]EXPLORE  [DataCube] /NOPAUSE

Just display the 2-D map and any already existing spectra, but do
not call the cursor.

.ti -4
2 Variables:
.ti +4

Like SHOW, VIEW and INSPECT__3D, EXPLORE is controlled by variables.  Most of them  are among  
those controlling SHOW:
.ti +8
SPAN, RANGE, SIZE, CENTER, SCALE, SPACING, DO__BIT DO__GREY, DO__CONTOUR, DO__MASK.

In addition, the SFLUX variable controls the displayed flux scale in the map.

.ti -4
2 CENTER
.ti +4
  REAL CENTER[2]

Specify the relative coordinates of the center of the displayed
region, in ANGLE__UNIT defined by SET ANGLE__UNIT command.


.ti -4
2 DO__BIT
.ti +4
  LOGICAL DO__BIT
  
Show a bitmap color plot (YES) or do not (NO) for each panel.
The bitmap range is controlled by variable SCALE.

.ti -4
2 DO__CONTOUR
.ti +4
  LOGICAL DO__CONTOUR

Draw (YES) or do not (NO) draw the contour level, which are controlled
by SPACING and SPACE__TYPE. This is provided for compatibility
with Mapping and Greg.

.ti -4
2 DO__GREY
.ti +4
  LOGICAL DO__GREY 

Do (YES) or do not (NO) use grey-scale contouring. Note that this
is independent of DO__CONTOUR.

.ti -4
2 DO__MASK
.ti +4
  LOGICAL DO__MASK
  
Hide part of the plot (contour or bitmaps, and even axis ticks) that lie
in the upper left corner of each panel to have a clean display of the
value specified by MARK.

.ti -4
2 RANGE
.ti +4
  REAL RANGE[2]
  
Specify the range to be displayed for the 3rd axis, as well as the displayed
range of the integrated spectrum. 

RANGE should not be confused with SPAN, which specifies the displayed
velocity range in the Position-Velocity (PV) diagram panels.

.ti -4
2 SCALE
.ti +4
  CHARACTER*12 SCALE[2]

SCALE indicates the Colour Scale Range, range of image units which are
displayed in the color bitmap. A * value implies an automatic evaluation
of this range, based on the Min and Max of the data cube. Combinations
like Value * or * Value are accepted. 

For backward compatibility, SCALE = 0 0 is equivalent to SCALE = * *.

.ti -4
2 SFLUX
.ti +4
  Character*32 SFLUX

Specify the flux (intensity) range for the spectra. SFLUX can be * or 0 to indicate
a fully automatic scale, or indicate a Min Max, each of which may be * to indicate an
automatic limit.

.ti -4
2 SIZE
.ti +4
  REAL SIZE[2]

Specify the displayed are size, in ANGLE__UNIT (see SET ANGLE__UNIT command).

.ti -4
2 SPACE__TYPE
.ti +4
  CHARACTER*8 SPACE__TYPE

 Define the type of spacing for the contour levels
.nf
   LIN       Linear spacings. The Zero contour is always omitted.
   LOG       Exponential spacing
   NONE      No contour levels at all (same as DO__CONTOUR = NO)
   USER      Keep the contour levels specified by command LEVELS 
.fi
For LOG case, see HELP LEVELS EXPO in the GreG internal help.
 
As a backward compatibility, a negative spacing is a convention to use 
the current contour levels, although using SPACE__TYPE = USER
should be preferred.

.ti -4
2 SPACING
.ti +4
  CHARACTER*16 SPACING[2]
  
SPACING indicates the step (and implicitely the contour levels) for
contouring and/or greyscale. SPACING[1] control the values, and
SPACING[2] the Unit of these values. It can be UNITS (default data
cube units), NOISE or SIGMA (noise level), Jy (which also stands
for Jy/Beam) and its sub-units mJy (or milliJy) and microJy, or K and its
sub-units mK (or milliK) or microK.  

Jy (and its sub-units) is taken as equivalent to Jy/Beam,
and automatic conversion between brightness unit (K) and flux unit (Jy/Beam)
is made when the data cube has a specified angular resolution and frequency.

SPACING[1] = 0 means an automatic guess 
of the contours from the Min and Max of the data cube.

The type of spacing is controlled by  variable SPACE__TYPE.   

.ti -4
2 SPAN
.ti +4
  REAL SPAN[2]
  
For EXPLORE, SPAN indicates the limits of plot for the spectra,
in 3rd axis unit (usually Velocity, but may be Frequency).

.!======================================================================
.ti -4
1 EXTRACT
.ti +4
[DISPLAY_\]EXTRACT VarName [blc1 blc2 blc3 trc1 trc2 trc3]

  Extract a subset of the image variable VarName and put it 
in the EXTRACTED image variable.
  
  Without argument, the region covered by the subset is 
defined by the SIZE, CENTER and RANGE values. In this case, 
the EXTRACTED variable dimensions are automatically derived
from this values, and EXTRACTED can be bigger than
the actual cube defined by VarName. Areas not covered by the
initial VarName are filled out with the Blanking value of
the VarName, or by zeros if VarName has no blanking. 

  If the arguments blc1 to trc3  are  specified, the subset
corresponds to  VarName[blc1:trc1,blc2:trc2,blc3:trc3]
of the image variable VarName. The BLCi and TRCi values must 
correspond to a valid subset.


.!======================================================================
.ti -4
1 FIND
.ti +4
[DISPLAY_\]FIND Fmin Fmax [/SPECIES Name]
  
Select spectral lines in the range Fmin to Fmax (in MHz) and return
them in the LINES% structure. 

LINES%SPECIES contains the name of the species for each line.
LINES%FREQUENCY holds its frequency in MHz. 
LINES%LINES contains the full line names, including the transition.
LINES%PLOT contains the string to be used in graphic display, with
codes for superscripts and subscrips when needed.

The sign of LINES%N encodes the number of selected lines
and type of catalog which was used.

The rest of the structure depends on the catalog type.

If the catalog is in the ASTRO format, LINES%N is negative and
contains the opposite of the number of lines. 

If the catalog is in the LINEDB format (see HELP LINEDB_\ for details), 
LINE%N is positive and contains the number of selected lines. Quantum
numbers, energy levels and line strengths are also available in this 
case, allowing a more precise selection.

.ti -4 
2 /SPECIES
.ti +4
[DISPLAY_\]FIND Fmin Fmax /SPECIES Name

Only select lines from species that match the specified Name.
Only one Name can be specified, and the match is case sensitive.
There is (limited) support for wildcard so far.

.!========================================================================
.ti -4
1 INSPECT__3D
.ti +4
[DISPLAY_\]INSPECT__3D [Argument [FirstPlane [LastPlane]]]
  [/DIRECTORY NameTree]

where
.br 
Argument
.ti +4 
is the the name of a 3-D internal buffer to be plotted (BEAM, CCT, CLEAN, DIRTY,
FIELDS, MASK, etc.. ), or any Sic Image variable, or a file name.
If not present, Argument falls back to the last argument used in EXPLORE,
INSPECT__3D, SHOW, or VIEW commands.

Simultaneously display cuts along each of main cube directions, as
well as the current spectrum. Coordinates are controlled by the cursor
position in the plots.


.ti -4
2 /DIRECTORY
.ti +4
[DISPLAY_\]INSPECT__3D Argument [FirstPlane [LastPlane]] /DIRECTORY NameTree

  Display the graphics under the user specified <NameTree "graphic tree", 
instead of the usual <GREG tree. The tree is created if needed, cleared
if it already exists.

Using different "graphic trees" allows the user
to simultaneously display (the same or different) data in different ways,
as each tree inherits a specific window.

A few names should not be used as NameTree:  VSIDE, POPUP, CCT because they are
already used by some specific plotting routine.

.ti -4
2 History

INSPECT__3D is a command similar to GO 3VIEW in Mapping, but with a simpler
syntax and the ability to display program buffers as well as files.

.ti -4
2 Variables:
.ti +4

Like SHOW, VIEW and EXPLORE, INSPECT__3D is controlled by variables, selected among 
those controlling SHOW:
.ti +8 
SPAN, RANGE, SIZE, CENTER and CROSS.


.ti -4
2 SPAN
.ti +4
  REAL SPAN[2]
  
SPAN indicates the limits of 2-D plot along the velocity axis, while
RANGE indicates the 3rd axis range that is displayed in the integrated
spectrum.  The spatial dimension (if any is displayed) is controlled by SIZE and CENTER. 

If SPAN is 0, it defaults to RANGE. If RANGE is zero, all planes/channels are displayed.

.!==========================================================================

.ti -4
1 LOAD
.ti +4 
[DISPLAY_\]LOAD File [Status] [/FREQUENCY NewFreq] [/PLANES Start End] [/RANGE Start End Type] 

Read the specified (part of) File (GILDAS or FITS data cube) into the DATA
buffer, for further display by any relevant command (e.g. SHOW, VIEW, EXPLORE,
INSPECT)

The optional Status can be READ (default, buffer cannot be modified) 
or WRITE (buffer can be modified by the user through SIC). /PLANE
and /RANGE options are mutually exclusive.

.ti -4
2 /FREQUENCY
.ti +4
[DISPLAY_\]LOAD File [Status] /FREQUENCY RestFreq [/RANGE Min Max Type]

Read the file into the DATA area  and reset the velocity scale to 
the corresponding rest frequencies. Velocities specified
in the /RANGE Min Max VELOCITY option would then refer to this
new frequency.

.ti -4
2 /PLANES
.ti +4
[DISPLAY_\]LOAD File [Status] /PLANES Min Max [/FREQUENCY NewFreq]

Read only the last axis "planes" between the  First and Last implied
by Min and Max. For an LMV-ordered cube, this would be equivalent to 
.ti +4
  LOAD File /RANGE Min Max CHANNEL
.br
However, for transposed data cubes, VML or LVM-ordered for example, this is
not true at all when a Frequency/Velocity axis is present: /RANGE would
specify a subset of that axis, while /PLANES always indicate
a subset of the 3rd axis of the cube.

Min and Max indicate offsets from Plane 1 and the number of planes Nplane.
Thus Max can be negative: it then indicates Last = Nplane-Max. 
Also Min=0 and Max=0 implies loading all the channels.

.ti -4
2 /RANGE
.ti +4
[DISPLAY_\]LOAD  File [Status] /RANGE Min Max Type [/FREQUENCY NewFreq]

Load only the channels between the First and Last
defined by Min Max and Type.  Type can be
CHANNEL, VELOCITY or FREQUENCY. If the Data cube has
no Frequency/Velocity axis, only CHANNEL is allowed.

For type CHANNEL, Min and Max indicate offsets from
Channel 1 and Channel Nchan (the number of channels
in the data set). Thus Max can be negative: it then
indicates Last = Nchan-Max. Also Min=0 and Max=0 implies
loading all the channels.

The /RANGE option is not (yet) allowed for FITS files.

.!=======================================================================
.ti -4
1 POPUP
.ti +4
    DISPLAY_\POPUP [Number] 
  
  POPUP allows to "pop up" a single plane display out of a multi-box plot.  
he action driven by POPUP depends on the content of the whole plot.
  
  After a SHOW command, POPUP will call the cursor, and any key stroke (except E to
EXIT the loop) will display the corresponding sub-plot in a separate window.
The sub-plot may contain an single plane display, a spectrum, a cumulative
flux, the phase or amplitude correction from a SELFCAL, etc...
  
  POPUP Number will popup the specified panel number (counted from Top Left 
Corner down to Bottom Right corner).
  
  POPUP will have no action if the display was not created by SHOW.
 
.!=======================================================================
.ti -4
1 SET
.ti +4 
[DISPLAY_\]SET KeyWord [Value [...]] [/DEFAULT]

Set an IMAGER or GREG internal value. The only current possible keywords
for IMAGER are ANGLE__UNIT and FORMAT. Use HELP GREG_\SET for help on the Greg
keywords. This command has no impact on axes that are in Angles.

.ti -4
2 ANGLE__UNIT
.ti +4
[DISPLAY_\]SET ANGLE__UNIT [Degree|Minute|Second|Radian|ABSOLUTE|RELATIVE] 

List or Specify the angular unit and mode used for box labelling. 
The mode can be ABSOLUTE to use sexagesimal notation in Hour - Degree 
for  Right Ascension and Declination, or RELATIVE to label with
offsets in the current angle unit.

SET ANGLE__UNIT
.br
will list the current and fallback units (if any)

SET ANGLE__UNIT ABSOLUTE|RELATIVE
.br 
will toggle between ABSOLUTE labels and relative ones in the current 
angular unit. ABSOLUTE labeling is not possible if there is a
rotation angle in the images: only relative labels are used in this case,
whatever the mode specified by SET ANGLE__UNIT.

SET ANGLE__UNIT Degree|Minute|Second|Radian
.br
will set the current angle unit to the specified value, and enforce
use of offset labels in the specified unit.

.ti -4
2 FORMAT
.ti +4
[DISPLAY_\]SET FORMAT DataFormat [Specifier]

List or specify the default data format for the WRITE command.
Allowed values are FITS or GILDAS.  For FITS format, the additional
Specifier can be NATIVE, VELOCITY or FREQUENCY to indicate the 
unit of the spectral axis. The default is NATIVE, namely taking the
current spectral axis type, if not specified.

The data format can be overidden by arguments of the command WRITE.

.ti -4
2 OtherKeyword
.ti +4
[DISPLAY_\]SET OtherKeyword [Value ...]

If the SET argument is not recognized, the command falls back
to the GREG_\SET command. See HELP GREG_\SET for possibilities.

.!=======================================================================
.ti -4
1 SHOW
.ti +4
[DISPLAY_\]SHOW Argument [Arg1 [Arg2]] [/DIRECTORY NameTree]
  [/OVERLAY [Variable [Channel]] [/SIDE] 

where
.br 
Argument
.ti +4 
is a Keyword (e.g. UV, BEAM, COVERAGE, NOISE, UV__FIT or MOMENTS,
see possible list among HELP SHOW subtopics), the
name of an internal buffer to be plotted (BEAM, CCT, CLEAN, 
DIRTY, etc.. ), a 2-D or 3-D SIC image variable or datacube
filename (in Gildas or simple FITS image format).

.ti +4
[DISPLAY_\]SHOW ?
.br
will list the names of recognized keywords and buffers. 

.br 
Arg1, Arg2, ... ArgN
.ti +4
are optional arguments that depends whether Argument indicates
a 3-D cube or is another recognized Keyword. For 3-D cubes,
Arg1 and Arg2 are used to restrict the range of
channels to be plotted. They default to  FIRST and LAST variable values
respectively, and Arg2 defaults to Arg1 if only Arg1 is specified.

Command VIEW offers a different style of display for cubes, NOISE and CCT.
Command INSPECT__3D offers another style for cubes.

  The /DIRECTORY option allows to the user
to simultaneously display (same or different) data in different ways,
as each display is then affected to a different "graphic tree" that 
inherits a specific window.



.ti -4
2 /DIRECTORY
.ti +4
[DISPLAY_\]SHOW Argument [FirstPlane [LastPlane]] /DIRECTORY NameTree
  [/OVERLAY [Variable [Channel]] [/SIDE]

  Display the graphics under the user specified <NameTree "graphic tree", 
instead of the usual <GREG tree. The tree is created if needed, cleared
if it already exists.

Using different "graphic trees" allows the user
to simultaneously display (same or different) data in different ways,
as each tree inherits a specific window.

A few names should not be used:  VSIDE, POPUP, CCT because they are
already used by some specific plotting routine.

.ti -4
2 /OVERLAY
.ti +4
[DISPLAY_\]SHOW Argument [First [Last]] /OVERLAY [Variable [Channel]]
 [/DIRECTORY NameTree] [/SIDE] 
  
Overlay (in contours) the specified Channel of the SIC 2 or 3-D Variable.  
The default Variable is CONTINUUM, the continuum
image. If Variable is a 3-D SIC Variable, Channel indicates which plane
is overlaid (default: last one).  The /OVERLAY option de-activates
the contouring of the Argument data, by temporarily setting DO__CONTOUR
to NO. 

In addition to this overlay, the user can add any display on the 
channel maps by a command to be executed through the OVERLAY__COM variable.
This command can be the execution of a script, e.g.
.ti +8
  LET OVERLAY__COM "@ draw__my__markers" 
.br
or
.ti +8
  LET OVERLAY__COM "@ p__beam clean" 
.br
to plot the clean beam.

Note that this variable is not defined by default, so must be defined
.ti +8 
.br
  DEFINE Char*80 OVERLAY__COM /GLOBAL
.br
when needed

.ti -4
2 /SIDE
.ti +4
[DISPLAY_\]SHOW Arg [FirstPlane [LastPlane]] /SIDE [/DIRECTORY NameTree]
  [/OVERLAY [Variable [Channel]]

  Add the <VSIDE display of coordinates and values like in the VIEW
command, and loop on the Graphic cursor to explore the data.

  This will be the default mode if variable SHOW__SIDE is set to YES.

.ti -4
2 Cube
.ti +4
[DISPLAY_\]SHOW Cube [FirstPlane [LastPlane]] /DIRECTORY NameTree
  [/OVERLAY [Variable [Channel]] [/SIDE]

  where Cube is the name of a 3-D SIC variable, Gildas data or FITS file name, will
display a per-plane view of the data cube, restricted to the channel
range specified by FirstPlane and LastPlane (default all, or
only FirstPlane if no LastPlane is given).

.ti -4
2 History
.ti +4 
SHOW derives from the GO PLOT script available in GreG and Mapping.
GO PLOT (or its variants GO BIT, GO NICE and GO MAP) and GO UVSHOW 
offered similar features to those of SHOW, but take data from files 
or SIC image variables, depending on variables NAME and TYPE.

.ti -4 
2 Keywords:

SHOW recognizes the following specific keywords
.nf
  BEAM        Synthesized beam(s)
  CCT         Clean Cumulative Flux
  COMPOSITE   0th,1st,2nd moments + Integrated spectrum
  COVERAGE    UV Coverage
  FLUX        Integrated spectra over defined regions
  INTENSITY   Like NOISE, but in LOG scale
  KEPLER      Radial profile and PV diagram of a Keplerian disk
  MOMENTS     0th,1st,2nd moments + peak value
  MOSAIC      Display Mosaic characteristics
  NOISE       per channel noise distribution
  PRIMARY     Primary beam(s) 
  PV          Position-Velocity plot
  SED         Spectral Energy Distribution 
  SELFCAL     Self-Calibration corrections
  SNR         Signal to noise (for Mosaics)
  SOURCES     Clean component positions
  SPECTRA     Spectra on a 2-D map-like grid
  STATISTIC   Like INTENSITY, and also updates the %rms Noise value
  UV          UV data
  UV__FIT      Results of the UV__FIT command
.fi

SHOW calls the appropriate procedures for each action
.nf
  p__show__map       for data cubes
  p__show__beam      for BEAM and PRIMARY cubes
  p__show__cct       for CCT (Clean Component Tables)
  p__show__composite for Composite display (Moments + Flux)
  p__show__flux      for FLUX
  p__show__moments   for MOMENTS 
  p__show__noise     for NOISE
  p__lmv__map        for PV 
  p__show__sed       for SED
  p__show__selfcal   for SELFCAL
  p__show__tcc       for SOURCES (Clean Component Positions)
  p__spectra        for SPECTRA
  p__uvshow__sub     for UV__DATA data
  p__plotfit        for UV__FIT data (UV__FIT results)
.fi

.ti -4
2 BEAM
.ti +4
  SHOW BEAM [PLANE|FIELD Kn] [First Last]

Show some sub-cube of the (up to 4-D) dirty Beam.

The 2nd argument indicates whether SHOW shows all Fields for a
given frequency plane (PLANE keyword), or all Frequency-dependent
beams for a given Field. The 2nd and 3rd arguments are optional if 
the beam is only 3-D, which occurs for a single field or a
frequency-indepedent beam in Mosaics (narrow band approximation).


.ti -4
2 CCT
.ti +4
SHOW CCT 

Display the Cumulative Clean Flux as function of component
number. Pretty useful to see if CLEAN has reasonably converged.

VIEW CCT is a more compact alternative.

.ti -4
2 COMPOSITE
.ti +4
SHOW COMPOSITE [WIDTH|PEAK]
    
Display the 3 "moments" images derived from a datacube by command MOMENTS,
and the integrated line flux computed by command FLUX.
The contour spacing for each image is controlled by its own variable:
.nf
AREA__SPACING   for the integrated area  M__AREA
PEAK__SPACING   for the peak brightness M__PEAK (in K)
VELO__SPACING   for the Velocity field M__VELO (in km/s)
WIDTH__SPACING  for the Width field M__WIDTH (in km/s)
.fi

As for other image displays, CENTER and SIZE control the center
and size of the image (in arcsec). Limits for the Flux spectrum
are computed automatically.

The 3 selected moments are AREA, VELO and either PEAK or WIDTH
according to the 2nd argument (sticky value).

.ti -4
2 CONTINUUM
.ti +4
SHOW CONTINUUM

Display the "continuum" map, i.e. the map obtained by UV__MAP /CONTINUUM
and CLEAN, or by the MAP__CONTINUUM command.

.ti -4
2 COVERAGE
.ti +4
SHOW COVERAGE [Ant [Date]]

Displays the UV coverage.
Ant and Date are optional arguments indicating which Antenna
is to be highlighted, and for which date. Date is a sequential
number from 1 to the number of observing dates.

For spectral line UV data, SHOW COVERAGE will only show one
UV coverage if FIRST and LAST are set to zero. It will show one
per channel otherwise.

.ti -4
2 FIELDS
.ti +4
SHOW FIELDS

Display the positions of the fields in a Mosaic, by a
circle at the half-power primary beam size. 

Note that this information can also be overlaid to a 
normal (per-plane) SHOW display by setting DO__FIELDS = YES.

.ti -4
2 FLUX
.ti +4
SHOW FLUX [FirstRegion [LastRegion]]

Displays the integrated spectra in regions used by  
command FLUX. FirstRegion and LastRegion may be
used to specify the range of regions displayed.

.ti -4
2 INTENSITY
.ti +4
SHOW INTENSITY [VarName]

Compute and display the intensity distribution of the specified SIC variable,
in logarithmic scale, and fit a Gaussian to the histogram of pixel intensities
per channel. VarName  must be the name of a 2-D or 3-D SIC image
variable.

If no VarName is specified, the last displayed image (by SHOW or VIEW)
is used. If none was ever displayed, SHOW selects among SKY, CLEAN and DIRTY
images in this priority order.  Variable SCALE (if non zero) is used
to define the displayed intensity scale.

See SHOW STATISTIC for a variant that updates the VarName%rms noise value in the
header. 

See SHOW NOISE for a linear scale equivalent.

.ti -4
2 KEPLER
.ti +4
SHOW KEPLER [ALl|BOth|PV|PRofile|SPectrum]

Displays the results of the KEPLER command, which can be
.nf
  PV              Position (radius) Velocity plot
  PRofile         Peak intensity radial profile
  SPectrum        Integrated spectrum
  BOth            Radial Profile and Integrated spectrum
  ALl             All of the above
.fi
Other combinations are allowed using the KEPLER__SHOW%PROF,
KEPLER__SHOW%PV and KEPLER__SHOW%SPEC variables.

Display ranges are controlled by variables KEPLER__SHOW%X, where
X = V for the velocity range, X = T for the temperature profile
range, X = R for the radius range, and X = F for the integrated
flux range.

.ti -4
2 MOMENTS
.ti +4
SHOW MOMENTS
  
Display the 4 "moments" images derived from a datacube by command MOMENTS.
The contour spacing for each image is controlled by its own variable:
.nf
AREA__SPACING   for the integrated area  M__AREA
PEAK__SPACING   for the peak brightness value M__PEAK (in K)
VELO__SPACING   for the Velocity field M__VELO (in km/s)
WIDTH__SPACING  for the Width field M__WIDTH (in km/s)
.fi

As for other image displays, CENTER and SIZE control the center
and size of the image (in arcsec). 

.ti -4
2 MOSAIC
.ti -4
SHOW MOSAIC

List the mosaic characteristics.
.ti -4
2 NOISE
.ti +4
SHOW NOISE [VarName [Rms]]

Compute and display the noise statistic of the specified SIC variable,
using a Gaussian fit to the histogram of pixel intensities
for each channel. VarName  must be the name of a 2-D or 3-D SIC image
variable.

If no VarName is specified, the last displayed image (by SHOW or VIEW)
is used. If none was ever displayed, SHOW selects among SKY, CLEAN and DIRTY
images in this priority order.

If specified, Rms indicates the expected rms noise of the data, which
is otherwised taken from the data itself. It is used to automatically scaled
the display to provide a good sampling of the noise distribution.

See SHOW INTENSITY for a Log scale equivalent.
.ti -4
2 PRIMARY
.ti +4
  SHOW PRIMARY [PLANE|FIELD Kn] [First Last]

Show some sub-cube of the (4-D) Primary Beams.

The 2nd argument indicates whether SHOW shows all Fields for a
given frequency plane (PLANE keyword), or all Frequency-dependent
beams for a given Field (FIELD keyword). The 2nd and 3rd arguments are optional if 
the beam is only 3-D, which occurs for a single field or a
frequency-indepedent beam in Mosaics (narrow band approximation).

.ti -4
2 PV
.ti +4
SHOW PV [[VarName] Axis Offset]

Extract from the indicated 3-D SIC variable a Position-Velocity image at the 
specified Offset (in arcsec) along the specified Axis (X or Y), and display it.

The data cube variable name VarName is optional: the last displayed among SKY, CLEAN and DIRTY
data cubes are used in this priority order.

.ti +4 
SHOW PV  

will simply redisplay (with different controls, see SHOW PV ? to have a list)
the last extracted Position-Velocity image.


.ti -4
2 SED
.ti +4
  SHOW SED [Frequency [FileName]] 

Display the SED, computed by the "SED" widget from images (using the FLUX command) 
or from UV Tables (by fitting a simple model using UV__FIT), and fit a simple
power law model through it.

Frequency is the reference frequency in GHz at which the flux is computed.

FileName is the data file produced by the "SED" widget.

If Frequency or Filename are not specified, their last values are re-used. 


.ti -4
2 SELFCAL
.ti +4

  See HELP SELFCAL SHOW, and/or use SHOW SELFCAL ?
  
.ti -4
2 SNR
.ti +4
SHOW SNR 

Display the Signal to Noise ratio map of a Mosaic.

.ti -4
2 SOURCES
.ti +4
SHOW SOURCES [First [Last]]

Display the "point sources" found by CLEAN at their positions,
using a marker with area proportional to their flux. Positive
sources are in black, negative ones are in red.

The displayed zone is controlled by variables SIZE and CENTER, as
for in SHOW CLEAN  or SHOW DIRTY. However, when SIZE is 0, the
displayed zone is set to  the minimum required to display all point 
sources detected by CLEAN. It may thus differ from the CLEAN map size.

.ti -4
2 SPECTRA
.ti +4
SHOW SPECTRA Clean|Dirty|Sky|ImageVar

Display individual spectra in a Map-like display (one per box, placed
at their respective positions) from a 3-D SIC variable, assumed
to be in the LMV order.

Control parameters: The displayed region and sampling are controlled by
variables CENTER and SIZE, and the 3-elements arrays XPIX and YPIX.
XPIX[3] gives the stpe (in pixels) between displayed spectra in X (resp in Y);
if 0,  a default step is guessed from the angular resolution and pixel size.
CENTER and SIZE select the displayed region. If zero, XPIX[1:2] give the 
first and last pixels along X (resp Y). If still zero, the inner quarter
is displayed.

RANGE indicate the displayed velocity range.  The spectra scale can be controlled by string 
BOX__LIMITS.

Note: the second argument may be omitted to re-display the same
dataset with different control parameters. SHOW SPECTRA is however not
fully protected against changes in the data set between two invocations,
so this should only be used for consecutive commands.

.ti -4
2 STATISTIC
.ti +4
SHOW STATISTIC [VarName]

Compute and display the intensity distribution of the specified SIC variable,
in logarithmic scale, and fit a Gaussian to the histogram of pixel intensities
per channel. VarName  must be the name of a 2-D or 3-D SIC image
variable.

If no VarName is specified, the last displayed image (by SHOW or VIEW)
is used. If none was ever displayed, SHOW selects among SKY, CLEAN and DIRTY
images in this priority order.  Variable SCALE (if non zero) is used
to define the displayed intensity scale.

This command is equivalent to SHOW INTENSITY, but in addition it updates
the VarName%rms value to indicate the computed noise in the data.


.ti -4
2 UV__DATA
.ti +4
SHOW UV__DATA [Ant [Date]]
.ti +4
SHOW UV [Ant [Date]]

Displays the UV data. The UV data in the internal buffer is the one loaded by command
READ UV File and optionally resampled by UV__RESAMPLE, UV__COMPRESS, etc..., or
transformed by UV__CONTINUUM. Flagged UV data  will appear in a different color.

Items to be displayed are controlled by XTYPE and YTYPE variables.

Ant and Date are optional arguments indicating which Antenna
is to be highlighted, and for which date. Date is a sequential
number from 1 to the number of observing dates.

Structure uvshow% controls some additional options, such
as coloring of various dates, of data flagging, etc...

.ti -4
2 UV__FIT
.ti +4
SHOW UV__FIT [? | RESET]

Display the UV__FIT results. The display is controlled by the
UVF% structure. 

SHOW UV__FIT ? will list the current values
of these control parameters. 

SHOW UV__FIT RESET  
will reset all control variables (UVF% structure) to their
default values.

The number and order of the fitted functions to be plotted are
controlled by UVFIT%NF and UVFIT%ORDER

The number of parameters to be plotted along X and Y axes are controlled
by UVFIT%NX, UVFIT%NY. The kinds and ranges of those parameters are 
coded in the UVFIT%XTYPE and UVFIT%YTYPE strings (e.g. kind min max).
Possible kinds are: CHANNEL VELO FREQ RMS RA DEC FLUX  WIDTH MAJOR MINOR
ANGLE and RATIO. A * instead of min and/or max implies the use of the default
minimum and maximum values of the plotted parameter.


.ti -4
2 Variables:
.ti +4
    SHOW Image  control variables

The following variables control the SHOW display. 
.nf 
  Display the header     DO__HEADER   [ YES ]   
  Display a color wedge  DO__WEDGE    [ YES ]     
  Plot bitmaps           DO__BIT      [ YES ]         
  Add the clean beam     DO__NICE     [ NO ]     
  Add the UV coverage    DO__COVERAGE [ NO ]  
  Add the dirty beam     DO__DIRTY    [ NO ]     
  Display the labels     DO__LABEL    [ YES ]     
  Display contour levels DO__CONTOUR  [ YES ] 
  grey-scale contours    DO__GREY     [ NO ] 
  Better marks           DO__MASK     [ NO ]           (Hide image behind channel marks)
 
  Channel range          RANGE       [ 0 0 ]         in 3rd axis unit, (0,0) ==> all
  Channel label          MARK        [ velocity ]    [VELOCITY, FREQUENCY or CHANNEL]
  Displayed field size   SIZE        [ 0 0 ]         in ANGLE__UNIT
  Field center           CENTER      [ 0 0 ]         offset in ANGLE__UNIT
  Cross size at center   CROSS       [ 2 ]           in arcsec, 0 ==> none 
  Fields layout          DO__FIELDS   [ NO ]          (for Mosaics)
 
  Colour Scale range     SCALE       [ 0 0 ]         (0,0) ==> all dynamic
  Contour levels         SPACING     [ 0 Units]      (0) =+> Guess
  Spacing type           SPACE__TYPE  [ AUTO]  [LIN, LOG or USER]
  Side Display           SHOW__SIDE  [ NO ]
.fi

SHOW also uses the (user-defined, optional) variable 
.nf
overlay__com       " " Command to be executed to add informations on Maps.
.fi

.ti -4
2 BOX__LIMITS
.ti +4
  CHARACTER*60 BOX__LIMITS
  
If not void, this character string must indicate the 4 limits of each panel display,
for example 
.ti +8  
  LET BOX__LIMITS "* * -5 10"

If void, variables SIZE and CENTER are used instead.

.ti -4
2 DO__BIT
.ti +4
  LOGICAL DO__BIT
  
Show a bitmap color plot (YES) or do not (NO) for each panel.
The bitmap range is controlled by variable SCALE.

.ti -4
2 DO__CONTOUR
.ti +4
  LOGICAL DO__CONTOUR

Draw (YES) or do not (NO) draw the contour level, which are controlled
by SPACING and SPACE__TYPE. This is provided for compatibility
with Mapping and Greg.

.ti -4
2 DO__COVERAGE
.ti +4
  LOGICAL DO__COVERAGE
  
For SHOW DIRTY or SHOW CLEAN, DO__COVERAGE indicates if in addition
to the channel maps, the UV coverage should be displayed in another
panel.

.ti -4
2 DO__DIRTY
.ti +4
  LOGICAL DO__DIRTY
  
For SHOW DIRTY or SHOW CLEAN, DO__DIRTY indicates if in addition
to the channel maps, the dirty beam should be displayed in another
panel.

.ti -4
2 DO__FIELDS
.ti +4
  LOGICAL DO__FIELDS

  Plot the 50 % contour levels of the individual pointings in a Mosaic
on top of the maps.

.ti -4
2 DO__GREY
.ti +4
  LOGICAL DO__GREY 

Do (YES) or do not (NO) use grey-scale contouring. Note that this
is independent of DO__CONTOUR.

.ti -4
2 DO__HEADER
.ti +4
  LOGICAL DO__HEADER
  
DO__HEADER indicates whether a panel displaying a summary information
about the displayed data is drawn or not.

.ti -4
2 DO__LABEL
.ti +4
  LOGICAL DO__LABEL
  
DO__LABEL indicates if the axes should be labelled.

.ti -4
2 DO__MASK
.ti +4
  LOGICAL DO__MASK
  
Hide part of the plot (contour or bitmaps, and even axis ticks) that lie
in the upper left corner of each panel to have a clean display of the
value specified by MARK.

.ti -4
2 DO__NICE
.ti +4
  LOGICAL DO__NICE
  
DO__NICE indicates if the angular resolution of the data ("beam") should
be displayed in the lower left corner of each panel.

.ti -4
2 DO__WEDGE
.ti +4
  LOGICAL DO__WEDGE
  
DO__WEDGE indicates whether a color wedge of the bitmaps is drawn or not. 
It appears in the Header panel, so DO__WEDGE is active only if DO__HEADER
and DO__BIT are set.

.ti -4
2 CENTER
.ti +4
  REAL CENTER[2]

Specify the relative coordinates of the center of the displayed
region, in ANGLE__UNIT (as specified by SET ANGLE__UNIT). 

.ti -4
2 CROSS
.ti +4
  REAL CROSS

Indicate the size (in arcsec) of a cross to be drawn at the map projection
center, as a reference marker for relative positions. If 0, no cross is
drawn. 

If CROSS is non 0 and a script "my__cross.ima" is in the current
directory, this script is executed instead of drawing a simple cross.
This allows to display for example minor and major axes of inclined disks.
A generic example of such a script is available in
.ti +8
  gag__demo:my__cross.ima
.br
It can be tailored by controlling the variables in the mycross% structure.  

.ti -4
2 MARK
.ti +4
  CHARACTER*12 MARK
  
Specify the type of labelling for each panel. It can be 
VELOCITY, FREQUENCY or CHANNEL. Case is not significant.

.ti -4
2 RANGE
.ti +4
  REAL RANGE[2]
  
Specify the range (in 3rd axis unit) of displayed channels. This
provides a facility similar to FIRST and LAST variables, but in a
more user-oriented unit.

RANGE should not be confused with SPAN, which specifies the displayed
velocity range when one of the 2 first axis is of type Velocity, e.g.
for SHOW PV

.ti -4
2 SCALE
.ti +4
  REAL SCALE[2]
  
SCALE indicates the Colour Scale Range, range of image units which are 
displayed in the color bitmap. SCALE = 0 implies an automatic evaluation 
of this range, based on the Min and Max of the data cube.

.ti -4
2 SIZE
.ti +4
  REAL SIZE[2]

Specify the displayed are size, in ANGLE__UNIT. 

.ti -4
2 SPACE__TYPE
.ti +4
  CHARACTER*8 SPACE__TYPE

 Define the type of spacing for the contour levels
.nf
   LIN       Linear spacings. The Zero contour is always omitted.
   LOG       Exponential spacing
   NONE      No contour levels at all (same as DO__CONTOUR = NO)
   USER      Keep the contour levels specified by command LEVELS 
.fi
For LOG case, see HELP LEVELS EXPO in the GreG internal help.
 
As a backward compatibility, a negative spacing is a convention to use 
the current contour levels, although using SPACE__TYPE = USER
should be preferred.

.ti -4
2 SPACING
.ti +4
  CHARACTER*16 SPACING[2]
  
SPACING indicates the step (and implicitely the contour levels) for
contouring and/or greyscale. SPACING[1] control the values, and
SPACING[2] the Unit of these values. It can be UNITS (default data
cube units), NOISE or SIGMA (noise level), Jy (which also stands
for Jy/Beam) and its sub-units mJy (or milliJy) and microJy, or K and its
sub-units mK (or milliK) or microK.  

Jy (and its sub-units) is taken as equivalent to Jy/Beam,
and automatic conversion between brightness unit (K) and flux unit (Jy/Beam)
is made when the data cube has a specified angular resolution and frequency.

SPACING[1] = 0 means an automatic guess 
of the contours from the Min and Max of the data cube.

The type of spacing is controlled by  variable SPACE__TYPE.   
 
.ti -4
2 SPAN
.ti +4
  REAL SPAN[2]
  
SPAN indicates the limits of plot along the velocity axis, when one of the
plotted dimensions is Velocity. In particular, SPAN is used for SHOW PV.
The spatial dimension (if any is displayed) is controlled by SIZE and CENTER. 

Note that SPAN differs from RANGE: RANGE controls the range of 
planes displayed for a 3-D cube. 

.ti -4
2 SHOW__COLOR
.ti +4
  REAL  SHOW__COLOR
  
  If non zero, force the color scale to use the COLOR SHOW__COLOR
  command automatically in order to have a Look-Up-Table that is white
  (or black is SHOW__COLOR is negative) around 0 to visually attenuate
  the contrast around the noise level.
  
  A value of 8 to 24 is in general appropriate.
  
.ti -4
2 SHOW__NX
.ti +4
  INTEGER SHOW__NX
  
  If non zero, SHOW will display SHOW__NX panels along the X axis.
  The area used in this case is the whole page, and no Header is displayed
  (as if DO__HEADER was false).
  
  This can be convenient to prepare a publication quality plot that
  span the whole page width (for Landscape format) or a full column
  (for double column articles, using a Portrait format).

.ti -4
2 SHOW__SIDE
.ti +4
  LOGICAL SHOW__SIDE
  
  Controls whether the Side Display is active by default or not.
  Option /SIDE can be used to overcome this default value.

.!===========================================================================


.ti -4
1 SLICE
.ti +4
[DISPLAY_\]SLICE VarName Start1 Start2 End1 End2 UNIT

  Cut a slice through the 3-D image variable VarName with the specified 
end points. UNIT is a keyword indicating in which units the end ponts
coordinates are specified. It can be PIXELS, 
DEGREE, MINUTE, SECOND, RADIAN, of ABSOLUTE.  For ABSOLUTE, Start1 and 
End1 are assumed to be in hours and Start2 End2 in degrees, with 
sexagesimal notation allowed. 

.ti +4
[DISPLAY_\]SLICE VarName StartX StartY Unit ANGLE AngleValue

  This alternate syntax allows to specify a starting point and an orientarion
of the slice. The coordinates StartX StartY are in the angular unit
specified by Unit (which can be ABSOLUTE) AngleValue is in Degree.
The Slice length will be automatically computed to intersect the whole cube.
This syntax can be more convenient to compare parallel slices, or slices
intersecting at a common point that can be specified by StartX StartY.

.ti +4
[DISPLAY_\]SLICE 

  This simple syntax will call the cursor IF and ONLY IF the current
display is that of a single plane (a pure 2-D array or one plane of  3-D
array). The start and end point can then be defined interactively.

In all case, the result is available in the SLICED image variable, and 
can be displayed by SHOW SLICED.

.!===========================================================================
.ti -4
1 SPECTRUM
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] 
      [/CORNER Imin Imax Jmin Jmax] [/PLANE First Last]  /MEAN  or  /SUM

Compute a Spectrum, stored in variable OutSpec from an input data cube 
stored in variable InCube, by summing (if /SUM is present) or averaging 
(if /MEAN is present). OutSpec must be an 
existing Real array of size equal to the number of selected channels.

The 2-D region overwhich the summation runs is determined by the following
rules:
.nf
  - the mask contained in variable MaskName if specified
  - the region enclosed by the current GreG polygon is any
  - the whole 2-D region otherwise
.fi
The region is further restricted by the corners specified by option /CORNER.

 
.ti -4
2 /CORNER
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] /CORNER Imin Imax Jmin Jmax
  [/PLANE First Last]  /MEAN or /SUM

  Restricts the computation to the specified 2-D region of the data cube.
One of the mutually exclusive options /MEAN or /SUM must be present.

.ti -4
2 /MEAN
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] /MEAN
  [/CORNER Imin Imax Jmin Jmax] [/PLANE First Last]

  Indicates that we are computing a Mean spectrum.
  The spectrum is the average spectrum accounting for all valid pixels
  defined by the selection.
  
  /MEAN is exclusive of /SUM.
  
.ti -4
2 /PLANE
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask]  /PLANE First Last
  [/CORNER Imin Imax Jmin Jmax] /MEAN  or  /SUM

  Restricts the spectrum to the specified channels of the data cube.
One of the mutually exclusive options /MEAN or /SUM must be present.

.ti -4
2 /SUM
.ti +4
[DISPLAY_\]SPECTRUM OutSpec InCube [Mask] /SUM
  [/CORNER Imin Imax Jmin Jmax] [/PLANE First Last]

  Indicates that we are computing an integrated spectrum. The result 
  corresponds to the integral of the signal over the valid area (sum of 
  values times the pixel size in user units).

  /SUM is typically used to compute integrated flux from Jy/Beam
  units. /SUM is exclusive of /MEAN.

.\"====================================================================

.ti -4
1 STATISTIC
.ti +4
[DISPLAY_\]STATISTIC [DataCube [FirstPlane [LastPlane]] 
  [/EDGE Margin] [/NOISE VarNoise [ONLY]] 

Compute some basic statistics (min, max, mean, rms,...) on the specified
DataCube buffer (default: CLEAN) and planes (default: variables FIRST and LAST). 
The current polygon or mask (see commands SUPPORT and MASK) is used 
to define the area on which the pixels are to be taken into account, 
except when /EDGE 0 is mentionned.

In addition to Min and Max, the command prints 3 noise numbers: 
.nf
- the rms inside the current support (whose value depends on the source 
strength and structure)
- the rms outside of the support (a good estimate of the effective 
noise), returned in variable STAT__NOISE. 
- the theoretical thermal noise (that would be the expected noise unless
the data is dynamic range limited, or unless the weights were
not set properly)
.fi

For primary-beam corrected images (SKY), the noise is non uniform.
In this case, the rms outside the support is actually derived through 
a Gaussian fit to the intensity histogram, whose shape is non-Gaussian
as larger noise happens at mosaic edges. This is a better approximation
on the rms noise towards the mosaic center.


.ti -4
2 /NOISE
.ti +4
[DISPLAY_\]STATISTIC [DataCube [FirstPlane [LastPlane]] 
  [/EDGE Margin] /NOISE VarNoise [ONLY]
  
Return the rms noise in the specified VarNoise SIC real scalar variable.
The rms noise is also available in variable STAT__NOISE, and if the
image is the CLEAN (resp. SKY) image, in CLEAN%NOISE (SKY%NOISE) as 
well for further convenience and use in scripts.

Keyword ONLY is reserved for specific internal use: it instructs
STATISTIC command to only use the simple rms derivation on SKY images,
rather than the more elaborate fitting of the intensity distribution.

.ti -4
2 /EDGE
.ti +4
[DISPLAY_\]STATISTIC [DataCube [FirstPlane [LastPlane]] 
  /EDGE Margin [/NOISE VarNoise] 

Define the size of the "edges" that are avoided in the statistic 
estimate. Margin is a number in range [0,0.5[ . Default is 1/16.

Margin 0 means considering the whole image, ignoring mask and supports.

.!===========================================================================
.ti -4
1 VIEW
.ti +4
[DISPLAY_\]VIEW Argument [FirstPlane [LastPlane]] [/NOPAUSE] 
[/OVERLAY [...]] [/DIRECTORY TreeName]


where (in the most general case, see details for specific Keywords)
.br Argument
.ti +4 
is the the name of an internal buffer to be plotted (BEAM, CCT, CLEAN, DIRTY,
FIELDS, MASK, etc.. ), or any Sic Image variable, or a file name.

.ti +4
[DISPLAY_\]VIEW ?

will list the names of recognized keywords. If Variable
is not one of the recognized keywords, but an existing
Image variable, this image will be displayed.

.br 
FirstPlane and LastPlane
.ti +4
are optional arguments to restrict the range of
channels to be plotted (default: planes between variables FIRST
and LAST). If only FirstPlane is specified, SHOW only that plane.

VIEW is also controlled by a set of variables, available in the View% 
global structure. VIEW shows 4 (or 6) panels, representing the
Integrated area, the current channel, and the Integrated spectrum and
the current spectrul (in possibly 2 different scales). An interactive
control of the View is possible using the cursor, unless the /NOPAUSE
option is given.

The spectral panels can display line identifications based
on the current CATALOG. If a variable REDSHIFT exists, the frequency 
scale is corrected for the source Redshift, so that line identification
remains possible.


.ti -4
2 /DIRECTORY
.ti +4
[DISPLAY_\]VIEW Argument [FirstPlane [LastPlane]] /DIRECTORY NameTree
 [/NOPAUSE] [/OVERLAY [...]]

  Display the graphics under the use specified <NameTree "graphic tree", 
instead of the usual <GREG tree. The tree is created if needed, cleared
if it already exists.

Using different "graphic trees" allows the user
to simultaneously display (same or different) data in different ways,
as each tree inherits a specific window.

A few names should not be used:  VSIDE, POPUP, CCT because they are
already used by some specific plotting routine.

.ti -4
2 /NOPAUSE
.ti +4
[DISPLAY_\]VIEW Argument [FirstPlane [LastPlane]] /NOPAUSE
 [/DIRECTORY NameTree] [/OVERLAY [...]]
  Just display the panels as currently defined, without looping 
with the Graphic cursor for interactive view.

  This will be the default mode if variable DO__LOOP is set to NO.

.ti -4
2 /OVERLAY
.ti +4
[DISPLAY_\]VIEW Argument [First [Last]] /OVERLAY [Variable [Channel]]
 [/DIRECTORY NameTree] [/NOPAUSE] 
  
Overlay (in contours) the specified Channel of the specified SIC 2 or 
3-D Variable.  The default Variable is CONTINUUM, the continuum
image. If Variable is a 3-D SIC Variable, Channel indicates which plane
is overlaid (default: last one).

In addition to this overlay, the user can add any display on the 
two map plots (current channel and integrated area) by specifying
a command to be executed through the OVERLAY__COM variable.
This command can be the execution of a script, e.g.
.ti +8
  LET OVERLAY__COM "@ draw__my__markers" 
.br
or
.ti +8
  LET OVERLAY__COM "@ p__beam clean" 
.br
to plot the clean beam.

Note that this variable is not defined by default, so must be defined
.ti +8 
.br
  DEFINE Char*80 OVERLAY__COM /GLOBAL
.br
when needed

.ti -4
2 Keys

Position-independent actions:
.nf
  Press E key: EXIT loop
  Press H key: HELP display
  Press P key: PRINT plot in "ha" subdirectory
  Press Q key: QUIT loop
  Press X key: EXTRACT on disk current zoomed region
  Press N key: Toggle  Narrow - Wide mode 
.fi

Cursor on images:
.nf
  Left  clic: Display spectrum at pointed position
  Right clic: Define a polygon
  Press B key: BACK to full field of view
  Press C key: COORDINATES toggled from absolute to relative and back
  Press M key: Display MASK if any
  Press S key: SLICE definition (velocity-position)
  Press U key: UNKILL pointed pixel
  Press Z key: ZOOM defined spatial region
  Press V key: Display map coordinates at current position 
  Press W key: WRITE Integrated Area image
.fi
Cursor on spectra:
.nf
  Left clic in Selected   Spectrum: Display selected velocity channel
  Left clic in Integrated Spectrum: Define velocity range
  Press B key: BACK to full velocity range
  Press C key: COORDINATES toggled from freq/velo to channels and back
  Press L key: LABEL spectral Lines
  Press M key: MOVIE  
  Press Z key: ZOOM defined velocity region
  Press W key: WRITE Integrated (and current) Spectrum
.fi
Cursor outside plots:
.nf
  Press B key: BACK to full velocity range AND full field of view
.fi

Returned values are found in iview%current structure. The
ZOOM action produces a sub-cube named EXTRACTED.  The SLICE action produces
a 2-D data set named SLICED. As any other SIC Image variable, EXTRACTED
and SLICED can be written on disk using command WRITE.

.ti -4
2 Scripts

The VIEW plot is done by procedure p__view__cct for Clean Components CCT
and p__view__sub for data cubes. 

.ti -4
2 Variables

VIEW uses the SHOW control variables SIZE, CENTER, RANGE and CROSS. 
In addition, it has its own control variables
.nf
iview%expand       0.8 Character and Tick expansion factor
iview%contour      NO  Contour the current channel map
iview%movie        0   Elapsed time in seconds for a movie (0 means guess)
iview%side         YES Display values in side Window
iview%status%rima  NO  Relative coordinates in Images
iview%status%rspe  NO  Relative coordinates in Spectra
.fi
and the (user-defined, optional) 
.nf
overlay__com       " " Command to be executed to add informations on Maps.
.fi

.ti -4
2 Keywords:
.ti +4

VIEW recognizes the following keywords
.nf
  BEAM        Synthesized beam(s)
  CCT         Clean Cumulative Flux
  CLEAN, DIRTY, SKY   Usual sky maps
  NOISE       per channel noise
  PRIMARY     Primary beams
.fi
or any other 3-D SIC variable.

VIEW falls back to SHOW for un-recognized keywords, such as MOMENTS,
COMPOSITE, UV, etc...

.ti -4
2 BEAM
.ti +4
  VIEW BEAM [PLANE|FIELD Kn] 

View some sub-cube of the (up to 4-D) dirty Beam.

The 2nd argument indicates whether VIEW shows dirty beams
of all Fields for a given frequency plane (PLANE keyword), or all 
Frequency-dependent beams for a given Field. 

The 2nd and 3rd arguments are optional if 
the beam is only 2-D or 3-D, which occurs for a single field or a
frequency-independent beam in Mosaics (narrow band approximation).

.ti -4
2 PRIMARY
.ti +4
  VIEW PRIMARY [PLANE|FIELD Kn] 

View some sub-cube of the (up to 4-D) primary Beams.

The 2nd argument indicates whether VIEW shows all Fields for a
given frequency plane (PLANE keyword), or all Frequency-dependent
beams for a given Field. 

The 2nd and 3rd arguments are optional if 
the beam is only 2-D or 3-D, which occurs for a single field or a
frequency-independent beam in Mosaics (narrow band approximation).






.ti -4
1 ENDOFHELP
