CTRANS(1NCARG)

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

💖 CTRANS 💖 — and yeah, it's from section 1NCARG of the NCAR Graphics manuals, bestie

okay so. sit down. hydrate. this one is a whole translator and she has OPINIONS.

✨ NAME ✨

ctrans — a Computer Graphics Metafile ( CGM ) translator. that's it, that's her. a whole icon whose entire personality is taking metafiles and making them make sense somewhere else 💅

✨ 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. she takes metafile(s) — a metafile being one of those things stored in the NCAR Computer Graphics Metafile (CGM) standard, iconic, we love her — and she interprets its instructions on whatever device the GRAPHCAP environment variable points at. fonts get stroked according to the specs living in the Fontcap file named by the FONTCAP environment variable. 🎀

by default she runs on Graphcaps — go peek at graphcap(5NCARG) — but she's also happy to do optional processing through libraries you provide, if your device needs that or you just want it. so basically: ctrans can drive ANY device that has a Graphcap available, and with some programming modifications she can accommodate any device that has an external library of plotting routines. iykyk. 🌈

currently these Graphcap-independent devices are supported: X11 under release 4 and 5, version 11 of X. periodt.

she can ALSO translate metacode into these raster formats: a60, avs, hdf, hppcl, nrif, sun and xwd. the device specifier for those raster formats is just the name of the format — like, -d xwd means translate to an xwd formatted raster file. and on top of all that there's a clear text driver, -d CTXT, that works on any terminal 🦋

⚠️ not every device listed above is necessarily supported by your particular configuration of ctrans. it's giving ✨custom build✨. for the list of what you actually have, run the gcaps(1NCARG) command.

also: ctrans reads from the standard input if you don't give her a metafile name, or if the name you gave her is -. simple as. 💖

✨ OPTIONS ✨

  • -bell — ring the bell at the end of each frame. default is silent mode, so if you want the little ding you have to ask for it. 🔔 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, 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, and 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. 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, 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, and 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 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 effectively insures that the maximum value for the CGM element "LINE WIDTH" is max.
💀 the results of setting max less then min are undefined. don't do it. i'm not joking. undefined is not a vibe.
  • -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 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.
  • -verbose — operate in verbose mode. she will simply tell you everything. 🗣️✨
  • -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 onto which the virtual device coordinate system of the metafile is mapped. 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.

and bestie… we're not done yet. keep scrolling 💜

🎀 DEVICE-SPECIFIC OPTIONS 🎀

Okay so bestie, here's the thing — some of these flags only exist for certain devices. It's giving ✨choose your own adventure✨. Here's the breakdown:

When your device is graphcap-driven (peep gcaps(1NCARG) for the whole list of graphcap-driven devices, iykyk):

  • -simulatebg — This one fakes out CGM background color requests by literally just drawing a big ol' filled rectangle in whatever color you asked for. Why? Because some devices — looking at you, color PostScript printers — have zero concept of what a background color even is. So we draw one. Slay 💅

When your device is CTXT:

  • -Data — Suppresses the display of CGM output primitive data. Everything else in the CGM element data still shows up. Lowkey this can make the clear text driver way less chatty, which is honestly a blessing 🙏
  • -Para — Suppresses CGM element data, except for output primitives. So if you pair -Data with -Para, you get only the CGM element names and nothing else. Minimalism, but make it technical ✨

When your device is X11:

  • -background color — Sets the default window background color for color devices. Heads up though: if the metafile explicitly sets color index 0, then this option gets overridden. The metafile said what it said 💀
  • -foreground color — Sets the default foreground color for color devices. Same deal: if the metafile explicitly sets color index 1, this option is overridden.
  • -geometry geometry — Lets you pick the size and/or the position of the graphics window, written in the format of an X11 Window System geometry string. Positional queen 👑
  • -ignorebg — Ignores any requests to change the background color. This is lowkey useful when ctrans is rendering into an X window that some other application created (not ctrans itself). Side effect alert though: with this option on, the rendering window does not get cleared between frames. Just so you know 🫶
  • -reverse — On monochrome devices, reverse video is simulated by swapping the foreground and background colors. Flip it, reverse it 🔄
  • -wid window_id — Renders into a previously created X window that you point at with window_id. Normally ctrans makes its own window to plot in, but not today bestie. A couple of rules though, no cap:
    • The window you specify with window_id must be of type InputOutput.
    • The window must also have inherited its color map, depth and visual class from the root window.

