|
With EnSight 8.2.6(e), CEI introduced a new, native Python API. This API builds on and largely supersedes the 'ensight.sendmesg()' API provided in previous versions of EnSight. The 'sendmesg()' API is still present in EnSight, but Python developers may find this new API much simpler to work with. Tools are also provided to automate the conversion of EnSight command language into this new API. These functions are fully documented in section 6 of the EnSight 'Interface' manual.
Accessing the Python interpreter
The Python interpreter in EnSight can be directly accessed through the File->Command... menu option and then selecting the "Python" tab of the Command Dialog. The dialog looks like this:
Commands may be entered at the "Cmd:" prompt and executed. The image is from the display after the commands:
print sys.version
print ensight.version()[0:4]
print ensight.query(ensight.SYSINFO)
have be executed. The log window displays Python output messages and errors. Two buttons in the panel allow the user to create a new Python file or edit an existing file. The editor used is Python aware and supports many common source code editing operations, including the conversion of command language into the new "native" Python command language interface.
The "native" Python command language interface
The ensight.sendmesg() function can be used to execute command lenguage directly from Python. Unfortunately, the interface is based on strings and requires the programmer to generate strings for every operation. While this interface works, it adds unnecessarily to the complexity of the adaptive, dynamic generation of commands. In response, a more native interface to the command language was developed as a heirarchy of modules in the 'ensight' Python module. These modules follow the form of the EnSight command language syntax. To review, the command language commands have the fundamental form:
category: command <args>
For example:
view_transf: rotate 9.657229e+000 2.282249e+001 0.000000e+000
has a category of ‘view_transf’, a command of ‘rotate’ and arguments of ‘9.657229e+000 2.282249e+001 0.000000e+000’. The native command language interface maps the category and command names to modules under the ‘ensight’ module. For example, the above command is equivalent to the following line of Python code:
ensight.view_transf.rotate(‘9.657229e+000 2.282249e+001 0.000000e+000’)
Additionally, the native interface will try to map data types to <args> strings. So the following lines of Python code are all equivalent:
ensight.view_transf.rotate(9.657229e+000,2.282249e+001,0.000000e+000)
ensight.view_transf.rotate([9.657229,2.282249e+01,0])
a=[9.657229,2.282249e+01,0]
ensight.view_transf.rotate(a)
The use of Python native variables makes this interface much more flexible for complex scripting. The native interface handles the “select_begin”/”select_end” commands very differently. The command language includes structures like:
part: select_begin
1 2 3 4 5 6 7 8
part: select_end
part: select_byname_begin
"(CASE:Case 1)Block ID 7 - HEX" "(CASE:Case 1)Block ID 8 - HEX"
"(CASE:Case 1)Block ID 9 - HEX" "(CASE:Case 1)Block ID 10 - HEX"
"(CASE:Case 1)Block ID 11 - HEX" "(CASE:Case 1)Block ID 1 - HEX"
part: select_byname_end
The native Python interface is aware of the list nature of the “select_begin”/”select_end” commands and maps them to a single command (the “select_begin”). The above lines translate to two lines of Python:
ensight.part.select_begin(1,2,3,4,5,6,7,8)
ensight.part.select_byname_begin("(CASE:Case 1)Block ID 7 -HEX",
"(CASE:Case 1)Block ID 8 - HEX",
"(CASE:Case 1)Block ID 9 - HEX",
"(CASE:Case 1)Block ID 10 - HEX",
"(CASE:Case 1)Block ID 11 - HEX",
"(CASE:Case 1)Block ID 1 - HEX")
The “*_end” functions are not necessary. Additionally, a list-based syntax is also supported, so the following lines are also equivalent:
ensight.part.select_begin([1,2,3,4,5,6,7,8])
list = ["(CASE:Case 1)Block ID 7 - HEX",
"(CASE:Case 1)Block ID 8 - HEX",
"(CASE:Case 1)Block ID 9 - HEX",
"(CASE:Case 1)Block ID 10 - HEX",
"(CASE:Case 1)Block ID 11 - HEX",
"(CASE:Case 1)Block ID 1 - HEX"]
ensight.part.select_byname_begin(list)
In all cases where the command language uses a “*_begin”/”*_end” syntax with a collection of items (numerical or strings), a Python command structure similar to the above may be used.
Conversion of command language into the native Python API
Conversion of command language scripts to the native interface In previous versions of EnSight, functions were provided to convert selections of command language to ensight.sendmesg() format. With the native interface, these have been replaced with two menu options in the EnSight Python script editor. Under the ‘Edit’ menu, there is an option ‘Convert selection to sendmesg()’ which converts the currently selected text in the editor into the ‘ensight.sendmesg()’ form. More importantly, there is a ‘Convert selection to native Python’ option. This function will convert command language to the native interface described here. One can convert a .enc file by loading it into the script editor window, selecting all of the text and converting it to native Python. The result can be saved as a ‘.py’ file. An example of the conversion results would be:
Translates into the following native Python code:
This language conversion is actually performed by the class ‘Cmd2Py’ in the Python module: cei.cmd2py. A quick study of the cmd2py.py file will give an overview of the conversion process and what is and what is not handled by the conversion. Some command language cannot be converted automatically. Files that include things like command language loops cannot be converted automatically and the conversion system will insert comments detailing the failures. Examples that use other command language features that cannot be directly translated (e.g. ‘$’ variables) will be converted to ensight.sendmesg() formatted lines as a fallback. In most cases, users are better off converting such sections of code into native Python in any case. A command line program: ‘cmd2py’ is also provided to aid in the conversion of files outside of EnSight.
Usage notes on the native Python interface
The native interface has the same limitations listed in the “Limitations of the EnSight Python Interface”. In general, all of the command language is supported with a few exceptions. One exception is the ‘test:’ commands. These commands are not supported by the native interface (i.e. there is no ‘ensight.test’ module). They can of course be issued using the ensight.sendmesg(“test:...”) interface. There are a number of commands in the EnSight command language that are not valid Python names. A few examples include:
function: #_of_levels 5
annotation: 3d_label_size 10.0
command: print “hello”
viewport: raise
The reasons a name might be invalid include:
- name includes an invalid character (e.g. “#”)
- name begins with a digit (e.g. “1”)
- name is a Python reserved word (e.g. “raise”)
These are transformed using the following rules:
- “#” characters are replaced with the text “number”
- names that start with a digit are prefixed with an “_”
- names that are the same as a Python reserved word are prefixed with an “_”
After transformations, the previous examples become:
ensight.function.number_of_levels(5)
ensight.annotation._3d_label_size(10.0)
ensight.command.print(“hello”)
ensight.viewport._raise()
There are a few obsolete EnSight command language functions that are not supported. One example would be:
part: symmetry_1_1_-1
Such functions can still be executed using ensight.sendmesg(). The native interface methods do not include the ‘exception’, ‘record’, ‘display’ or ‘version’ keywords like ensight.sendmesg(). However, they do honor the values set by ensight.sendmesgoptions(). That function can be used to cause the code that uses the native interface do be executed under the particular rules of a specific command language version or to throw exceptions on errors for instance.
The next installment...
In our next installment of the QuickTools series, we will change gears a bit and discuss some new computational functions available in the latest versions of EnSight and creative ways of using these functions.
Until then, we hope you find the new Python API useful and we look forward to hearing how you use this new capability.
|
