FIGURE

Figure makes figures and posters by drawing graphics and text together. You can include output from other Accelrys GCG (GCG) graphics programs as part of a figure.

DESCRIPTION

[ Previous | Top | Next ]

The Figure program displays a figure from a source file that you can create with a text editor. The source file can also be obtained as the output from any GCG graphics program. This source file contains commands for the Figure program as well as text for the figure itself. There are three kinds of commands you can use with Figure. The first kind is for line drawing. The second is for writing simple labels, and the third is for filling whole paragraphs within set margins. Most Figure commands, for instance .Draw, can be abbreviated with short commands like .D.

EXAMPLE

[ Previous | Top | Next ]

Here is a session using Figure to generate the plot printed at the end of this program entry in the Program Manual:

% figure

  FIGURE from what file ?  figure.figure

  When your LaserWriter attached to tty07 is ready, press <Return>.

OUTPUT

[ Previous | Top | Next ]

The output from this session is shown in the figure at the end of this program entry. Another figure is included that was drawn with the source file simple.figure.

RELATED PROGRAMS

[ Previous | Top | Next ]

Red is a text formatter that creates publication-quality documents on a PostScript printer such as the Apple LaserWriter. You can use 13 different fonts, scaling each font to any size. You can also include figures and graphics from any GCG graphics program within the text of the document.

The Figure program can be used to annotate and display the output of any GCG graphics program.

USING GCG GRAPHICS WITH FIGURE

[ Previous | Top | Next ]

Any GCG graphics program run with -FIGure on the command line writes a source file of plotting instructions (called a figure file) that can be used as input to Figure. You can use Figure's .Include command to include one figure within another (see the topic MISCELLANEOUS COMMANDS below).

An advantage of making figure files from GCG graphics programs is that you can store a graph and then replot it several times on different devices or make several copies of the same plot without having to redo an entire analysis.

SUGGESTIONS

[ Previous | Top | Next ]

Use Fetch to copy the file simple.figure and modify it with your text editor to get started. Use -GRId on the command line to see the coordinates of the platen.

INPUT FILE

[ Previous | Top | Next ]

A figure file is a list of commands and text that you create and modify with a text editor. The Figure program treats any line that has a period in the left-most column as a command. If your figure contains paragraph text, type it in any format after the commands that define the paragraph format. A paragraph stops at the first Figure command after the text itself. If you have experience with RUNOFF, you will find that figure files look very familiar.

You can use Figure's .Include command to nest one figure inside another. Included figures can be nested up to ten layers deep. You may also specify a smaller viewport in which to draw the included figure. Here is part of the input file from the example session:

 .! This is a FIGURE source file for the example in the Program Manual.

 .NoText

 .Include GenDocData:mountains.fig 95 150 34 66

 .Text

 .! Put a caption under the included figure.

 .NewColor 1

 .Location 122.5 34

 .TextOrg 6

 .Width 55

 .Center                                          ! justify

 .Spacing 3                                       ! between lines

 .CHeight 1.8

 .Font 3

 Include and shrink GCG graphics.  Annotate them with clever remarks.

 ////////////////////////////////////////////////////////////////////

 .Location 50 23

 .TextOrg 4

 .CHeight 2

 .Font 3

 .CAspect 0.6

 .NewColor 1

 Draw whatever you want with a full set of drawing and labeling commands.

 Make incremental improvements -- achieve PERFECTION!

 .! Add a little figure from the CIRCLES program.

 .NoText

 .Include GenDocData:circles.fig 97 142 65 95

THE DEVICE-INDEPENDENT PLATEN: PLATEN UNITS

[ Previous | Top | Next ]

GCG graphics programs draw on a rectangular platen that is 1.5 times as wide as it is tall. The platen is divided into what we call platen units (PUs). The vertical axis of the platen is 100 PUs tall and the horizontal axis is 150 PUs wide. The point (0,0) is the lower left corner of the platen, (150,100) is the upper right, (75,50) is the center. Be sure you know about the command-line parameter -GRId; it sets any GCG graphics program to draw graph paper ruled in platen units in the background of any GCG plot.

LINES

[ Previous | Top | Next ]

Lines, Symbols, and Curves

