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

.nf
CHANGE      : Change some attributes of the plot.
CLEAR Arg   : Clear (some parts of) the plot or windows.
COMPRESS    : Remove invisible parts of the plot.
CREATE Arg  : Create directory, windows or LUTs.
DESTROY Arg : Destroys (some parts of) the plot or windows.
DEVICE      : Open the graphic device.
DISPLAY     : List some parameters of the plot.
GTV SEARCH  : Search for a GTV directory.
HARDCOPY    : Get a printed copy of the plot.
LENS        : Call the lens on the active window.
LUT [arg]   : Change the color Look-Up-Table.
METACODE    : Save or load part of the plot to/from metacode file.
REFRESH     : redraw all or some windows
REPLICATE   : Copy a directory to another place.
ZOOM        : Zoom on the plot (possibly in another window).
.fi
.\"====================================================================
.ti -4
1 CHANGE
.ti +4
[GTVL_\]CHANGE Item SegName Value [Val2 [Val3]]
.ti +4
[GTVL_\]CHANGE Behaviour Value

Changes some attribute of the Graphic Library. Two items concern the
current directory and active windows:
.in +6
.ti -4
-_ CHANGE_ DIRECTORY_ [DirName [WinNum]]
.br
changes the default directory to DirName (default is to change to the
top directory), and optionally the active window number to WinNum
(instead of 1) within this directory. The current working directory is
stored as a character string in the SIC variable GTV%PWD.
.ti -4
-_ CHANGE_ WINDOW_ WinNum|ZOOM
.br
changes the active window number to WinNum or to the ZOOM window. The
active window is in particular the one in which the cursor appears for
commands which use it.
.in -6

Some other items are image segment attributes:
.in +6
.ti -4
-_ CHANGE_ SCALING_ _ _ _ SegName_ LIN|LOG_ [Lcut_ [Hcut]]
.br
will change the transfer function for the specified image segment.
.ti -4
-_ CHANGE_ BLANKING_ _ _ SegName_ BLACK|WHITE|Colour
.br
will change the colour of blanked pixels (if any) in the displayed
image. Colour is a colour value as in PENCIL command (1-8).
.ti -4
-_ CHANGE_ COLOUR_ _ _ _ _ SegName_ Value
.ti -4
-_ CHANGE_ DASH_ _ _ _ _ _ _ SegName_ Value
.ti -4
-_ CHANGE_ DEPTH_ _ _ _ _ _ SegName_ Value. See subtopic for details.
.ti -4
-_ CHANGE_ VISIBILITY_ SegName_ ON|OFF
.ti -4
-_ CHANGE_ WEIGHT_ _ _ _ _ SegName_ Value
.in -6
The last five items are general segment attributes. For these, if
SegName is a segment, only that segment is modified, but if it is a
directory, all segments attached to this directory are modified
accordingly. See subtopic SEGMENT__NAMES for details on naming
segments.

And finally, some general behaviours can be changed will the following
keywords:
.in +6
.ti -4
-_ CHANGE_ LUT_ STATIC|DYNAMIC
.br
toggles the Look-Up-Tables to STATIC or DYNAMIC mode. Default is
DYNAMIC. See subtopic LUT for details.
.ti -4
-_ CHANGE_ PENCIL_ HARD|SOFT
.br
specifies whether the GTV library should use the (output dependent)
hardware generator for dashes and thickness, or whether it should use
its own (output independent) software emulation. Hardware generator
may (or may not) produce nicer output, and may be faster...
.ti -4
-_ CHANGE_ POSITION
.br
changes the window position on the screen. See subtopic for details.
.in -6
.\"--------------------------------------------------------------------
.ti -4
2 DEPTH

The GTV segments have a depth attribute in order to create, control,
or reorder different drawing layers. Depth value must lie in range
1-40.

By default, all vector-like segments are at depth 1. Images are always
at the deepest available depth (2 at startup) so that e.g. the BOX is
always drawn on top of a PLOT, independently of their creation order.

