ctrans
Description
ctrans is a metafile translator, taking
metafile(s), a metafile stored in the NCAR Computer
Graphics Metafile (CGM) standard, and interpreting its
instructions on the device defined by the GRAPHCAP environment
variable. Fonts are stroked according to specifications in the Fontcap
file defined by the FONTCAP environment variable.
ctrans utilizes Graphcaps by default (see graphcap) while providing optional
processing by user provided libraries, if that is required by the
device or desired by the user. Thus, ctrans is
capable of driving any device for which a Graphcap is
available; with programming modifications, ctrans can
accommodate any device for which an external library of plotting
routines is available. Currently, the following Graphcap
independent devices are supported: X under release
4 and 5, version 11.
ctrans can also translate metacode into the following
raster formats: a60, avs, hdf, hppcl, nrif, sun and
xwd. The device specifier for these raster formats
is the name of the format. For example "-d xwd" specifies translation
to an xwd formatted raster file. Additionally, a clear text driver,
"-d CTXT", is available on any terminal. Not all of the
aforementioned devices may be supported by your particular
configuration of ctrans. For a list of supported
devices see the gcaps command.
ctrans will read from the standard input if no
metafile name is specified or the the name specified is `-'.
Synopsis
ctrans [-bell]
[-d device]
[-f font]
[-lmin min]
[-lmax max]
[-lscale scale]
[-movie time]
[-outfile file]
[-pal pal_fname]
[-pause]
[-quiet]
[-record record_num ...]
[-soft]
[-verbose]
[-Version]
[-viewport llx:lly:urx:ury]
[-wid window_id]
[-window llx:lly:urx:ury]
device-specific options
metafile ...
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. ctrans 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
ctrans will look in that directory for the specified
graphcap. Otherwise ctrans 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 for a description of supported
devices. See gcaps for a list of devices
supported by your particular configuration of
ctrans.
This option overrides the GRAPHCAP environment
variable.
- -f 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
ctrans will look in that directory for the specified
fontcap. Otherwise ctrans searches the directory
$NCARG_ROOT/lib/ncarg/fontcaps for the fontcap.
See fontcap for a description of the
available fontcaps. See fcap 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
This option is subject to modification by the -lmin and
-lmax options.
- -movie time
- Set pause to time seconds. In normal operation mode the
translator requires user interaction after the display of each plot.
ctrans will not proceed until the user responds. If
movie mode is set ctrans will wait
time seconds after the display of each frame and then proceed
automatically. This option and the -pause option
are mutually exclusive.
This option may not behave as expected on slower devices.
- -outfile file
- Direct translator output to file. By default translator
output is written to the standard output. This option has no effect
for devices of which ctrans has a function-callable
interface. e.g. X11.
- -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.
- -pause
- Pause after each frame in the metafile is displayed and wait for
the user to type a newline before proceding. This option is probably
only useful when used in conjunction with the -wid
option as this is the normal behaviour for ctrans in
most instances. This option and the -movie option
are mutually exclusive.
- -quiet
- Suppress reporting of non-fatal (warning) error messages; only
fatal error messages are reported.
- -record < record_number... >
- If processing only single frames of the metafile is desired, this
option specifies the record number containing the start of
that frame. ctrans assumes the processing is to
start at the first BEGIN PICTURE element in that
record. The user must perform bookkeeping to determine the record
that contains the desired frame. Normally, a metafile editor (e.g.,
ictrans) may be used as the actual user
interface to perform this bookkeeping. Without a specified record
number, ctrans processes the entire metafile.
- -soft
- Unconditionally perform software filling of all filled
polygons. This option may be useful for devices which do not support
the filled polygon drawing primitive or 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.
- -verbose
- Operate in verbose mode.
- -Version
- Print the version number and then exit.
- -viewport llx:lly:urx:ury
- Set the viewport of the output device. The viewport is the
rectangular region of the output device of which the virtual device
coordinate system of the metafile is mapped onto. Normally this region
is the largest device-addressable square which fits in the center of
the device address space. The -viewport option may be
used to change the default mapping. llx and lly
specify the lower left corner of the device in normalized coordinates.
urx and ury specify the upper right corner of the
device in normalized coordinates. For example, -viewport 0.0
0.0 0.5 0.5, specifies the lower left corner of the
device.
- -window llx:lly:urx:ury
- Specify the 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) and
(1.0,1.0). llx and lly specify the lower left
corner. urx and .ury specify the upper right
corner. The specified window is mapped onto the entire display
viewport. For example, if the workstation window is defined by the
corner points (0,0) and (0.5 0.5) then the lower left quarter of a
plot would be blown up to fill the entire viewport. Specification of
such a window can 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.
Device-specific options
The following options are available when the device is graphcap-driven
(See the gcaps command for a list of
graphcap-driven devices):
- -simulatebg
- Simulate CGM background color requests by drawing a large filled
rectangle of the appropriate color. This option is useful for devices
such as color PostScript printers which have no concept of background
color.
The following options are available when device is
CTXT:
- -Data
- Suppress display of CGM output primitive data. All other
CGM element data is displayed. This may substantially reduce
the verbosity of the clear text driver.
- -Para
- Suppress display of CGM element data except for
output primitives. The -Data combined with
the -Para option permit the display of only the CGM
element names.
The following options are available when device is
X11:
- -background color
- Specifies the default window background color for color
devices. If the metafile explicitly sets color index 0 then this
option is overridden.
- -foreground color
- Specifies the default foreground color for color devices. If the
metafile explicitly sets color index 1 then this option is
overridden.
- -geometry geometry
- Specify the size and/or position of the graphics window in the
format of an X11 Window System geometry string.
- -ignorebg
- Ignore requests to change the background color. This option may be
useful when ctrans renders into a X window created by
an application other than ctrans. As a side effect
of this option the rendering window is not cleared between frames.
- -reverse
- On monochrome devices reverse video is simulated by swapping the
foreground and background colors.
- -wid window_id
- Render into the previously created X window specified by
window_id. Normally ctrans creates its own
window for plotting. The window specified by window_id must
be of type InputOutput. The window must also have inherited
its color map, depth and visual class from the root window.
Note also that when this option is used ctrans cannot
receive X events from the drawing window. Hence,
ctrans cannot use "mouse clicks" as a signal to
advance frames. For this reason the -pause option is
useful to prevent ctrans from processing the entire
metafile without pausing between frames.
window_id may be specified as a decimal or hexidecimal
integer.
The following options apply to the X11 color map management of
ctrans when device is X11:
ctrans supports three different methods of X11 color
map management.
If the user specifies a shared color map (using the
-scmap option), then ctrans will use
the default X color map for the screen, that is shared by all
applications. If the metafile contains more colors than there are
available in the default X color map, then a color matching algorithm
is employed. The idea of the algorithm is that the color in the
current color table that is closest to the requested color
will be selected. Closest is defined in terms of the normal
distance metric on the RGB cube. If the closest color is equal to or
farther away than the percentage error allowed
(-colerr), then a warning message will be printed.
The closest color is still used.
If the user specifies a private color map (using the
-pcmap option), then ctrans will
create a private color map for the graphics window. This will
guarantee that 256 distinct colors are available to the window. This
means that the X window will have a different color map than all the
other windows on the screen. Therefore, you usually have to have the
mouse pointer in the window for the correct color table to be
installed. One disadvantage to this option is that there is usually a
color flashing effect on the screen since the wrong color table will
be installed for the other windows on the screen.
The default color map management scheme attempts to take the best of
the two previous models. It starts out behaving like the shared
model, in that it uses the default color map for the screen. It
differs in that, once it can't allocate any more colors from the
default color map, in allocates its own private color table and starts
using it. This way, the color flashing is only present if it
absolutely needs to be so that ctrans can display the
correct color.
- -scmap
- Ask ctrans to use the shared default X color map
only.
This is the option used if -wid is specified.
- -colerr n
- Specifies the percentage color error that is acceptable if the
-scmap option is being used. If the color being used
is n percentage or more different from the color requested, a
warning will be reported by ctrans.
- -pcmap
- Ask ctrans to create its own X color map and use
it exclusively.
This option is ignored if the -wid option is
present.
The following options are available when device is
a60, avs, hdf, hppcl, nrif, sun, or xwd:
- -dpi dpi
- Specify the number of dots per inch. This option is only
meaningful for the HP LaserJet, hppcl, which ignores
the -resolution option. dpi may be one of
75, 100, 150, or 300. The default is 150.
- -direct
- By default ctrans outputs raster imagery with
8-bit-indexed encoding. When this option is used, if the raster file
format supports it, raster imagery is output in a 24-bit-direct
encoding scheme. Be warned: the resultant file is three times the size
of its 8-bit-indexed counterpart.
- -landscape
- Generate the image in landscape mode. This option is ignored by
all raster devices except the HP LaserJet, hppcl. By default
the LaserJet uses portrait mode.
- -resolution width x height
- width and height specify the spatial resolution
in pixels of the raster file to be created. The default is 512x512.
Examples
To process a metafile named gmeta and display its
contents on the TEKTRONIX 4107 terminal, use the following call:
% ctrans -d t4107 gmeta
If this device is already defined by the GRAPHCAP environment
variable, simply call:
% ctrans gmeta
If you wish to display only the first frame starting in the third
record, call:
% ctrans -record 3 -d t4107 gmeta
To examine the metafile gmeta's contents without
CGM element data being displayed:
% ctrans -d CTXT -Data -Para gmeta
To render the metafile gmeta (under X Windows) in a
window that is 512x512 pixels in dimension in the lower right corner
of your screen
% ctrans -d X11 -geometry 512x512-0-0 gmeta
To rasterize the contents of the metafile gmeta at a resolution
of 1024x1024 pixels, call:
% ctrans -d xwd -res 1024x1024 gmeta > raster.xwd
The raster output is in X11 "xwd" format and is sent to the file
raster.xwd.
To zoom in on the upper right quarter of the metafile
gmeta and display it in an X window, call:
% ctrans -d X11 -window 0.5:0.5:1.0:1.0
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.
Files
$NCARG_ROOT/lib/ncarg/graphcaps/* - the binary NCAR
Graphcap files
$NCARG_ROOT/lib/ncarg/fontcaps/* - the binary NCAR
Fontcap files
See also
fcaps,
fontcap,
gcaps,
graphcap,
idt,
ras_palette,
med,
ictrans
Caveats
Running in "movie" mode may give surprising results on slower devices,
such as dumb terminals. If too short a time interval is specified slow
devices may not have finished rendering before the movie timer
expires. This results in no pause between frames.
Metafiles which reference color table indices that were not previously
defined may have varying results from one device to the next.
Using the -wid option to have ctrans
display its output in a window created by another X application may
produce unexpected results, particularly with regard to color.
At ctrans' current level of implementation, the
subset of CGM elements supported is closely approximated by the list
provided in NCAR's CGM, Graphcap,
and Fontcap Supplement. However, the best way to determine
whether a particular CGM element is supported by the translator is
feed a metafile containing the element in question to
ctrans.
Copyright
Copyright © 1987-1999
University Corporation for Atmospheric Research
The use of this
software and documentation is governed by a License Agreement.