Provided by: ncl-ncarg_6.6.2.dfsg.1-2_amd64 bug

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

              or

                   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

SEE ALSO

       ctrans(1NCARG),      fcaps(1NCARG),      gcaps(1NCARG),      idt(1NCARG),     med(1NCARG),
       ncarv_spool(5NCARG)

       Hardcopy: NCAR Graphics Fundamentals, UNIX Version

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.