next up previous contents
Next: Memory Management and Large Up: Appendices Previous: Customization   Contents

Subsections


Overlay Files

Statements are usually one per line. To place more than one statements on a line separate them with a semicolon (``;''). Comments begin with the ``#'' character, which must be the first non white space character of the statement. To place a comment at the end of a line, the preceding statement will need to be ended with a semicolon, which can appear anywhere after the end of the statement. eg: 

vector 0.0 0.0 90.0 10       ;# Draw vector

is equivalent to 

vector 0.0 0.0 90.0 10;      # Draw vector

Commands

There are commands to draw lines, text, and markers. It is also possible to change the drawing color, line width, and other graphics characteristics.

Line Drawing Commands

Table of line drawing commands.

Command Arguments Description  
line $<$x0$>$ $<$y0$>$ $<$x1$>$ $<$y1$>$ $<$color$>$ Draw line.  
linea $<$x0$>$ $<$y0$>$ $<$x1$>$ $<$y1$>$ $<$color$>$ Draw arrow.  
vector $<$x0$>$ $<$y0$>$ $<$angle$>$$^\dag $ $<$length$>$ $<$color$>$ Vector.  
vectora $<$x0$>$ $<$y0$>$ $<$angle$>$$^\dag $ $<$length$>$ $<$color$>$ Vector Arrow.  
pavector$^\ddag $ $<$x0$>$ $<$y0$>$ $<$angle$>$$^\dag $ $<$length$>$ $<$color$>$ Position angle vector.  
pavectora$^\ddag $ $<$x0$>$ $<$y0$>$ $<$angle$>$$^\dag $ $<$length$>$ $<$color$>$ Position vector with arrowhead.  

$^\dag $Angles in vector commands are measured in degrees.
$^\ddag $pavector stands for position angle vector.

The above line drawing commands (i.e., line and linea) draw a line using the current line style and line width from the ($<$x0$>$, $<$y0$>$) to ($<$x1$>$, $<$y1$>$). Vector commands (i.e., vector, vectora, pavector, and pavectora) draw a line from the starting point ($<$x0$>$, $<$y0$>$) at the given $<$angle$>$. The $<$length$>$ is given as the percentage of the viewport size and the actual vector size is this number combined with the Vector Scale slider in the Overlay Setup window (see Appendix 2.3.2). For normal vectors, an $<$angle$>$ of 0.0 is horizontal. For pavectors, 0.0 degrees is vertical. For both, positive angles increase in the counterclockwise direction and angles are measured in degrees.

Appending an a (e.g., linea) results in an arrowhead being drawn at the end of the line. The positions for line drawing commands are given in the selected coordinates (see window command, below). All line drawing commands take an optional last argument which specifies a color to be used for that command only. The default color is specified by the Color variable described below.

Sometimes it is more convenient to break line drawing into parts.

Table of line drawing commands, using move.

Command Arguments Description  
move $<$x$>$ $<$y$>$ Move to point ($<$x$>$ $<$y$>$).  
draw $<$x$>$ $<$y$>$ $<$color$>$ Draw a line from current point to $<$x$>$ $<$y$>$.  
arrow $<$x$>$ $<$y$>$ $<$color$>$ Draw an arrow from current point to $<$x$>$ $<$y$>$.  

These commands allow the user to move to a position and draw a line or arrow, possibly after changing world coordinates. Note that all drawing commands change the "current point".

Text Drawing Commands

There are two text drawing commands text and label.

Table of text drawing commands.

Command Arguments Description  
text $<$x$>$ $<$y$>$ $<$angle$>$ $<$just$>$ "text" Draw "text" at $<$x$>$ $<$y$>$ using $<$angle$>$ and $<$just$>$.  
text "text" Draw "text" at current position.  