The .Move and .Draw commands move the pen and draw straight lines; the .Point command makes dots. Use .Symbol to draw symbols after setting the symbol size with .CHeight. The .NewColor and .LineStyle commands change the color and the line type. The .RelMove and .RelDraw commands move the pen and draw lines relative to the pen's current position. The .Set Center and .Curve commands draw circular arcs.

ViewPort and Window

You can select a portion of the platen with the .ViewPort command and impose a convenient coordinate system upon it with the .Window command if you don't like the 0-150 by 0-100 PU coordinate system.

Clipping

The .Clip command confines pen movement to positions within the current viewport. Use .NoClip to return to normal.

Ellipses

If you want to squash a circle into an ellipse, change the ratio of window units to viewport units on one of the coordinate axes.

Additional Pages

The .NewPage command gives you a fresh piece of paper or a blank screen at any time.

LINE COMMANDS

[ Previous | Top | Next ]

.Move or .m x y

moves to the point x,y without drawing a line.

.Draw or .d x y

draws a straight line from the current pen position to x,y. If you said .Clip, then pen movement is confined to the current viewport.

.Point or .p x y

draws a single dot at x,y.

.RelMove or .relm x y

like .Move, but moves relative to the current pen position.

.RelDraw or .reld x y

like .Draw, but draws relative to the current pen position.

.Symbol or .sy n

draws a centered symbol at the current pen position. The symbol size is controlled by the text style command .CHeight. The integer n can range from one to ten to specify which symbol you want plotted:

1 square
2 octagon
3 triangle
4 plus sign
5 cross
6 diamond
7 asterisk
8 vertical line
9 minus sign
10 square (without line from center to perimeter)

.SetCenter or .sc x y

specifies the center for use by the .Curve command. The point (0,0) is the default.

.Curve or .cu radius angle1 angle2

draws a curved line centered on the current center. The line is drawn counterclockwise from angle1 to angle2 at a distance of radius from the current center.

LINE STYLE SETTINGS

[ Previous | Top | Next ]

Line attributes like color, width, and style are stable until you reset them with the line-style commands.

.LineStyle or .ls style period

changes the line style used by .Draw so that lines of the same color can be distinguished. Period is the length, in PUs, of one pattern repetition. Style is an integer from one through seven as follows:

1 standard continuous line
2 dots at each end of repeat period
3 half-period dash
4 three-quarter-period dash
5 dash dot
6 dash short-dash
7 dash short-dash short-dash

Some plotting devices will not let you set the line style.

.NewColor or .nc color

changes the color of the pen. Color is an integer from one to the number of colors available on a particular device. We install our pens so that 1=black, 2=green, 3=blue, and 4=red.

.LineWidth or .lw width

changes the line width used by .Draw. Width is a real number from 1.0 through 10.0 in PUs. Many plotting devices do not yet support setting the line width.

COORDINATES

[ Previous | Top | Next ]

.ViewPort or .vp left right bottom top

defines a rectangle on the platen onto which you can map convenient units with the .Window command. The default viewport is the whole platen (0-150 by 0-100). Left, right, bottom and top are real numbers in PUs. Pen movement can be confined to the viewport with the .Clip command.

.Window or .wn left right bottom top

defines units (coordinate ranges) for the current viewport. Pen movement under the control of line commands such as .Move and .Draw is always specified in these new user-units. If you change the viewport, your user-units are mapped onto the new viewport without the need for another .Window command.

.Clip or .cl

confines pen movement to the current viewport.

.NoClip or .ncl

turns off clipping, allowing the pen to move outside the current viewport.

LABELS

[ Previous | Top | Next ]

Labels are text that can be written as a single line with a single character font, color, and size. Labels are plotted with the .PlotText command after setting any text attributes you wish to change.

Before using .PlotText, position the pen with the .Move command and choose its color with the .NewColor command.

You can select different fonts with the .Font command (see Appendix I). Text is plotted horizontally unless you change its angle with the .TextDir command. The .CHeight command controls the text size by adjusting the character height.

LABEL COMMANDS

[ Previous | Top | Next ]

Text attributes like font, size, aspect, and color are stable until you reset them with label commands.

.PlotText or .pt String