In practice, when the plotting window is refreshed, it draws first all
the segments at deepest level, then all the segments at deepest level
minus one, and so on up to level 1. For a given depth, segments are
drawn in chronological order (i.e. in the order they were created).
.\"--------------------------------------------------------------------
.ti -4
2 LUT
.ti +4
Specifies whether the color Look-Up-Tables (LUT and LUT /PEN) are
static, i.e. associated with each graphic segment, or Dynamic, i.e.
controlled by the terminal colors. This changes the behaviour of the
LUT and LUT /PEN commands.
 
In STATIC mode, each graphic segment has its own LUT, so that this
allows to display complex plots with many colors. The LUT and LUT /PEN
which are stored with each segment must be set before the segment
creation. It cannot be changed after. In this mode, the display may
differ from the hardcopy output, because not all interactive displays
support many colors.

In DYNAMIC mode, one single LUT its associated to the plot. It can be
changed dynamically afterwards using the LUT (and LUT /PEN)
commands. It is appropriate for interactive visualisation. The
hardcopy output will be identical to the display.

The default is DYNAMIC.
.\"--------------------------------------------------------------------
.ti -4
2 POSITION
.ti +4
CHANGE POSITION Num
.ti +4
CHANGE POSITION Posx[Unitx] Posy[Unity]

The first syntax moves the current window to the specified position,
where Num is in the range 1-9. The 9 most remarkable points of the
screen (corners, middle of the sides, and center) are numbered
according to a VT100 numeric keypad notation.

The second syntax moves the current window to the specified
coordinates. The recognized units are 'p' for pixels, and '%' for
percent of the screen size. Units default to 'p' if they are omitted.
.\"--------------------------------------------------------------------
.ti -4
2 SEGMENT__NAMES
.ti +4

The 'SegName' used in all the CHANGE commands is formed by a name,
given by the calling high-level program (usually a reminder of the
command used), followed by an unique, incremental, number. To refer a
particular segment, one uses the full name (as in
CHANGE_ VISIBILITY_ CONTOUR:46_ OFF). To refer to ALL the segments
with the same name, omit the number (as in
CHANGE_ VISIBILITY_ CONTOUR_ OFF). To refer to a range of segments,
use a 'minus' sign in the range (as in
CHANGE_ VISIBILITY_ CONTOUR:32-46_ OFF). Segments names can be
'wildcarded' (an '*' can replace part of the beginning or the end of
the segment name, as in CHANGE_ VISIBILITY_ *TOUR_ OFF).
.\"====================================================================
.ti -4
1 CLEAR
.ti +4
[GTVL_\]CLEAR [Arg [Value]]

CLEAR without argument performs a CLEAR ALL, i.e. it empties all the
top directories and thus their associated windows.

Consult the following sections for the various CLEAR arguments.
.\"--------------------------------------------------------------------
.ti -4
2 ALL
.ti +4
 CLEAR_ ALL

Performs a CLEAR DIRECTORY on all the top directories, i.e. they are
emptied and their attached windows are cleared.
.\"--------------------------------------------------------------------
.ti -4
2 DIRECTORY
.ti +4
 CLEAR_ DIRECTORY_ [DirName]

Empties the named directory (or by default the current directory),
i.e. remove the segments and subdirectories it contains. As a
consequence, under X, the windows attached to input directory are also
cleared.

If the subdirectories had windows attached, they are destroyed in
conjunction to them. If the current working directory has to be
destroyed, i.e. it is a subdirectory of the directory to be cleaned,
it is implicitely moved to the latter.
.\"--------------------------------------------------------------------
.ti -4
2 SEGMENT
.ti +4
 CLEAR_ SEGMENT [SegName]

Without argument, CLEAR_ SEGMENT destroys the last graphic segment of
the current directory, i.e. in simplest case the part of the plot
corresponding to the last graphic command. It can be used
repetitively.

CLEAR_ SEGMENT_ SegName makes destroys the named segment.One can erase
a range of graphic segments in a single command by typing a range of
segment numbers, as in CLEAR_ SEGMENT_ 24-16. See command GTVL\CHANGE
for details.
.\"====================================================================
.ti -4
1 COMPRESS
.ti +4
[GTVL_\]COMPRESS
.ti +4

Compress the internal metacode, by removing all the invisible segments
and directories.
.\"====================================================================
.ti -4
1 CREATE
.ti +4
[GTVL_\]CREATE Argum Value [options]

