Ubuntu Manpage: ictrans - interactive NCAR CGM translator ctrans

NAME

       ictrans - interactive NCAR CGM translator ctrans

SYNOPSIS

       ictrans  [  -d  device ] [ -font font ] [ -e script ]* [ -soft ] [ -bell ] [ -lmin min ] [
       -lmax max ] [ -lscale scale ] [ -pal pal_fname ]  [  -Version  ]  [  -wid  window_id  ]  [
       device-specific options ] metafile...

DESCRIPTION

       ictrans  is  the user interface to the Computer Graphics Metafile (CGM) translator ctrans.
       ictrans will enter command interpreter mode upon invocation and  await  instructions  from
       the user. When waiting for commands from the user, ictrans displays the prompt `ictrans>'.

       Upon invocation ictrans performs a configuration of its spooled device table. The table is
       configured by processing several sources.  ictrans first searches for the file ncarv_spool
       in  the $NCARG_ROOT/lib/ncarg directory.  If the file exists ictrans will load it into the
       spooled device table. Next, ictrans searches for the file .ncarv_spool in the user's  home
       directory.  If  found,  its  contents  are  merged  into  the  spooler table. Finally, the
       NCARV_SPOOL environment variable may contain the definition for a single spooler. If  this
       variable  is set, its contents also are merged into the table. Each entry in the above set
       of sources is identified by a name. If a conflict in names  exists  then  the  last  entry
       encountered takes precedence. i.e. the previous entry of the same name is overridden.

OPTIONS

-bell Ring the bell at the end of each frame. The default is to run in silent mode. This
option is not supported by all devices.

-d device
Device name. ictrans will use the Graphcap (if it exists) or the appropriate
graphics library indicated by device;

If device is preceded by a UNIX directory path then ictrans will look in that
directory for the specified graphcap. Otherwise ictrans searches the directory
$NCARG_ROOT/lib/ncarg/graphcaps for the graphcap.

For all device specifications except X11 output is directed to standard out. In the
case of X11 translation results in appropriate calls to the X11 libraries. See
graphcap(5NCARG) for a description of supported devices. See gcaps(1NCARG) for a
list of devices supported by your particular configuration of ctrans.

This option overrides the GRAPHCAP environment variable.

-e script
script is a single ictrans command. The valid ictrans commands are discussed in the
COMMANDS section below. Multiple -e options may appear on a single command line.
Be careful to use quotes if your command contains spaces or metacharacters that
might be interpreted by the shell. When this option is used ictrans does not enter
interactive mode. It simply performs the given commands and then exits.

-font fontcap
Fontcap file to be used for stroking text. When interpreting CGM TEXT command
elements use fontcap as the default font for textual translation. Note: CGMs may
contain textual descriptions which are not embedded in CGM TEXT elements. Hence
they are not influenced by fontcap specifications. Note also that a CGM may
explicitly specify a named font which may override a font provided on the command
line. The environment variable FONTCAP may also be used to specify a default
fontcap.

If fontcap is preceded by a UNIX directory path then ictrans will look in that
directory for the specified fontcap. Otherwise ictrans searches the directory
$NCARG_ROOT/lib/ncarg/fontcaps for the fontcap.

See fontcap(5NCARG) for a description of the available fontcaps. See fcap(1NCARG)
for a list of the fontcaps installed on your system.

This option overrides the FONTCAP environment variable.

-lmin min
On devices which support line width scaling all lines are guaranteed to be scaled
at least min times the default line width for that device. This option effectively
insures that the minimum value for the CGM element "LINE WIDTH" is min.

-lmax max
On devices which support line width scaling all lines are guaranteed to be scaled
at most max times the default line width for that device. This option effectively
insures that the maximum value for the CGM element "LINE WIDTH" is max. The
results of setting max less then min are undefined.

-lscale scale
On devices which support line width scaling all line width specifications within
the metafile will be scaled by scale. will be scaled scale This option is subject
to modification by the -lmin and -lmax options.

-pal pal_fname
Use the color palette defined in the file pal_fname for subsequent translation of
the metafile. This palette will override any color map defined by the CGM being
translated. For a description of the format of pal_fname see ras_palette(5NCARG).

-soft Unconditionally perform software filling of all filled polygons. This option may be
useful for devices which have limits on the number of vertices describing a
polygon. On some devices this number is known and software filling is performed, as
appropriate, without user specification.

-Version
Print the version number and then exit.

DEVICE SPECIFIC OPTIONS

       ictrans  accepts  an  identical  set  of device-specific options to that of ctrans.  For a
       description of the device-specific options see ctrans(1NCARG).

COMMANDS

Command Structure
ictrans commands have a simple and regular structure. Commands which operate directly on
the metafile being processed may be preceded by a frame_list which designate the frames to
which the command applies. Some commands accept arguments. Anything following a command
name is regarded as an argument:

( frame [ ,frame ])* command ( argument )*

A comma-separated pair of frames implies the inclusive list of frames. If a frame list is
omitted and a command requires a frame then the current frame is used as the default. If
no argument list is specified and one is required then a default argument is used whenever
possible.

For example, the command 1,5 8 save /tmp/foo would write the first through fifth and the
eighth frame of the metafile to the file /tmp/foo.

Commands will ignore any unexpected arguments. Command names may be abbreviated up to the
point that they are unique.

Frame Lists
Frames can be addressed in several ways:

nnn By frame number. Frames are assigned a relative number from first to last in the
metafile. The first frame is numbered 1.

$ The last frame in the file.

. The current frame. ictrans keeps track of the last frame upon which an operation
was performed. This frame is called the "current frame".

frame+-n
A frame number followed by a plus sign (+) or a minus sign (-), followed by a
decimal number, specifies the frame plus or minus the indicated number of frames.
frame may be omitted in which case the current frame is assumed. For example,
`10+2' addresses frame 12 in the metafile.

