NAME¶
ctrans - a Computer Graphics Metafile (
CGM ) translator
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 ... ]
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(5NCARG), 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:
X11 under release 4
and 5, version 11 of
X.
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(1NCARG) command.
ctrans will read from the standard input if no metafile name is specified
or the the name specified is `-'.
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(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.
- -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(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. 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(5NCARG).
- -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(1NCARG). 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(1NCARG) 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 widthxheight
- 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 > 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(1NCARG), fontcap(5NCARG), gcaps(1NCARG),
graphcap(5NCARG), idt(1NCARG), ras_palette(5NCARG),
med(1NCARG), ictrans(1NCARG)
Hardcopy: NCAR Graphics Fundamentals, UNIX Version
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
Graphics Installer's Guide, Version 2.00 (August 1987). 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. Consult the aforementioned publication for a discussion of
Graphcaps and Fontcaps as well.
COPYRIGHT¶
Copyright (C) 1987-2009
University Corporation for Atmospheric Research
The use of this Software is governed by a License Agreement.