writes String at the current pen position, using the current settings for color, font, direction, origin, and size. String is simply all the text on the line after the .PlotText command.

TEXT STYLE SETTINGS

[ Previous | Top | Next ]

Text attributes like font, size, direction, aspect, and color are stable until you reset them with label commands. They apply to both labels and paragraphs.

.Font or .fo font

chooses a character font (see Appendix I). Font 0 (the label default) is whatever font is provided by the plotting device you are using. Fonts 1 through 22 are software-generated and appear the same on all of our devices. Font 0 cannot be used with paragraphs, so font 1 is the default here.

.TextDir or .td angle

changes the angle at which text is plotted. The default is .TextDir 0 for horizontal text. Angle is measured in degrees counterclockwise from three o'clock. With an angle of 180.0, you get upside-down text.

.TextOrg or .to origin

controls the label or paragraph's orientation with respect to the current pen position or bounding box location. Think of the text origin as one of nine points on a rectangle surrounding the label or paragraph:

3     6     9

2 T e 5 x t 8

1     4     7

So for text origin=5 (the default), the text is centered at the current pen position. For origin=1, the current pen position is at the lower left of the text rectangle.

.CHeight or .ch Height

sets the character height for uppercase letters.Height is a real number in PUs. The default is .CHeight 1.5.

.CAspect or .ca aspect

sets the character aspect ratio for subsequent calls to .PlotText. The aspect ratio is the character's width divided by its height. The default is .CAspect 0.6.

.CSlant or .cs slant

sets the character slant. This is the angle in degrees clockwise from vertical at which Figure draws the vertical strokes of characters. Horizontal strokes are not slanted so this command produces oblique characters, not rotated characters. The default on many graphics devices is .CSlant 10.0. Character slant is not implemented for character fonts other than Font 0 at this writing.

PARAGRAPHS

[ Previous | Top | Next ]

The Figure program can format paragraphs. The general approach is to define a rectangle called a bounding box, specify the ways in which text fills the box, and then fill it with text. Figure handles filling (word wrap) and justification within the bounding box. Text style attributes, like height, aspect, font, and color, that are fixed for label text, may be changed inside a paragraph.

Four commands define the bounding box on each paragraph. .Location establishes an anchor point for the box on the platen. .TextOrg defines where the anchor point is located on the box. With an origin of one, the paragraph grows above and to the right of the anchor. .Width selects the width of the bounding box in PUs. The height of the box is determined by the amount of text in the paragraph. The .TextDir command rotates the entire paragraph around its anchor point.

Six commands define the way the text fills the bounding box. .Spacing controls the distance in PUs between successive lines of text. The .Left, .Center commands, or .Right set the justification. If you use .NoFill, new lines occur in the plot exactly where they appear in your source file, and word wrap is disabled. Turn the word wrap on again with .Fill.

If Figure reads a line from your source file that is not a command, it assumes that it is a line of text and stores it. When Figure next finds a command in your file, it plots the stored text with either the default or newly specified characteristics. The commands that change character height, aspect ratio, color, and font may be embedded in the paragraph text: $H$ sets character height; $A$ sets character aspect ratio; $F$ changes fonts; and $C$ changes colors.

LOCATING PARAGRAPHS

[ Previous | Top | Next ]

.Location or .l x y

locates the anchor point of the bounding box on the platen. The x andy are in platen units. The relation of the bounding box to this anchor point is determined by the .TextOrg and .TextDir commands. The default is .Location 0 100, or the upper-left corner of the platen.

Important: the .Move command will not locate paragraphs.

.TextOrg or .to n

defines the point on the bounding box that corresponds to the anchor, or the direction away from the anchor that the paragraph expands as text is added. This is the paragraph analog of what .TextOrg does for labels. The default is .TextOrg 5, or the center of the bounding box.

.Width or .wd x

defines the width of the bounding box (its maximum line length) in platen units. The height of the box (number of lines) is determined automatically by the amount of text in the paragraph. The default is .Width 150, or the entire width of the platen. If filling is turned off, lines may overflow the width of the box, but the box still has meaning to the origin and justification settings.

.TextDir or .td angle

