RALCGM(1)

NAME
ralcgm - translate, view or print Computer Graphics Metafiles.

ORIGIN
Rutherford Appleton Laboratory

SYNOPSIS
ralcgm [ -btcnpixfev ] [ -d driver name ] [ -g gdp types ]
[ -l profile name ] [ -o driver options ]
[ -a terminal string ]
[ infilename ] [ outfilename ] [ errfilename ]

AVAILABILITY

This is RALCGM release 3.0 (man version 2.7). The source code of this program together with information on how to install it is available from the University of Kent.

DESCRIPTION

ralcgm is a program for:

    - translation between CGM encodings;
    - viewing CGM files on X Windows.
    - hardcopy output of CGM files on PostScript printers.
    - viewing CGM files on Silicon Graphics Iris 3130 or 4D
    workstation.
    - viewing a CGM file on a Tektronix 4200 series
    Terminal.
    - translating a CGM file to a Tektronix 4200 file.
    - converting a CGM file to a HPGL file.
    - viewing on an IBM PC or compatible with a VGA screen.

On the translation side, four encoding methods exist in ralcgm:

    - binary
    - character
    - clear text
    - native character output (non-ASCII machines only)

Any input CGM file can be translated to one of the above encodings by specifying options -b, -c, -t, -n respectively. Binary, character, and clear text encodings are as described in ISO 8632(1987) document. The native character encoding is a variant of the character encoding with input and output being treated according to the host machine's native character set, i.e. EBCDIC for the IBM machines.

The encoding method of the input CGM is automatically detected on entry. If an output encoding is specified, the input file is translated accordingly. If no output encoding option is specified, a system dependent default (determined by the installer at the compilation time or by setting an environment variable) is chosen. For instance, where X-windows has been selected as the system default, the CGM file will be viewed in an X window. The normal default is clear text encoding to standard output.

All of the filename arguments are optional, and they have to appear on the command line in the order described in the synopsis. If none of the filename arguments is present, ralcgm reads from standard input and writes to standard output, or sends the picture to the screen, depending on whether translation or viewing is required. On some non-unix systems (VMS and CMS) piping from stdin is not allowed. All diagnostics and error messages are sent to the standard error stream.

If a number of filename arguments are given, the first argument will be taken to represent the input file name, second the output file name, and the third the error file name. An extension of cgm is assumed if no file extension is specified.

To view a CGM file in a X Windows environment, GL Window or on a terminal, invoke ralcgm by selecting the option -d driver , where driver is the name of the output device as specified below.

ARGUMENTS

infilename - optional input file name.
outfilename - optional output file name.
errorfilename - optional error file name.

OPTIONS

Options may appear anywhere on the command line and single character options may be grouped together, as long as each set of options starts with a '-'. If an option has an extra data string this must follow the option, with or without a seperating space, and must terminate the group. All single character options may be either upper or lower case.

-b  translate input CGM into binary encoding.

-c  translate input CGM into character encoding.

-n  produce native character set version of input CGM's character encoding.

-t  translate input CGM into clear text encoding.

-p  convert input CGM to PostScript. The PostScript output can be directed to standard output or a named file, and subsequently printed out on a PostScript printer. (This option has been replaced by the -d ps option, but is retained for compatability.)

-i  display input CGM using the Iris Graphics Library (applicable to the Silicon Graphics Iris Workstations only). (This option has been replaced by the -d igl option, but is retained for compatability.)

-x  display input CGM using X-windows (applicable to the X-windows environment only). (This option has been replaced by the -d xw option, but is retained for compatability.)

-a terminal string
    (Applicable to the X Windows environment only). This option will pass the terminal string specifing the host and the default display device for the X Window environment. Note that the terminal string is case dependent.

-e  ignore error count limit (16 by default).

-f  sends diagnostic and error messages to a file. If no error filename is given the default is to send to a file with the root of the input file and a suffix of .err.

-v  use verbose mode. This causes diagnostic messages to appear on the standard error stream.

-g gdp types
    Generalized Drawing Primitive Identifiers may be non-negative or negative. Non-negative values are reserved for ISO registration and future use, and negative values are available for private use. No GDP identifiers have been registered yet, hence non-negative GDP identifiers are illegal. A number of packages generate negative GDPs. At present ralcgm can only interpret those that have been generated by RAL-GKS. Specifying -g RAL or -g ral will turn this feature on. By default, negative GDPs are treated as errors.

-l profile name
    This flag is used to define a profile.

    At present the only profile supported is oldbin , which allows ralcgm to read Binary CGMs produced by RAL-CGM version 2.00 and earlier. These CGMs have wrongly coded negative integers. Only use this flag if there are problems reading a CGM as not many CGMs contain negative integers.