Also, important: when you use this option, ctrans cannot receive X events from the drawing window. Which means ctrans can't use "mouse clicks" as a signal to advance frames. For that exact reason, the -pause option is useful so ctrans doesn't just zoom through the entire metafile without pausing between frames.

You can give window_id as a decimal or hexidecimal integer 💖

Now for the color map management girlies — these options apply to ctrans' X11 color map management when the device is X11:

ctrans supports three different methods of X11 color map management. Let's get into it:

  1. Shared color map — If you specify a shared color map (with -scmap), then ctrans uses the default X color map for the screen, which is shared by all the applications. If your metafile has more colors than the default X color map has room for, a color matching algorithm kicks in. The idea is: whatever color in the current color table is closest to the color you requested gets picked. "Closest" is defined in terms of the normal distance metric on the RGB cube. And if that closest color is equal to or farther away than the percentage error you allowed (-colerr), a warning message gets printed. The closest color is still used anyway. It's giving "we tried our best" 😭
  2. Private color map — If you specify a private color map (with -pcmap), then ctrans creates a private color map just for the graphics window. This guarantees 256 distinct colors are available to the window. That means the X window will have a different color map than every other window on the screen. So you usually have to keep the mouse pointer inside the window for the correct color table to be installed. One disadvantage: there's usually a color flashing effect on the screen, since the wrong color table will be installed for the other windows. Chaos, but make it colorful 🌈
  3. Default scheme — The default color map management scheme tries to take the best of both previous models. It starts out behaving like the shared model, using the default color map for the screen. It differs in that, once it can't allocate any more colors from the default color map, it allocates its own private color table and starts using that. This way, the color flashing only happens if it absolutely has to, so that ctrans can display the correct color. Main character energy, honestly 👑
  • -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's acceptable when the -scmap option is being used. If the color being used is n percentage or more different from the color requested, a warning gets 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.

Last batch! These ones are available when the 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 btw. dpi can 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 you use this option, and if the raster file format supports it, raster imagery is output in a 24-bit-direct encoding scheme instead. ⚠️ Be warned: the resultant file is three times the size of its 8-bit-indexed counterpart. Three times. Not a drill 💀
  • -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. Rotate, bestie 🦋
  • -resolution widthxheight — width and height specify the spatial resolution in pixels of the raster file you want to create. The default is 512x512.

✨ EXAMPLES ✨

Wanna process a metafile named gmeta and see its contents on a TEKTRONIX 4107 terminal? Do this:

% ctrans -d t4107 gmeta

If that device is already defined by the GRAPHCAP environment variable, you can just go:

% ctrans gmeta

Wanna display only the first frame, starting at the third record? Say less:

% ctrans -record 3 -d t4107 gmeta

Wanna peek at the metafile gmeta's contents with no CGM element data showing?

% ctrans -d CTXT -Data -Para gmeta

Wanna render the metafile gmeta (under X Windows) in a window that's 512x512 pixels, down in the lower right corner of your screen?

% ctrans -d X11 -geometry 512x512-0-0 gmeta

Wanna rasterize the contents of the metafile gmeta at a resolution of 1024x1024 pixels?

% ctrans -d xwd -res 1024x1024 > raster.xwd

The raster output is in X11 "xwd" format and gets sent to the file raster.xwd. Clean 🧼

Wanna zoom in on the upper right quarter of the metafile gmeta and display it in an X window?

% 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 the root of the 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 you some surprising results on slower devices, like dumb terminals. If you specify too short a time interval, slow devices may not have finished rendering before the movie timer expires — and that means no pause between frames. Not the vibe you wanted 😭

Metafiles that reference color table indices that were not previously defined may have varying results from one device to the next. Every device is on its own journey, apparently 🦋

Using the -wid option to have ctrans display its output in a window created by another X application may produce unexpected results, particularly when it comes to color. Be careful bestie 🫶

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). But honestly? The best way to figure out whether a particular CGM element is supported by the translator is to just feed a metafile containing the element in question to ctrans. Consult that aforementioned publication for a discussion of Graphcaps and Fontcaps as well. Fr fr, just test it 💅

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

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

And that's a wrap on the whole page, bestie! This one's from the NCARG crew, dated January 1993, and it lives at CTRANS(1NCARG) in the manual. Go forth and translate those metafiles, you absolute legend 🎀✨💖
📦 where this page comes from