RALCGM(1) User Command (Local) 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 Page 1 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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. Page 2 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) (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. Page 3 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) -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 Page 4 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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 Page 5 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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 Page 6 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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 Page 7 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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: Page 8 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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. Page 9 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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 Page 10 (printed 12/23/92) RALCGM(1) User Command (Local) RALCGM(1) 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 ). Page 11 (printed 12/23/92)