EnSight object API#

The object interface directly exposes core EnSight objects using proxy Python objects that hold references to the underlying C++ objects. These proxy objects can be used to get or set attributes on the C++ objects as well as call methods on them. The object interface has a number of advantages over the native interface.

  • Attributes support the event callback mechanism. This makes it possible to register callbacks in Python that are executed when a specific set of attributes change on a single object or a class of objects.

  • The interface supports the specification of objects via name, ID, or object. This helps remove ambiguity and adds flexibility when passing things like parts.

  • In general, the object API does not necessitate the use of stored state, meaning the command language’s currently selected parts notion. The API provides access to and the ability to change the state for interoperability with the native API, but it does not require its use.

Proxy objects: ENSOBJ class#

The object interface revolves around proxy object classes. The base class for these objects is the ENSOBJ class. The object is a wrapper around an EnSight object ID. An EnSight object ID is a monotonically increasing 64-bit integer, unique for a given EnSight session. The proxy object stores the object ID in the objid object and can make method and attribute calls directly on the C++ core objects via that ID. The ENSOBJ interface supports attribute introspection, including attribute names, types, and general organization. In most cases where an attribute takes an object, the API supports objects, descriptions, and IDs, making transition between the various APIs fairly seamless. For example, the Python bindings search the variable list for names and IDs if those types are provided:

part = session.objs.core.PARTS["Clip"][0]
var = session.ensight.objs.core.VARIABLES["temperature"][0]
print(var, var.DESCRIPTION, var.ID)
# The COLORBYPALETTE attribute is defined as being a ENS_VAR object.
# It is legal to pass the object, the object name or the object ID.
p.COLORBYPALETTE = var
p.COLORBYPALETTE = var.DESCRIPTION
p.COLORBYPALETTE = var.ID

Interface root: ensight.objs module#

The session ensight.objs module serves as the access point into the object interface. All other EnSight objects can be accessed from methods and objects in this module. Key modules and objects include ensight.objs.enums (enumerations used for attribute IDs and values) and all proxy object base classes (such as the ensight.objs.ENS_VAR class). There are also methods for searching for objects and manipulating object IDs.

Global state: ensight.objs.core object#

Access to the global state of the EnSight session is stored in an ENS_GLOBALS singleton object accessed by the session.ensight.objs.core object. All other object instances can be accessed through attributes or methods on this object. For example, ENS_PART objects can be accessed via the PARTS property, and ENS_VAR objects can be accessed via the VARIABLES property.

Attributes#

The state of all objects is stored as a collection of attributes on the object. There are a collection of methods for accessing attributes. Here is an example:

p = session.ensight.objs.core.PARTS[0]
p.DESCRIPTION = "HELLO"
p.setattr("DESCRIPTION", "HELLO")
p.setattr(session.ensight.objs.enums.DESCRIPTION, "HELLO")
p.setattrs(dict(DESCRIPTION="HELLO"))

Attribute names may be specified using string names or enumerations. There are multiple interfaces to get or set attributes. You can use the attrinfo method or the attrtree method to access detailed information about an attribute. Descriptions of attributes are available in multiple languages, which can be selected via the Session.language property.

One nuance to the attribute interface is that all object attributes are lists. Thus, while an attribute like COLORBYPALETTE is a single variable object, it is always returned as a list.

Finally, objects are always returned as ensobjlist instances. This is a subclass of a Python list object that includes extra methods for searching via '[]' indexing and the find method as well as calls to get or set attribute values in bulk on all the objects in the container.

It is also possible to create user-defined attributes. These may hold simple values, string, integers, or floats. They are stored in the METADATA attribute, but they behave the same as intrinsic attributes.

Events#

Whenever an attribute changes its value, an event is generated. Callback functions can be attached to these events. Thus, a PyEnSight app can respond to changes in state caused by Python calls or intrinsic changes in the EnSight core state (such as a time-varying animation playback). Here is a simple example that connects the part_event() function to any changes in the VISIBLE or COLORBYRGB properties on any ENS_PART subclass object:

def part_event(uri: str):
    p = urlparse(uri)
    q = parse_qs(p.query)
    obj = session.ensight.objs.wrap_id(int(q["uid"][0]))
    value = obj.getattr(q["enum"][0])
    part_disp.value = f"Part: {obj}, Attribute: {q['enum'][0]} Value: {value}"

attribs = [session.ensight.objs.enums.VISIBLE, session.ensight.objs.enums.COLORBYRGB]
session.add_callback("'ENS_PART'", "partattr", attribs, part_event)

Replacing the ENS_PART string with a specific ENSOBJ instance would limit the function to the one specific object instance rather than a class of objects.

Selection and the native API#

Unlike the native API, the object API does not require a “current selection” as the target of all operations is explicit. The object API supports SELECTED attributes and selection group objects. These directly represent the state of the EnSight GUI. In cases where one would like to use both APIs in a single script, it can become necessary to synchronize these two selections. See: Selection and the object API for details on how this can be done.

Tips and tricks#

You can access an additional collection of EnSight-specific Python notes in the Python and EnSight documentation.

On this page
Show Source