Commands
! command
Run command as a shell command on the local machine.

alias [ name [ def ] ]
Assign def to the alias name. If def is omitted, the alias name is displayed along
with its current definition. If both name and def are omitted, all aliases are
displayed. def is of the form:

: [ ctrans_args ] : [ filter_chain ]

where ctrans_args is list of command line arguments for the metafile translator
ctrans and filter_chain is a set of simple commands separated by |. filter_chain
may be terminated by > or >> filename. For example:

ictrans> alias name1 : -d xwd : | cat > outfile

ictrans> alias name2 : -d ps.mono : | filter1 | lpr

dup [number]
This command is used to set the number of times each frame is displayed during
subsequent plotting. The default is one. If dup is invoked without any arguments
the current value of dup is returned.

count
Reports number of frames contained in the file.

current
Reports the current frame.

file [ metafile ]
The file metafile will be used for subsequent translation. ictrans uses the shell
defined by the environment variable SHELL (/bin/sh by default) to perform filename
substitution on metafile. The rules governing filename substitution are as defined
by the working shell. If no argument is given the current metafile name is
reported.

font [ font ]
Set the fontcap to font for future translation. This function is identical to that
of the -font option. If font is omitted the current fontcap name is reported.

help [ command ]
Print a usage statement for command. If command is omitted a brief description of
all commands is given.

[ frames ] list
Provide brief information about each metafile frame in frames. If frames is
omitted then the current frame is used. If frames is omitted and the current frame
is not the last frame then the current frame is incremented to the next frame in
the metafile.

< frame1 > < frame2 > merge
Plot frame number frame1 and then plot frame number frame2 over the first frame
without clearing the device. The result is a "merge" of the two plots. The current
frame is not changed. There are no defaults for frame1 or frame2. The resulting
plot might not be what was expected. Attributes from the first frame, such as
color, may override attributes in the second frame.

loop
Toggle loop mode on or off. When loop mode is on subsequent plot commands will
cause the requested frames to be plotted and then ictrans will proceed to either
the first frame in the defined segment or the last and repeatedly display the first
through last (last through first) frames. Looping continues until an interrupt
signal is received. The determination of which order to loop, forwards or
backwards, is made as follows: If the last group of frames plotted was in ascending
order loop forward. If the last group of frames plotted was in descending order
loop backwards. If the order cannot be determined don't loop. For example; if loop
mode is set "1 3,4 plot" will result in forward looping, "1 4,3 plot" will result
in backward looping, and "3,4 1 plot" will result in no looping because the last
group of frames plotted, "1", is a single frame.

movie [ time ]
Display each frame for time seconds before proceding to the next frame during
subsequent plots. If time is omitted then movie mode is toggled off or on. In the
case the movie mode is toggled on the default time is zero seconds. If movie mode
is toggled to off a newline must be received before advancing to the next frame
during plotting.

