graphics


workstations

  A "workstation" in the context of Garfield, is approximately
  the same as the workstation defined in the GKS standard: a
  device that can do one or more of the following:

  - 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 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:

  --------------------------------------------------------------
  state      description
  --------------------------------------------------------------
  defined    A workstation in state "defined" does not receive
             graphics ouput, 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:

  --------------------------------------------------------------
  state      reached from previous by    to return to previous
  --------------------------------------------------------------
  defined    !ADD-WORKSTATION            !DELETE-WORKSTATION
  open       !OPEN-WORKSTATION           !CLOSE-WORKSTATION
  active     !ACTIVATE-WORKSTATION       !DEACTIVATE-WORKSTATION
  --------------------------------------------------------------

ACTIVATE-WORKSTATION

  Activates a workstation. The graphics output is sent only to
  the workstations that are active.

  A workstation that is to be activated, must already be open.

  The argument is an alphanumeric string designating the workstation,
  two workstations are predefined: TERMINAL and METAFILE, but you
  may define additional workstations via !ADD-WORKSTATION.

  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

  Is used to create additional workstations. Two workstations are
  predefined in Garfield: TERMINAL and METAFILE, you may not create
  workstations by those names (unless you delete them first).

  After !ADD-WORKSTATION, the workstation is in the state 'defined',
  which in GKS terminology means that the workstation is neither 'open'
  nor 'active'. Use !OPEN-WORKSTATION and !ACTIVATE-WORKSTATION to
  first open and then activate the newly defined workstation.

  For output-only workstations (2nd format), a file name must be
  given. In both formats, either the type (e.g. MG600 or APPENDIX_E)
  or the GKS identifier (the driver number) must be specified, but
  not both. The connection identifier and the offset between logical
  unit and connection identifier are both optional and can both be
  used together with TYPE and with GKS-IDENTIFIER.

  Format for input/output workstations:

  ! ADD-WORKSTATION name [TYPE type] [GKS-IDENTIFIER GKSid]
                         [CONNECTION-IDENTIFIER conid]

  Format for output (metafile, PostScript etc) workstations:

  ! ADD-WORKSTATION name [TYPE type] [GKS-IDENTIFIER GKSid]
                         [OFFSET offset] FILE-NAME file

  Example:

  !add postscript type ps file-name garfield.ps

  This instruction adds a PostScript formatted metafile.

ARROW-TOP-ANGLE

  Vector plots, such as those produced in the field section,
  contain small arrows. The half top angle of these arrows
  can be modified with this command.

  The angle should be entered in degrees.

  Format:

  !ARROW-TOP-ANGLE  angle

  Example:

  !arrow 60

  This would make the top angles twice the default.

  [The default setting is 30 degrees.]

CLEAR-SCREEN

  Clears all active workstations.

  Format:

  !CLEAR-SCREEN

CLOSE-WORKSTATION

  Closes a workstation. The argument is an alphanumeric string
  designating the 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 file attached to the workstation being closed, will also
  be closed. This file may be overwritten if you perform an
  !OPEN-WORKSTATION again.

  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

  Some graphics terminals allow the use of colours - if you have
  such a device, you may prefer to use colours to distinguish the
  various components of a plot instead of linetype, markertype
  and the like.

  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, each on a scale of 0 to 1 inclusive.
  White (or FOREGROUND) has 1 for all three, the BACKGROUND has
  0 for all three.

  The format allows for a workstation to be specified, this should
  for the time not be used.

  Format:

  ! COLOUR colour_name RED red BLUE blue GREEN green [WORKSTATION wkid]

  Examples:

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