names the angle of rotation of the entire bounding box. Angle is measured in degrees counterclockwise from three o'clock. The default is .TextDir 0, or horizontal text.

.Spacing or .sp y

names the distance between lines of the paragraph in platen units. Naturally, some spacing greater than the character height produces the best results. The default is .Spacing 3.0.

JUSTIFYING PARAGRAPHS

[ Previous | Top | Next ]

You usually want to choose a justification that corresponds to the paragraph origin -- center justification with origins 4, 5, and 6; left for origins 1, 2, and 3, etc.

.Left or .lj

calls for left justification. Each line of the paragraph begins flush with the left side of the bounding box. The paragraph has a ragged right margin. This is the default justification.

.Center or .cj

calls for center justification. Each line of the paragraph is centered between the left and right sides of the bounding box.

.Right or .rj

calls for right justification. Each line of the paragraph ends flush with the right side of the bounding box. The paragraph has a ragged left margin.

.NoFill or .nf

turns off paragraph filling or word wrap.

.Fill or .f

turns paragraph filling back on again.

CHANGING TEXT STYLE WITHIN A PARAGRAPH

[ Previous | Top | Next ]

Paragraph style settings are described under the TEXT STYLE SETTINGS topic above. The commands described here let you change text characteristics within a paragraph. They are separated from their surroundings by blanks, just like any other word. They are distinguished from the rest of the text by the pair of dollar signs that enclose them.

$Hy$

changes the character height (in platen units) to y. The height should be less than the .Spacing between lines; the default is $H2.0$.

$Ax$

changes the character aspect ratio (width divided by height) to x. The default is $A0.6$.

$Cn$

changes the pen color to n. The default is $C1$, or black.

$Fn$

changes the character font to n. The default is $F1$, the Simplex Roman graphics font (see Appendix I).

TICKS

[ Previous | Top | Next ]

You can draw ticks along an axis with the .LabelTicks command. Ticks are styled according to global characteristics that are set before using the .LabelTicks command with commands like .TickSpace and .TickDivs.

.LabelTicks X1 Y1 X2 Y2 StartLabel EndLabel

labels ticks from the position (X1,Y1) to (X2,Y2). The ticks are styled with the global characteristics set up before using the .LabelTicks command. Always label ticks in an counterclockwise sense so that the labels point away from the data area into the surrounding space.

.TickSpace TSpace

sets the number of units per major tick toTSpace. The major ticks may or may not be numbered according to .TickLOrg.

.TickDivs NDivs

sets the number of divisions between major ticks to the integer number NDivs.

.TickLOrg origin

If you do not want to number the major ticks, set the integer origin to zero.

If you want to number the major ticks, this call controls the number label's orientation with respect to the end of each major tick. The label origin can be any one of nine points on a rectangle surrounding the number:

3     6     9

2 n n 5 n n 8

1     4     7

Usually you would use 2 for the right axis, 8 for the left axis, 6 for the bottom axis, and 4 for the top axis.

.TickLength TLen

sets the length of the major ticks to the real number TLen in the current unit system. Minor ticks are half as long as major ticks.

.TickAxis

draws a line along the whole extent of the ticked axis.

.NoTickAxis

does not draw a line along the ticked axis; the ticks just float in space.

MISCELLANEOUS COMMANDS

[ Previous | Top | Next ]

The following commands direct the figure generating process as a whole.

.Include or .i filename left right bottom top

suspends reading temporarily from the current input file and begins reading from file name. The optional viewport parameters following the file name replaces the default GCG platen with the smaller platen. This new platen is used until the included file ends, at which time the platen is restored to normal. Within the included file, any .Include or .ViewPort commands further subdivides the platen.

.NoText

disables all text plotting until the .Text command is found. This command is useful if you want to include GCG graphics output, but you don't want the original labels to show.

.Text

enables text plotting if it has been shut off with a previous call to .NoText.

.GoTo Address

suspends all activity and reads down in your file until a line begins with the comment .!Address. While creating a figure, you may want to skip over large parts of the figure that are correct while you fix small problems in one part of the figure.

.NewPage or .np

clears the graphics terminal screen or loads a new sheet of paper into the plotter. The behavior depends on the particular device being used. You only need this command if you draw on more than one page because Figure automatically initializes your first page.