next
Multiple files may be specified on the ictrans command line. To edit the next file
in the argument list use the next command.

[ frames ] plot
Plot the addressed frames. If frames is omitted then the current frame is plotted
and if possible, the current frame number is incremented. If "movie" mode is set
ictrans will wait time seconds after displaying each plot before continuing. time
is set with the movie command. If "movie" mode is not set ictrans will wait for a
newline character before advancing to the next frame. plot will report the number
of frames and the last frame in frames. Plotting will be terminated and ictrans
will reenter command mode after the last frame is plotted or upon receiving a
interrupt signal, SIGINT.

[ frames ] Print
The addressed frames are translated and sent to the current spooling device.
Translation is performed by a spawned translator. The spooler command may be used
to select a spooling device. See ncarv_spool(5NCARG).

quit
Terminate the session.

[ frames ] save [ metafile ]
Save the addressed frames to metafile. If metafile does not exist then it is
created. Filename substitution is performed on metafile. If metafile is omitted
than the last file saved to is used. If frames is omitted than the current frame is
used.

[ frames ] Save [ metafile ]
Same as the save command except Save does not confirm its actions with the user in
the case that the file exists. If the file exists but is not a valid NCGM it is
overwritten. If the file exists and is a valid NCGM it is appended to.

skip [ number ]
Set number of frames to skip over during subsequent plotting. For example, if
"skip" is set to 1 and a request is made to plot frames 1 through 10 frames 1, 3,
5, 7, and 9 will be displayed. With no arguments skip reports its current value.
The default is zero.

spooler [ spooler_alias ]
With no arguments the current spooler alias name is reported. If spooler_alias is a
valid alias either defined by the alias command, or in a ncarv_spool configuration
file, or by the NCARV_SPOOL environment variable, then spooler alias becomes the
current spooler. Subsequent Print commands will use the spooler definition defined
by the current spooler. See ncarv_spool(5NCARG).

[ start frame ] start
This command defines the first frame in a segment of frames. start, together with
the stop command, define the boundaries of a segment of metafile frames. When
ictrans is in loop mode the contents of this segment are repeatedly displayed. The
default start frame is the first frame in the metafile, 1. If no arguments are
given start reports the first frame in the current segment.

[ stop frame ] stop
This command defines the last frame in a segment of frames. The default stop frame
is the last frame in the metafile, $. If no arguments are given stop reports the
last frame in the current segment.

zoom [ llx [ lly [ urx [ ury ]]]]
The zoom command allows for specification of a workstation window (in the GKS
sense). Four coordinates are specified which define a rectangular window which is a
subset of the normalized VDC rectangle with corner points (0.0, 0.0) and (1.0,
1,0). The specified window is then mapped onto the entire viewport. For example

ictrans> zoom 0.0 0.0 0.5 0.5

would result in the lower left quarter of subsequent plots being blown up to fill
the entire display. Specification of such a window may be used for zooming and
panning.

The range with which one may zoom in on a plot may be limited by the integer
addressing precision of the device.

EXAMPLES

       The following example shows how ictrans might be used in  a  batch  mode  to  translate  a
       metafile  called  gmeta  and  send  the translated results of the entire file to a spooled
       device called "imagen" which might be defined in the system ncarv_spool file:

              % ictrans -e 'spooler imagen' -e '1,$Print' gmeta

ENVIRONMENT

       FONTCAP
              Default fontcap specifier.

       GRAPHCAP
              Default output device specifier.

       NCARG_ROOT
              Path to root of NCAR Graphics installation.

       NCARG_LIB
              If set this variable contains the path to the installed  NCAR  Graphics  libraries.
              NCARG_LIB overrides NCARG_ROOT.

       NCARG_TMP
              If  set,  this  environment  variable  contains  a  directory  path  to be used for
              temporary files. On most systems the default is /tmp.  On some systems the  default
              is /usr/tmp.

       TMPDIR If  NCARG_TMP is not set this environment variable specifies the directory path for
              scratch disk space. If neither NCARG_TMP TMPDIR is set a site-dependent, hard-coded
              default is used.

FILES

       $NCARG_ROOT/lib/ncarg/ncarv_spool
                                   local ictrans spooler config file
       ~/.ncarv_spool              user's ictrans spooler config file

CAVEATS

       Metafile frames written to an existing file via the save command will be  subject  to  the
       effects of any global "attribute elements" contained within the file.

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research

       The use of this Software is governed by a License Agreement.