Creates either a directory, a window, or a Look Up Table stored in the
metacode.
.\"--------------------------------------------------------------------
.ti -4
2 DIRECTORY
.ti +4
CREATE DIRECTORY PathName [/PLOT__PAGE SizeX SizeY] [/GEOMETRY Args]
[/POSITION Args]

Create a new directory. PathName syntax follows "Unix-like" pathnames,
with the use of token '<' instead of '/'. Constructs like ..<Dir are
valid.

To create a new directory tree (called e.g. NewTop), use the following
syntax:
.ti +4
CREATE DIRECTORY <NewTop

The plot space size of a new directory tree can be customized with the
option /PLOT__PAGE. This option can not be used to create
subdirectories, since they inherit the plot space size of their parent
directory.

Under X, a new window is implicitely attached to a new top directory
being created. Its geometry and position can be customized through the
options /GEOMETRY and /POSITION respectively. See HELP CREATE WINDOW
for syntax and creation rules. These options are illegal when
creating a subdirectory (for which no window is attached at creation
time).
.\"--------------------------------------------------------------------
.ti -4
2 LUT
.ti +4
CREATE LUT

Store the current Look Up Table into the internal metacode. This makes
sense if the LUT behavior is static (see HELP CHANGE LUT), so that the
next graphic segments will use the last LUT stored in the metacode.
.\"--------------------------------------------------------------------
.ti -4
2 PENLUT
.ti +4
CREATE PENLUT

Store the current pencil colors into the internal metacode.
.\"--------------------------------------------------------------------
.ti -4
2 WINDOW
.ti +4
CREATE WINDOW [BLACK|WHITE] [NAME Name] [/GEOMETRY Sizex[Unitx]
Sizey[Unity]] [/POSITION Posx[Unitx] Posy[Unity]]

Create a new window seeing the content of the current directory, with
the corresponding attributes of background colour and Name. This
command is only available under X.

The window geometry is set:
.in +2
.ti -2
- if the option /GEOMETRY is present, to the values given to this
option, recognized units being 'p' for pixels, '%' for percent of the
screen size, and 'r' for a fraction (aspect ratio) of the other size
(units default is 'p' if omitted),
.ti -2
-_ else, to the values read in the SIC logical named WINDOW__GEOMETRY,
with the same syntax used for the option /GEOMETRY, if this SIC
logical exists,
.ti -2
- else, to the internal default values.
.in -2

The window position on the screen is then ruled:
.in +2
.ti -2
-_ if the option /POSITION is present, by the values given to this
option, recognized units being 'p' for pixels or '%' for percent of
the screen size (units default is 'p' if omitted),
.ti -2
- else, by the choice of the window manager.
.in -2

For example:
.ti +4
GREG> CREATE WINDOW /GEOMETRY 400 2r
.br
creates a window of size 400 x 800 pixels, and
.ti +4
GREG> CREATE WINDOW /POSITION 100% 100p
.br
creates a window aligned on the right and 100 pixels above the bottom
of the screen.
.\"====================================================================
.ti -4
1 DESTROY
.ti +4
[GTVL_\]DESTROY ALL|DIRECTORY|WINDOW [Values]

Destroys (parts of) the plot tree and/or the windows seeing it.
.\"--------------------------------------------------------------------
.ti -4
2 ALL
.ti +4
DESTROY ALL

Destroys all the plot, i.e. destroys all the top directories and their
windows.

Since the user can not be in the root directory (<) and create
segments in it, a new top directory and its first window are
implicitely created after this. DESTROY ALL is thus the way to reset
the tree and windows to their startup status.
.\"--------------------------------------------------------------------
.ti -4
2 DIRECTORY
.ti +4
DESTROY DIRECTORY [DirName]

With a directory name as argument, completely suppress the input
directory and its windows (if any). If the current working directory
has to be destroyed, it is implicitely moved to the first parent
directory which is not destroyed.

Without argument, completely suppress the last subdirectory of the
current working directory.
.\"--------------------------------------------------------------------
.ti -4
2 WINDOW
.ti +4
DESTROY WINDOW [DirName [WinNum|ZOOM]]