GRAPHICS

[ Previous | Top | Next ]

GCG must be configured for graphics before you run any program with graphics output! If the % setplot command is available in your installation, this is the easiest way to establish your graphics configuration, but you can also use commands like % postscript that correspond to the graphics languages GCG supports. See Section 5, Using Graphics in the User's Guide for more information about configuring your process for graphics.

<CTRL>C

[ Previous | Top | Next ]

If you need to stop this program, use <Ctrl>C to reset your terminal and session as gracefully as possible. Searches and comparisons write out the results from the part of the search that is complete when you use <Ctrl>C. The graphics device should stop plotting the current page and start plotting the next page. If the current page is the last page, plotters should put the pen away and graphic terminals should return to interactive mode.

COMMAND-LINE SUMMARY

[ Previous | Top | Next ]

All parameters for this program may be added to the command line. Use -CHEck to view the summary below and to specify parameters before the program executes. In the summary below, the capitalized letters in the parameter names are the letters that you must type in order to use the parameter. Square brackets ([ and ]) enclose parameter values that are optional.

Minimal Syntax: % figure [-INfile=]figure.figure -Default

Prompted Parameters: None

Local Data Files: None

Optional Parameters:

-FRAme       draws a frame around each paragraph for debugging

-MARk[=n]    adds a file name in the lower right-hand corner

All GCG graphics programs accept these and other switches. See the Using

Graphics section of the USERS GUIDE for descriptions.

-FIGure[=filename]  stores plot in a file for later input to FIGURE

-FONT=3             draws all text on the plot using font 3

-COLor=1            draws entire plot with pen in stall 1

-SCAle=1.2          enlarges the plot by 20 percent (zoom in)

-XPAN=10.0          moves plot to the right 10 platen units (pan right)

-YPAN=10.0          moves plot up 10 platen units (pan up)

-PORtrait           rotates plot 90 degrees

LOCAL DATA FILES

[ Previous | Top | Next ]

None.

PARAMETER REFERENCE

[ Previous | Top ]

You can set the parameters listed below from the command line.

-FRAme

Draws a box around each paragraph as an aid in development. The frame shows the location, origin, width, and rotation of each paragraph at a glance.

-MARk=2

Shows the input file name and time in the lower-right corner of the plot. The optional value can be used to include more or fewer fields of the file name where -MARk=1 is the name only, 2 adds the extension, 3 adds the directory, 4 adds the disk, and 5 adds the version. Use -NOMARk to suppress this label altogether.

The parameters below apply to all GCG graphics programs. These and many others are described in detail in Section 5, Using Graphics of the User's Guide.

-FIGure=programname.figure

Writes the plot as a text file of plotting instructions suitable for input to the Figure program instead of sending it to the device specified in your graphics configuration.

-FONT=3

Draws all text characters on the plot using Font 3 (see Appendix I).

-COLor=1

Draws the entire plot with the pen in stall 1.

The parameters below let you expand or reduce the plot (zoom), move it in either direction (pan), or rotate it 90 degrees (rotate).

-SCAle=1.2

Expands the plot by 20 percent by resetting the scaling factor (normally 1.0) to 1.2 (zoom in). You can expand the axes independently with -XSCAle and -YSCAle. Numbers less than 1.0 contract the plot (zoom out).

-XPAN=30.0

Moves the plot to the right by 30 platen units (pan right).

-YPAN=30.0

Moves the plot up by 30 platen units (pan up).

-PORtrait

Rotates the plot 90 degrees. Usually, plots are displayed with the horizontal axis longer than the vertical (landscape). Note that plots are reduced or enlarged, depending on the platen size, to fill the page.

Printed: May 27, 2005 12:22

Technical Support: support-us@accelrys.com, support-japan@accelrys.com,
or support-eu@accelrys.com

Licenses and Trademarks: Discovery Studio ®, SeqLab ®, SeqWeb ®, SeqMerge ®, GCG ® and, the GCG logo are registered trademarks of Accelrys Inc.

All other product names mentioned in this documentation may be trademarks, and if so, are trademarks or registered trademarks of their respective holders and are used in this documentation for identification purposes only.