Both commands draw text using current color value. An $<$angle$>$ of 0.0 gives horizontal text. Justification can be given as a string or a floating point number; it must be one of: LEFT=0.0, CENTER=0.5, or RIGHT=1.0, (nb, for justification only the first letter is checked). The label command writes text at the current position, with an angle and justification given by the respective variables (see Appendix A.2.2). If the text to be drawn includes spaces, they should be enclosed in double quotation marks, otherwise the text will be drawn with all words concatenated together.

Example: 

text 0.5 0.9 0.0 CENTER "This is a text message"

or 

set Angle 0.0
set Justification CENTER            ;# or "set Justification 0.5"
move 0.5 0.9
label "This is also a text message"

Marker Commands

The command to draw markers can be executed in two ways:

marker $<$x$>$ $<$y$>$ $<$markertype$>$ $<$color$>$

or

marker

where $<$markertype$>$ is either a string (See Appendix A.2.2) or an integer greater than $-32$. The maximum is around 2932. Consult the PGPLOT Graphics Subroutine Library for a better description. If no arguments are given, marker uses the current position and symbol. Valid marker types are given with the description of the Symbol variable below.

Miscellaneous Commands

There are several miscellaneous commands, which control aspects such as the graphics state and coordinate system.

Table of miscellaneous commands.

Command Arguments Description  
save -- Save graphics and window state.  
restore -- Restore graphics and window state.  
window $<$x0$>$ $<$y0$>$ $<$x1$>$ $<$y1$>$ Set range of window coordinates from  
    ($<$x0$>$, $<$y0$>$) to ($<$x1$>$, $<$y1$>$).  
window [NDC$\vert$INDEX$\vert$INDEX1$\vert$DATASET] Set the coordinate system.  

Save and restore are used to save and restore the current graphics state and window settings. Currently, save may be nested 10 levels.

By default, the window coordinates (NDC, see next table) are in the range (0.0-1.0) for both the X and Y axes. This may be changed with the "window" command with arguments $<$x0$>$ $<$y0$>$ $<$x1$>$ $<$y1$>$.

The window command with an argument NDC, INDEX, INDEX1, or DATASET sets up a default coordinate system based on the image.

Table of window ranges.

Coordinate System Range Description  
NDC$^\dag $ 0.0-1.0 Normalized Device Coordinates (default).  
INDEX 0-($<$npixels$>-1$) Integer indices, origin is (0,0).  
INDEX1 1-$<$npixels$>$ Integer indices, origin is (1,1).  
DATASET \dag World coordinates.  

$^\dag $Range from BLC to TRC in world coordinates.

All but DATASET use linear mapping to convert between world and plotting coordinates. DATASET uses the coordinate conversion routine in aipsview, which allows for accurate curvilinear transformation. Note that DATASET coordinates can be retrieved from aipsview by activating the Raw Position toggle from the Misc submenu of the Options menu of the Display window, see Section 2.3.4.

Note since NDC, INDEX, and INDEX1 window systems do not deal with coordinates from the data set, positions will not correct when graphics are drawn on a subregion of the data. However, with DATASET coordinates, the positions should be correct whether the graphics are drawn on the original or selected regions.


Variables

The set command is used to set variables which hold the default color, line width, etc. Variables are set using the following syntax:

set $<$variable$>$ $<$value$>$

Table of variables used in overlay files.

Variable Description
Color Sets color used for drawing lines, text, etc. Valid colors and their numerical
  equivalents are: BLACK=0, WHITE=1, RED=2, GREEN=3, BLUE=4, CYAN=5,
  MAGENTA=6, YELLOW=7. Thus, set Color 5 is equivalent to set Color CYAN.
TextBackground Sets color used for text background. In addition to the above values,
  TRANSPARENT (or $-1$) is valid. The default is TRANSPARENT.
Font Sets the character font. Valid fonts are: SIMPLE=1 (default), ROMAN=2, ITALIC=3,
  or SCRIPT=4.
LineStyle Sets line drawing mode. Valid line styles and their integer equivalents are:
  SOLIDLINE=1 (default), DASHED=2, DOT_DASH_DOT_DASH=3, DOTTED=4, or
  DASH_DOT_DOT_DOT=5.
