1CTRANS(1NCARG)                   NCAR GRAPHICS                  CTRANS(1NCARG)
2
3
4

NAME

6       ctrans - a Computer Graphics Metafile ( CGM ) translator
7

SYNOPSIS

9       ctrans  [ -bell ] [ -d device ] [ -f font ] [ -lmin min ] [ -lmax max ]
10       [ -lscale scale ] [ -movie time ] [ -outfile file ] [ -pal pal_fname  ]
11       [  -pause ] [ -quiet ] [ -record record_num ...  ] [ -soft ] [ -verbose
12       ] [ -Version ] [ -viewport llx:lly:urx:ury ] [ -wid window_id ] [ -win‐
13       dow llx:lly:urx:ury ] [ device-specific options ] [ - | metafile ...  ]
14

DESCRIPTION

16       ctrans  is a metafile translator, taking metafile(s), a metafile stored
17       in the NCAR Computer Graphics Metafile (CGM) standard, and interpreting
18       its  instructions  on  the  device  defined by the GRAPHCAP environment
19       variable. Fonts are stroked according to specifications in the  Fontcap
20       file  defined  by  the  FONTCAP  environment variable.  ctrans utilizes
21       Graphcaps by default, see graphcap(5NCARG),  while  providing  optional
22       processing  by  user  provided  libraries,  if  that is required by the
23       device or desired by the user.  Thus, ctrans is capable of driving  any
24       device  for  which a Graphcap is available; with  programming modifica‐
25       tions, ctrans can accommodate any device for which an external  library
26       of  plotting  routines is available.  Currently, the following Graphcap
27       independent devices are supported: X11 under release 4 and  5,  version
28       11 of X.
29
30       ctrans  can  also translate metacode into the following raster formats:
31       a60, avs, hdf, hppcl, nrif, sun and  xwd.   The  device  specifier  for
32       these  raster  formats  is the name of the format. For example "-d xwd"
33       specifies translation to an xwd formatted raster file.  Additionally, a
34       clear text driver, "-d CTXT", is available on any terminal.  Not all of
35       the aforementioned devices may be supported by your particular configu‐
36       ration   of   ctrans.    For  a  list  of  supported  devices  see  the
37       gcaps(1NCARG) command.
38
39       ctrans will read from the standard input if no metafile name is  speci‐
40       fied or the the name specified is `-'.
41

OPTIONS

43       -bell  Ring the bell at the end of each frame. The default is to run in
44              silent mode.  This option is not supported by all devices.
45
46       -d device
47              Device name.  ctrans will use the Graphcap (if it exists) or the
48              appropriate graphics library indicated by device;
49
50              If  device is preceded by a UNIX directory path then ctrans will
51              look in that directory for  the  specified  graphcap.  Otherwise
52              ctrans  searches  the  directory $NCARG_ROOT/lib/ncarg/graphcaps
53              for the graphcap.
54
55              For all device specifications except X11 output is  directed  to
56              standard  out.  In the case of X11 translation results in appro‐
57              priate calls to the X11 libraries.  See graphcap(5NCARG)  for  a
58              description  of supported devices.  See gcaps(1NCARG) for a list
59              of devices supported by your particular configuration of ctrans.
60
61              This option overrides the GRAPHCAP environment variable.
62
63       -f fontcap
64              Fontcap file to be used for stroking  text.   When  interpreting
65              CGM  TEXT  command  elements use fontcap as the default font for
66              textual translation. Note: CGMs may contain textual descriptions
67              which  are not embedded in CGM TEXT elements. Hence they are not
68              influenced by fontcap specifications.  Note also that a CGM  may
69              explicitly  specify  a named font which may override a font pro‐
70              vided on the command line. The environment variable FONTCAP  may
71              also be used to specify a default fontcap.
72
73              If fontcap is preceded by a UNIX directory path then ctrans will
74              look in that directory  for  the  specified  fontcap.  Otherwise
75              ctrans searches the directory $NCARG_ROOT/lib/ncarg/fontcaps for
76              the fontcap.
77
78              See fontcap(5NCARG) for a description of the available fontcaps.
79              See  fcap(1NCARG)  for  a list of the fontcaps installed on your
80              system.
81
82              This option overrides the FONTCAP environment variable.
83
84       -lmin min
85              On devices which support line width scaling all lines are  guar‐
86              anteed  to  be  scaled at least min times the default line width
87              for that device. This option effectively insures that the  mini‐
88              mum value for the CGM element "LINE WIDTH" is min.
89
90       -lmax max
91              On  devices which support line width scaling all lines are guar‐
92              anteed to be scaled at most max times the default line width for
93              that  device.  This  option effectively insures that the maximum
94              value for the CGM element "LINE WIDTH" is max.  The  results  of
95              setting max less then min are undefined.
96
97       -lscale scale
98              On devices which support line width scaling all line width spec‐
99              ifications within the metafile will be scaled  by  scale.   This
100              option  is  subject  to  modification  by  the  -lmin  and -lmax
101              options.
102
103       -movie time
104              Set pause to time seconds. In normal operation mode the transla‐
105              tor  requires  user  interaction after the display of each plot.
106              ctrans will not proceed until the user responds.  If movie  mode
107              is  set  ctrans will wait time seconds after the display of each
108              frame and then  proceed  automatically.   This  option  and  the
109              -pause option are mutually exclusive.
110
111       This option may not behave as expected on slower devices.
112
113       -outfile file
114              Direct  translator output to file.  By default translator output
115              is written to the standard output. This option has no effect for
116              devices  of which ctrans has a function-callable interface. e.g.
117              X11 .
118
119       -pal pal_fname
120              Use the color palette defined in the file pal_fname  for  subse‐
121              quent  translation  of  the metafile. This palette will override
122              any color map  defined  by  the  CGM  being  translated.  For  a
123              description of the format of pal_fname see ras_palette(5NCARG).
124
125       -pause Pause after each frame in the metafile is displayed and wait for
126              the user to type a newline  before  proceding.  This  option  is
127              probably  only  useful  when  used  in conjunction with the -wid
128              option as this is  the  normal  behaviour  for  ctrans  in  most
129              instances.   This  option  and  the  -movie  option are mutually
130              exclusive.
131
132       -quiet Suppress reporting of non-fatal (warning) error  messages;  only
133              fatal error messages are reported.
134
135       -record
136              < record_number...  >
137              If  processing  only  single  frames of the metafile is desired,
138              this option specifies the record number containing the start  of
139              that  frame.   ctrans  assumes the processing is to start at the
140              first BEGIN PICTURE element in that record.  The user must  per‐
141              form  bookkeeping  to  determine  the  record  that contains the
142              desired   frame.    Normally,   a   metafile    editor    (e.g.,
143              ictrans(1NCARG).   may  be  used as the actual user interface to
144              perform this bookkeeping. Without  a  specified  record  number,
145              ctrans processes the entire metafile.
146
147       -soft  Unconditionally perform software filling of all filled polygons.
148              This option may be useful for devices which do not  support  the
149              filled polygon drawing primitive or have limits on the number of
150              vertices describing a polygon. On some devices  this  number  is
151              known and software filling is performed, as appropriate, without
152              user specification.
153
154       -verbose
155              Operate in verbose mode.
156
157       -Version
158              Print the version number and then exit.
159
160       -viewport llx:lly:urx:ury
161              Set the viewport of the output device. The viewport is the  rec‐
162              tangular region of the output device of which the virtual device
163              coordinate system of the metafile is mapped onto. Normally  this
164              region  is  the  largest device-addressable square which fits in
165              the center of the device address space. The -viewport option may
166              be  used to change the default mapping.  llx and lly specify the
167              lower left corner of the device in normalized coordinates.   urx
168              and  ury specify the upper right corner of the device in normal‐
169              ized coordinates.  For example, -viewport 0.0 0.0 0.5 0.5, spec‐
170              ifies the lower left corner of the device.
171
172       -window llx:lly:urx:ury
173              Specify  the workstation window (in the GKS sense). Four coordi‐
174              nates are specified which define a rectangular window which is a
175              subset  of the normalized VDC rectangle with corner points (0,0)
176              and (1.0,1.0).  llx and lly specify the lower left corner.   urx
177              and  .ury  specify the upper right corner.  The specified window
178              is mapped onto the entire display viewport. For example, if  the
179              workstation  window  is  defined  by the corner points (0,0) and
180              (0.5 0.5) then the lower left quarter of a plot would  be  blown
181              up  to fill the entire viewport.  Specification of such a window
182              can be used for zooming and panning.
183
184              The range with which one may zoom in on a plot may be limited by
185              the integer addressing precision of the device.
186

DEVICE-SPECIFIC OPTIONS:

188       The  following options are available when the device is graphcap-driven
189       (See the gcaps(1NCARG) command for a list of graphcap-driven devices):
190
191       -simulatebg
192              Simulate CGM background color requests by drawing a large filled
193              rectangle  of  the  appropriate color. This option is useful for
194              devices such as color PostScript printers which have no  concept
195              of background color.
196
197       The following options are available when device is CTXT:
198
199       -Data  Suppress  display  of  CGM  output primitive data. All other CGM
200              element data is displayed. This  may  substantially  reduce  the
201              verbosity of the clear text driver.
202
203       -Para  Suppress  display  of  CGM element data except for output primi‐
204              tives.  The -Data combined with the -Para option permit the dis‐
205              play of only the CGM element names.
206
207       The following options are available when device is X11:
208
209       -background color
210              Specifies the default window background color for color devices.
211              If the metafile explicitly sets color index 0 then  this  option
212              is overridden.
213
214       -foreground color
215              Specifies the default foreground color for color devices. If the
216              metafile explicitly sets color index 1 then this option is over‐
217              ridden.
218
219       -geometry geometry
220              Specify  the  size and/or position of the graphics window in the
221              format of an X11 Window System geometry string.
222
223       -ignorebg
224              Ignore requests to change the background color. This option  may
225              be  useful  when  ctrans  renders  into a X window created by an
226              application other than ctrans.  As a side effect of this  option
227              the rendering window is not cleared between frames.
228
229       -reverse
230              On monochrome devices reverse video is simulated by swapping the
231              foreground and background colors.
232
233       -wid window_id
234              Render into the previously created X window  specified  by  win‐
235              dow_id.   Normally  ctrans  creates its own window for plotting.
236              The window specified by window_id must be of  type  InputOutput.
237              The  window  must  also  have inherited its color map, depth and
238              visual class from the root window.
239
240              Note also that when this option is used ctrans cannot receive  X
241              events  from the drawing window. Hence, ctrans cannot use "mouse
242              clicks" as a signal to  advance  frames.  For  this  reason  the
243              -pause  option  is  useful to prevent ctrans from processing the
244              entire metafile without pausing between frames.
245
246              window_id may be specified as a decimal or hexidecimal integer.
247
248       The following options apply to the X11 color map management  of  ctrans
249       when device is X11:
250
251              ctrans supports three different methods of X11 color map manage‐
252              ment.
253
254              If the user specifies a  shared  color  map  (using  the  -scmap
255              option),  then  ctrans  will use the default X color map for the
256              screen, that is shared by all  applications.   If  the  metafile
257              contains  more  colors than there are available in the default X
258              color map, then a color matching  algorithm  is  employed.   The
259              idea of the algorithm is that the color in the current color ta‐
260              ble that is closest to the requested  color  will  be  selected.
261              Closest is defined in terms of the normal distance metric on the
262              RGB cube.  If the closest color is equal to or farther away than
263              the percentage error allowed ( -colerr ), then a warning message
264              will be printed.  The closest color is still used.
265
266              If the user specifies a private  color  map  (using  the  -pcmap
267              option),  then  ctrans  will  create a private color map for the
268              graphics window.  This will guarantee that 256  distinct  colors
269              are available to the window.  This means that the  X window will
270              have a different color map than all the  other  windows  on  the
271              screen. Therefore, you usually have to have the mouse pointer in
272              the window for the correct color table  to  be  installed.   One
273              disadvantage  to  this  option  is that there is usually a color
274              flashing effect on the screen since the wrong color  table  will
275              be installed for the other windows on the screen.
276
277              The  default  color  map  management scheme attempts to take the
278              best of the two previous models.  It starts  out  behaving  like
279              the  shared model, in that it uses the default color map for the
280              screen.  It differs in that, once it  can't  allocate  any  more
281              colors  from the default color map, in allocates its own private
282              color table and starts using it.  This way, the  color  flashing
283              is  only present if it absolutely needs to be so that ctrans can
284              display the correct color.
285
286       -scmap Ask ctrans to use the shared default X color map only.
287
288              This is the option used if -wid is specified.
289
290       -colerr n
291              Specifies the percentage color error that is acceptable  if  the
292              -scmap  option is being used.  If the color being used is n per‐
293              centage or more different from the color  requested,  a  warning
294              will be reported by ctrans.
295
296       -pcmap Ask ctrans to create its own X color map and use it exclusively.
297
298              This option is ignored if the -wid option is present.
299
300       The  following  options  are  available  when  device is a60, avs, hdf,
301       hppcl, nrif, sun, or xwd:
302
303       -dpi dpi
304              Specify the number of dots per inch. This option is  only  mean‐
305              ingful for the HP LaserJet, hppcl, which ignores the -resolution
306              option.  dpi may be one of 75, 100, 150, or 300.  The default is
307              150.
308
309       -direct
310              By  default  ctrans  outputs  raster  imagery with 8-bit-indexed
311              encoding. When this option is used, if the  raster  file  format
312              supports  it, raster imagery is output in a 24-bit-direct encod‐
313              ing scheme. Be warned: the resultant file  is  three  times  the
314              size of its 8-bit-indexed counterpart.
315
316       -landscape
317              Generate  the image in landscape mode. This option is ignored by
318              all raster devices except the HP LaserJet,  hppcl.   By  default
319              the LaserJet uses portrait mode.
320
321       -resolution widthxheight
322              width and height specify the spatial resolution in pixels of the
323              raster file to be created.  The default is 512x512.
324

EXAMPLES

326       To process a metafile named gmeta and display its contents on the  TEK‐
327       TRONIX 4107 terminal, use the following call:
328
329            % ctrans -d t4107 gmeta
330
331       If this device is already defined by the GRAPHCAP environment variable,
332       simply call:
333
334            % ctrans gmeta
335
336       If you wish to display only the  first  frame  starting  in  the  third
337       record, call:
338
339            % ctrans -record 3 -d t4107 gmeta
340
341       To examine the metafile gmeta's contents without CGM element data being
342       displayed:
343
344            % ctrans -d CTXT -Data -Para gmeta
345
346       To render the metafile gmeta (under X Windows)  in  a  window  that  is
347       512x512 pixels in dimension in the lower right corner of your screen
348
349            % ctrans -d X11 -geometry 512x512-0-0 gmeta
350
351       To  rasterize  the  contents  of  the metafile gmeta at a resolution of
352       1024x1024 pixels, call:
353
354            % ctrans -d xwd -res 1024x1024 > raster.xwd
355
356       The raster output is in X11 "xwd"  format  and  is  sent  to  the  file
357       raster.xwd.
358
359       To zoom in on the upper right quarter of the metafile gmeta and display
360       it in an X window, call:
361
362            % ctrans -d X11 -window 0.5:0.5:1.0:1.0
363
364

ENVIRONMENT

366       FONTCAP
367              Default fontcap specifier.
368
369       GRAPHCAP
370              Default output device specifier.
371
372       NCARG_ROOT
373              Path to root of NCAR Graphics installation.
374
375       NCARG_LIB
376              If set this variable contains the path  to  the  installed  NCAR
377              Graphics libraries.  NCARG_LIB overrides NCARG_ROOT.
378
379       NCARG_TMP
380              If  set,  this environment variable contains a directory path to
381              be used for temporary files. On  most  systems  the  default  is
382              /tmp.  On some systems the default is /usr/tmp.
383

FILES

385       $NCARG_ROOT/lib/ncarg/graphcaps/*
386                                     The binary NCAR Graphcap files
387
388       $NCARG_ROOT/lib/ncarg/fontcaps/*
389                                     The binary NCAR Fontcap files
390

SEE ALSO

392       fcaps(1NCARG),    fontcap(5NCARG),   gcaps(1NCARG),   graphcap(5NCARG),
393       idt(1NCARG), ras_palette(5NCARG), med(1NCARG), ictrans(1NCARG)
394
395       Hardcopy: NCAR Graphics Fundamentals, UNIX Version
396

CAVEATS

398       Running in "movie" mode may give surprising results on slower  devices,
399       such  as dumb terminals. If too short a time interval is specified slow
400       devices may not have finished rendering before the movie timer expires.
401       This results in no pause between frames.
402
403       Metafiles  which reference color table indices that were not previously
404       defined may have varying results from one device to the next.
405
406       Using the -wid option to have ctrans display its  output  in  a  window
407       created  by  another X application may produce unexpected results, par‐
408       ticularly with regard to color.
409
410       At ctrans' current level of implementation, the subset of CGM  elements
411       supported is closely approximated by the list provided in NCAR's Graph‐
412       ics Installer's Guide, Version 2.00 (August 1987).  However,  the  best
413       way  to  determine whether a particular CGM element is supported by the
414       translator is feed a metafile containing the  element  in  question  to
415       ctrans.   Consult  the  aforementioned  publication for a discussion of
416       Graphcaps and Fontcaps as well.
417
419       Copyright (C) 1987-2009
420       University Corporation for Atmospheric Research
421
422       The use of this Software is governed by a License Agreement.
423
424
425
426NCARG                            January 1993                   CTRANS(1NCARG)
Impressum