Vis5D Scripting

Last updated: March 23, 1999

Contents

  1. Introduction
  2. Setting up full Tcl support
  3. The built-in interpreter
  4. Accessing the Tcl interface in Vis5D
  5. Examples of basic Vis5D Tcl commands
  6. Basic Tcl syntax
  7. Vis5D Tcl command structure
  8. Command reference
  9. Example scripts


1. Introduction

Vis5D 5.1 features a Tcl interface for automation of Vis5D with scripts.
Tcl (Tool command language, pronounced "tickle") is a free, popular, interpreted scripting language designed by John Ousterhout. Example uses of scripts include automatically setting colors, computing graphics, and making off-line animations.

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.




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.

To obtain and install Tcl see the instructions on the Tcl page. We recommend using Tcl version 7.4 at this time since version 7.5 has a bug which effects Vis5D.

After Tcl has been installed you can enable the full Tcl support in Vis5D by following these instructions:

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.




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.

The set command assigns a value to a variable. Its syntax is:

   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.

The value of a variable is obtained by preceding the name with a $ sign. Example:

   set time 4
   vis5d_set_timestep $dtx $time
The source command reads Tcl commands from another file. Its syntax is:
   source file
Where 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.




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.

You may also execute a script file when you start vis5d with the -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.

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.




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 $dtx VIS5D_ISOSURF $ctx "T" 1.0 0.0 0.0 1.0

The command name is vis5d_set_color. The arguments are:

Example 2

Suppose we simply want to set the currently displayed timestep to be the fourth in the dataset.

   vis5d_set_timestep $dtx 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

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.

Example 4

To print the current parameters of the horizontal contour slice of SPD:

   puts [ vis5d_get_hslice $ctx "SPD" ]



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
    }

Printing

C:
    puts( "Hello world!\n" );   /* string */
    printf( "i=%d\n", i );      /* integer */
    printf( "x=%f\n", x );      /* real (float) */
Fortran:
    print *,"Hello world!"
    print *,i
    print *,x
Tcl:
    puts "Hello world!"
    puts $i
    puts $x



7. Vis5D Tcl command structure

All of the Vis5D Tcl commands start with the prefix vis5d_ or vis5d_gui_ 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/$itx/$dtx/$grp arguments

vis5d_gui_command $ctx/$dtx/$grp arguments

That is, a command name followed by one context variable, followed by zero or more arguments.

A note on $ctx/$itx/$dtx/$grp and Vis5D contexts

Vis5D's internal core supports multiple contexts of four different types. The $ctx represents the data context. The $ctx can be thought of as a Vis5D file read into memory plus all the associated graphics. The $itx represents the irregular data context, similar to the $ctx but the data is non-gridded. The $dtx is the display context, it contains information on how the data from $ctxs and $itxs are displayed on the 3-D graphics window. The $grp represents the group context. The $grp contains information about $dtxs that are linked together. In many cases there may be multiple contexts of any one type. For example, two Vis5d files can be viewed in one 3D graphics window, two $ctxs and one $dtx. One could also view four Vis5d files in four different graphics windows, four $ctxs and four $dtxs. With multiple contexts the nomenclature would change, it might be $ctx1, $ctx2, etc.
Note: In cases where only one Vis5d file is used, $ctx can be used in place of $dtx.

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 supply either a number or 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. There are also serveral vis5d GUI functions documented here which are not part of the API, they are specific to the standard GUI distributed with Vis5D.

General Commands

vis5d_terminate
Exit Vis5D.

Timestep Commands

When there are multiple $ctxs attached to a $dtx the time steps are merged in such a way that a $dtx time step contains one time step from each data context. The same is true when multiple data contexts are attached to a group context.
vis5d_get_ctx_numtimes data_context
Returns the number of timesteps in the given data_context.
vis5d_get_itx_numtimes irregular_data_context
Returns the number of timesteps in the given irregular_data_context.
vis5d_get_dtx_numtimes display_context
Returns the number of timesteps in the given display_context.
vis5d_get_grp_numtimes group_context
Returns the number of timesteps in the given group_context.
vis5d_get_ctx_time_stamp data_context timestep
Returns the date and time associated with the given timestep as a list of two elements: {YYDDD HHMMSS}. Timestep 0 is the first timestep.
vis5d_get_itx_time_stamp irregular_data_context timestep
Returns the date and time associated with the given timestep as a list of two elements: {YYDDD HHMMSS}. Timestep 0 is the first timestep.
vis5d_get_dtx_time_stamp display_context timestep
Returns the date and time associated with the given timestep as a list of two elements: {YYDDD HHMMSS}. Timestep 0 is the first timestep.
vis5d_set_ctx_time_stamp data_context timestep data time
Sets the date (YYDDD) and time (HHMMSS) associated with a timestep.
vis5d_set_dtx_timestep display_context timestep
Sets the current timestep. The first timestep is number zero.
vis5d_set_grp_timestep group_context timestep
Sets the current timestep. The first timestep is number zero.
vis5d_get_ctx_timestep data_context
Returns the number of the current timestep, starting at zero.
vis5d_get_itx_timestep irregular_data_context
Returns the number of the current timestep, starting at zero.
vis5d_get_dtx_timestep display_context
Returns the number of the current timestep, starting at zero.
vis5d_get_grp_timestep group_context
Returns the number of the current timestep, starting at zero.

File Commands

vis5d_get_v5dfilename data_context
Returns the file name for the given vis5d context.
vis5d_get_context_name data_context
Return the context name for the given vis5d context.
vis5d_load_v5dfile display_context memory filename ctxname
Load a v5dfile named filename into vis5d. memory is the amount of memory (in megabytes) to allocate for this file. ctxname is the name of the $ctx. The number of the $ctx is returned if all goes well, else VIS5D_FAIL is returned.
vis5d_load_irregular_v5dfile display_context memory filename itxname
Load an irregular v5dfile named filename into vis5d. memory is the amount of memory (in megabytes) to allocate for this file. itxname is the name of the $itx. The number of the $itx is returned if all goes well, else VIS5D_FAIL is returned.
vis5d_destroy_data_context data_context
Remove a data context (data set).
vis5d_save_to_v5dfile data_context filename
Save a data set which has been loaded, to a v5d file. This is useful when new variables have been created
vis5d_set_user_data_flag data_context flag
Set the flag to indicate that user-provided functions are to be used to read gridded data. If flag is 1 then implement the user-provided functions, if flag is 0 use default loading of v5d files.
vis5d_set_user_flags display_context topo_flag map_flag
Set flags to indicate that user-provided functions are to be used to read map and/or topography data. If flag is 1 then implement the user-provided functions, if flag is 0 use default loading of files.
vis5d_open_gridfile data_context filename readflag
Loads a Vis5D data set from the file named 'filename'. readflag indicates whether or not data should immediately be read from the file (1) or if data should be read as needed later (0).
vis5d_open_recordfile irregular_data_context filename datasetname readflag
Loads an irregular Vis5D data set from the file named 'filename'. readflag indicates whether or not data should immediately be read from the file (1) or if data should be read as needed later (0). datasetname is what the data set is to be named.

Physical Variable Commands

