ICTRANS(1NCARG)

📦 version 6.6.2, in epel 9, fedora 43, fedora 44

🎀 ictrans — ICTRANS(1NCARG), NCAR GRAPHICS ✨

okay bestie, welcome to the manual page for ictrans, the interactive NCAR CGM translator 💅 it lives in the NCAR GRAPHICS manual, section 1NCARG, and it's basically the glow-up front-end for ctrans. let's get into it 🫶

✨ NAME ✨

ictrans — the interactive NCAR CGM translator, aka 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 🌸

so. ictrans is the user interface to the Computer Graphics Metafile (CGM) translator ctrans. the way that it works is: the second you invoke it, ictrans drops into command interpreter mode and just… waits for you to tell it what to do 👑 while it's waiting for commands from you, it shows you this prompt:

ictrans>

main character energy, honestly.

On invocation, ictrans also does a whole configuration ritual for its spooled device table — and it builds that table by processing several sources, in order, no skipping:

  1. first it hunts for the file ncarv_spool in the $NCARG_ROOT/lib/ncarg directory. if that file exists, ictrans loads it into the spooled device table.
  2. next, it hunts for the file .ncarv_spool in your home directory. if it finds it, its contents get merged into the spooler table.
  3. finally, the NCARV_SPOOL environment variable may contain the definition for a single spooler. if that variable is set, its contents also get merged into the table.

Every entry in all of those sources is identified by a name. and if there's a name conflict? the last entry encountered wins — like, the previous entry of the same name gets overridden. periodt. 💅

🔥 OPTIONS 🔥

  • -bell — ring the bell at the end of each frame 🔔 the default is to run in silent mode. not every device supports this option, so don't be shocked (pun intended) if it does nothing.
  • -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, and 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 get 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, so those are not influenced by fontcap specifications. also note 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, and 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 than min are undefined. like, genuinely undefined. don't do it, bestie 😭
  • -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.
  • -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. that's it, that's the whole thing 💖

🦋 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).

and yeah, that's only part one, bestie — there's more coming 👀💜

🌸 COMMANDS 🌸

✨ Command Structure ✨

okay so bestie, ictrans commands are so regular, it's giving clean girl aesthetic 💅 Every command has the same lil shape. Commands that work directly on the metafile you're processing can be preceded by a frame_list telling them which frames they apply to. Some commands take arguments. And literally anything that comes after a command name? That's an argument, periodt:

( frame [  ,frame ])* command  ( argument )*

A comma-separated pair of frames means the inclusive list of frames, no cap. If you skip the frame list and the command needs a frame, it just uses the current frame as the default. And if you skip the argument list when one's required, a default argument gets used whenever that's even possible 🫶

So like, 1,5 8 save /tmp/foo would write the first through fifth frame and the eighth frame of the metafile out to the file /tmp/foo. Iconic.

Commands will ignore any unexpected arguments (rude of you to send them, honestly). And command names can be abbreviated up to the point where they're unique 🔥

🌈 Frame Lists 🌈

You can address frames in several ways, bestie:

  • nnn — by frame number. Frames get a relative number from first to last in the metafile, and the first frame is numbered 1.
  • $ — the last frame in the file.
  • . — the current frame. ictrans keeps track of the last frame an operation was performed on, and that 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 that indicated number of frames. frame can be omitted, in which case the current frame is assumed. So 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 a 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] — sets how many times each frame gets displayed during subsequent plotting. Default is one. If you invoke dup with no arguments, it hands you back the current value of dup 🫶
  • count — reports the 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 do filename substitution on metafile. The rules governing filename substitution are exactly as defined by the working shell. If you give no argument, the current metafile name gets reported.
  • font [ font ] — set the fontcap to font for future translation. This function is identical to the one from 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, you get a brief description of all the commands 🌸
  • [ frames ] list — give brief info about each metafile frame in frames. If frames is omitted, the current frame is used. If frames is omitted and the current frame isn't the last frame, 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 that 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 you expected — attributes from the first frame, like 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 (or last through first) frames. Looping continues until an interrupt signal is received. How it decides which way to loop, forwards or backwards, goes like this: 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 can't 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 at all — because the last group of frames plotted, 1, is a single frame 💀
  • movie [ time ] — display each frame for time seconds before proceeding to the next frame during subsequent plots. If time is omitted, movie mode gets toggled off or on. If 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, 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 an 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. bye bestie 👋
  • [ frames ] save [ metafile ] — save the addressed frames to metafile. If metafile doesn't exist, it's created. Filename substitution is performed on metafile. If metafile is omitted, the last file saved to is used. If frames is omitted, the current frame is used.
  • [ frames ] Save [ metafile ] — same as the save command, except Save does not confirm its actions with you when the file already exists. If the file exists but isn't a valid NCGM, it gets overwritten. If the file exists and is a valid NCGM, it gets appended to.
  • skip [ number ] — set the number of frames to skip over during subsequent plotting. So 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 lets you specify a workstation window (in the GKS sense). Four coordinates are specified, which define a rectangular window that's a subset of the normalized VDC rectangle with corner points (0.0, 0.0) and (1.0, 1,0). That 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. Specifying a window like this 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 nor TMPDIR is set, a site-dependent, hard-coded default is used.

💾 FILES 💾

ok so here's where your config lives, bestie:

  • $NCARG_ROOT/lib/ncarg/ncarv_spool — the local ictrans spooler config file, aka the site-wide one
  • ~/.ncarv_spool — your very own user's ictrans spooler config file 🎀

👀 SEE ALSO 👀

go read these next, fr fr:

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

Hardcopy: NCAR Graphics Fundamentals, UNIX Version — yes, actual paper, iconic behavior 📄✨

⚠️ CAVEATS ⚠️

ok so listen up because this one matters: metafile frames that get written to an existing file via the save command will be subject to the effects of any global "attribute elements" contained within the file. like, the file's existing global vibes will absolutely influence your new frames. no cap. 🙈

Copyright (C) 1987-2009
University Corporation for Atmospheric Research

The use of this Software is governed by a License Agreement.

and that's the whole page, bestie!! 🫶 this one's from the NCARG crew, dated January 1993, and it's filed under ICTRANS(1NCARG) — go forth and translate those metafiles, you absolute main character 💅✨🌈

📦 where this page comes from