Object API

The object API was introduced in EnSight 9.0. This is largely an undocumented API and is subject to change without notice. The API forms many of the underpinnings of EnSight. The API directly exposes the core EnSight objects using a structured API. It provides for object introspection, "attribute/property"-based interfaces, a new deferred event mechanism and an atomic execution model.

At the core of the Object API is a common object interface.  All EnSight objects are represented by Python proxy objects. These objects have a standard interface documented here.  All EnSight objects are assigned a unique ID and the proxy uses this ID to find the underlying C++ object. Note: the lifetime of the proxy object does not match that of the EnSight object. It is possible for the EnSight object to be destroyed independently of the Python proxy.  When this happens, the Python interfaces will throw an error that the target C++ object no longer exists. A set of utility functions exist to manage the nature of the proxy objects. These are available in the ensight.objs module.

ensight.objs Module

The system is realized in the module: ensight.objs In that module are the class wrappers themselves (named as ‘ENS_CLASSNAME’), a module named ‘enums’, an object reference ‘core’ and several methods.

Class type objects

• ENS_ANNOT
• ENS_CASE
• ENS_EVENTCB
• ENS_FLIPBOOK
• ENS_GLOBALS
• ENS_GROUP
• ENS_JLC
• ENS_LPART
• ENS_MAT
• ENS_PALETTE
• ENS_PART
• ENS_PLOTTER
• ENS_POLYLINE
• ENS_PROBE
• ENS_QUERY
• ENS_SPEC
• ENS_TEXTURE
• ENS_TOOL
• ENS_VAR
• ENS_VPORT

Models

• enums is a module with all of the known numerical attribute name/value pairs as well as other useful CVF constants (e.g. for interpretation of extended attribute type info).
• core is a singleton object of type ENS_GLOBALS whose attributes form the basis of the object system (e.g. cases, parts, variables, etc)

Methods