CONTOUR-PARAMETERS

  Contour are computed using a number of numerical parameters
  for which defaults have been set that are suitable for a wide
  of applications.

  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 epsilon
  parameters by a factor of 10.

  Contour plotting works as follows:

  1. a 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 eps-gradient ] ...
                       [ EPSILON-TRACING eps_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**-4.

Additional Information on:

  • BISECTION-ITERATIONS
  • EPSILON-GRADIENT
  • EPSILON-TRACING
  • GRID-TOLERANCE
  • NEWTON-ITERATIONS
  • STEP-MAXIMUM

  • DEACTIVATE-WORKSTATION

      Deactivates a workstation. After this operation, the workstation
      is in the GKS state 'open'. The workstation can then be closed
      via !CLOSE-WORKSTATION or re-activated by !ACTIVATE-WORKSTATION.
    
      This instruction is very useful 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

      Deletes a workstation from the workstation tables. After this
      operation, all information about the workstation is lost. A
      workstation can therefore not be opened or activated again
      after a !DELETE-WORKSTATION - it has to be added to the tables
      again with !ADD-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

      Leaves the graphics subsection.
    
      Format:
    
      EXIT
    

    GET-COLOURS

      Reads a list of colours from a dataset which has been written by
      a call to WRITE-COLOURS. This command can only be executed if you
      are using a terminal which has colour facilities.
    
      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 !REPRESENT
      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 dsname [member]
    
      Examples:
    
      !GET-COL TEST PARROT
    
      Picks up the member PARROT on dataset TEST.
    

    GET-REPRESENTATION

      Loads a representation table from a dataset. Any data that you
      might have entered using !REPRESENTATION statements, will be
      overwritten.
    
      Be sure that all colours that are referenced by the representations
      in the file are defined before issuing !GET-REPRESENTATION commands.
      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 dsname [member]
    
      Examples:
    
      !GET-REP TEST MG*
    
      Picks up the first member that matches MG*, presumably MG600.
    

    INQUIRE-DEFERRAL-UPDATE-STATE

      Shows the deferral and update states of the workstation specified.
      If no argument is given, and if the argument is *, the states of
      all known workstations are shown.
    
      Format:
    
      ! INQUIRE-DEFERRAL-UPDATE-STATE
    
      Example:
    
      !inq-def
    

    INQUIRE-LEVEL

      Informs you about the level of the GKS the program is running with.
    
      Format:
    
      !INQUIRE-LEVEL
    

    INQUIRE-OPERATING-STATE

      Tells you in which state GKS is at the moment.
    
      Format:
    
      !INQUIRE-OPERATING-STATE
    

    INQUIRE-WORKSTATIONS

      Lists the known workstations, their states and associated files.
    
      Format:
    
      !INQUIRE-WORKSTATIONS
    

    MAP-COLOURS

      Plots a table of the currently defined colours.
    
      Format:
    
      !MAP-COLOURS
    

    OPEN-WORKSTATION

      Opens a workstation. The argument is an alphanumeric string
      designating the 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

      This command is used to modify the setting of some graphics
      switches: plotting of a grid, logarithmic/linear axes and the
      presence of a time-stamp on pictures in a metafile.
    
      If you switch GRID on, a coordinate grid is plotted on top of
      your plots. The type of line used to draw this grid can be changed
      via !REPRESENTATION, by default dotted lines are used.
    
      The gas plots have forced vertical logarithmic scales, the
      logarithmic/linear options are reset when these plots are produced.
      These options are otherwise not touched.
    
      Format:
    
      ! OPTIONS [GRID | NOGRID] ...
                [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]
    
      Example:
    
      !OPT GRID
    
      (The plots that follow will have a grid overlaid.)
    

    Additional Information on:

  • LOGARITHMIC-X
  • LOGARITHMIC-Y
  • GRID
  • TIME-STAMP
  • CLEAR-BEFORE-PLOT
  • CLEAR-AFTER-PLOT
  • WAIT-BEFORE-PLOT
  • WAIT-AFTER-PLOT
  • EXECUTE-CONTROL-CHARACTERS

  • REPRESENTATION

      This command enables you to change the appearance of the various
      components ('items') of the plot such as the box and tickmarks,
      drift lines, isochrones, contours, titles, functions etc.
    
      Each item is associated with one or more primitives: polyline,
      text, polymarker or fill area. Each of the primitives has a series
      of attributes.
    
      Example: the title of the plot is a piece of text and the
      attributes of text you can change are the font, the character
      quality, character size etc.
    
      Per REPRESENTATION statement, you may modify only one item; if an
      item consists of more than one primitive, you are further restricted
      to only one of these.
    
      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
      !rep isochrones linetype solid polyline-colour blue
      !rep isochrones polymarker-colour blue
      !rep isochrones
    
      The first example will ensure 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.
    
      The next two examples show how isochrones can be plotted in blue.
      Isochrones consist both of lines segments and single points, hence
      two statements are needed: polyline and polymarker.
    
      The last example inquires the representation of the isochrones.
      Both the polyline and polymarker attributes are shown.
    

    Additional Information on:

  • item
  • fill_area_attributes
  • polyline_attributes
  • polymarker_attributes
  • text_attributes

  • RESET-COLOURS

      Resets the colour table to contain only BACKGROUND and FOREGROUND.
    
      Format:
    
      !RESET-COLOURS
    

    SET-DEFERRAL-STATE

      Sets the deferral and update states.
    
      Format:
    
      !SET-DEFERRAL-STATE ...
           { AS-SOON-AS-POSSIBLE | BEFORE-NEXT-INTERACTION-GLOBALLY | ...
             BEFORE-NEXT-INTERACTION-LOCALLY | AT-SOME-TIME } ...
           { SUPPRESSED | ALLOWED}
    

    SHADING-MAP

      Produces a map of the various colour shades that can be used
      in 3D views. Depending on the illumination and point of view,
      lighter or darker variations of the shades are used.
    
      The map contains the shaded variations of the 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.
    

    STAMP

      Sets the time stamp comment string, the string which is plotted
      after the time and date in the time stamp. By default, this string
      is simply a dot.
    
      This string may contain expressions in terms of global variables.
    
      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): 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 the value of
      VC is substituted only when the string is plotted.
    

    WRITE-COLOURS

      Writes a list of colours to a dataset so that you can easily
      retrieve them later on by GET-COLOURS.
    
      Format:
    
      ! WRITE-COLOURS DATASET dsname [member] [REMARK remark]
    
      Example:
    
      ! WR-COL TEST.DAT PARROT "Lots of bright colours"
    

    WRITE-REPRESENTATION

      Writes the representation table to a file such that it can later
      on be retrieved easily. The idea is that you keep the tables for
      the various terminal types in one dataset, using the terminal
      name for member name.
    
      Format:
    
      ! WRITE-REPRESENTATION DATASET dsname [member] [REMARK remark]
    
      Example:
    
      ! WR-REP TEST.DAT MG600 "For Monterey terminals"
    

    Keyword index. Formatted on 10/11/98.