LineWidth Sets the line width. Valid numbers are integers from 1 (default) to 201.
TextHeight Changes the height of characters and markers. Valid numbers are real values
  $>$ 0.0. The default is 1.0.
Angle Angle at which labels are drawn. A value of 0.0 (default) is horizontal.
Justification How to justify text. Valid values and their numerical equivalents are:
  LEFT=0.0 (default), CENTER=0.5, or RIGHT=1.0.
Symbol Default marker to draw. The value is either one of the following names
  or an integer between -32 and 2932, (see the PGPLOT manual for a better
  description). Predefined marker types are: PLUS=2, ASTERIX=3, CIRCLE=4,
  CROSS=5, STAR=12, BOX=16, FILLED_STAR=18, FILLED_CIRCLE=-26.

Examples

To change the default color to RED:

set Color RED

or

set Color 2

To change the default text scale to 2 (double the default):

set Symbol FILLED_STAR

or

Set Symbol 18

Another Way to Set Variables

To accommodate people more comfortable with executing commands rather than setting variables, most variables also have a command that may be used to set the value. However, the only way to retrieve the current value is by reading the variable. The arguments are the same as for setting the corresponding variable.

Commands and corresponding variables.

Command Variable
color Color
textBackground TextBackground
font Font
lineStyle LineStyle
lineWidth LineWidth
textHeight TextHeight
angle Angle
justification Justification
symbol Symbol

To set the default marker symbol to PLUS one could set the Symbol variable:

set Symbol PLUS

or use the symbol command

symbol PLUS.

Advanced Usage

The overlay files provide a flexible way to layout complex text and graphics. Note that overlay files are actually TCL files

Arithmetic
To calculate a numerical expression, the expr command must be used. The expr command and its arguments (an arithmetic expression) must be enclosed in in square brackets ``[]''.

Example: 

set NarrowWidth 2
set ThickWidth [ expr $NarrowWidth*3 ]

Note the brackets and the expr command.

Functions
There are a few functions defined that only advanced users will be interested in.

double pixelToWorld($<$x$>$, $<$y$>$, $<$axisnum$>$)
Convert an $<$x$>$, $<$y$>$ position to DATASET value along one axis.

$<$x$>$, $<$y$>$
Real numbers representing a position in the image in the current coordinate units.

$<$axisnum$>$
Integer representing which axis coordinate value to return. 0 for X axis, 1 for Y axis.

Example: window INDEX; set Y1 [ expr pixelToWorld(10, 12, 1) ]

double datum($<$x$>$, $<$y$>$)
Return the value of the data set at position ($<$x$>$, $<$y$>$).

$<$x$>$, $<$y$>$
Real numbers representing a position in the image in the current coordinate units.

Note: the result is undefined if the requested position is not within the displayed region.

Variable use
To refer to the value of a variable, precede it with a dollar sign ("$"). For instance, to save the value of Color into a variable called OldColor: set OldColor $Color

Constants
There are several constants defined. These are used for setting the graphics variables and have been already listed. Below is an alphabetical list of all defined constants.

ASTERIX BLACK BLUE BOX CIRCLE CROSS CYAN DASHED DASH_DOT_DOT_DOT DOTTED DOT_DASH_DOT_DASH FILLED_CIRCLE FILLED_STAR GREEN ITALIC MAGENTA PLUS RED ROMAN SCRIPT SIMPLE SOLIDLINE STAR TRANSPARENT WHITE YELLOW

Accessing additional files
You can execute commands in additional files by using the source command. The syntax is: source $<$filename$>$

The file sourced will be executed as if it were directly included in the original overlay file. In this way, a file containing only vector commands could be separated from the main overlay file.

Example Overlay Files

The first example overlay file writes a text string and draws an arrow from the string to a pixel. The output ps file from this example is shown after the file. 

# Example1.overlay
#
# This overlay file draws a text string and an arrow from the string
# to a pixel.
#
# Note that lines need to end in a semicolon if a comment follows on
# the same line otherwise no ending character is required.
#