• wrap_id(#) will generate a Python interface object for the CVF object with the given ID number
• valid_id(#) returns true if the ID number is a valid CVF object ID
• next_id() returns the ID number of the next CVF object that will be created.  This can be used to help find objects created after a certain point in time.  This method was introduced in 10.0.2(f).
• events_suspend() disables the execution of Python callbacks until events_resume() is called. This allows code to maximize the use of event compression.
• events_resume() re-enables the execution of Python callbacks. One call to this function MUST be called for every call to events_suspend().
• events_queued() Returns a list of callback tuples that are currently pending dispatch.
• ID = allocextattr(class,name,description,defaultvalue[,readonly=0][,bool=0]) Adds a new atttribute to the specified class.  The type of the attribute will be defined by the 'defaultvalue', which is used when the attribute has not had a value assigned to it.  Attributes defined this way can be included in the columns of the various GUI lists.  If 'readonly' is specified, the value cannot be changed and 'bool' can be used to specify that that integer default value should be interpreted as a boolean.  An example that adds the string attribute MY_ATTRIB to the part oobjects might be: id=ensight.objs.allocextattr("ENS_PART","MY_ATTRIB","My attribute","").  The EnSight core defines the following string attributes for use with various schema:

Object type        Attribute        Description

ENS_PART        ENS_KIND        "Kind"

ENS_CASE        ENS_KIND        "Kind"

ENS_PART        ENS_DETAILS        "Details"

ENS_CASE        ENS_DETAILS        "Details"

ENS_PART        ENS_MATERIAL        "Material"

ENS_PART        DTA_BLOCK        "Block"

ENS_VAR        CFD_VAR        "CFD Type"

ENS_PART        ENS_UNITS_LABEL        "Units"

ENS_VAR        ENS_UNITS_LABEL        "Units"

ENS_VAR        FEA_VAR         "FEA Type"

 

• name = enum_to_name(attrid) will convert an attribute number into its string name
• ID = addcallback(target,object,”method”[,attrs=[]][,userdata=UD][,flags=flgs]) This function will register a callback on the ‘target’. The ‘target’ can either be an EnSight object reference or the name of a class (e.g. “ENS_PART”). A callback of the form: ret = object.method(targetobj,why[,userdata]) will be called whenever an attribute of the object changes. By default the callback is made for all attributes, but a list of attributes can be provided by the ‘attrs=’ keyword. If a value is specified via the ‘userdata=’ keyword, it will be in the callback as well. The ‘why’ value in the callback is the actual attribute ID that changed and ‘targetobj’ is the actual object it changed on. Several flags can be set. EVENTMAP_FLAG_IMMEDIATE causes the callback to be called immediately instead of being queued up for later when EnSight is idle. Use this flag with caution, it can be very expensive and can lead to recursion issues. EVENTMAP_FLAG_COMP_LOCAL causes multiple consecutive instances of this callback in the deferred event queue to be consolidated into a single event. EVENTMAP_FLAG_COMP_GLOBAL performs the same consolidation, but allows for discontinuous instances of the callback to be collapsed to the last callback instance. The return value of the callback controls if the callback will be made again in the future. If any value other than 0 is returned, the callback is removed from the queue and will not be called again.

• removecallback(ID) will remove the callback with the given ID (from the addcallback() function) from the event queue system.
• classify_file(pathname) Given a filename, this function compares it to the list of known datasets, image, movie and intrinsic EnSight filetypes.  It returns the type of the file and gives hints on how it might be opened. The return value is a dictionary containing the keys:

• 'type' : is None if the file cannot be identified.  Other values include 'dataset', ' movie', 'image', 'context' and 'script'
• 'detail' : provides more information on the type.  For scripts, this can be 'python' or 'cmdlang'.  For a context file, it is 'ctx'.  For images/moves, it is the udil name. For a dataset, it is the reader name.
• 'path' : The pathname passed to the function.
• version() Returns the version number of the EnSight object API interface.
• 1.0 - EnSight 8 though 9.1
• 1.1 - EnSight 9.2
• 2.0 - EnSight 10.0
• 2.01 - EnSight 10.0.2(c)
• 2.02 - EnSight 10.0.2(f)
• 2.11 - EnSight 10.2.0(a)
• 3.0 - EnSight 2020 R1

Objects

Internal objects used in the representation for various attributes and system state.

ens_animobj - a periodic callback object designed for animation

 

ens_emitterobj - a particle trace emitter

a=ensight.objs.ens_emitterobj([type=t][repr=s])

Types:

ensight.objs.EMIT_CURSOR

ensight.objs.EMIT_LINE

ensight.objs.EMIT_PLANE

ensight.objs.EMIT_PART

ensight.objs.EMIT_FILE

Attributes:

TYPE - read only

ID - read only

CENTROID,POINT1 - 3 floats

POINT2 - 3 floats

POINT3 - 3 floats

POINT4 - 3 floats

NUM_POINTS - number of points (e.g. along a line)

NUM_POINTS_X - grid for a plane tool emitter

NUM_POINTS_Y - see above

PART - part object (1D?)

FILENAME - from a file

Methods:

a.fromtool(toolobj) - set the emitter values from a tool object

a.totool(toolobj) - set the tool object to the emitter object settings

 

infotree - used in the representation of attribute group trees

Notes

 One thing to note about events. If they are registered with the classname instead of an object, they will be called back for all objects of that class. Also, if the object is an ENS_PART or ENS_LPART, the event will be pushed up the parent-child hierarchy and any parent callbacks will be made.

Example code:

import ensight

from ensight.objs import *  

class example:

    def __init__(self):

        self.p = core.PARTS[0]

        self.id1 = addcallback(self.p,self,"cb1")

        self.id2 = addcallback(self.p,self,"cb2",attrs=[enums.VISIBLE])

        print("registered {} {}".format(self.id1, self.id2))

    def cb1(self,target,why):

        print("cb1: {} {} {}".format(target, why, enum_to_name(why)))

        return 0

    def cb2(self,target,why):

        print("cb2: {} {} {}".format(target, why, enum_to_name(why)))

        return 0

  foo = example()

  print "TEST1: both callbacks called"

foo.p.VISIBLE = 0

print("TEST2: only 'cb1' called")

foo.p.COLORBYRGB = [1.,1.,1.]

callbacks in the parent object will be invoked as well as those on the target child.