DESTROY_ WINDOW_ DirName destroys all the windows attached to the
input directory. DirName defaults to the current directory.

If a window number is given, only the window identified by this number
in Dirname is destroyed. The keyword "ZOOM" can be used as an alias
for the zoom window in this directory, if any.
.\"====================================================================
.ti -4
1 DEVICE
.ti +4
[GTVL_\]DEVICE [Dev__Type [Mode]] [/OUTPUT Dev__Name]

Without argument, DEVICE displays the current working graphic device.

With a graphic device type as argument, directs the graphic output to
it and sets default values for the plot region location and device
physical limits. The basic unit is 1 cm for hardcopies. All plots to
interactive devices are made with some pre-computed factor to match
the screen size to the Plot Page size, defined by command SET
PLOT__PAGE (default size is an A4 format page, 30 by 21).

Use DEVICE ? to get the list of recognized graphics devices or DEVICE
type ? to get the list of modes on a given device.

/OUTPUT_ Dev__Name option allows you to direct the graphic output to
something else than your own terminal (TT:). Note that some specific
devices will not support this option: this is currently the case for
X-Window devices.
.\"====================================================================
.ti -4
1 DISPLAY
.ti +4
[GTVL_\]DISPLAY Item [Arguments]

List the internal parameters of the named item:
.in +4
.ti -2
DISPLAY_ DATA SegName
.br
shows the data values in input segment. For debugging purpose.
.ti -2
DISPLAY_ DIRECTORY
.br
shows the current directory and its active window, if any.
.ti -2
DISPLAY_ POINTER_ [SEGMENT|TREE]
.br
shows the internal values of the pointers. For debugging purpose.
.ti -2
DISPLAY_ SEGMENT_ [SegName]
.br
shows the attributes of input segment (either a leaf or a
directory). Default is current directory.
.ti -2
DISPLAY_ TREE [DirName]
.br
shows the directory tree in a recursive way. Default lists from
current directory.
.ti -2
DISPLAY_ WINDOW
.br
shows the active window and its attributes.
.in -4
.\"====================================================================
.ti -4
1 FLUSH
.ti +4
[GTVL_\]FLUSH

Flush the internal stack. This could be useful when creating a complex
plot (stored in the metacode) and when the graphic device is late
(when reading the metacode). Then you may want to force the
synchronization: FLUSH will return only when all the instructions in
the stack are executed.
.\"====================================================================
.ti -4
1 GTV
.ti +4
[GTVL_\]GTV SEARCH DirName

If the GTV directory DirName exists, sets the variable GTV%EXIST
to .TRUE., e.g.

.nf
GREG> GTV SEARCH <GREG
GREG> EXAMINE GTV%EXIST
GTV%EXIST       = T              ! Logical GLOBAL
.fi
.\"====================================================================
.ti -4
1 HARDCOPY
.ti +4

[GTVL_\]HARDCOPY [File] [/DEVICE Name [Attributes]] [/PRINT [Printer]]
[/DIRECTORY DirName] [/GEOMETRY Sizex[Unitx] Sizey[Unity]] [/FITPAGE]
[/EXACT] [/OVERWRITE]

Create a "hardcopy" of the current plot.

There are 3 possible outputs:
.in +4
.ti -2
- a file: if a file name is provided, or if GTV%STDOUT is NO
(default). In this latter case, the file name defaults to
"gregplot.*".
.ti -2
- the terminal: if no file name is provided and GTV%STDOUT is YES.
.ti -2
- the printer: if /PRINT is used, see below.
.in -4
Sending hardcopies to the terminal can be useful to avoid using
temporary files on the disk. The calling process can read it instead
directly from STDOUT. In case of PostScript or SVG hardcopies, their
ASCII content is directly dumped in the terminal. In case of PNG, the
binary data is encoded using the Base64 algorithm (portable ASCII
sequence), and a header and a footer are added as description.

The default behaviour of the command is to scale the GreG PLOT__PAGE
(centimeters) into the output physical page. This can be overriden
with the two options:
.in +4
.ti -2
-_ /EXACT: 1 cm on the GreG PLOT__PAGE will be 1 cm on the hardcopy
physical page, for devices for which it makes sense,
.ti -2
-_ /FITPAGE: the plot will be automatically rotated and scaled to make
the best use of the hardcopy physical page. The option /PRINT
implicitely enables this feature. See subtopic for details.
.in -4
These two options are exclusive.

