graphics

workstation

• render graphics output
• store graphics output
• obtain graphics input

Examples are an X-terminal, a printer, a PostScript file, a mouse or a set of crosshairs.

In interactive jobs, Garfield by default usually has only X-terminal output, while in batch it will have only PostScript output.

These defaults can be changed both with the command line line arguments -terminal and -metafile and from the running program via the commands described below.

Workstations can be in 3 states in Garfield, 2 of which are also in the GKS definition:

defined

A workstation in state "defined" does not receive graphics output, but its description (type, name of file associated with it, address etc) is available. A file associated with a workstation in this state is not open, nor is a graphics output window displayed.

open

The same state as "defined" except that a file associated with such a workstation is open. Also graphics output windows are open. However, neither the file nor the graphics window receive output.

active

In this state, a file and a graphics window do receive output.

Moving between the 3 states is accomplished with the following set of commands:

ACTIVATE-WORKSTATION

A workstation that is to be activated, must already be "open". If you try to activate a workstation that is "defined" but not "open", then an implicit !OPEN-WORKSTATION is performed.

After this operation, the workstation is in the GKS state "active" which means that it will receive graphics output. The workstation can then be deactivated with !DEACTIVATE-WORKSTATION.

The argument is an alphanumeric string designating the workstation, Usually, this will be the name that you gave to the workstation when issuing a !ADD-WORKSTATION command, but this can also be one of the two workstations that can be predefined: TERMINAL and METAFILE. Whether these 2 are defined or not depends on the mode in which you run Garfield.

Format:

! ACTIVATE-WORKSTATION workstation

Example:

! deact metafile
(make some plots)
! act metafile
(make final version of plots again)

You do not wish to fill the metafile with useless plots. Therefore, you first make a few tests without metafile active and once you are happy with them, you activate the metafile and make the plots again.

ADD-WORKSTATION

Up to two workstations can be predefined in Garfield: TERMINAL and/or METAFILE. You can manipulate them like any other workstation.

After !ADD-WORKSTATION, the workstation is in the state 'defined', which in GKS terminology means that the workstation is neither 'open' nor 'active'. Thus, the workstation will not receive any graphics output until you have used !OPEN-WORKSTATION and !ACTIVATE-WORKSTATION to first open and then activate the newly defined workstation.

A workstation displays can as a rule handle both input and output, and the output that is sent there will as a rule not be stored. The first format below deals with this situation.

Output-only workstations, second format, are associated with a graphics file which will store the images. By default, it is assumed that one file can contain any number of images. Use the SINGLE-FRAME-FILE option in case the output format you wish to use can only deal with a single image per file.

In both formats, either the type (e.g. "inquire" for X-windows inquiry at startup, or "EPS" for Encapsulated PostScript ) or the GKS identifier (the driver number) must be specified, but not both.

Format for input/output workstations:

! ADD-WORKSTATION name [TYPE  type  |  GKS-IDENTIFIER  identifier] ...
                       [CONNECTION-IDENTIFIER  connection]

Format for output (metafile, PostScript etc) workstations:

! ADD-WORKSTATION name [TYPE  type  |  GKS-IDENTIFIER  identifier] ...
                       FILE-NAME  file ...
                       [OFFSET  offset] ...
                       [MULTIPLE-FRAME-FILE | SINGLE-FRAME-FILE]

Examples:

!add postscript type ps file-name garfield.ps

This instruction adds a PostScript formatted metafile.

Global quencher `CH4`
Global ps True
If ps Then
   !add meta type PostScript file-name "gain_{quencher}.ps"
   !open meta
   !act meta
Endif

...

If ps Then
    !deact meta
    !close meta
    !del meta
Endif

The name of the PostScript file is made to depend on the quencher gas which is used. Note the use of substitution using curly brackets.

Additional information on:

ARROW-TIP-ANGLE

The angle should be entered in degrees.

Format:

!ARROW-TIP-ANGLE  angle

Example:

!arrow-angle 60

This would make the tip angles twice the default.

[The default setting is 30\°.]

ARROW-TIP-LENGTH

The length should be specified either as an absolute length in normalised device coordinates (in which the screen has a width and height of 1) or as a fraction of the total length of the arrow, in the range 0 (excluded) to 1 (included).

Format:

!ARROW-TIP-LENGTH length [RELATIVE | ABSOLUTE]

Example:

!arrow-length 0.2

This would make the tip a bit shorter than the default.

[The default setting is 0.3, relative.]

BARCHART-WIDTH

The width should be specified as a fraction of the maximum bin width, in the range 0 (excluded) to 1 (included). The bars touch if set to 1, effectively producing an histogram.

Format:

!BARCHART-WIDTH fraction

Example:

!bar-w 0.5

This would make the bars much more narrow than default.

[The default setting is 0.9.]

CLEAR-SCREEN

Format:

!CLEAR-SCREEN

CLOSE-WORKSTATION

Before !CLOSE-WORKSTATION, the workstation should be in the state 'open', afterwards it is in the state 'defined'. It can be re-opened with !OPEN-WORKSTATION and then be activated with !ACTIVATE-WORKSTATION.

Any metafile attached to the workstation being closed, will first be completed with any data that might still be buffered and then the file will be closed. The file will be overwritten if you perform an !OPEN-WORKSTATION on the same workstation.

If !CLOSE-WORKSTATION is invoked for a workstation that is still in the state "active", then !DEACTIVATE-WORKSTATION will automatically be called before closing the workstation.

Format:

! CLOSE-WORKSTATION workstation

Example:

!close metafile

This will deactivate workstation METAFILE if still active, then close the workstation and close the file receiving the graphics output.

COLOUR

Each workstation has (at least) two predefined colours: the colour used by default for all items: FOREGROUND and the screen which is in BACKGROUND, items plotted with this colour are therefore normally invisible.

For each additional colour, you have to state how much red, blue and green there is in it.

Use the MAP-COLOURS graphics command to inspect graphically the colours which are currently defined.

Format:

! COLOUR colour_name {RED red BLUE blue GREEN green | ...
                      RGB hex}                        ...
                     [WORKSTATION wkid]

Examples:

! COL RED BLUE 0 GREEN 0 RED 1
! COL LIGHT_BLUE BLUE 1 RED 0 GREEN 1

Additional information on:

CONTOUR-PARAMETERS

However, if the area over which the contours are to plotted is much smaller than 1, then contours will occasionally be "jumping" from one contour segment to another, with the default set of parameters. This can be cured by lowering the \ε parameters by a factor of 10.

Contour plotting works as follows:

1. the GRID is scanned to find grid points between which a contour is expected to pass;
2. if a contour passes between 2 neighbouring grid points, first a bisection search and then a Newton search are performed to find an accurate point on the contour;
3. at each point on the contour, the gradient is computed, a step perpendicularly to the gradient is taken, where the gradient is again computed along which a Newton search is made to find the contour back;
4. tracing is terminated when either of the following conditions is fulfilled:
   • the maximum number of steps is reached;
   • the contour passes a second time its starting point;
   • the contour leaves the area, enters a wire etc.;
   • no continuation of the contour can be found.

Format:

! CONTOUR-PARAMETERS [ BISECTION-ITERATIONS n_bisection ] ...
                     [ EPSILON-GRADIENT \ε-gradient ] ...
                     [ EPSILON-TRACING \ε_tracing ] ...
                     [ GRID-TOLERANCE tol ] ...
                     [ NEWTON-ITERATIONS n_Newton ] ...
                     [ STEP-MAXIMUM steps ]

Example:

area -0.01 -0.01 0.01 0.01
!cont-par eps-gra 1e-4 eps-tra 1e-4
plot cont V

Since the area is small, the step size scaling factor for computing gradients and for making steps perpendicular to the gradient are reduced to 10\<SUP\>-4\</SUP\>.

Additional information on:

DEACTIVATE-WORKSTATION

After this operation, the workstation is in the GKS state 'open'. This means that it will still be known to Garfield and GKS, but it will not receive any graphics output. The workstation can then be closed via !CLOSE-WORKSTATION or re-activated by !ACTIVATE-WORKSTATION.

A workstation can only be deactivated if it is in the "active" state.

This instruction is used to disable temporarily graphics output to the metafile (e.g. when you wish to optimise some parameters without getting a huge metafile) or to the terminal.

Format:

! DEACTIVATE-WORKSTATION workstation

Example:

! deact terminal

Temporarily suspends graphics output to the terminal.

DELETE-WORKSTATION

Before this operation, the workstation should be in the state "open". If !DELETE-WORKSTATION is invoked for a workstation that is still in the state "open" or "active", then !CLOSE-WORKSTATION will automatically be called before deleting the workstation.