vis5d_get_ctx_numvars data_context
Returns the number of physical variables in the given data_context.
vis5d_get_itx_numvars irregular_data_context
Returns the number of physical variables in the given irregular_data_context.
vis5d_get_ctx_var_name data_context varnum
Returns the name of a physical variable. varnum is an integer where zero is the first variable.
vis5d_get_itx_var_name irregular_data_context varnum
Returns the name of a physical variable. varnum is an integer where zero is the first variable.
vis5d_get_var_units data_context varnum
Returns the physical units of a variable. For example, the units typically associated with "U" is "m/s" (meters per second).
vis5d_get_var_type data_context var
Returns the type of the given variable. var may be a variable name or number. Possible types are VIS5D_REGULAR, VIS5D_CLONE, VIS5D_EXT_FUNC, and VIS5D_EXPRESSION.
vis5d_get_ctx_var_range data_context var
Returns the min and max values for the specified variable. var may be a name or number. The min and max values are returned as a list of two numbers.
vis5d_get_itx_var_range irregular_data_context var
Returns the min and max values for the specified variable. var may be a name or number. The min and max values are returned as a list of two numbers.
vis5d_set_var_range data_context var min max
Set the min and max values for the specified variable. var may be a name or number. min and max may specify any range.
vis5d_set_sound_vars display_context temp dewpt uwind vwind var1 var2 var3
Sets the variables used in the sounding window. temp and dewpt are the temperature and dew point used in the skew-t plot. uwind and vwind are the the U and V components of the wind, used in plotting the wind barbs. var1, var2, and var3 are the variables used for the vertical plots.
vis5d_get_sound_vars display_context
Returns the variables used in the sounding window. The output will be: temp dewpt uwind vwind var1 var2 var3. temp and dewpt are the temperature and dew point used in the skew-t plot. uwind and vwind are the the U and V components of the wind, used in plotting the wind barbs. var1, var2, and var3 are the variables used for the vertical plots.
vis5d_set_sound_vars_and_owners display_context tempctx temp dewptctx dewpt uwindctx uwind vwindctx vwind var1ctx var1 var2ctx var2 var3ctx var3
Sets the variables used in the sounding window. temp and dewpt are the temperature and dew point used in the skew-t plot. uwind and vwind are the the U and V components of the wind, used in plotting the wind barbs. var1, var2, and var3 are the variables used for the vertical plots. Since mutlpile $ctxs are possible, tempctx, dewptctx,..var3ctx represent which $ctx the variable is from.
vis5d_get_sound_vars_and_owners display_context
Returns the variables used in the sounding window and the $ctxs where they come from. The output will be: tempctx temp dewptctx dewpt uwindctx uwind vwindctx vwind var1ctx var1 var2ctx var2 var3ctx var3. temp and dewpt are the temperature and dew point used in the skew-t plot. uwind and vwind are the the U and V components of the wind, used in plotting the wind barbs. var1, var2, and var3 are the variables used for the vertical plots.
vis5d_set_wind_vars_and_owners display_context uvarctx uvar vvarctx vvar wvarctx wvar u2varctx u2var v2varctx v2var w2varctx w2var trjuctx trju trjvctx trjv trjwctx trjw
Sets the variables used to compute the two sets of wind slices and trajectories. The first three names( uvar, vvar, wvar ) are the U,V, and W components for the first wind slice set. The second three names( u2var, v2var, w2var ) are the U,V, and W components used for the second wind slice. The third set of three names( trju, trjv, trjw ) are those used for computing wind trajectories. The names uvarctx, vvarctx,..trjwctx represent which $ctx the variable is from.
vis5d_get_wind_vars_and_owners display_context
Returns a list of variable names used to compute the two sets of wind slices and trajectories. The output will be: uvararctx uvar vvarctx vvar wvarctx wvar u2varctx u2var v2varctx v2var w2varctx w2var trjuctx trju trjvctx trjv trjwctx trjw. The first three names( uvar, vvar, wvar ) are the U,V, and W components for the first wind slice set. The second three names( u2var, v2var, w2var ) are the U, V, and W compnents used for the second wind slice. The third set of three names( trju, trjv, trjw ) are those used for computing wind trajectories. The variables uvarctx, vvarctx,..trjwctx represent which $ctx the variable is from.

Group Commands

vis5d_set_display_group display_context group_context
Attaches the given display context($dtx) to the group context($grp). group_context is a number [1..9] To ungroup a $dtx set group_context to -1.
vis5d_get_display_group display_context
Return the group number ($grp) which the $dtx belongs to. If the $dtx is not attached to a group then -1 is returned.
vis5d_get_num_of_dtxs_in_group group_context
Return the number of $dtxs attached to a group. A list of the $dtx index numbers will be displayed after that.

Linking Commands

vis5d_link_slices data_context1 type1 var 1 data_context2 type2 var2
This will link two slices together including any links to other slices. The movement and state of the linked slices will then be synchronized. Horizontal and vertical slices can not be linked.
  • ctx_index1 - the data set which slice 1 belongs to
  • type1 - one of
    • VIS5D_HSLICE
    • VIS5D_CHSLICE
    • VIS5D_VSLICE
    • VIS5D_CVSLICE
    • VIS5D_HWIND
    • VIS5D_HSTREAM
    • VIS5D_VWIND
    • VIS5D_VSTREAM
  • var1 - the variable number or wind slice number
  • ctx_index2 - the data set which slice 2 belongs to
  • type2 - one of
    • VIS5D_HSLICE
    • VIS5D_CHSLICE
    • VIS5D_VSLICE
    • VIS5D_CVSLICE
    • VIS5D_HWIND
    • VIS5D_HSTREAM
    • VIS5D_VWIND
    • VIS5D_VSTREAM
  • var2 - the variable number or wind slice number
vis5d_unlink_slice data_context type var
This removes the slice from a chain of linked slices.
  • ctx_index - the data set which slice belongs to
  • type - one of
    • VIS5D_HSLICE
    • VIS5D_CHSLICE
    • VIS5D_VSLICE
    • VIS5D_CVSLICE
    • VIS5D_HWIND
    • VIS5D_HSTREAM
    • VIS5D_VWIND
    • VIS5D_VSTREAM
  • var - the variable number or wind slice number

Display Functions

vis5d_set_display_matrix rows columns
Set size of matrix of 3-D displays - no larger than 4 x 4.
vis5d_get_display_matrix
Get numbers of rows and columns in matrix of 3-D displays.
vis5d_assign_display_to_data data_context display_context
Attach the $ctx given by 'data_context' to the $dtx given by display_context.
vis5d_assign_display_to_irregular_data irregular_data_context display_context
Attach the $itx given by 'irregular_data_context' to the $dtx given by display_context.
vis5d_get_num_of_ctxs_in_display display_context
Return the number of $ctxs attached to a display. A list of the $ctx index numbers will be displayed after that.
vis5d_get_num_of_itxs_in_display display_context
Return the number of $itxs attached to a display. A list of the $itx index numbers will be displayed after that.

Grid Commands