The /DEVICE option argument specifies which type of plotter will be
used. See the subtopic /DEVICE for a list of the allowed devices. The
other arguments passed to this option can modify the attributes of the
hardcopy. If the option is not used, the harcopy device defaults to
the content of the SIC logical GAG__HARDCOPY.

The /DIRECTORY option allows to specify which GTV directory should be
sent to the hardcopy. Without this option, default is current
directory.

The /PRINT option is used to force immediate printing and, optionally,
to control which printer should be used. Printer is the printer name,
which defaults to the content of the SIC logical GAG__PRINTER. The
printing command is ruled by the SIC logical GAG__LPR. If no file name
was specified for an immediate printing, the metacode file is deleted
after print completion, otherwise it is kept.
.\"--------------------------------------------------------------------
.ti -4
2 /DEVICE
.ti +4
[GTVL_\]HARDCOPY [/DEVICE Name [Attributes]]

The /DEVICE option argument specifies which type of device will be
used. The other arguments passed after the device name can modify the
harcopy attributes. Several attributes can be combined. Allowed
devices and attributes are:

.in +10
.ti -8
PS (PostScript): the plot is automatically rotated and scaled on the
hardcopy physical page.
.ti -6
GREY_ _ PostScript with fixed greyscale transfer function for bitmap.
.ti -6
COLOR_ PostScript with user controlled color transfer function. This
is the default.
.ti -6
FAST_ _ PostScript with hardware pen thickness handling. Clipping of wide
pens may be inaccurate. This is not the default.

.ti -8
EPS (Encapsulated PostScript): As PS, with the BoundingBox computed
from the plot boundaries rather than from the Plot Page size. The plot
is NOT rotated neither scaled to the hardcopy physical size by
default. Use the option /FITPAGE to enable this feature.
.ti -6
GREY_ _ Same as PS.
.ti -6
COLOR_ Same as PS.
.ti -6
FAST_ _ Same as PS.

.ti -8
PDF (Portable Document Format): the plot is exported as PS and
converted to PDF using "ps2pdf" if available on the system. The PS
usual attributes can be used:
.ti -6
GREY_ _ Same as PS.
.ti -6
COLOR_ Same as PS.
.ti -6
FAST_ _ Same as PS.

.ti -8
EPDF (Encapsulated Portable Document Format): the plot is exported as
EPS and converted to PDF using "epstopdf" if available on the
system. The EPS usual attributes can be used:
.ti -6
GREY_ _ Same as EPS.
.ti -6
COLOR_ Same as EPS.
.ti -6
FAST_ _ Same as EPS.

.ti -8
PNG (Portable Network Graphics): create a bitmap representation of the
GreG plot. The size of the PNG can be tuned with the option /GEOMETRY.
.ti -6
GREY_ _ Same as PS
.ti -6
COLOR_ Same as PS
.ti -6
WHITE_ PNG with white background and black foreground. This is the
default.
.ti -6
BLACK_ PNG with black background and white foreground.
.ti -6
TRANSPARENT PNG with transparent background. This is not exclusive
with WHITE and BLACK attributes, i.e. "TRANSPARENT BLACK" creates a
PNG with transparent background and white foreground. Transparency is
not activated by default.
.ti -6
NOBLANK Blanked pixels will not be drawn, i.e. they will use the
background color (white, black, or transparent) or they will let you
see previous drawings made behind.
.ti -6
CROPPED the GreG plot is expanded to fit exactly to the best PNG
dimensions, and the other PNG dimension is shrinked to leave no
margin.

.ti -8
SVG (Scalable Vector Graphics): create a vectorial representation of
the GreG plot in the SVG format. The size of the SVG can be tuned with
the option /GEOMETRY.
.ti -6
CROPPED the GreG plot is expanded to fit exactly to the best SVG
dimensions, and the other SVG dimension is shrinked to leave no
margin.
.in -10
.\"--------------------------------------------------------------------
.ti -4
2 /FITPAGE
.ti +4
HARDCOPY /FITPAGE