-d driver name
    To allow for a larger range of drivers than are allowed by single character codes, drivers may be specified by name. The following names are recognised where capital letters indicate the minimum abbreviation:

    CHaracter
        Character encoding

    Native
        Character encoding (native)

    CLear Text or TEXt
        Clear Text encoding

    Binary
        Binary encoding

    Postscript or PS
        PostScript

    Xwindows or X11
        X-Windows (release 11.4)

    Igl or IRIS
        Iris Graphics Library (GL2)

    Hpgl
        HPGL

    TEKtronix
        Tektronix 4200 series (including EMU-TEK)

    Vga PC VGA screen

-o driver options
    This option allows driver dependent options to be specified as as single string which is interpreted by the output driver. Options may be case dependent for some drivers. Currently the following options are recognised:

    Applicable to PostScript driver only.

    -o[BFCMENIVPLQ]
        where any combination of single characters (case independent) can be specified, from each of the following pairs of mutually exclusive options:

        B   Ignore Background Colour setting. This is needed when a black background is put in the CGM for screen output and the foreground colour is not set, which would normally result in the output consisting of a Black square with all drawing done in black.

        F   Respect Background Colour setting (default).

        C   Colour PostScript.

        M   Monochrome PostScript (default).

        E   EPSF (Encapsulated PostScript).

        N   Normal PostScript (default).

        V   Add Picture border.

        I   Do not print Border (default).

        P   Portrait mode (default).

        L   Landscape mode.

        Q   Output for extended A4 on a QMS plotter. This gives a larger plotting area than the default.

    Applicable to Iris Graphics Library only

    -o[DSBMCFTVP]
        where any combination of single characters (case independent) can be specified.

        D   Use double buffer mode for graphics display. This means that the process of updating the graphic screen is done off-screen and will only become visible when a picture is complete.

        S   Use single buffer mode for graphics display (default). Also stop after each frame.

        M   Movie mode. Do not pause between frames and use double buffered mode.

        C   Continuous mode. Do not pause between frames, but do not use current buffered mode, unless D is also set.

        B   Single Buffer mode. Same as S option, but does not disable movie mode.

        F   Full screen mode. In full screen mode no textport is displayed. This prevents diagnostic messages appearing on the screen.

        T   Textport on. In full screen mode the textport is displayed to the right of the screen.

        V   Virtual 24-bit Colour mode for Iris Indigo (Default for direct colour)

        P   Pseudocolour mode for direct colours, rather than Virtual 24-bit mode.

    Applicable to HPGL only

    -o[34PLCN]
        where any combination of single characters (case independent) can be specified.

        3   Use A3 paper

        4   Use A4 paper (default)

        P   Portrait mode (default)

        L   Landscape mode

        C   Output printer initialisation controls (default)

        N   Do not output printer initialisation controls

    Applicable to Tektronix 4200 Terminal only

    -o[NC]
        where any combination of single characters (case independent) can be specified.

        N   Use 16 colours ie 4 bit-planes (default)

        C   Use 256 colours rather than default of 16. This only applies to terminals with more than 4 bit-planes.

    Applicable to PC (VGA) only

    -o[HL]
        where a single characters (case independent) can be specified.

        H   Use High Resolution mode (default) - 760x480 pixels with 16 colors

        L   Use Low Resolution mode - 480x360 pixels with 256 colors

ENVIRONMENT

Ralcgm recognises various environment variables to override default options. The following Environment variables are recognised:

CGMDATA pathname
    A directory name to overridew the default data directory pathname (specified at installation time). Note that the name must include the trailing delimiter ('/' on Unix systems).

CGMMENUFONT font (X-Windows only)
    Override default font used by X-Window menus.

CGMOUTPUT driver name
    A text string specifying the Output driver as listed in the '-D' option above, plus the 'CHaracter', 'Native', 'CLeartext', 'Text' or 'Binary' for translators.

CGMERRCOUNT num
    A number to indicate the number of errors before RALCGM aborts processing. Setting CGMERRCOUNT to 0 will prevent aborting.

CGMPSOPT option list
    PostScript options. See '-O' option above.

CGMIGLOPT option list
    Iris Graphics Library options. See '-O' option above.

CGMHPGLOPT option list
    HPGL driver options. See '-O' option above.

CGMTEKOPT option list
    Tektronix 4200 driver options. See '-O' option above.

CGMVGAOPT option list
    VGA Screen driver options. See '-O' option above.

CGMGDP gdptype
    A text string to set a default GDP type. See option '-G' above.

CGMVERBOSE on | off
    See option '-V' above.

CGMHPGLn + 4 floating point numbers
    where n is a pen number. HPGL Pen description (red, green, blue values in range 0.0 to 1.0 plus pen width in mm).

CGMPROFILE profile type
    specify a Profile type. see option '-L' above.

X WINDOWS VIEWER COMMANDS

To display a CGM file in an X window, invoke the ralcgm program (with X running) selecting the appropriate option and passing the CGM file name as the first argument, e.g.
    ralcgm -d xw map.cgm