After this operation, all information about the workstation is lost. A workstation can therefore not be re-opened or re-activated after a !DELETE-WORKSTATION - it would first have to be re-added to the workstation table with !ADD-WORKSTATION.

!DELETE-WORKSTATION does not delete a metafile that might be attached to the workstation.

Format:

! DELETE-WORKSTATION workstation

Example:

!delete metafile

You opened the metafile by accident and decide you don't need a metafile at all during this run.

EXIT

Format:

EXIT

GET-COLOURS

The representation and colour tables are closely connected. When retrieving representations and colours, the recommended approach is to first read the colours and then the representations. Since the representations contain a colour sequence number (assigned on the basis of the colour table present when processing REPRESENTATION statements) rather than a colour name, reading a new colour table without updating the colour references in the representation table, can create incorrect colour references. Representation files do contain colour names, ensuring correct references.

You may modify colours after having retrieved them from a file - modifications of colours do not change their sequence number.

Format:

! GET-COLOURS file [member]

Examples:

!GET-COL TEST PARROT

Picks up the member PARROT on dataset TEST.

Additional information on:

GET-REPRESENTATION

Be sure that all colours that are referenced by the representations in the file, are defined before issuing a !GET-REPRESENTATION command. In practice, this means that GET-COLOURS commands should precede !GET-REPRESENTATION commands. Items that reference an undefined colour will be shown with a colour set to FOREGROUND.

Format:

! GET-REPRESENTATION file [member]

Example:

!GET-REP TEST MG*

Picks up the first member that matches MG*, presumably MG600.

Additional information on:

INQUIRE-DEFERRAL-UPDATE-STATE

Format:

! INQUIRE-DEFERRAL-UPDATE-STATE

Example:

!inq-def

INQUIRE-LEVEL

Format:

!INQUIRE-LEVEL

INQUIRE-OPERATING-STATE

Format:

!INQUIRE-OPERATING-STATE

INQUIRE-WORKSTATIONS

Format:

!INQUIRE-WORKSTATIONS

LAYOUT

All distances are measured in Normalised Device Coordinates (NDC) which cover the graphics screen from 0 to 1 both in x and in y.

By default, Garfield plots occupy the entire NDC frame: the actual image covers both in x and in y the range [0.1, 0.9] leaving the margins for labels, numbers, comments, the time stamp and the title. The so-called viewport, or the part of the NDC frame occupied by the image, labels, numbers, comments, stamp and title can be reduced with the VIEWPORT graphics command.

Format:

!LAYOUT [ X-NUMBER  x_number ] ...
        [ Y-NUMBER  y_number ] ...
        [ X-DECADE  x_decade ] ...
        [ Y-DECADE  y_decade ] ...
        [ X-LABEL   x_label ] ...
        [ Y-LABEL   x_label ] ...
        [ TITLE     title ]

The parameters are graphically illustrated in the diagram.

Additional information on:

MAP-COLOURS

Format:

!MAP-COLOURS

OPEN-WORKSTATION

A workstation to be opened must already have been defined, for instance via !ADD-WORKSTATION. After !OPEN-WORKSTATION, the workstation is in the GKS state 'open' and can be activated by means of !ACTIVATE-WORKSTATION.

Format:

! OPEN-WORKSTATION workstation

Example:

!add falco type falco
!open falco
!act falco

This example shows how to add, open and activate a workstation named FALCO of type FALCO.

OPTIONS

Format:

! OPTIONS [GRID | NOGRID] ...
          [DECADES-ONLY | COMPLETE-GRID] ...
          [TIME-STAMP | NOTIME-STAMP] ...
          [LOGARITHMIC-X | LINEAR-X] ...
          [LOGARITHMIC-Y | LINEAR-Y] ...
          [CLEAR-BEFORE-PLOT | NOCLEAR-BEFORE-PLOT] ...
          [CLEAR-AFTER-PLOT | NOCLEAR-AFTER-PLOT] ...
          [WAIT-BEFORE-PLOT | NOWAIT-BEFORE-PLOT] ...
          [WAIT-AFTER-PLOT | NOWAIT-AFTER-PLOT] ...
          [DISPLAY-CONTROL-CHARACTERS | EXECUTE-CONTROL-CHARACTERS] ...
          [CLIP-AREAS | NOCLIP-AREAS] ...
          [CLIP-LINES | NOCLIP-LINES] ...
          [CLIP-MARKERS | NOCLIP-MARKERS] ...
          [CLIP-TEXT | NOCLIP-TEXT]