Automatically rotate and scale the desired part of the plot to match
at best the hardcopy physical size. Alternatively, the variable
GTV%FITPAGE can be set to YES to force this feature.

The desired part of the plot is the full Greg plot page for PS, or the
cropped plot for EPS. The hardcopy physical page is controled by the
sic logical GAG__PAPER__SIZE set at compilation time.

In the case of PS/EPS hardcopies, if the plot actually needs rotation,
the line "%%Orientation: Landscape" or "%%Orientation: Portrait" is
added in the PostScript header. This line is recognized by PostScript
viewers (e.g. ghostview) so that they unrotate the file when
displaying it. On the other hand, empirical tests show that Latex,
MS/Open/Libre-Office, or eps2jpg ignore it. Hopefully, printers also
ignore this line, giving this option its full sense.
.\"--------------------------------------------------------------------
.ti -4
2 /GEOMETRY
.ti +4
HARDCOPY /GEOMETRY Sizex[Unitx] Sizey[Unity]

The /GEOMETRY option allows to customize the size of the
hardcopy. This option is supported on the following devices:
.in +2
.ti -2
-_ PNG: units allowed are 'p' (pixels) and 'r' (aspect ratio). If
absent, units default to pixels.
.ti -2
-_ SVG
.in -2

Typical use cases are:
.nf
  HARDCOPY /GEOMETRY 800 560    ! 800x560 pixels
  HARDCOPY /GEOMETRY 800p 560p  ! 800x560 pixels
  HARDCOPY /GEOMETRY 800 0.5r   ! Twice less pixels in Y than X: 800x400 pixels
  HARDCOPY /GEOMETRY 3r 100     ! 3 times more pixels in X than Y: 300x100 pixels
  HARDCOPY /GEOMETRY 1r 2r      ! Invalid: both dimensions defined as
                                ! ratio of the other
.fi

Without this option, the hardcopy size can be ruled through the
following SIC logicals, using the same syntax as above:
.in +2
.ti -2
- PNG__GEOMETRY
.ti -2
- SVG__GEOMETRY
.in -2

If neither the option is used nor the SIC logical is set, then the
hardcopy size is defined with internal default values (800x560
pixels).
.\"--------------------------------------------------------------------
.ti -4
2 /OVERWRITE
.ti +4

Existing hardcopy files are not overwritten, but the option /OVERWRITE
can be used to force this. Alternatively, the variable GTV%NOFAIL can
be set to YES to force overwriting.
.\"====================================================================
.ti -4
1 LENS
.ti +4
[GTVL_\]LENS

Under X, call the lens on the active window. The flow of commands is
suspended until the lens is closed.

The usual way to call the lens is using the middle-click of the mouse
on the plot. However, this command is useful to give a detailed look
to an intermediate plot during a procedure, since it acts like a
PAUSE.

When opened, the lens is controled by the following actions:
.in +2
- Mouse wheel: reduce or enlarge the zooming factor,
.br
- Left-click or CTRL+wheel: reduce the lens area,
.br
- Right-click or CTRL+wheel: enlarge the lens area,
.br
- Middle-click: close the lens
.in -2
.\"====================================================================
.ti -4
1 LUT
.ti +4
[GTVL_\]LUT [Argum] [/PEN] [/REVERSE] [/BLANK Color]

Modify the bitmap or pen look up table. Option /PEN indicates to
modify the value of the 16 user-controlled pen colors (colors 8 to 23)
rather than the bitmap look-up table.

The default argument is LUT. Possibles arguments are:
.in +4
.ti -4
- ?
.br
Type "LUT_ ?" to display the list of available LUTs, or execute the
demonstration procedure @ gag__demo:demo-luts.greg for an overview.
One can use alternatively the LUT editor (button "Edit Lut") to browse
and edit the LUTs in an interactive widget.
.ti -4
- DEFAULT
.br
Load the default color table.
.ti -4
- COLOR
.br
Load a color table with a circular hue value, from red to red.
.ti -4
- BLUERED
.br
Load a color table from dark blue to light blue, white, light red,
dark red, suited for blueshift to redshift display.
.ti -4
- BLACK
.br
Load a black and white color table (white background, black sources).
.ti -4
- WHITE, RED, GREEN, BLUE, MAGENTA, YELLOW, CYAN and NULL
.br
Load a color table with black background and sources in the
corresponding color (NULL is fully black).
.ti -4
- LUT
.br
A custom color model can be defined in RGB or HSV arrays and
applied. See subtopic LUT for details.
.ti -4
-_ Any other LUT_ Argum will read Red Green Blue values from the
formatted file named "Argum". See subtopic FILE for details.
.in -4