This displays the picture in a window with the current frame number and title printed in the title window (the invoking X terminal acts as a console for ralcgm interpreter messages). There are four title window buttons for controlling the display sequence, a pop-up button box to manipulate scaling and translation of any part of the picture within the window, and a pop-up keypad to display a randomly chosen frame.

The title window buttons are:

    nx  display next frame

    pr  display previous frame

    cu  re-display current frame

    ab  abort current frame

    The buttons set and the keypad are invoked by clicking different mouse buttons. Here, the mouse button will be referred to as button 1, button 2 and button 3 for left, middle and right button respectively. To move through the CGM file frame by frame, pick appropriate title window button and click mouse button 1.

    To select a random frame, click button 1 on the picture window to raise the keypad. Select frame number by clicking on the appropriate digits, and then pick D. Picking D with no number selected drops the window. Picking C clears the number selected.

    If a frame beyond the end of the file is selected, the last frame will be displayed. If a frame before the first frame in the file is selected, the first frame will be displayed.

    The set of pop-up buttons is invoked by clicking button 2 in the picture window. To select any of the items in the set, click button 1.

    The set of items includes:

        copy
            Creates new display windows showing the same frame as the present window. New windows can be used independently in the same way as the original ones.

        bigger
            Makes the picture bigger. Use the mouse to define two points at opposite corners of a rectangle which is then expanded as much as possible (see note on dragging the mouse below).

        smaller
            Makes the picture smaller. Use the mouse to define two points at opposite corners of a rectangle. The picture will then be compressed into the defined rectangle.

        move
            Moves the frame in the window. Define two points - the first is moved to the second.

        normal
            Restore picture to normal size and position.

        close
            Remove this window but leave others.

        finish
            Close all windows and terminate program.

        drop
            Remove the menu with no action.

    For bigger, smaller and move you must define two points on the screen. To do this, depress button 3 at one point, drag the mouse to the other point and then release the button. Move is operated in a similar manner, with first point as the anchor point and the second point as the destination of the specified anchor point.

    Note: There is no rubber banding when dragging the mouse button, so the user has to estimate the result of the scaling and moving while dragging the mouse with button 3 depressed.

IGL VIEWER COMMANDS

On the Silicon Graphis Iris 3130, there are two modes of working, Full screen mode or Window mode (mex). The RAL-CGM interpreter will work in either mode, but the control is slightly different. On the Iris 4D only the Window mode is used.

In both modes the left mouse button is used to pause the current frame and if the middle mouse button is pressed while the left button is held down then the frame is aborted, otherwise a second left button will continue processing.

In full screen mode, unless in movie mode, at the end of each frame a 'beep' will sound and pressing the left button will advance to the next frame. Pressing the middle button will prompt for a frame number, unless the left button is held down at the same time, in which case the program will be aborted. In movie mode, a left button will interupt the program, which can then be controlled as above.

In window mode at the end of each frame a pop-up menu will appear, which is controlled by the right mouse button. This menu give you the options:

Next
    next frame

Redraw
    redraw current frame

Last
    return to last frame

Find
    displays a second menu to choose a frame number

Quit
    exit program

To use the second menu click the right mouse on each digit until the required number is displayed in the 'Frame' box, then select the 'Frame' box. Use the 'undo' box to delete the last digit.

TEKTRONIX VIEWER

The Tektronix has only a very basic control, which issues a prompt at the end of each picture. The allowable replies are 'Q' to quit, or anything else to continue.

EXAMPLES

ralcgm ship.bin -t clear
    will create a CGM file clear which will contain the clear text encoding version of the input CGM ship.bin.

ralcgm -d xw ship.clear
    will view ship.clear in an X window.

ralcgm -d ps ship laser.ps
    will produce a PostScript version of ship.cgm, in file laser.ps.

DIAGNOSTICS
As soon as the input encoding is recognized, a message to that effect is sent to standard error if verbose mode is chosen. Three levels of error severity exist. Fatal errors abort the program; errors and warnings do not. Messages are sent to the standard error stream.

BUGS
Some CGM Metafile Descriptor elements are ignored. Particularly Polygon Set and Auxillary colour are not handled on most drivers. Correct Pattern Filling for User defined patterns is not yet supported.
Complicated Polygon Sets may hit the ceiling of available memory when processed by the PostScript interpreter.
The Tektronix does not support Hatch fill and HPGL will currently only Hollow fill.
Convex Polygons are not displayed correctly using the Iris Graphics Library. Also Direct colours are not support if less than 24-bit planes are available, except on an Iris Indigo which uses the Virtual 24-bit system.

AUTHORS
R T Platon ( RAL CCD ) is the original author. Contributors: C D Osland, A R Mayhook, C D Seelig, K E V Palmen, N M Hill, W M Lam (all from RAL CCD ); P L Popovic and W K Lui ( RAL ID ); A H Francis ( Page Description ).