save                            ;# Save graphics state so any following
                                 # commands aren't affected. 
set xpos 83.1944362058           # Set an X-position in world coordinates.
set ypos -5.40555546497         ;# Set a Y-position in world coordinates.
set TextBackground BLACK        ;# Erase image behind any text.
set Color GREEN                 ;# Set color to green.
window DATASET                  ;# Set window coordinates to those
                                 # of the data set.
set d [expr datum($xpos, $ypos)];# Set variable "d" to the value of
                                 # dataset at location 83, -5.4.
window NDC                      ;# Switch coordinate system to NDC,
                                 # which are easier for positioning text.
text 0.5 0.9 0.0 CENTER "The datum value is " $d        ;# Write text.
set Color RED                   ;# Set color for line to red.
move 0.5 0.9                    ;# Move to next position.
window DATASET                  ;# Go back to world coordinates.
arrow $xpos $ypos               ;# Draw arrow to new location.
restore                         # Restore window, color, etc.

#
# Notes:(a) The save and restore are optional, but for long files,
#            they may help avoid unexpected sudden changes in the way
#            the output looks.
#        (b) The overlay file can't currently determine the plane
#            number being shown; thus, the same overlay will be
#            displayed for every plane.

Figure A.1: Output of Example1.overlay file.
\begin{figure}\begin{center} \epsfig{file=Aipsview.dir/Example1.ps,height=5.5in}\end{center}\end{figure}

The second overlay file labels the two components and also overlays a series of vectors on the image using world (DATASET) coordinates. All graphics in the second example are drawn twice, once with a wide line as a background and a second time with a narrow line. The data to draw the vectors in Example2 are kept in another file (following). 

# Example2.overlay
#
# This overlay file draws text with arrows pointing to two components.
# Also vectors are drawn on the image which are included from another
# file (Vectors.dat).  Both the labels and vectors are drawn twice,
# once in a background color and a second time in another color (blue
# for labels and red for vectors).  This example illustrates how to
# use procedures, import files, and set variables.
#
# Note that lines need to end in a semicolon if a comment follows on
# the same line otherwise no ending character is required.
#

#
# Initialize default scaling.
#
set TextScale 2;                # Set default text height to 2.
set ArrowScale 1;               # Set scale for arrow to 1.

#
# Procedure to draw labels.
#
proc drawLabels {} {
    global Color LineWidth;     # Set all variables global otherwise
    global TextScale ArrowScale;# they cannot be passed to commands.
    global TextHeight Angle;
    window INDEX;               # Select pixel coordinate system.
    set TextHeight $TextScale;  # Set text scale.
    move 23 51;                 # Move to desired position for text label.
    label "Component A";        # Write label.
    set TextHeight $ArrowScale; # Set scaling for arrow.
    move 38 50;                 # Move to position for beginning of vector.
    arrow 38 33;                # Draw a line with an arrow to this position.
    set Angle 90;               # Set the angle for text to 90deg (vertical).
    set TextHeight $TextScale;  # Set text scale.
    move 11 12;                 # Move to position for text label.
    label "Component B";        # Write next text label.
    set Angle 0;                # Set the angle for text to 0deg (horizontal).
    set TextHeight $ArrowScale; # Set text scaling.
    move 12 24;                 # Move to position for beginning of vector.
    arrow 37 24;                # Draw a line with an arrow to this position.
}

drawLabels;

#
# Draw wide lines for vectors.
#
window DATASET;                 # Set world coordinate system.
set LineWidth 12;               # Set wide LineWidth for background
set Color BLACK;                # Set background color.
source Vectors.dat;             # Input vector information from vectors file.

#
# Draw narrow colored lines for vectors.
#
set LineWidth 4;                # Set narrow LineWidth for foreground.
set Color RED;                  # Set foreground color.
source Vectors.dat;             # Input vector information from vectors file.