The LUT, whereever it comes from, can be reverted before use with the
option /REVERSE.
.\"--------------------------------------------------------------------
.ti -4
2 /PEN
.ti +4
Same behaviour as LUT, but will update the colors of the 16 pens
(colors 8 to 23) used for contour-filling.

The associated HSV and RGB models can be found and customized in the
sic arrays named LUT%PEN%HUE, LUT%PEN%SATURATION, LUT%PEN%VALUE, and
LUT%PEN%RED, LUT%PEN%GREEN and LUT%PEN%BLUE, one or the other being
used depending on the LUT%MODE value.
.\"--------------------------------------------------------------------
.ti -4
2 /BLANK
.ti +4
The blanking color is used to paint blanked pixels in images. By
default at startup this color is white. This can be customized with
.ti +4
LUT /BLANK Color
.br
where the color is one of the supported pen colors (type LUT /BLANK ?
for the complete list). The 2 most relevant values are BACKGROUND and
FOREGROUND which translate as WHITE or BLACK depending on the device
color.

For a custom blanking color, use command LUT LUT (see subtopic for
details).
.\"--------------------------------------------------------------------
.ti -4
2 LUT
.ti +4

If the argument is "LUT", load the color table defined by an HSV (HUE,
SATURATION and VALUE) or RGB (RED, GREEN and BLUE) color model. There
are six user-writeable SIC variables named:
.ti +2
- LUT%HUE,
.ti +2
- LUT%SATURATION,
.ti +2
- LUT%VALUE, and
.ti +2
- LUT%RED,
.ti +2
- LUT%GREEN
.ti +2
- LUT%BLUE
.br
that contain the HSV and RGB model of the current LUT. These arrays
values can be manipulated using standard SIC mathematic functions to
create new Look-Up Tables (see below). Depending on the value on
LUT%MODE, the model is reloaded from the HSV (LUT%MODE.eq.1) or from
the RGB (LUT%MODE.eq.2) arrays.

A convenient value for the hue array is
.ti +8
LET LUT%HUE[I] = 256*(1-(I/LUT%SIZE))
.ti +8
LET LUT%SATURATION 1
.ti +8
LET LUT%VALUE 1
.ti +8
LUT LUT
.br
which is a "classical" color table from blue to red as used in AIPS
for example. Color contours can be obtained using variations around
the following command:
.ti +8
LET LUT%HUE[I] = 16*INT(256*(1-(I/LUT%SIZE))/16)
.br
and so on with the most funny functions you may invent.

A similar behaviour is defined for the BLANKING color, with the six
reals LUT%BLANK%HUE, LUT%BLANK%SATURATION, LUT%BLANK%VALUE, and
LUT%BLANK%RED, LUT%BLANK%GREEN, LUT%BLANK%BLUE.

CAUTION: the hue is a real number between 0.0 and 360.0
.\"--------------------------------------------------------------------
.ti -4
2 FILE
.ti +4
The command LUT can read the colormaps from a formatted file. A
various number of these files is already available in the
distribution. Type "LUT ?" to see these files.

The files are searched in the path(s) contained in the SIC logical
LUT#DIR:. It can be a collection of paths customized by the user. By
default LUTs are searched in the current directory and in GAG__LUT:
(where the standard GTV LUTs are stored). The default extension is
".lut".

User can define and save its own LUT in such a file. The formatted
file must be an ASCII file providing the three R, G and B intensities
in three columns, and there must be as many lines as color levels
needed. The intensities are three real numbers between 0.0 and 1.0.

The LUT loaded from such a file will then be resampled (using
interpolation) to match the effective number of colors the device
supports. For example, the file example.lut:
.nf
shell> cat example.lut
     .00000    .00000    .00000
     1.0000    .00000    .00000
