Vis5D Scripting Last updated: May 13, 1996
While Tcl experience is recommended for writing Vis5D scripts, some short but useful scripts can be written without any real Tcl knowledge.
Note that the Tcl package does not have to be installed on your computer in order to use Vis5D's script interface. If it is not installed, Vis5D uses a small, built-in interpreter which can execute very simple Tcl scripts. However, if you want to take full advantage of Vis5D's Tcl interface you should install Tcl on your computer.
To obtain and install Tcl see the instructions on the
Tcl page
.
After Tcl has been installed you can enable the full Tcl support in Vis5D
by following these instructions:
The set command assigns a value to a variable. Its syntax is:
The value of a variable is obtained by preceding the name with a $ sign.
Example:
Lines which start with the # symbol are considered to be comments and
ignored.
The built-in interpeter cannot evaluate mathematical expressions or
execute control structures like loops, conditionals or subroutines. The
Tcl package must be installed to execute scripts with those constructs.
You may also execute a script file when you start vis5d with the
If it exists, the startup file
The second command tells vis5d to actually compute the horizontal colored
slice graphic of "SPD" for all time steps.
The third command tells vis5d to actually display the colored slice.
Vis5D Tcl commands are of the form:
vis5d_command $ctx arguments
That is, a command name followed by the context variable, followed by zero
or more arguments.
For the time being, you should always use $ctx to specify the context of
your commands for future compatability.
2. Setting up full Tcl support
If you do not have Tcl installed on your computer and only plan to use
simple Vis5D Tcl scripts you may skip this section.
If all goes well vis5d will compile and link with Tcl support. If
there are errors be sure that you've correctly specified the location
of the include and library files described above.tcl.h include file and the
libtcl.a library file are located. /usr/local/include
and /usr/local/lib are common.ln -s tcl7.0.h tcl.h and
ln -s libtcl7.0.a libtcl.a if this wasn't done when Tcl
was installed.src/Makefile as follows
#Tcl support: uncomment and edit to enable
#TCL_INCLUDE = -DTCL -I/usr/local/include
#TCL_LIB = -L/usr/local/lib -ltcl
Remove the leading # on the 2nd and 3rd lines and change
the /usr/local/include and /usr/local/lib
parts to reflect the location of Tcl on your computer. You should
have something like this:
#Tcl support: uncomment and edit to enable
TCL_INCLUDE = -DTCL -I/usr/local/include
TCL_LIB = -L/usr/local/lib -ltcl
make followed by your operating
system configuration. Type make alone to see a list of
possibilities.
3. The built-in interpreter
When Tcl is not installed Vis5D uses a simple built-in interpreter. It
only understands the Tcl set and source commands,
the Vis5D-specific commands, variable substitution and comments.
set var value
Where var is a variable name and value is
a number or a character string. Examples:
set temperature 280.0
set month February
set message "Press any key"
Note that multi-word strings must be surrounded by double-quotation marks.
set time 4
vis5d_set_timestep $ctx $time
The source command reads Tcl commands from another file.
Its syntax is:
source file
Where file is the name of another Tcl file.
4. Accessing the Tcl interface in Vis5D
On Vis5D's control panel there are two buttons labeld SCRIPT..
and INTERP... The first button is used to execute a Tcl script
from a file and the second button is used to interactively type in
Tcl commands.
Script files
When you click on the SCRIPT.. button a file selector
window will appear. Select the Tcl script you want to execute
and click on OK. If an error occurs while executing
the script a pop-up window will tell you
so. Also, look in your shell window for error messages.-script command line option. For example
vis5d LAMPS.v5d -script foo.tcl
executes foo.tcl automatically upon startup.Interactive Tcl commands
When you click on the INTERP.. button Vis5D will halt. In your
shell window the vis5d> prompt will appear. You can now
type in Tcl commands. Type exit when finished.vis5d.tcl is
automatically executed before you get the vis5d> prompt.
One use of this file is to load macros or functions that you always use.
5. Examples of basic Vis5D Tcl commands
We begin with some simple examples which could be executed either from
a script file or typed in by hand.Example 1
Suppose we have an isosurface of temperature (variable name "T")
displayed in vis5d and we want to color it red. The following Tcl
command will do that:
vis5d_set_color $ctx VIS5D_ISOSURF "T" 1.0 0.0 0.0 1.0
The command name is vis5d_set_color. The arguments are:
$ctx - this specifies the vis5d context. Don't worry
about its meaning now, it will be explained more later.
VIS5D_ISOSURFACE - this identifies what kind of graphic
to color.
"T" - this specified which isosurface to color
1.0 0.0 0.0 1.0 - this is the RGBA color of the isosurface.
Each number is in the range 0.0 to 1.0. The first three numbers are
the red, green, and blue color components and the last number is the
opacity or transparency where 0.0 is completely transparent and 1.0
is completely opaque.
Example 2
Suppose we simply want to set the currently displayed timestep to be
the fourth in the dataset.
vis5d_set_timestep $ctx 3
This command should be self explanatory except for the fact that we
specified 3 instead of perhaps 4. The reason is Vis5D begins counting
timesteps starting at zero, not one. Therefore timestep number 3 is
actually the fourth timestep.Example 3
Suppose we want to compute and display a horizontal colored slice
of wind speed (variable name "SPD") at vertical grid level 2. The
following commands will do that.
vis5d_set_chslice $ctx "SPD" 2.0
vis5d_make_chslice $ctx VIS5D_ALL_TIMES "SPD"
vis5d_enable_graphics $ctx VIS5D_CHSLICE "SPD" VIS5D_ON
The first command sets the position of the colored slice to grid level 2.0
6. Basic Tcl syntax
This section gives examples of basic Tcl language constructs by comparing
them to C and Fortran syntax. See a Tcl language reference for more
information.Comments
C: /* this is a comment */
Fortran: C this is a comment
Tcl: # this is a comment
Assigments
C: x = 1.0;
Fortran: x = 1.0
Tcl: set x 1.0
Expressions and assignments
C: average = (a+b)/2.0;
Fortran: average = (a+b)/2.0
Tcl: set average [ expr ($a+$b)/2.0 ]
For Loops
C:
for (i=1;i<=10;i++) {
body of loop
}
Fortran:
do i=1,10
body of loop
enddo
Tcl:
for {set i 1} {$i <= 10} { set i [expr $i+1] } {
body of loop
}
Conditionals
C:
if (x<0.0) {
y = 0.0;
}
else if (x>100.0) {
y = 100.0;
}
else {
y = x;
}
Fortran:
if x .lt. 0 then
y = 0.0
else if x .gt. 100 then
y = 100.0
else
y = x
end if
Tcl:
if {$x<0.0} {
set y 0.0
}
elseif {$x>100.0} {
set y 100.0
}
else {
set y $x
}
7. Vis5D Tcl command structure
All of the Vis5D Tcl commands start with the prefix vis5d_
and all of the Vis5D Tcl constants start with the prefix
VIS5D_. This makes it easy to spot Vis5D-specific
commands in a script and prevents confusion with other Tcl identifiers.A note on $ctx and Vis5D contexts
Vis5D's internal core supports multiple contexts. A context can be
thought of as a Vis5D file read into memory plus all the associated graphics.
At Vis5D's user level, however, only one context is ever used at a time.
To reference this context we use the default $ctx variable in each command.
Future applications based on Vis5D's core may use more than one context.
In that case, complex scripts controlling multiple contexts will use other
identifiers in place of $ctx.A note on variable and timestep numbers
Many of the Vis5D Tcl commands take timestep and/or physical variable
parameters. Be aware that timesteps are numbered starting at 0. Similarly,
variables are numbered starting with 0. Also, wherever a physical variable
argument is expected you may either supply a number a name.
8. Command reference
In this section we document each of the Vis5D Tcl commands. Programmers
should note that the Vis5D Tcl commands are a subset of the Vis5D API
functions described in the Vis5D API document. More of the API functions
may be made available as Tcl commands in the future.Timestep Commands
vis5d_get_numtimes context
vis5d_get_time_stamp context timestep
vis5d_set_time_stamp context timestep data time
vis5d_set_timestep context timestep
vis5d_get_timestep context
Physical Variable Commands
vis5d_get_numvars context
vis5d_get_var_name context varnum
vis5d_get_var_units context varnum
vis5d_get_var_type context var
vis5d_get_var_range context var
Grid Commands
vis5d_get_grid_rows context
vis5d_get_grid_columns context
vis5d_get_grid_levels context var
Cloning, External Functions and Expression Commands
vis5d_make_clone_variable context clonename var
vis5d_compute_ext_func context name
vis5d_make_expr_var context expression
Rendering Commands
vis5d_draw_frame context
vis5d_graphics_mode context graphic mode
Returns 1 if graphic is displayed, 0 if graphic is not displayed or an
error message if any parameters are invalid.
vis5d_enable_graphics context graphic number mode
Returns 1 if graphic is displayed, 0 if graphic is not displayed or an
error message if any parameters are invalid.
vis5d_get_volume context
vis5d_set_volume context var
vis5d_set_color context graphic number red green blue alpha
vis5d_set_color_table_entry context graphic var entry r g b a
Note that changes to the topography color table will not be put into
effect until vis5d_recolor_topo is called.
vis5d_alpha_mode context mode
vis5d_font context fontname [size]
vis5d_linewidth context width
Map and Topography Commands
vis5d_recolor_topo context reset
reset is non-zero, then the colortable will be reset to its
initial, default values.
3-D View Commands
vis5d_set_matrix context matrix
vis5d_set_view context xrot yrot zrot scale xtrans ytrans ztrans
vis5d_set_camera context perspective frontclip zoom
Isosurface, Slice, and Trajectory Commands
vis5d_set_isosurface context var isolevel
vis5d_get_isosurface context var
vis5d_set_isosurface_color_var context isovar colorvar
vis5d_make_isosurface context time var urgent
vis5d_set_hslice context var interval low high level
Note that this function does not actually compute the slice.
vis5d_make_hslice context time var urgent
vis5d_set_vslice context var interval low high r0 c0 r1 c1
Note that this function does not actually compute the slice.
vis5d_make_vslice context time var urgent
vis5d_set_chslice context var level
Note that this function does not actually compute the slice.
vis5d_make_chslice context time var urgent
vis5d_set_cvslice context var r0 c0 r1 c1
Note that this function does not actually compute the slice.
vis5d_make_cvslice context time var urgent
vis5d_set_hwindslice context slicenum density scale level
Note that this function does not actually compute the slice.
vis5d_make_hwindslice context time slice urgent
vis5d_set_vwindslice context slicenum density scale r0 c0 r1 c1
Note that this function does not actually compute the slice.
vis5d_make_vwindslice context time slice urgent
vis5d_set_streamslice context slicenum density level
Note that this function does not actually compute the slice.
vis5d_make_streamslice context time slice urgent
vis5d_make_traj context row column level time trajset
vis5d_set_traj context step length ribbonflag
vis5d_delete_last_traj context
vis5d_delete_traj_set context set
vis5d_set_trajectory_color_var context set var
Text Label Commands
vis5d_make_label context x y text
Cursor Commands
vis5d_get_cursor context
vis5d_set_cursor context x y z
3-D Window Commands
vis5d_get_image_formats context
vis5d_save_window context filename format
Coordinate Conversion Commands
vis5d_xyz_to_grid context time var {x y z}
vis5d_grid_to_xyz context time var {row col lev}
vis5d_xyz_to_geo context time var {x y z}
vis5d_geo_to_xyz context time var {lat lon hgt}
Miscellaneous Commands
vis5d_free_graphics context
vis5d_sleep time
9. Example scripts
This section contains a number of example scripts. The
Tcl package must be installed to execute them.
Example 1: Save a time series of GIF images
This script will generate a GIF image file for each timestep in your
dataset. Near the top is the basename variable which is
used to name the GIF files. You may want to change it.
# movie.tcl
# Base file name for all images:
set basename "frame"
# File format and file extension
set format VIS5D_GIF
set extension ".gif"
# Determine how many timesteps there are
set numtimes [ vis5d_get_numtimes $ctx ]
# Loop over the timesteps
for {set time 0} {$time<$numtimes} {set time [expr $time+1]} {
# Set current timestep
vis5d_set_timestep $ctx $time
# Draw the frame
vis5d_draw_frame $ctx
# Setup the filename
set name $basename$time$extension
# Write window image to file
vis5d_save_window $ctx $name $format
}
Example 2: Generate a column of wind trajectories
This script generates a column of trajectories, one for each grid level,
at the cursor's current latitude/longitude.
# trajcol.tcl
# Generate a column of trajectories at the cursor's lat/lon
# for the current timestep.
# Which trajectory set should the trajectories be put in:
set trajset 0
# This is a bit tricky: we need to know how many grid levels are
# present for trajectory tracing. We query the variables used for
# trajectory tracing and then call vis5d_get_grid_levels to find out
# how many grid levels are present for the U rajectory component.
# Note: element 6 of the wind_vars list is the traj U variable.
set wind_vars [ vis5d_get_wind_vars $ctx ]
set traj_uvar [ lindex $wind_vars 6 ]
set traj_levs [ vis5d_get_grid_levels $ctx $traj_uvar ]
# Get current timestep
set curtime [ vis5d_get_timestep $ctx ]
# Get the current cursor position as (row,col).
set cursor_xyz [ vis5d_get_cursor $ctx ]
set cursor_rcl [ vis5d_xyz_to_grid $ctx $curtime $traj_uvar $cursor_xyz ]
set row [ lindex $cursor_rcl 0 ]
set col [ lindex $cursor_rcl 1 ]
# Loop over grid levels making a trajectory for each level.
for {set lev 0} {$lev < $traj_levs} {set lev [expr $lev+1]} {
vis5d_make_traj $ctx $row $col $lev $curtime $trajset
}
Example 3: Display a horizontal contour slice of W
# wslice.tcl
# Display a horizontal contour line slice of W (vertical wind) at the
# middle altitude using dashed lines for negative values. Draw the
# slice in yellow.
# You can change these:
set wvar "W"
set interval -0.05
# The color specified in RGBA:
set red 1.0
set green 1.0
set blue 0.0
set alpha 1.0
# Get min and max W values
set minmax [ vis5d_get_var_range $ctx $wvar ]
set low_val [ lindex $minmax 0 ]
set high_val [ lindex $minmax 1 ]
# Compute location of middle grid level
set num_levels [ vis5d_get_grid_levels $ctx $wvar ]
set level [ expr $num_levels / 2.0 ]
# set the color
vis5d_set_color $ctx VIS5D_HSLICE $wvar $red $green $blue $alpha
# setup slice parameters
vis5d_set_hslice $ctx $wvar $interval $low_val $high_val $level
# compute the slice
vis5d_make_hslice $ctx VIS5D_ALL_TIMES $wvar 0
# display it!
vis5d_enable_graphics $ctx VIS5D_HSLICE $wvar VIS5D_ON
Example 4: Spin and zoom the 3-D box
# spin.tcl
# Spin and zoom the 3-D box
# spin
for {set angle 0} {$angle <= 360} {set angle [expr $angle + 10]} {
vis5d_set_view $ctx -60.0 0.0 $angle 1.0 0.0 0.0 0.0
vis5d_draw_frame $ctx
vis5d_sleep 100
}
# zoom in
for {set scale 1.0} {$scale <= 1.8} {set scale [expr $scale + 0.1]} {
vis5d_set_view $ctx -60.0 0.0 0.0 $scale 0.0 0.0 0.0
vis5d_draw_frame $ctx
vis5d_sleep 100
}
# zoom out
for {set scale 1.8} {$scale >= 1.0} {set scale [expr $scale - 0.1]} {
vis5d_set_view $ctx -60.0 0.0 0.0 $scale 0.0 0.0 0.0
vis5d_draw_frame $ctx
vis5d_sleep 100
}
Other links:
Vis5D,
API document,
Scripting document,
Bill Hibbard,
Brian Paul.