#
# Draw the wide lines for labels.
#
set LineWidth 12;               # Set wide LineWidth for background
set Color BLACK;                # Set background color.
drawLabels;                     # Call drawLabels procedure.

#
# Draw narrow colored lines for labels.
#
set LineWidth 4;                # Set narrow LineWidth for foreground.
set Color BLUE;                 # Set foreground color.
drawLabels;                     # Call drawLabels procedure.

Below is the input file that contains the data for the vectors (vectors.dat). 

# Vectors.dat
## This overlay file contains position angle vector (angle [measured in
# degrees] is measured counterclockwise from north) commands.  Note
# the X-pos and Y-pos mark the starting positions of the vectors in
# the coordinate system (given by the "window" command, in this case
# DATASET, ie, world coordinates) and the end of the vector is drawn in
# the direction specified by "Angle".  In order for the position given
# to be in the center of the vector, another vector with the
# complement angle must additionally be given.  In this example, the
# complement vectors are given in the second list (nb, all Angles for
# original list are 33 and second list are 33+180=213).  The length of
# the vectors is given initially by "Length", but can be additionally
# scaled by the "Vector Scale" slider on the Overlay setup window.
#
# Format: pavector X-pos Y-pos Angle Length
#
# First list (Angle=33).
#
pavector 83.1994586472 -5.40666655917 33 10
pavector 83.1980634517 -5.40666655917 33 10
pavector 83.1966683561 -5.40666655917 33 10
pavector 83.1952732606 -5.40666655917 33 10
pavector 83.193878165  -5.40666655917 33 10
pavector 83.1924830695 -5.40666655917 33 10
pavector 83.1910879739 -5.40666655917 33 10
pavector 83.1994586472 -5.40805544795 33 10
pavector 83.1980634517 -5.40805544795 33 10
pavector 83.1966683561 -5.40805544795 33 10
pavector 83.1952732606 -5.40805544795 33 10
pavector 83.193878165  -5.40805544795 33 10
pavector 83.1924830695 -5.40805544795 33 10
pavector 83.1910879739 -5.40805544795 33 10
pavector 83.1994586472 -5.40944433673 33 10
pavector 83.1980634517 -5.40944433673 33 10
pavector 83.1966683561 -5.40944433673 33 10
pavector 83.1952732606 -5.40944433673 33 10
pavector 83.193878165  -5.40944433673 33 10
pavector 83.1924830695 -5.40944433673 33 10
pavector 83.1910879739 -5.40944433673 33 10

#
# List of complement vectors (Angle=33+180=213).
#
pavector 83.1994586472 -5.40666655917 213 10
pavector 83.1980634517 -5.40666655917 213 10
pavector 83.1966683561 -5.40666655917 213 10
pavector 83.1952732606 -5.40666655917 213 10
pavector 83.193878165  -5.40666655917 213 10
pavector 83.1924830695 -5.40666655917 213 10
pavector 83.1910879739 -5.40666655917 213 10
pavector 83.1994586472 -5.40805544795 213 10
pavector 83.1980634517 -5.40805544795 213 10
pavector 83.1966683561 -5.40805544795 213 10
pavector 83.1952732606 -5.40805544795 213 10
pavector 83.193878165  -5.40805544795 213 10
pavector 83.1924830695 -5.40805544795 213 10
pavector 83.1910879739 -5.40805544795 213 10
pavector 83.1994586472 -5.40944433673 213 10
pavector 83.1980634517 -5.40944433673 213 10
pavector 83.1966683561 -5.40944433673 213 10
pavector 83.1952732606 -5.40944433673 213 10
pavector 83.193878165  -5.40944433673 213 10
pavector 83.1924830695 -5.40944433673 213 10
pavector 83.1910879739 -5.40944433673 213 10

Figure A.2: Output of Example2.overlay file.
\begin{figure}\begin{center} \epsfig{file=Aipsview.dir/Example2.ps,height=5.5in}\end{center}\end{figure}

next up previous contents
Next: Memory Management and Large Up: Appendices Previous: Customization   Contents