


     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)