Example:

!options grid

(The plots that follow will have a grid overlaid.)

Additional information on:

REPRESENTATION

Per REPRESENTATION statement, you may modify only one item; if an item consists of more than one primitive, you are further restricted to the attributes of only one of these primitives.

Each item has a preset representation in black and white. These are usually overwritten at startup by the various initialisation files.

If the attributes are omitted, the current representation is shown. If the item is omitted, all representations are displayed.

Format:

! REPRESENT item attribute value attribute value ...

Examples:

!rep title text-font -7, text-precision stroke, text-colour red, ...
           character-height 0.03

This ensures the title is plotted in the locally defined (font number is negative) font -7, using the colour RED (which you are supposed to have defined beforehand). The characters will be a bit larger than default.

!rep isochron linetype solid polyline-colour blue
!rep isochron polymarker-colour blue
!rep isochron

This shows how isochrons can be plotted in blue. Isochrons consist both of lines segments and single points, hence two statements are needed: polyline and polymarker. The last line inquires the representation of the isochrons. Both the polyline and polymarker attributes are shown.

Additional information on:

RESET-COLOURS

Format:

!RESET-COLOURS

SET-DEFERRAL-STATE

Format:

!SET-DEFERRAL-STATE ...
     { AS-SOON-AS-POSSIBLE | BEFORE-NEXT-INTERACTION-GLOBALLY | ...
       BEFORE-NEXT-INTERACTION-LOCALLY | AT-SOME-TIME } ...
     { SUPPRESSED | ALLOWED}

SHADING-MAP

The map contains the shaded variations of the colours of the fill area representations BOX-TICKMARKS, PLANES, CONDUCTORS-1, CONDUCTORS-2, CONDUCTORS-3, DIELECTRICA-1, DIELECTRICA-2 and DIELECTRICA-3 representations that are used for one or more solids.

These shades are only generated during execution of the AREA statement. No colour memory is allocated for representations that are not in use - it can therefore be that parts of the shading map are left empty.

The number of shades of each colour can be set with the COLOURS option of the AREA command.

STAMP

This string may contain expressions in terms of global variables, as explained in the example below.

Whether the time stamp appears at all is controlled with the TIME-STAMP graphics option.

The string is displayed using the MESSAGE representation.

Format:

! STAMP string

Examples:

!stamp

Global vc=2000
...
!stamp "Vc=\\{vc\\}"

In the first example, you ask the program to display the current time stamp comment string. In the second example, you first set a global variable VC, probably in the cell section. You then include the value of this variable in the stamp. Note the use of the escape character (backslash, see ESCAPE): without backslash, VC would be substituted and subsequent changes in the value of VC would not be reflected in the string that is plotted. With the backslash, the { and } are preserved as part of the string and substitution of the value of VC is done only when the string is plotted.

VIEWPORT

The viewport is the part of the output surface that is used for displaying graphics. In the GKS model, the output surface is a square with corners (0,0) and (1,1). The viewport is specified using the coordinate system of the output surface, a system that is known as "normalised device coordinates" or NDC for short.

Since Garfield allocates 0.1\&nbsp;NDC units all around the actual graph in order to place labels, numbers and titles, the viewport must have a width of at least 0.2\&nbsp;NDC units in x and in y.

Some plots assume that the viewport is square, this is for instance the case for 3D plots of the drift and field area which may be distorted.

The current viewport settings are displayed if all arguments are omitted.

This command should not be confused with the GKS_VIEWPORT procedure.

Format:

! VIEWPORT xmin ymin xmax ymax

Initial settings: (0,0) to (1,1).

WRITE-COLOURS

Format:

! WRITE-COLOURS DATASET file [member] [REMARK remark]

Example:

! WR-COL TEST.DAT PARROT "Lots of bright colours"

Additional information on:

WRITE-REPRESENTATION

Representation datasets are read with GET-REPRESENTATION.

Format:

! WRITE-REPRESENTATION DATASET file [member] [REMARK remark]

Example:

! WR-REP TEST.DAT MG600 "For Monterey terminals"

Additional information on:

Formatted on 21/01/18 at 16:55.