January 2008 Archives

In the Tecplot distributions ($TECHOME/examples/python) are some sample python scripts to illustrate different concepts and address specific user-requested features.  Over the next few months, we'll dissect these, calling out useful features. 

Until then, here is an overview of what's there:

• Keyframe animation (by Andrew Ritzmann) --  [Tutorial]  This script lets you generate an animation based on the viewer's perspective moving.  Simply set a view, take a snapshot, move to the next view, take another snapshot, etc. When you're done, click "OK" and the script interpolates ten positions between each snapshot, generating an AVI animation as its output.  Future versions may include more sophisticated splines. With a two-line change, one can generate a Flash animation.  Source: KeyFrame.py
  
  
• Direct Excel Reading (by Andrew Ritzmann) -- This script is illustrative of using a third-party python library to directly read from an Excel file, do some conversion, and plot the results.  The reader must be installed separately.  The zip file includes the xlrd reader for Windows.  Other platforms may download it from John Machin's site.
  
  The sample geyser temperature reading data is courtesy of Dr. Hank Heasler, National Park Service. 
  
  Zip distribution: convert_excel.zip.  
  
  
• FFT (by Jim Carson, based on work by Anders Andressen in Linux Gazette) -- This simple example illustrates loading data, computing an FFT, and plotting the results. The space-delimited data file, sunspots.dat, contains the number of sunspots observed from 1700 through 2000.   Script: sunspots.py
  
  
• Integration visual (by Andrew Ritzmann) -- this python script fills in the area under a curve, useful to show a user which area will be integrated. Source: integration_visual.py

Tecplot 360 2008 only (because Tecplot Focus doesn't have these two loaders):

• Load multiple plot3D grid files (by Andrew Ritzmann) -- this python routine uses a TK dialog as a front-end to load multiple PLOT-3D files into Tecplot, saving many mouse clicks. It intelligently pattern matches for grid and solution files, then uses Tecplot's macro language to actually load the data.
  Script, animated example
  
  
• Load multiple STL files (by Andrew Ritzmann) -- this python routine uses a TK dialog as a front-end to load multiple STL (CAD-type drawings) data files, saving many mouse clicks.
  Script, (no animation, yet)
  
  

Finally, for humor value, my first python script ever:

• Style-o-Matic (by Jim Carson) -- This script is an example of using python to automate calling Tecplot's macro language.  What it does is automatically set surface versus volume styles differently, based on the contents of a text file in the user's TECHOME directory.  For example, for volume zones it will toggle off the shade and mesh styles.    Archive: styleomatic.zip.
  

To familiarize yourself with the basic use of the Quick Python Scripts panel, here is an interactive tutorial using the sample KeyFrame.py (also contained in your examples/python/ directory).

Now, we will write the ubiquitous Hello World.  Here is the code:

import TecUtil
import TecVals

def TP_hello_world():
    TecUtil.DialogMessageBox("Hello, world!",TecVals.MessageBox_Information)


Save the file into your examples/python directory.  Load and run it via quick macro panel as shown on the right.


You will see this:


Now for some explanation.  These lines:

import TecUtil
import TecVals


include the set of Tecplot constant definitions and functions documented in the ADK reference manual.  We've tried to make these function calls as python-like as we could. 

This next line:

def TP_hello_world():


defines the function to call.  As a convention, any function beginning with TP_ will be visible from the Quick Python Scripts panel for that module (with the TP_ removed).  We did this to give users flexibility in what functions were displayed in the list.  For example, without this filtering, importing a library like NumPy or SciPy would show a long, unwieldy list of functions.

Finally, this line:

    TecUtil.DialogMessageBox("Hello, world!",TecVals.MessageBox_Information)

calls the Tecplot function to post a message box.   The function's parameters are a message to post and the type of message.  If I were a real programmer, I would check the return value of the function.

Let's make this slightly more useful and show another feature of the QuickPythonScripts panel, the ability to pass parameters.  Here's the source, hello_ymh.py.

def TP_hello_world(your_message_here):
    return TecUtil.DialogMessageBox("Hello, " + your_message_here + "!",
    TecVals.MessageBox_Information)

When loaded, you'll notice a slight change when the function is selected:
We can now send a parameter to the script.  For example, I've added my name. When the function's run, the obvious happens:


Multiple parameters are separated by a comma.  For example, the debugv function takes a message and a value.  (And, illustrating the earlier point about this dialog not showing functions that are not prefaced by TP_, TP_debugv calls another function, debugm.

For those who have used Tecplot's macro language, you can record Tecplot macros that load and call functions in the Quick Python Scripts.  This might be useful if you're doing a batch set of operations.  For example:

$!EXTENDEDCOMMAND COMMANDPROCESSORID = 'Python Utility'
  COMMAND = 'RUNPYFUNCTION MODULE="hello_world" FUNCTION="hello_ymh" ARGUMENTS="Jim"'

First: Don't Panic.  This tutorial is erring on the side of being more thorough.

To keep things simple, the Tecplot installation installs Python 2.5.1.  For Windows, we run the Python.org installation.  For Linux and Mac, it's included in our installation.

Python utilizes the PYTHONPATH environment variable for setting up a list of directories where it will search for scripts.  This means that if you try to run a Quick Python Script from a location not specifically contained in the PYTHONPATH list, python will not recognize it. You will receive a "Python module failed to load ... No module named ..." message.

If you're running a script just once, and you don't want to exit your Tecplot session, you can append a path for that Tecplot session.  Under the Scripts menu, select Configure Python Search Path.  Browse to a directory you wish to include and click Add to list.

This setting will remain until you exit Tecplot.  By default, we pre-load this with a small set of directories, including the examples/python directory.

For daily use, we'd recommend setting the PYTHONPATH environment variable:

Linux:   
1. Add this line to your .bashrc file:


export PYTHONPATH=${PYTHONPATH}:/some/directory/goes/here

where, obviously, /some/directory/goes/here is a colon-delimited list of directories where you want to search for scripts.
 
2. Source this:
     . ~/.bashrc

3. Then start Tecplot.  Wohoo, that was easy!

Windows:
1. Press the [Start] and [break] keys at the same time. (Alternatively, right click on your computer's icon and select "Properties"

 







2. Click on the Advanced tab
3. Click on the Environment Variables button
4. The "Environment Variables" dialog pops up.  On the bottom half ("System Variables"), scroll down until you see PYTHONPATH.  Highlight it, then click the Edit button.






Note: if you want the changes to only apply to you, or you don't have administrative rights on your desktop, use the top half of this dialog.  Same variable name. 


5. Our Windows installation pre-populates this with a few directories underneath the Tecplot installation directory, e.g. ?\python, ?\examples\python

Append the Variable Value field with a semi-colon and the path you wish to add.  For example:

;%TEC_360_2008%\test


Much of this assumes you have some familiarity with the python programming language.  If you do not, we would recommend Mark Pilgrim's tutorial.

Documentation:

• Tecplot User's manual -- Chapter 30, "Working with Python Scripts" shows how to call python functions from Tecplot.
• Tecplot's Reference Manual -- Part 2 discusses the syntax rules of using our ADK functions.
  
• Tecplot ADK reference -- is the online listing of functions available. The functions are identical to the C and FORTRAN sets we've provided in the Application Developer's Kit, but with python bindings.  Supported functions have an example of python syntax.

Examples and Getting Help:

• Examples directory -- in your ?/examples/python directory are some sample scripts that were written during the beta testing.  We will post updates to TecplotTalk and encourage user-contributed scripts.
• Tecplot Talk Forums, especially the Scripting section, are an excellent place to post your questions.