.. |CAMERA| replace:: :class:`ENS_CAMERA` .. |CASE| replace:: :class:`ENS_CASE` .. |GLOBALS| replace:: :class:`ENS_GLOBALS` .. |LIGHTSOURCE| replace:: :class:`ENS_LIGHTSOURCE` .. |PROBE| replace:: :class:`ENS_PROBE` .. |TEXTURE| replace:: :class:`ENS_TEXTURE` .. |TOOL| replace:: :class:`ENS_TOOL` .. |TOOL_BOX| replace:: :class:`ENS_TOOL_BOX` .. |TOOL_CONE| replace:: :class:`ENS_TOOL_CONE` .. |TOOL_SPHERE| replace:: :class:`ENS_TOOL_SPHERE` .. |TOOL_CURSOR| replace:: :class:`ENS_TOOL_CURSOR` .. |TOOL_CYLINDER| replace:: :class:`ENS_TOOL_CYLINDER` .. |TOOL_LINE| replace:: :class:`ENS_TOOL_LINE` .. |TOOL_PLANE| replace:: :class:`ENS_TOOL_PLANE` .. |TOOL_REVOLUTION| replace:: :class:`ENS_TOOL_REVOLUTION` .. |VPORT| replace:: :class:`ENS_VPORT` .. |ANNOT| replace:: :class:`ENS_ANNOT` .. |ANNOT_ARROW| replace:: :class:`ENS_ANNOT_ARROW` .. |ANNOT_DIAL| replace:: :class:`ENS_ANNOT_DIAL` .. |ANNOT_GAUGE| replace:: :class:`ENS_ANNOT_GAUGE` .. |ANNOT_LGND| replace:: :class:`ENS_ANNOT_LGND` .. |ANNOT_LINE| replace:: :class:`ENS_ANNOT_LINE` .. |ANNOT_LOGO| replace:: :class:`ENS_ANNOT_LOGO` .. |ANNOT_SHAPE| replace:: :class:`ENS_ANNOT_SHAPE` .. |ANNOT_TEXT| replace:: :class:`ENS_ANNOT_TEXT` .. |GROUP| replace:: :class:`ENS_GROUP` .. |LPART| replace:: :class:`ENS_LPART` .. |PALETTE| replace:: :class:`ENS_PALETTE` .. |PART| replace:: :class:`ENS_PART` .. |PART_AUX_GEOM| replace:: :class:`ENS_PART_AUX_GEOM` .. |PART_BUILT_UP| replace:: :class:`ENS_PART_BUILT_UP` .. |PART_CLIP| replace:: :class:`ENS_PART_CLIP` .. |PART_CONTOUR| replace:: :class:`ENS_PART_CONTOUR` .. |PART_DEVELOPED_SURFACE| replace:: :class:`ENS_PART_DEVELOPED_SURFACE` .. |PART_ELEVATED_SURFACE| replace:: :class:`ENS_PART_ELEVATED_SURFACE` .. |PART_FILTER| replace:: :class:`ENS_PART_FILTER` .. |PART_FX_SEP_ATT| replace:: :class:`ENS_PART_FX_SEP_ATT` .. |PART_FX_SHOCK| replace:: :class:`ENS_PART_FX_SHOCK` .. |PART_FX_VORTEX_CORE| replace:: :class:`ENS_PART_FX_VORTEX_CORE` .. |PART_ISOSURFACE| replace:: :class:`ENS_PART_ISOSURFACE` .. |PART_MODEL| replace:: :class:`ENS_PART_MODEL` .. |PART_PARTICLE_TRACE| replace:: :class:`ENS_PART_PARTICLE_TRACE` .. |PART_POINT| replace:: :class:`ENS_PART_POINT` .. |PART_PROFILE| replace:: :class:`ENS_PART_PROFILE` .. |PART_TENSOR_GLYPH| replace:: :class:`ENS_PART_TENSOR_GLYPH` .. |PART_VECTOR_ARROW| replace:: :class:`ENS_PART_VECTOR_ARROW` .. |PLOTTER| replace:: :class:`ENS_PLOTTER` .. |POLYLINE| replace:: :class:`ENS_POLYLINE` .. |QUERY| replace:: :class:`ENS_QUERY` .. |VAR| replace:: :class:`ENS_VAR` .. _user_guide: User guide ========== This section explains the relationship between the various EnSight Python interfaces and the EnSight core. .. toctree:: :maxdepth: 1 :hidden: ensight_scripts cmdlang_native object_api api_differences omniverse_info 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 :ref:`api_differences`. 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 :ref:`ref_cmdlang_native`. 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 :ref:`ref_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: 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 :ref:`ref_object_api` and :ref:`ref_cmdlang_native`. 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 :ref:`ref_api_docs`. ================ ================================================== Class Description ================ ================================================== |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. |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. |GLOBALS| The ``GLOBALS`` object provides an interface to the core EnSight state. All objects can be accessed via the properties on the ``GLOBALS`` object. |LIGHTSOURCE| The EnSight scene supports a finite number of preallocated lighting sources. ``LIGHTSOURCE`` objects provide the interface to the light properties. |PROBE| The ``PROBE`` object allows for creation of spatial data probes. The result of probe queries can be accessed via the ``PROBE`` object. |TEXTURE| The ``TEXTURE`` object maintains the pixel arrays that can be applied via projective or explicit texture coordinates. |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 =================== =========================================== |TOOL_BOX| Box. |TOOL_CONE| Line segment with a base radius. |TOOL_SPHERE| Sphere. |TOOL_CURSOR| Single point. |TOOL_CYLINDER| Line segment with a fixed radius. |TOOL_LINE| Line segment. |TOOL_PLANE| Bounded plane. |TOOL_REVOLUTION| Line segment with a list of radii. =================== =========================================== |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 :ref:`ref_api_docs`. ================ ================================================== Class Description ================ ================================================== |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 =============== =============================================== |ANNOT_ARROW| 3D arrow pointing at a location in data space. |ANNOT_DIAL| Display of a constant variable as a dial. |ANNOT_GAUGE| Display of a constant variable as a linear gauge. |ANNOT_LGND| Legend representation of a variable palette that are only created by ``ENS_VAR`` objects. |ANNOT_LINE| Single line. |ANNOT_LOGO| Image annotation. |ANNOT_SHAPE| Generic 2D shapes, such as boxes, circles, and 2D arrows. |ANNOT_TEXT| Block of 2D overlay text. =============== =============================================== |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. |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. |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). |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 ========================== ====================================================== |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. |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. |PART_CLIP| This part is created by clipping a parent set of parts. |PART_CONTOUR| The part is a result of contouring a parent set of parts. |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. |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. |PART_FILTER| A filter part is created by applying a collection of variable range filters to a collection of parent parts. |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. |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. |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. |PART_ISOSURFACE| This part is created by applying isosurfacing to a parent set of parts. |PART_MODEL| This part is read from a dataset via an ``LPART`` object. |PART_PARTICLE_TRACE| Particle traces generated by integrating points through a vector field defined on a collection of parent parts. |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. |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. |PART_TENSOR_GLYPH| A part representing a tensor field on a collection of parts as a collection of orientated and colored glyphs. |PART_VECTOR_ARROW| A part representing a vector field on a collection of parts as a collection of orientated and colored arrows. ========================== ====================================================== |PLOTTER| A ``PLOTTER`` object is a visual frame for displaying one or more ``ENS_QUERY`` objects. It includes axes, titles, backgrounds, borders, and legends. |POLYLINE| In EnSight, ``POLYLINE`` objects are called splines. They can be used to set up things like camera paths. |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. |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. ================ ==================================================