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:
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.
The set command assigns a value to a variable. Its syntax is:
set var valueWhere 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.
The value of a variable is obtained by preceding the name with a $ sign. Example:
set time 4 vis5d_set_timestep $ctx $timeThe source command reads Tcl commands from another file. Its syntax is:
source fileWhere file is the name of another Tcl file.
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
-script command line option. For example
vis5d LAMPS.v5d -script foo.tclexecutes
foo.tcl automatically upon startup.
vis5d> prompt will appear. You can now
type in Tcl commands. Type exit when finished.
If it exists, the startup file 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.
vis5d_set_color $ctx VIS5D_ISOSURF "T" 1.0 0.0 0.0 1.0The 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.
vis5d_set_timestep $ctx 3This 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.
vis5d_set_chslice $ctx "SPD" 2.0 vis5d_make_chslice $ctx VIS5D_ALL_TIMES "SPD" vis5d_enable_graphics $ctx VIS5D_CHSLICE "SPD" VIS5D_ONThe first command sets the position of the colored slice to grid level 2.0
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.
/* this is a comment */Fortran:
C this is a commentTcl:
# this is a comment
x = 1.0;Fortran:
x = 1.0Tcl:
set x 1.0
average = (a+b)/2.0;Fortran:
average = (a+b)/2.0Tcl:
set average [ expr ($a+$b)/2.0 ]
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
}
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
}
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.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.
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
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
vis5d_get_grid_rows context
vis5d_get_grid_columns context
vis5d_get_grid_levels context var
vis5d_make_clone_variable context clonename var
vis5d_compute_ext_func context name
vis5d_make_expr_var context expression
vis5d_draw_frame context
vis5d_graphics_mode context graphic mode
vis5d_enable_graphics context graphic number mode
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
vis5d_alpha_mode context mode
vis5d_font context fontname [size]
vis5d_linewidth context width
vis5d_recolor_topo context reset
reset is non-zero, then the colortable will be reset to its
initial, default values.
vis5d_set_matrix context matrix
vis5d_set_view context xrot yrot zrot scale xtrans ytrans ztrans
vis5d_set_camera context perspective frontclip zoom
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
vis5d_make_hslice context time var urgent
vis5d_set_vslice context var interval low high r0 c0 r1 c1
vis5d_make_vslice context time var urgent
vis5d_set_chslice context var level
vis5d_make_chslice context time var urgent
vis5d_set_cvslice context var r0 c0 r1 c1
vis5d_make_cvslice context time var urgent
vis5d_set_hwindslice context slicenum density scale level
vis5d_make_hwindslice context time slice urgent
vis5d_set_vwindslice context slicenum density scale r0 c0 r1 c1
vis5d_make_vwindslice context time slice urgent
vis5d_set_streamslice context slicenum density level
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
vis5d_make_label context x y text
vis5d_get_cursor context
vis5d_set_cursor context x y z
vis5d_get_image_formats context
vis5d_save_window context filename format
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}
vis5d_free_graphics context
vis5d_sleep time
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
}
# 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
}
# 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
# 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
}