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 to False at the ENS_PART level, hidden lines are never shown on this part.

• If the HIDDENLINE property is set to False at the ENS_VPORT level, no hidden lines are shown on any parts that might be viable (and have the HIDDENLINE property set to True) in the specific ENS_VPORT level.

• If the HIDDENLINE property is set to False at the ENS_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
ENS_CAMERA	CAMERA objects are used to set up views of the current scene. They can be associated with viewports and attached to polylines, nodes, and other graphics entities.
ENS_CASE	CASE objects are used to read a dataset. There are a fixed number of CASE objects that can be active. Each CASE object can load a dataset in a different format.
ENS_GLOBALS	The GLOBALS object provides an interface to the core EnSight state. All objects can be accessed via the properties on the GLOBALS object.
ENS_LIGHTSOURCE	The EnSight scene supports a finite number of preallocated lighting sources. LIGHTSOURCE objects provide the interface to the light properties.
ENS_PROBE	The PROBE object allows for creation of spatial data probes. The result of probe queries can be accessed via the PROBE object.
ENS_TEXTURE	The TEXTURE object maintains the pixel arrays that can be applied via projective or explicit texture coordinates.
ENS_TOOL	Tool objects are spatial input devices in the scene. They allow for the selection of points, regions of space, reference lines or planes, and more. There are several unique tool types. The PyEnSight API uses these subclasses for each tool singleton. Subclass Description ENS_TOOL_BOX Box. ENS_TOOL_CONE Line segment with a base radius. ENS_TOOL_SPHERE Sphere. ENS_TOOL_CURSOR Single point. ENS_TOOL_CYLINDER Line segment with a fixed radius. ENS_TOOL_LINE Line segment. ENS_TOOL_PLANE Bounded plane. ENS_TOOL_REVOLUTION Line segment with a list of radii.
ENS_VPORT	There are a fixed number of independent viewports. Each VPORT object has an independent camera or projection. The visibility of all 3D objects can be specified independently for each viewport.

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
ENS_ANNOT	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. Subclass Description ENS_ANNOT_ARROW 3D arrow pointing at a location in data space. ENS_ANNOT_DIAL Display of a constant variable as a dial. ENS_ANNOT_GAUGE Display of a constant variable as a linear gauge. ENS_ANNOT_LGND Legend representation of a variable palette that are only created by ENS_VAR objects. ENS_ANNOT_LINE Single line. ENS_ANNOT_LOGO Image annotation. ENS_ANNOT_SHAPE Generic 2D shapes, such as boxes, circles, and 2D arrows. ENS_ANNOT_TEXT Block of 2D overlay text.
ENS_GROUP	GROUP objects play two roles. First, they provide a hierarchical interface to collections of ENS_PART and ENS_LPART objects for display in the GUI or general organization. Second, GROUP objects can be the output of a find operation, which can be handy because they support fast, recursive, bulk property changes.
ENS_LPART	The LPART object represents an unloaded mesh object in a dataset. These objects are created by ENS_CASE objects when a case loads a dataset. The LPART object is used to create ENS_PART objects from a dataset. In most cases, these objects are automatically leveraged when a dataset is loaded.
ENS_PALETTE	PALETTE objects are allocated dynamically, but only indirectly under user control. Every ENS_VARIABLE object has one or more ENS_PALETTE objects. For example, a ENS_VARIABLE object has one ENS_PALETTE object for scalars and four ENS_PALETTE objects for vectors ([X],[Y],[Z],mag).
ENS_PART	A PART object represents a block of geometry in the current scene. The geometry can come from the dataset on disk (via an LPART object), or it can come from part creation methods. For example, a geometry can come from creating such parts as iso-contours, clips, profiles, and vortex cores. The PyEnSight API uses specific subclasses for each annotation type. They all represent a mesh consisting of a collection of elements. Usually these are located on the EnSight server, but in some cases they are realized on the client. Subclass Description ENS_PART_AUX_GEOM An auxiliary geometry part allows for scripted creation of objects like boxes that can be used in other calculations or to enhance visualizations. A backdrop is an example. ENS_PART_BUILT_UP This part is more commonly known as a subset part. It allows for collections of elements and nodes to be selected from a set of input parts. This collection is merged into this subset part. ENS_PART_CLIP This part is created by clipping a parent set of parts. ENS_PART_CONTOUR The part is a result of contouring a parent set of parts. ENS_PART_DEVELOPED_SURFACE A developed surface is generated by treating any 2D part (or parent part) as a surface of revolution and mapping specific curvilinear coordinates of the revolved surface into a planar representation. ENS_PART_ELEVATED_SURFACE For a given collection of 2D parent parts, this part presents a displacement of the surface of the parents based on a specific variable and various parameters. ENS_PART_FILTER A filter part is created by applying a collection of variable range filters to a collection of parent parts. ENS_PART_FX_SEP_ATT Separation and attachment lines can be created on 2D surfaces. These help visualize areas where flow abruptly leaves or returns to the 2D surface in 3D flow fields. ENS_PART_FX_SHOCK Shock region parts help visualize shock waves in a 3D flow field. Shock waves are characterized by an abrupt increase in density, energy, and pressure gradients, as well as a simultaneous sudden decrease in the velocity gradient. ENS_PART_FX_VORTEX_CORE Vortex cores help visualize the centers of swirling flow in a flow field. EnSight creates vortex core segments from the velocity gradient tensor of 3D flow field parts. ENS_PART_ISOSURFACE This part is created by applying isosurfacing to a parent set of parts. ENS_PART_MODEL This part is read from a dataset via an LPART object. ENS_PART_PARTICLE_TRACE Particle traces generated by integrating points through a vector field defined on a collection of parent parts. ENS_PART_POINT This part can be created via the API or from a file. It is a list of points. Commonly, the point tool is used to generate the list of points for the part. ENS_PART_PROFILE Profile parts are created by combining a 1D entity (such as a line clip, contour, or particle trace) with a surface part. The profile of a specific variable, sampled over the 1D entity, is captured in a profile part. ENS_PART_TENSOR_GLYPH A part representing a tensor field on a collection of parts as a collection of orientated and colored glyphs. ENS_PART_VECTOR_ARROW A part representing a vector field on a collection of parts as a collection of orientated and colored arrows.
ENS_PLOTTER	A PLOTTER object is a visual frame for displaying one or more ENS_QUERY objects. It includes axes, titles, backgrounds, borders, and legends.
ENS_POLYLINE	In EnSight, POLYLINE objects are called splines. They can be used to set up things like camera paths.
ENS_QUERY	A QUERY object represents y = f(x) data. This data can come directly from a dataset, created when the ENS_CASE object loads a dataset. Or, queries can be created using loaded or computed data. For example, you could query the values of pressure along a line segment through a PART object of volumetric elements.
ENS_VAR	A VAR object represents a specific field variable, case, or part constant. The base object contains the metadata associated with the variable, such as ranges. Variables can be introduced directly from datasets, but they can also be created using calculator functions.