User guide#
This section explains the relationship between the various EnSight Python interfaces and the EnSight core.
EnSight and PyEnSight interfaces#
There is a Python interpreter embedded in the EnSight desktop app. In
general, this interpreter is referred to as EnSight or the embedded interpreter.
This interface is based on a built-in ensight
module that cannot be imported
into any other interpreter. It is the fastest Python interface to EnSight, and
much of EnSight itself is written in Python running in this interpreter.
The other interface is PyEnSight. This interface is implemented as a portable
wheel and can be installed in most any Python interpreter. The interface provided
by this component resides in the ansys.pyensight
module. It is a remote interface
in that it actually starts an independent EnSight instance in another process and
connects to it. Over this connection, the PyEnSight interface makes it possible
to execute Python commands in the embedded interpreter and return results.
Because the PyEnSight interface has a nearly identical API to the embedded interface,
code written for one interface basically works in the other interface, providing
that the code is structured properly. For information on API differences, see
Python API differences in EnSight versus PyEnSight.
History: Native and object APIs#
EnSight has always had a journaling language, often referred to as the command language or cmdlang. This journaling language makes it possible to view and review every interaction in EnSight as a command stream. You can play back the journal streams to automate tasks.
The EnSight 9.x release introduced an embedded Python interpreter into the EnSight core. The initial language binding to EnSight was via the native API. The native API is derived from the EnSight journaling language. It is basically a direct Python mapping with object-specific conversion operations to simplify the interface. For more information, see EnSight command language native Python API. This interface is the most complete interface to EnSight. The EnSight script editor provides tools for the conversion of blocks of command language into this Python API.
As the sophistication of Python scripts increased, limitations in the journal-based interface were exposed. In response, the object API was developed. The object API is a direct interface to the core C++ EnSight objects. It is a proxy interface that exposes C++ object attribute interfaces as Python properties. The advantages of the object API is support for fine-grained queries and event handling. For more information, see EnSight object API. This API does not yet cover everything the native API does, but it allows for using more interactive and reactive component interfaces. Because of this, a significant portion of the EnSight GUI is written using the EnSight object API.
EnSight architecture#
The EnSight Python APIs reflect the core EnSight architecture. Specifically, they reflect the various objects inside of EnSight and their relationships. The interface to these objects is largely a collection of properties. Note that these are properties in the PyEnSight interface. The documentation for the core interface refers to them as attributes and properties almost interchangeably.
There are two types of objects in EnSight. The first set are parts of the code that are generally created automatically at startup.
Note
The following sections briefly describe many of the core classes. They do not describe all core classes but rather only commonly used objects.
There are two unique concepts in the EnSight architecture that are important to explaining core EnSight behavior.
The first is the idea of hierarchical property filtering.
The second is the concept of default objects.
Hierarchical property filters#
A number of properties have global versions as well as per-object versions.
Often a specific visual property must be enabled globally before the
object-specific value can be applied. This can happen at different levels in
the visible object tree. Consider the HIDDENLINE
property.
This property can be set on these levels: ENS_PART
, ENS_VPORT
, and
ENS_GLOBAL
.
Here is an example in the object API:
print(ensight.objs.core.HIDDENLINE)
print(ensight.objs.core.VPORTS[0].HIDDENLINE)
print(ensight.objs.core.PARTS[0].HIDDENLINE)
If the
HIDDENLINE
property is set toFalse
at theENS_PART
level, hidden lines are never shown on this part.If the
HIDDENLINE
property is set toFalse
at theENS_VPORT
level, no hidden lines are shown on any parts that might be viable (and have theHIDDENLINE
property set toTrue
) in the specificENS_VPORT
level.If the
HIDDENLINE
property is set toFalse
at theENS_GLOBAL
level (ensight.objs.core
), no hidden lines are shown on any parts in any viewports.
Default objects#
The default object is a key concept for EnSight. To create an object in EnSight, you often set up the properties on a fake default object and then make a create call to realize a new object of this type. The new object has the same properties as the current default object properties. For examples, see EnSight object API and EnSight command language native Python API.
Common static objects#
There are a fixed number of each of the common static objects that are all allocated
statically at startup. The Python API allows you to modify the attributes on these objects
and query their statuses. The key object is ENS_GLOBAL
, which is accessed via
ensight.objs.core
. Properties on the ENS_GLOBAL
object can generally
access all of the other objects in the system. For descriptions of the properties on
these objects, see API reference.
Class |
Description |
||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|||||||||||||||||||
|
|||||||||||||||||||
The |
|||||||||||||||||||
The EnSight scene supports a finite number of
preallocated lighting sources. |
|||||||||||||||||||
The |
|||||||||||||||||||
The |
|||||||||||||||||||
|
|||||||||||||||||||
There are a fixed number of independent viewports.
Each |
Common dynamic objects#
There are a fixed number of each common dynamic object that are all allocated statically at startup. The Python API allows you to modify attributes on these objects and query their statuses.
Many of the dynamically created objects are created implicitly through other objects. For example, part objects are created from lpart objects and legend objects are created automatically when variable objects are created. Other objects (such as annotation objects and derived part objects like clips) are created using default objects. For descriptions of the properties on these objects, see API reference.
Class |
Description |
||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Provides the base class for annotation. Annotations are mostly 2D objects that overlay the 3D scene, such as text blocks and lines. However, there are more complex types. For example, a legend annotation is used to display the palette associated with a variable. The PyEnSight API uses specific subclasses for each annotation type.
|
|||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||
The |
|||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||
A
|
|||||||||||||||||||||||||||||||||||||
A |
|||||||||||||||||||||||||||||||||||||
In EnSight, |
|||||||||||||||||||||||||||||||||||||
A |
|||||||||||||||||||||||||||||||||||||
A |