.fi
will produce a black to red color map, with continuous color levels
between.
.\"--------------------------------------------------------------------
.ti -4
2 CET
.ti +4

GREG provides the collection of look-up-tables from colorcet.com under
names cet-*.lut. These LUTs have uniform contrast which avoid missing
significant features in the data and detecting false ones (see
https://colorcet.com for details).

In practice the file name suffix encodes:
.in +4
.ti -2
-_ cet-l*.lut: linear color maps,
.ti -2
-_ cet-d*.lut: diverging color maps (differentiate values that lie
above, or below, a reference value),
.ti -2
-_ cet-r*.lut: rainbow color maps,
.ti -2
-_ cet-c*.lut: cyclic color maps (colors are matched at each end),
.ti -2
-_ cet-i*.lut: isoluminant color maps (equal perception lightness),
.ti -2
-_ cet-cb**.lut: color blind maps (the 'cb' characters are added in
addition to the previous nomenclature).
.in -4
Last, a trailing "s" stands for shifted colors.

These colour maps are released under the Creative Commons BY License.
.\"====================================================================
.ti -4
1 METACODE
.ti +4
[GTVL_\]METACODE EXPORT|IMPORT FileName [DirName] [/PATH PathName]

Allow to save or load whole or parts of the current plot to or from a
metacode file.
.\"--------------------------------------------------------------------
.ti -4
2 EXPORT
.ti +4
[GTVL_\]METACODE EXPORT FileName [DirName]

Export the current (or specified) directory tree to an external
metacode file of name FileName. The default extension is .meta . The
sub-plot can later be reincorporated using command METACODE_ IMPORT.
This allows merging several plots together.
.\"--------------------------------------------------------------------
.ti -4
2 IMPORT
.ti +4
[GTVL_\]METACODE IMPORT FileName [DirName] [/PATH PathName]

Insert an external metacode file at the specified PathName into the
current plot. PathName defaults to the current directory.
.\"====================================================================
.ti -4
1 REFRESH
.ti +4
[GTVL_\]REFRESH [DirName [WinNum|ZOOM]]

By default, redraw all windows in all directories. If a directory name
is provided, redraw the windows seeing this directory and its
subdirectories. If a window number is also specified, redraw only this
window. The keyword "ZOOM" can be used as an alias for the zoom window
in this directory, if any.

The windows are drawn and redrawn as soon as new segments are added,
or if the window manager requires it (e.g. window is
resized). However, for efficiency purpose, segments are first drawn
one onto the previous ones, in the chronological order. Depending on
their depth (e.g. images which are by default at depth 2), this is not
what happens in the subsequent redraws and in hardcopies. In this
case, it makes sense to force the refresh of a window.
.\"====================================================================
.ti -4
1 REPLICATE
.ti +4
[GTVL_\]REPLICATE Dir1 Dir2

Copy Dir1 subtree to Dir2 subtree. Not very useful now, but will
become interesting when shifting, stretching, rotations, and user
coordinate changes will be allowed for all segments.
.\"====================================================================
.ti -4
1 ZOOM
.ti +4
[GTVL_\]ZOOM [X1 X2 Y1 Y2 | OFF]

The command ZOOM opens or closes a new window which displays a smaller
region of the current plot. Each plot can have its own zooming
window. It will be reused by subsequent calls to the command ZOOM.

Without arguments, ZOOM calls the cursor to define the viewing area.
This area will be defined by its center (at the cursor position) and a
zooming factor (by steps of 1.414):
.nf
   Z       Increase the zooming factor
   -       Decrease it
   0       Reset it
   E       Exits from the routine
.fi
These commands do not produce effective zooming, press the space bar
to do it. For graphical displays, you may use the mouse buttons for the
commands <Space> (left mouse button), Z (middle mouse button), and E
(right mouse button).

ZOOM_ X1_ X2_ Y1_ Y2_ can be used to define the viewing area by a
non-interactive mean. The values must be in paper units (cm).

Use ZOOM_ OFF to close the zoom window of the current plot, if any.
.\"====================================================================
.ti -4
1 ENDOFHELP
