Provided by: ncl-ncarg_6.3.0-6build1_amd64 bug

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.