The display grid or 'virtual' grid defines the 3-D space where the graphics are mapped to. The values defining the display grid may be changed where as the data grids remains static.
vis5d_get_ctx_grid_rows data_context
Returns the number of rows in the each 3-D data grid.
vis5d_get_dtx_grid_rows display_context
Returns the number of rows in the 3-D display grid.
vis5d_get_ctx_grid_columns data_context
Returns the number of columns in each 3-D data grid.
vis5d_get_dtx_grid_columns display_context
Returns the number of columns in the 3-D display grid.
vis5d_get_ctx_grid_levels data_context var
Returns the number of levels in each 3-D data grid for a particular physical variable. The number of levels in a 3-D grid can vary from variable to variable.
vis5d_get_dtx_grid_levels display_context
Returns the number of levels in the 3-D display grid. The display grid is the same for all variables and time steps.
vis5d_set_dtx_grid_rows display_context numrows
Sets the number of rows in the 3-D display grid.
vis5d_set_dtx_grid_columns display_context numcols
Sets the number of columns in the 3-D display grid.
vis5d_set_dtx_grid_levels display_context numlevs
Sets the number of levels in the 3-D display grid.
vis5d_verylarge_mode data_context flag
flag is either VIS5D_ON, VIS5D_OFF, VIS5D_TOGGLE, or VIS5D_GET. This command sets or tests the status of the verylarge mode flag. When set, graphical elements from a particular data context are computed on demand, not in advance, in an effort to minimize memory usage so larger datasets can be visualized.

Return value is either VIS5D_ON or VIS5D_OFF indicating the current status of the mode flag.

Map projection and vertical coordinate system commands

vis5d_get_ctx_projection data_context
This command returns the type and parameters of the current map projection associated with the data context. An example result is: PROJ_LINEAR 90.0 10.0 2.0 2.5
vis5d_get_dtx_projection display_context
This command returns the type and parameters of the current map projection associated with the display context. An example result is: PROJ_LINEAR 90.0 10.0 2.0 2.5
vis5d_get_ctx_vertical data_context
This command returns the type and parameters of the current vertical coordinate system associated with the data context. An example result is: VERT_EQUAL_KM 0.0 1.5
vis5d_get_dtx_vertical display_context
This command returns the type and parameters of the current vertical coordinate system associated with the display context. An example result is: VERT_EQUAL_KM 0.0 1.5
vis5d_set_dtx_projection_and_vertical display_context proj_arg proj_value level
This sets anyone of the values which define a map projection or vertical coordinate system associated with the $dtx. ***NOTE***, a call to SET_PROJ_Done is needed after altering any parameters.

  • proj_arg - one of
    • SET_PROJ_Projection,
      • proj_value -one of
        • PROJ_GENERIC
        • PROJ_LINEAR
        • PROJ_STEREO
        • PROJ_ROTATED
        • PROJ_CYLINDRICAL
        • PROJ_SPHERICAL
    • SET_PROJ_NorthBound,
    • SET_PROJ_WestBound,
    • SET_PRO_RowInc,
    • SET_PROJ_ColInc,
    • SET_PROJ_Lat1,
    • SET_PROJ_Lat2,
    • SET_PROJ_PoleRow,
    • SET_PROJ_PoleCol,
    • SET_PROJ_CentralLat,
    • SET_PROJ_CentralLon,
    • SET_PROJ_CentralRow,
    • SET_PROJ_CentralCol,
    • SET_PROJ_Rotation,
    • SET_PROJ_CylinderScale
    • SET_PROJ_VerticalSystem,
      • proj_value -one of
        • VERT_GENERIC
        • VERT_EQUAL_KM
        • VERT_NONEQUAL_KM
        • VERT_NONEQUAL_MB
    • SET_PROJ_LevInc,
    • SET_PROJ_BottomBound,
    • SET_PROJ_Height.
    • SET_PROJ_Done.
  • proj_value - this is the value that proj_arg is set to.
  • level - specifies the grid level (0..MaxGridLevels-1) when proj_arg = SET_PROJ_Height and heights are unegually spaced. NOTE: this is omitted otherwise.
vis5d_get_curved display_context
Returns whether or not the current map projection associated with the display context results in the display of a curved or rectangular 3-D bounding box. Returns VIS5D_ON if curved and VIS5D_OFF if rectangular.

Topography, Map and Texture Commands

vis5d_check_topo display_context
Returns VIS5D_ON if a topography is available for display, otherwise returns VIS5D_OFF.
vis5d_set_topo_base display_context state level
Turn on or off the topography base and set the level for the base.
  • state - 1 enable topo base, 0 disable topo base(defualt = 0)
  • level - level at which the topography base extends below ground, gridlevel [0..Nl-1]
vis5d_check_map display_context
Returns VIS5D_ON if a map outline is available for display, otherwise returns VIS5D_OFF.
vis5d_set_flatmap_level display_context level
Set the level where the (non-surface) map is located.
  • level - grid level [0..Nl-1]
vis5d_get_flatmap_level display_context
Get the grid level where the (non-surface) map is located.
vis5d_check_textureo display_context
Returns VIS5D_ON if a topography texture map(s) is available for display, otherwise returns VIS5D_OFF.
vis5d_get_topo_range display_context
Returns a two element list indicating the min and max topography heights in the display grid domain. Values are in km.
vis5d_reset_topo_colors display_context
Reset the topography color ramp to the default.
vis5d_set_topo_color_var_and_owner display_context varctx var
Specity the variable used to color the topography. 'varctx' is the $ctx where the variable is from. If var = -1 then the topography is colored according to height, the default.
vis5d_init_map display_context mapfilename
Load a map from mapfilename into a display. Vis5D map files can be created using util/makemap.c.
vis5d_init_topo display_context topofilename
Load topography from topofilename into a display. Vis5D topo files can be created using util/maketopo.c.
vis5d_init_texture display_context texturefilename
Load a texture from an SGI RGB file named texturefilename into a display. This is texture mapped onto the topography.
vis5d_init_firstarea display_context area_number
Load a sequence of McIDAS area files, starting at area_number one for each time step, into a display. These are texture mapped onto the topography.
vis5d_init_sequence display_context sequencefilename
Load a sequence of images, one for each time step, from sequencefilename. These are texture mapped onto the topography. These files contain a header of three integers giving (1) the number of images in the sequence, (2) the height (# lines) of each image, and (3) the width (# pixels per line). After that each image consists of height*width unsigned characters.

Cloning, External Functions and Expression Commands

vis5d_make_clone_variable data_context clonename var
Make a clone of an existing variable. clonename is the new for the clone and var is the number or name of the variable to copy.
vis5d_compute_ext_func display_context funcname
Invoke an external Fortran function named funcname to compute a new variable. funcname is a Unix file path/name. The name of the resulting new variable will be the funcname without the leading directory specification. The $ctx which this new variable belongs to will be the first $ctx attached to the $dtx.
vis5d_make_expr_var display_context expression
Evaluate a simple expression, resulting in a new variable. Expressions are of the form: "var.# = expression" An example expression might be: diffU.1 = U.1 - U.2 The variable 'diffU' belongs to $ctx number 1, along with the first 'U' variable. The second 'U' variable belongs to $ctx number 2. If the number of the $ctx is omitted from the end of the variable, it is assumed that the variable belongs to the first $ctx attacted to the $dtx.

Rendering Commands

vis5d_draw_frame display_context
Redraw the window image for the current dtx timestep.
vis5d_draw_3d_only display_context animflag
Draw the 3-D elements of the scene only. animflag controls whether or not contour numbers are displayed. Zero means draw the numbers, non-zero means do not draw contour numbers.
vis5d_draw_sounding_only display_context redraw_background
Draw the elements in the sounding window only. redraw_background controls whether or not the constant pixmap graphics such as tick marks or theta lines should be redrawn (in case Sounding window is resized or graphics enables change). Zero means do not redraw, and one means redraw.
int vis5d_init_samescale display_context
This will normalize the scale to which the 3 vertical plot variables will be drawn to.
vis5d_map_sndwindow display_context show
Map/Unmap the sounding window to the graphics display. If show is 1 then map the sounding window to the graphics display, it show is 0 then unmap the sounding window to the graphics display.
vis5d_invalidate_dtx_frames display_context
Invalidate any cached image frames belonging to the display context. Only useful on systems with slow 3-D graphics.
vis5d_graphics_mode display_context graphic mode
Enable/disable drawing of a Vis5D graphic.
  • graphic - one of
    • VIS5D_BOX = the 3-D box
    • VIS5D_CLOCK = the clock
    • VIS5D_MAP = the map lines
    • VIS5D_TOPO = the topography
    • VIS5D_PERSPECTIVE = perspective rendering
    • VIS5D_CONTOUR_NUMBERS = display of contour numbers in slices NOTE this is reversed so you must set this to VIS5D_OFF to see contour numbers
    • VIS5D_GRID_COORDS = display grid coords instead of geographic coords
    • VIS5D_PRETTY = pretty rendering mode
    • VIS5D_INFO = information display
    • VIS5D_PROBE = the probe values
    • VIS5D_CURSOR = the 3-D cursor
    • VIS5D_ANIMRECORD = stored frame animation
    • VIS5D_TEXTURE = texture mapping on topography
    • VIS5D_DEPTHCUE = depth cuing of 3-D box
    • VIS5D_BARBS = use wind barbs rather than arrows
    • VIS5D_JULIAN = use yyddd rather than dd month yy in clock
    • VIS5D_SND_THTA = display theta lines
    • VIS5D_SND_THTE = display theta-e lines
    • VIS5D_SND_W = display constant mixing ratio (w) lines
    • VIS5D_SND_TICKS = display horz. & vert. tick lines
    • VIS5D_REVERSE = reverse video (exchange black and white)
    • VIS5D_ALPHAMODE = specifies alpha blending
    • VIS5D_HIRESTOPO = hi-res topo
    • VIS5D_SAMESCALE = same vertical plot scale in sounding window
  • mode - one of
    • VIS5D_ON = turn on the graphic
    • VIS5D_OFF = turn off the graphic
    • VIS5D_TOGGLE = toggle the graphics display state
    • VIS5D_GET = just return current setting
Returns 1 if graphic is displayed, 0 if graphic is not displayed or an error message if any parameters are invalid.
vis5d_enable_irregular_graphics irregular_data_context graphic mode
Enable/disable drawing of a Vis5D graphic.
  • graphic - one of
    • VIS5D_TEXTPLOT = text plot
  • mode - one of
    • VIS5D_ON = turn on the graphic
    • VIS5D_OFF = turn off the graphic
    • VIS5D_TOGGLE = toggle the graphics display state
    • VIS5D_GET = just return current setting
Returns 1 if graphic is displayed, 0 if graphic is not displayed or an error message if any parameters are invalid.
vis5d_enable_graphics data_context graphic number mode
Enable/disable drawing of a Vis5D graphic.
  • graphic - one of
    • VIS5D_ISOSURF = isosurface
    • VIS5D_HSLICE = horizontal contour line slice
    • VIS5D_VSLICE = vertical contour line slice
    • VIS5D_CHSLICE = horizontal colored slice
    • VIS5D_CVSLICE = vertical colored slice
    • VIS5D_VOLUME = volume rendering
    • VIS5D_TRAJ = wind trajectory set
    • VIS5D_HWIND = horizontal wind slice
    • VIS5D_VWIND = vertical wind slice
    • VIS5D_HSTREAM = horizontal streamline slice
    • VIS5D_VSTREAM = vertical streamline slice
  • number - depends on value of graphic:
    • variable number, if graphic = VIS5D_ISOSURF, VIS5D_HSLICE, VIS5D_VSLICE, VIS5D_CHSLICE, VIS5D_CVSLICE or VIS5D_VOLUME
    • trajectory set if graphic = VIS5D_TRAJ
    • slice number if graphic = VIS5D_HWIND, VIS5D_VWIND, VIS5D_HSTREAM or VIS5D_VSTREAM
    • ignored otherwise
  • mode - one of
    • VIS5D_ON = turn on the graphic
    • VIS5D_OFF = turn off the graphic
    • VIS5D_TOGGLE = toggle the graphics display state
    • VIS5D_GET = just return current setting
Returns 1 if graphic is displayed, 0 if graphic is not displayed or an error message if any parameters are invalid.
vis5d_enable_sfc_graphics data_context graphic number mode
Enable/disable drawing of a Vis5D surface graphic.
  • graphic - one of
    • VIS5D_HSLICE = horizontal contour line slice
    • VIS5D_HWIND = horizontal wind slice
    • VIS5D_HSTREAM = horizontal streamline slice
    • VIS5D_MAP = map
  • number - depends on value of graphic:
    • variable number, if graphic = VIS5D_HSLICE
    • slice number if graphic = VIS5D_HWIND, VIS5D_HSTREAM
    • ignored otherwise
  • mode - one of
    • VIS5D_ON = turn on the surface graphic
    • VIS5D_OFF = turn off the surface graphic
    • VIS5D_TOGGLE = toggle the surface graphics display state
    • VIS5D_GET = just return current setting
Returns 1 if graphic is displayed, 0 if graphic is not displayed or an error message if any parameters are invalid.
vis5d_get_volume_and_owner display_context
Returns two variables, varctx and var. var is the variable number of the currently displayed volume or -1 if none is currently displayed. varctx is the $ctx number where the var belongs.
vis5d_set_volume_and_owner display_context varctx var
Set the currently displayed volume. var is a variable number or name indicating the variable to display. If var is -1, disable volume display. varctx is the $ctx number where the var belongs to.
vis5d_init_clock display_context flag
Specify if a circle should be drawn around the clock. If flag is 0 then no circle is draw, if flag is 1 then the circle is drawn
vis5d_set_color display_context graphic numberctx number red green blue alpha
or
vis5d_set_color display_context graphic number red green blue alpha
Set the color of a Vis5D graphic such as an isosurface, slice or trajectory.
  • graphic - one of
    • VIS5D_ISOSURF = isosurface
    • VIS5D_HSLICE = horizontal contour line slice
    • VIS5D_VSLICE = vertical contour line slice
    • VIS5D_CHSLICE = horizontal colored slice
    • VIS5D_CVSLICE = vertical colored slice
    • VIS5D_VOLUME = volume rendering
    • VIS5D_TRAJ = wind trajectory set
    • VIS5D_HWIND = horizontal wind slice
    • VIS5D_VWIND = vertical wind slice
    • VIS5D_HSTREAM = horizontal streamline slice
    • VIS5D_VSTREAM = horizontal streamline slice
    • VIS5D_BOX = the 3-D box
    • VIS5D_BACKGROUND = window background color
    • VIS5D_LABEL = color of text labels
    • VIS5D_MAP = color of map lines
  • numberctx - if number represents a variable then this is the $ctx number where the variable belongs to (if not present, use display_context), ignored otherwise
  • number - meaning depends on value of graphic argument
    • variable number, if graphic = VIS5D_ISOSURF, VIS5D_HSLICE, VIS5D_VSLICE, VIS5D_CHSLICE or VIS5D_CVSLICE
    • trajectory set if graphic = VIS5D_TRAJ
    • slice number if graphic = VIS5D_HWIND, VIS5D_VWIND, VIS5D_HSTREAM or VIS5D_VSTREAM
    • ignored otherwise
  • red, green, blue - the color components as floating point numbers in the interval [0,1]
  • alpha - the transparency where 0 is completely transparent and 1 is completely opaque
vis5d_get_color display_context graphic numberctx number
or
vis5d_get_color display_context graphic number
Return the colors of a Vis5D graphic such as an isosurface, slice or trajectory.
  • graphic - one of
    • VIS5D_ISOSURF = isosurface
    • VIS5D_HSLICE = horizontal contour line slice
    • VIS5D_VSLICE = vertical contour line slice
    • VIS5D_CHSLICE = horizontal colored slice
    • VIS5D_CVSLICE = vertical colored slice
    • VIS5D_VOLUME = volume rendering
    • VIS5D_TRAJ = wind trajectory set
    • VIS5D_HWIND = horizontal wind slice
    • VIS5D_VWIND = vertical wind slice
    • VIS5D_HSTREAM = horizontal streamline slice
    • VIS5D_VSTREAM = horizontal streamline slice
    • VIS5D_BOX = the 3-D box
    • VIS5D_BACKGROUND = window background color
    • VIS5D_LABEL = color of text labels
    • VIS5D_MAP = color of map lines
  • numberctx - if number represents a variable then this is the $ctx number where the variable belongs to (if not present, use display_context), ignored otherwise
  • number - meaning depends on value of graphic argument
    • variable number, if graphic = VIS5D_ISOSURF, VIS5D_HSLICE, VIS5D_VSLICE, VIS5D_CHSLICE or VIS5D_CVSLICE
    • trajectory set if graphic = VIS5D_TRAJ
    • slice number if graphic = VIS5D_HWIND, VIS5D_VWIND, VIS5D_HSTREAM or VIS5D_VSTREAM
    • ignored otherwise
vis5d_set_color_table_entry display_context graphic varctx var entry r g b a
or
vis5d_set_color_table_entry display_context graphic var entry r g b a
Set one entry in a color lookup table. To setup a whole color table will typically require 256 calls to this function. One call per color table entry.
  • graphic - one of
    • VIS5D_ISOSURF = an isosurface's color table
    • VIS5D_CHSLICE = a horizontal colored slice's color table
    • VIS5D_CVSLICE = a vertical colored slice's color table
    • VIS5D_TRAJ = a trajectory set's color table
    • VIS5D_VOLUME = a volume's color table
  • varctx - which $ctx the var belongs to (if not present, use display_context)
  • var - which variable
  • entry - which color table entry, must be between 0 and 255.
  • r, g, b, a - the red, green, blue, and alpha values in [0,255]
vis5d_set_legends display_context position size
Set the positon and size of the color legends.
  • position -one of
    • VIS5D_TOP
    • VIS5D_BOTTOM
    • VIS5D_RIGHT
    • VIS5D_LEFT
  • size - size of lengend
vis5d_set_logo_size display_context size
Set the size of the 'Vis5D' logo. The logo is reduced by a factor size
vis5d_alpha_mode display_context mode
Sets the alpha (transparency) mode for a display context. If mode is zero then "screen-door" transparency is used. If mode is one then alpha blending is used to render transparent surfaces.
vis5d_font display_context fontname [size]
Specifies the font used for drawing text labels and the clock. fontname is the name of a GL or X font. If using GL fonts, size is the height of the font to use where 72 equals one inch.
vis5d_get_font_height display_context
Return the font height used for drawing text labels and the clock.
vis5d_linewidth display_context width
Specifies the width of line segments in pixels. Default is 1.0.
vis5d_resize_contour_font data_context sizefactorx sizefactory
Increase the width/height size of the contour numbers by a factor of 'sizefactorx', and 'sizefactory'. Default value of 'sizefactorx'and 'sizefactory' is 0.
vis5d_set_probe_vars data_context numvars varlist
Specifie which variables to display when using the probe.
  • numvars - number of variables, -1 for all variables, 0 for no variables
  • varlist - list of variables numbers, or blank if numvars = -1 or numvars = 0
  • Example: vis5d_set_probe_vars 0 5 0 1 2 3 7

Clipping Functions

vis5d_set_hclip display_context number level
Set a a horizontal clipping plane.
  • number - one of
    • 0 = default level position is MaxLevels
    • 1 = default level position is 0
  • level - the grid level at which to set the selected horizontal clipping plane
vis5d_set_vclip display_context number r1 c1 r2 c2
Set a vertical clipping plane.
  • number - one of
    • 0 = default position is north side of grid box, (r1,c1,r2,c2) = (0,0,0,Nc)
    • 1 = defualt position is south side of grid box, (r1,c1,r2,c2) = (Nr,0,Nr,Nc)
    • 2 = default position is west side of grid box, (r1,c1,r2,c2) = (0,0,Nr,0)
    • 3 = default position is east side of grid box, (r1,c1,r2,c2) = (0,Nc,Nr,Nc)
  • r1, c1, r2, c2 - grid coordinates of the two corners of the vertical clipping plane
vis5d_get_hclip display_context number
Return the grid level at which the horizontal clipping plane, designated by number(0..1), is located at.
vis5d_get_vclip display_context number
Return the grid coordinates (r1, c1, r2, c2) for the two corners of the vertical clipping plane designated by number (0..3).

3-D View Commands

vis5d_set_matrix display_context matrix
Sets the 3-D viewing matrix. matrix is a list of sixteen values representing the transformation matrix in row-major order. This is an advanced function not intended for most users.
vis5d_get_matrix display_context
Returns a list of 16 numbers which is the current 3-D viewing transformation matrix.
vis5d_set_ortho_view display_context view
Set the current view to either VIS5D_NORTH, VIS5D_SOUTH, VIS5D_EAST, VIS5D_WEST, VIS5D_TOP or VIS5D_BOTTOM.
vis5d_set_view display_context xrot yrot zrot scale xtrans ytrans ztrans
Sets the 3-D viewing matrix by means of separate rotation, scale and translation values. The order of transformations is Z-axis rotate, X-axis rotate, Y-axis rotate, scale then translate. Arguments:
  • xrot, yrot, zrot - rotation about each axis in degrees
  • scale - scaling factor
  • xtrans, ytrans, ztrans - translation along each axis
vis5d_get_view display_context
Returns the xrot, yrot, zrot, scale, xtrans, ytrans, and ztrans.
vis5d_set_view_scales display_context scalex scaley scalez
Set the current 3-D transformation matrix scale factors.
  • scalex - scale factor for the X axis
  • scaley - scale factor for the Y axis
  • scalez - scale factor for the Z axis
vis5d_get_view_scales display_context
Get the current 3-D transformation matrix scale factors.
vis5d_set_camera display_context perspective frontclip zoom
Sets the parameters of the imaginary 3-D camera. Arguments:
  • perspective - 0=orthographic, 1=perspective
  • frontclip - position of front clipping plane, a value in [0,1] where 0=no clipping and 1=all clipped
  • zoom - zoom (scale) factor, 1.0 is normal
vis5d_get_camera display_context
Returns the parameters of the imaginary 3-D camera: perspec, frnotclip, zoom.

Text Plots

vis5d_set_text_plot irregular_data_context var density fontx fonty fontspace
Sets the parameters for a text plot.
  • var - variable number
  • density - number specifying the density for plotting the data
  • fontx, fonty - text plot font size
  • fontspace - number specifying size of the space between text plot characters
vis5d_get_text_plot irregular_data_context var
Returns the parameters for a text plot: density, fontx, fonty and fontspace
vis5d_make_text_plot irregular_data_context time urgent
Compute a text plot for 'time'. If urgent is non-zero then computing this text plot will be given priority over any other pending computation.
vis5d_set_textplot_color_status irregular_data_context var status
Set the color status of the text plot variable 'var'. If status is VIS5D_ON then a colormap will be used to determine the colors of the text plot. If status is VIS5D_OFF then monocolor will be used.
vis5d_get_textplot_color_status irregular_data_context var
Return the status of the text plot variable. VIS5D_ON indicates multicolor and VIS5D_OFF indicates a monocolor.

Isosurface, Slice, and Trajectory Commands

vis5d_set_isosurface data_context var isolevel
Sets the isolevel for the isosurface specified by var. Note that the isosurface is not computed by this function.
vis5d_get_isosurface data_context var
Returns the current isolevel for a particular variable.
vis5d_set_isosurface_color_var_and_owner data_context isovar colorvarctx colorvar
Specifies which variable to use to color an isosurface. isovar is the isosurface to color. colorvar is the variable to color the surface or -1 which means don't color the surface. colorvarctx is the $ctx number where colorvar is from.
vis5d_make_isosurface data_context time var urgent
Compute a(n) isosurface(s). Time indicates which timestep to compute. The value VIS5D_ALL_TIMES can be used to specify all timesteps. var indicates which variable to compute the isosurface for. If urgent is non-zero then computing this isosurface will be given priority over any other pending computation.
vis5d_set_hslice data_context var interval low high level
Sets the attributes for a horizontal contour line slice.
  • var - which variable, a name or number
  • interval - the interval between contour lines
  • low - the low limit for contouring
  • high - the high limit for contouring
  • level - position of the slice as a grid level
Note that this function does not actually compute the slice.
vis5d_get_hslice data_context var
Returns the attributes of a horizontal contour lines slice. A list of four values is returned: interval low high level. These values correspond to those of vis5d_set_hslice.
vis5d_make_hslice data_context time var urgent
Compute (a) horizontal contour slice(s). Time indicates which timestep to compute. The value VIS5D_ALL_TIMES can be used to specify all timesteps. var indicates which variable to compute the slice for. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_set_vslice data_context var interval low high r0 c0 r1 c1
Sets the attributes for a vertical contour line slice.
  • var - which variable, a name or number
  • interval - the interval between contour lines
  • low - the low limit for contouring
  • high - the high limit for contouring
  • r0, c0 - position of left edge of slice in grid rows and columns
  • r1, c1 - position of right edge of slice in grid rows and columns
Note that this function does not actually compute the slice.
vis5d_get_vslice data_context var
Returns the attributes of a vertical contour lines slice. A list of seven values is returned: interval low high r0 c0 r1 c1. These values correspond to those of vis5d_set_vslice.
vis5d_make_vslice data_context time var urgent
Compute (a) vertical contour slice(s). Time indicates which timestep to compute. The value VIS5D_ALL_TIMES can be used to specify all timesteps. var indicates which variable to compute the slice for. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_set_chslice data_context var level
Sets the attributes for a horizontal color slice.
  • var - which variable, a name or number
  • level - position of the slice as a grid level
Note that this function does not actually compute the slice.
vis5d_get_chslice data_context var
Returns the attributes of a horizontal color slice. A list of one value is returned: level, as is used by vis5d_set_chslice.
vis5d_make_chslice data_context time var urgent
Compute (a) horizontal color slice(s). Time indicates which timestep to compute. The value VIS5D_ALL_TIMES can be used to specify all timesteps. var indicates which variable to compute the slice for. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_set_cvslice data_context var r0 c0 r1 c1
Sets the attributes for a vertical color slice.
  • var - which variable, a name or number
  • r0, c0 - position of left edge of slice in grid rows and columns
  • r1, c1 - position of right edge of slice in grid rows and columns
Note that this function does not actually compute the slice.
vis5d_get_cvslice data_context var
Returns the attributes of a vertical color slice. A list of four values is returned: r0, c0, r1, c1, as is used by vis5d_set_cvslice.
vis5d_make_cvslice data_context time var urgent
Compute (a) vertical color slice(s). Time indicates which timestep to compute. The value VIS5D_ALL_TIMES can be used to specify all timesteps. var indicates which variable to compute the slice for. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_set_hwindslice display_context slicenum density scale level
Sets the attributes for a horizontal wind vector slice.
  • slicenum - which slice, currently 0 or 1
  • density - density of wind vectors 0.25, 0.5 or 1.0 for example
  • scale - scale factor for vectors. 1.0 is normal
  • level - position of the slice as a grid level
Note that this function does not actually compute the slice.
vis5d_get_hwindslice display_context slicenum
Returns the attributes of a horizontal wind slice. A list of three values is returned: density scale level which correspond to the parameters of vis5d_set_hwindslice.
vis5d_make_hwindslice display_context dtx_time slice urgent
Compute (a) horizontal wind vector slice(s). Time indicates which timestep to compute. NOTE: dtx_time = [0..Numtimes-1] where Numtimes is the number of timesteps in the display context. The value VIS5D_ALL_TIMES can be used to specify all timesteps. slice indicates which slice to compute. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_set_vwindslice display_context slicenum density scale r0 c0 r1 c1
Sets the attributes for a vertical wind vector slice.
  • slicenum - which slice, currently 0 or 1
  • density - density of wind vectors 0.25, 0.5 or 1.0 for example
  • scale - scale factor for vectors. 1.0 is normal
  • r0, c0 - position of left edge of slice in grid rows and columns
  • r1, c1 - position of right edge of slice in grid rows and columns
Note that this function does not actually compute the slice.
vis5d_get_vwindslice display_context slicenum
Returns the attributes of a vertical wind slice. A list of six values is returned: density scale r0 c0 r1 c1 which correspond to the parameters of vis5d_set_vwindslice.
vis5d_make_vwindslice display_context dtx_time slice urgent
Compute (a) vertical wind vector slice(s). Time indicates which timestep to compute. NOTE: dtx_time = [0..Numtimes-1] where Numtimes is the number of timesteps in the display context. The value VIS5D_ALL_TIMES can be used to specify all timesteps. slice indicates which slice to compute. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_set_hstreamslice display_context slicenum density level
Sets the attributes for a horizontal wind stream slice.
  • slicenum - which slice, currently 0 or 1
  • density - density of stream lines, 1.0 is default
  • level - position of the slice as a grid level
Note that this function does not actually compute the slice.
vis5d_get_hstreamslice display_context slicenum
Returns the attributes of a horizontal stream slice. A list of two values is returned: density level which correspond to the parameters of vis5d_set_hstreamslice.
vis5d_make_hstreamslice display_context dtx_time slice urgent
Compute (a) horizontal wind stream slice(s). Time indicates which timestep to compute. NOTE: dtx_time = [0..Numtimes-1] where Numtimes is the number of timesteps in the display context. The value VIS5D_ALL_TIMES can be used to specify all timesteps. slice indicates which slice to compute. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_set_vstreamslice display_context slicenum density r0 c0 r1 c1
Sets the attributes for a vertical wind stream slice.
  • slicenum - which slice, currently 0 or 1
  • density - density of stream lines, 1.0 is default
  • r0, c0 - position of left edge of slice in grid rows and columns
  • r1, c1 - position of right edge of slice in grid rows and columns
Note that this function does not actually compute the slice.
vis5d_get_vstreamslice display_context slicenum
Returns the attributes of a vertical stream slice. A list of five values is returned: density r0 c0 r1 c1 which correspond to the parameters of vis5d_set_vstreamslice.
vis5d_make_vstreamslice display_context dtx_time slice urgent
Compute (a) vertical wind stream slice(s). Time indicates which timestep to compute. NOTE: dtx_time = [0..Numtimes-1] where Numtimes is the number of timesteps in the display context. The value VIS5D_ALL_TIMES can be used to specify all timesteps. slice indicates which slice to compute. If urgent is non-zero then computing this slice will be given priority over any other pending computation.
vis5d_print_traj display_context traj_num
Prints the tail position of the trajectory and the variable value if one is mapped to it for each time step. traj_num specifies which trajectory to print out. The output will be of the form: TimeStep Lat Lon Hgt VarValue
vis5d_make_traj display_context row column level dtx_time trajset
Compute a window trajectory.
  • row, column, level - starting coordinate of trajectory in dtx (virtual) grid coordinates
  • dtx_time - display context timestep at which to start trajectory trace
  • trajset - which trajectory set
vis5d_set_traj display_context step length ribbonflag
Set trajectory attributes.
  • step - trajectory step size. 1.0 is default
  • length - trajectory length scaling. 1.0 is default
  • ribbonflag - if non-zero draw a ribbon trajectory, else draw as line segments.
vis5d_get_traj display_context
Returns current trajectory attributes as a list of three values: step length ribbonflag which correspond to the parameters of vis5d_set_traj
vis5d_delete_last_traj display_context
Delete the last trajectory made.
vis5d_delete_traj_set display_context set
Delete a whole set of trajectories.
vis5d_set_trajectory_color_var_and_owner display_context set varctx var
Color all trajectories in the specified set according to the physical variable var. var may be a variable name or number. varctx is the $ctx number where the var is from.
vis5d_make_timestep_graphics display_context timestep
Compute all graphics for the specified display context timestep.
vis5d_free_graphics data_context
Deallocate all stored graphics. This can be useful if memory becomes severlay fragmented.

Text Label Commands

vis5d_make_label display_context x y text
Make a text label at coordinate (x,y). x and y are in window coordinates with (0,0) being the upper-left corner. text is a string.
vis5d_delete_label display_context x y
Delete a text label at coordinate (x,y). x and y are in window coordinates with (0,0) being the upper-left corner.

Cursor Commands

vis5d_get_cursor display_context
Returns the current 3-D cursor position as a list of three numbers which are in $dtx graphics coordinates.
vis5d_set_cursor display_context x y z
Sets the current 3-D cursor position given an (X,Y,Z) position in $dtx graphics space.

3-D Window Commands

vis5d_get_image_formats
Return's a list of image file formats supported by this implementation of Vis5D. The list may include:
  • VIS5D_RGB - SGI's RGB image file format
  • VIS5D_GIF - GIF image file format
  • VIS5D_XWD - X window dump file format
  • VIS5D_PS - Black and white PostScript
  • VIS5D_COLOR_PS - Color PostScript
vis5d_save_window filename format
Save the large window image to the named file. format is one of the file format identifiers returned by vis5d_get_image_formats.
vis5d_save_snd_window display_context filname format
Save the sounding/vertical plot window to the named file. There is a seperate window for each $dtx so the display_context denotes which $dtx. format is one of the file format identifiers returned by vis5d_get_image_formats.
vis5d_print_window
Print the large window image to the default PostScript printer.
vis5d_print_snd_window display_context
Print the sounding/vertical plot window image to the default PostScript printer. display_context specifies which $dtx sounding/vertical plot window to print.
vis5d_resize_BIG_window width height
Resize the BIG main window which all other 3-D graphics displays are mapped to.
vis5d_resize_3d_window display_context width height
Resize the 3-D graphics window associated with the $dtx.
vis5d_moveresize_BIG_window xpos ypos width height
Move and Resize BIG main window which all other 3-D graphics displays are mapped to.
vis5d_moveresize_3d_window display_context xpos ypos width height
Move and Resize the 3-D graphics window associated with the $dtx.

Coordinate Conversion Commands

A $ctx may have a different graphics and/or grid coordinate system than the $dtx it is attached to. In the following functions a PRIME will indicate that the coordinate system is defined by the $dtx. If the PRIME is omitted then the coordinate system is defined by the $ctx.
vis5d_xyz_to_grid data_context time var {x y z}
Convert a data graphics (x,y,z) coordinate to a data grid coordinate. The resulting grid coordinate is returned as a list of three values: {row column level}.
vis5d_xyzPRIME_to_gridPRIME display_context time var {x y z}
Convert a display graphics (x,y,z) coordinate to a display grid coordinate. The resulting grid coordinate is returned as a list of three values: {row column level}.
vis5d_grid_to_xyz data_context time var {row col lev}
Convert a data grid (row,column,level) coordinate to a data graphics coordinate. The resulting graphics coordinate is returned as a list of three values: {x y z}.
vis5d_gridPRIME_to_xyzPRIME display_context time var {row col lev}
Convert a display grid (row,column,level) coordinate to a display graphics coordinate. The resulting graphics coordinate is returned as a list of three values: {x y z}.
vis5d_xyz_to_geo data_context time var {x y z}
Convert a data graphics (x,y,z) coordinate to a geographic coordinate. The resulting geographic coordinate is returned as a list of three values: {latitude longitude height}.
vis5d_xyzPRIME_to_geo display_context time var {x y z}
Convert a display graphics (x,y,z) coordinate to a geographic coordinate. The resulting geographic coordinate is returned as a list of three values: {latitude longitude height}.
vis5d_geo_to_xyz data_context time var {lat lon hgt}
Convert a geographic coordinate (lat,lon,hgt) to a data graphics coordinate. The resulting graphics coordinate is returned as a list of three values: {x y z}.
vis5d_geo_to_xyzPRIME display_context time var {lat lon hgt}
Convert a geographic coordinate (lat,lon,hgt) to a display graphics coordinate. The resulting graphics coordinate is returned as a list of three values: {x y z}.
vis5d_grid_to_geo data_context time var {row col lev}
Convert a data grid coordinate (row,col,lev) to a geographic coordinate. The resulting geographic coordinate is returned as a list of three values: {latitude longitude height}.
vis5d_gridPRIME_to_geo display_context time var {row col lev}
Convert a display grid coordinate (row,col,lev) to a geographic coordinate. The resulting geographic coordinate is returned as a list of three values: {latitude longitude height}.
vis5d_rowcol_to_latlon data_context time var {row col}
Convert a data row and column to lat and lon. The output is a list of two values: {latitude longitude}.
vis5d_rowcolPRIME_to_latlon display_context time var {row col}
Convert a display row and column to lat and lon. The output is a list of two values: {latitude longitude}.
vis5d_latlon_to_rowcol data_context time var {lat lon}
Convert a lat and lon to a data row and column. The output is a list of two values: {row column}.
vis5d_latlon_to_rowcolPRIME display_context time var {lat lon}
Convert a lat and lon to a display row and column. The output is a list of two values: {row column}.
vis5d_geo_to_grid data_context time var {lat lon hgt}>/CODE>
Convert a geographic coordinate (lat,lon,hgt) to a data grid coordinate. The resulting grid coordinate is returned as a list of three values: {row column level}.
vis5d_geo_to_gridPRIME display_context time var {lat lon hgt}>/CODE>
Convert a geographic coordinate (lat,lon,hgt) to a display grid coordinate. The resulting grid coordinate is returned as a list of three values: {row column level}.

Commands Useful with -pipe command line option

vis5d_locate_dtx window x_location y_location
Return $dtx and $grp based on location in window (either the BIG 3-D window or a small 3-D window).
vis5d_name_ctx ContextName
Return $ctx, $dtx and $grp based on ContextName.
vis5d_iconify display_context
Iconify Vis5D windows with GUI for display_context. Iconify current GUI if display_context = -1.
vis5d_deiconify display_context
De-iconify Vis5D windows with GUI for display_context. De-iconify current GUI if display_context = -1.
vis5d_set_name_value name value
Bind the value string to the name string. This is useful for successive scripts to communicate with each other.
vis5d_get_name_value name
Return the value string bound to the name string. This is useful for successive scripts to communicate with each other.

Miscellaneous Commands

vis5d_save display_context filename
Save current Vis5D state of a $dtx to a file as a Tcl script.
source filename
Restore Vis5D state from Tcl script file. This is a general Tcl command rather than a special Vis5D Tcl command.
vis5d_sleep time
Pause execution of the script for time milliseconds.
vis5d_set_busy_cursor display window busy_flag
This changes the status of the window cursor bewteen an arrow and a watch.
  • display - the display
  • window - the window
  • busy_flag - if 0 then use arrow cursor, if 1 then use watch cursor

Vis5d GUI commands

vis5d_gui_set_mouse_mode display_context mode
Set the current mouse mode for the given vis5d GUI associated with the display_context.
  • mode - one of
    • 1 - Normal
    • 2 - Trajectory
    • 3 - Slice
    • 4 - Label
    • 5 - Probe
    • 6 - Sounding
    • 7 - Clipping
vis5d_gui_set_animate display_context state rate dwell
Set the animation attributes for the given vis5d GUI associated with the display_context.
  • state - one of
    • -1 - animate backward
    • 0 - stop animation
    • 1 - animate forward
  • rate - minimum delay time in ms between animation frames.
  • dwell- minimum delay time in ms bewteen the last timestep and first timestep while animating
vis5d_gui_get_animate display_context
Get the animation attributes(state, rate, dwell) for the given vis5d GUI associated with the display_context.
vis5d_gui_set_title x y font title
Create a title and place it in a margin. This function is used in conjunction with 'vis5d_gui_set_margins'. Any number of titles may be created.
  • x, y - location of the title in screen coordinates. (0,0) is upper left.
  • font - X font to use for title.
  • title - string to use as title.
vis5d_gui_set_margins top bottom left right
Create margins around all windows mapped. Top, bottom, left and right specify the size of the window margins in screen pixels. This option will only work when 2 or more windows are mapped.



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

If only one v5dfile is loaded 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

# A Vis5d Tcl script for saving a whole time series of images

# You may need to change these:
set base "frame"
set ext ".gif"
set format VIS5D_GIF

set numtimes [ vis5d_get_dtx_numtimes $ctx ]

for {set time 1} {$time<=$numtimes} {set time [expr $time+1]} {
        vis5d_set_dtx_timestep $ctx [expr $time-1]
        vis5d_draw_frame $ctx
        set name $base$time$ext
        vis5d_save_window $name $format
}


# At this point you may want to invoke a Unix utility to convert a
# series of GIF files into an MPEG animation file.....

Example 2: Save a time series of GIF images with two v5d files

The following example includes two v5d files and each data set is attached to one display. In order to animate both data sets correctly they have been grouped. The result is similar to example 1.
# movie2.tcl

# A Vis5d Tcl script for saving a whole time series of images
# with multiple data sets.

# You may need to change these:
set base "frame"
set ext ".gif"
set format VIS5D_GIF
set ctx0 0
set ctx1 1
set dtx0 0
set dtx1 1
set grp 1

vis5d_set_display_group 0 1
vis5d_set_display_group 1 1
set numtimes [ vis5d_get_grp_numtimes $grp ]

for {set time 1} {$time<=$numtimes} {set time [expr $time+1]} {
        vis5d_set_grp_timestep $grp [expr $time-1]
        vis5d_draw_frame $dtx0
        vis5d_draw_frame $dtx1
        set name $base$time$ext
        vis5d_save_window $name $format
}

Example 3: 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_ctx_grid_levels to find out
# how many grid levels are present for the U rajectory component.
# Note: element 14 of the wind_vars list is the traj U variable.
set wind_vars [ vis5d_get_wind_vars $ctx ]
set traj_uvar [ lindex $wind_vars 14 ]
set traj_levs [ vis5d_get_ctx_grid_levels $ctx $traj_uvar ]


# Get current timestep
set curtime [ vis5d_get_dtx_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: Genenerate a column of wind trajectories for two data sets in one display

This script is the same as the above except there are two data sets sharing the same display( two $ctxs attached to the same $dtx ). The second set of trajectories is also colored yellow instead of white.
# trajcol.tcl

# Generate a column of trajectories at the cursor's lat/lon
# for the current timestep for both data sets which are in the
# same display.


# Which trajectory set should the trajectories be put in:
set trajset 0

set dtx 0
set ctx0 0
set ctx1 1

#set the wind vars for the first data set ctx0, assuming there number
#0 1 and 2 for U V and W.
vis5d_set_wind_vars $dtx -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 0 0 0 1 0 2

# use the levels of the display grid (not data grid), so it's not
# dependent on the variable.
set traj_levs [ vis5d_get_dtx_grid_levels $dtx ]


# Get current timestep
set curtime [ vis5d_get_dtx_timestep $dtx ]


# Get the current cursor position in display grid coordinates
# (not data grid coordinates) as (row,col).
set cursor_xyz [ vis5d_get_cursor $dtx ]
set cursor_rcl [ vis5d_xyzPRIME_to_gridPRIME $dtx $curtime 0 $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 $dtx $row $col $lev $curtime $trajset
        puts "calculating trajset0 for ctx0 at level $lev"
}

#now set the wind vars for the second data set and repeat the above logic.
vis5d_set_wind_vars $dtx -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 1 0 1 1 1 2

set trajset 1
for {set lev 0} {$lev < $traj_levs} {set lev [expr $lev+1]} {
        vis5d_make_traj $dtx $row $col $lev $curtime $trajset
        puts "calculating trajset1 for ctx1 at level $lev"
}

Example 4: 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_ctx_grid_levels $ctx $wvar ]
set level [ expr $num_levels / 2.0 ]


# set the color
vis5d_set_color $ctx VIS5D_HSLICE $ctx $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 5: 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
}


Example 6: Invoking scripts from cron via shell scripts

You can invoke a Vis5D script from cron via a shell script like this (note that Vis5D needs an open display):

  #!/bin/csh
  setenv DISPLAY your_x_display.your_department.your_university.edu:0  
  vis5d your_file.v5d -script your_script.tcl ...

Other links:
Vis5D, API document, Scripting document, Bill Hibbard,