States: ENS_STATE

An ENS_STATE object stores a collection of object references and their attributes.  A state object can be thought of as a "mini-context" file.  It lacks the ability to create new objects, but it records most of the visual attributes for a collection of existing objects.  It allows one to store and recall the visual state of an EnSight session. A state can be saved to disk and reloaded.

There is a "root" ENS_STATE object that cannot be destroyed.  It serves as the parent of all of the other ENS_STATE objects and does not actually store a visual "state". It can be referenced as: ensight.objs.core.STATES[0].  Its CHILDREN are the captured states. 

An ENS_STATE can contain a collection of ENS_SOURCE objects.  Each ENS_SOURCE object defines how to capture a report data item (image, movie, plot, geometry, etc). The collection of ENS_STATE objects can be used (with their ENS_SOURCE children) to define a Nexus report.

Methods:

• capture([record=1]): This method will re-capture the attributes of the current EnSight scene in this state. If 'record' is zero, the action will not be recorded in the command language journal. This method is not available the "root" state.
• apply([record=1]): This method will apply the attributes in this state to the current EnSight scene. If 'record' is zero, the action will not be recorded in the command language journal. This method is not available the "root" state.
• undo([record=1][count=0]): Whenever a state is applied, EnSight captures the current scene state to a undo stack before the state is applied. The undo method reverts the scene to the status stored on top of the stack and removes it form the stack. The stack has a finite depth. The return value of this method is the number of valid entries remaining on the stack. If 'count' is non-zero, the number of entries on the stack is returned without applying or removing the topmost entry. If 'record' is zero, the action will not be recorded in the command language journal.
• save(filename[,record=1]): This method will save all of the states and their attributes to disk into an XML formatted file with the supplied filename. If 'record' is zero, the action will not be recorded in the command language journal. This method is only available the "root" state.
• read(filename[,append=0][,record=1]): This method will read all of the states and their attributes from an XML formatted file (generated by the save() method) with the supplied filename. By default, the read states will replace all of the current states.  If 'append[' is 1, the states in the XML file will be appended from the file and the properties of the root state object will not be updated. If 'record' is zero, the action will not be recorded in the command language journal. This method is only available the "root" state.
• generate_report([record=1]): When this method is called, a Nexus report will be generated using the current state definitions. If 'record' is zero, the action will not be recorded in the command language journal. This method is only available the "root" state.
• add_state(name[,uuid=""][,capture=0][,record=1]): This method will create a new ENS_STATE object with the provided name. It will become a child of the "root" state. By default, a new GUID will be generated for the state, but if a "uuid" string is specified, that string will be used as the GUID for the new object. By default, the state will have no captured attributes. If 'capture' is set to 1, after the state is created, it will also be 'capture()'ed. If 'record' is zero, the action will not be recorded in the command language journal. This method is only available the "root" state.
• add_source(name[,extension_name=""][,uuid=0][,record=1]): This method will create a new ENS_SOURCE object with the provided name. If specified, it will use the specified EnSight extension to provide the ENS_SOURCE interface object. The new source will become a child of the state. By default, a new GUID will be generated for the state, but if a "uuid" string is specified, that string will be used as the GUID for the new object. If 'record' is zero, the action will not be recorded in the command language journal. This method is not available the "root" state.  An example call to create an image source might be:

state_obj.add_source('Image source',uuid='87720db4-a08c-11e8-8376-6763cf9f766b',extension_name='image_source')

• move(target[,position=0]): This method is used to re-order the children of an ENS_STATE object. If applied to the "root" state, it will re-order the ENS_STATE children.  If applied to a non-root state, it will re-order the ENS_SOURCE children. The "target" object must be one of the CHILDREN of this state object.  The "position" is the desired position in the CHILDREN list for the target.  For example, a position of 0 will move the target to become the first child.
• destroy(): call this method to delete this object and its ENS_SOURCE children.
• set_logo_file(filename[,record=1]): When this method is called on the "root" state, the specified "filename" will be read as an image file (e.g. png or jpeg). The contents will be converted into png format and stored as the LOGO_DATA attribute on the "root" state for use as a banner during report generation. If 'record' is zero, the action will not be recorded in the command language journal. This method is only available the "root" state.
• update_tags(tags[,new_session=0][,random_session=0]): This method can be used to set the current EnSight session GUID based on the value of the tags specified in the 'tags' string. The method will first set the TAGS on the root state to the value of the string. If 'new_session' is non-zero, a new EnSight session GUID will be generated.  By default, this GUID will be based on the data in the 'tags' string (e.g. for the same tag string, the same EnSight session GUID will be generated).  If 'random_session' is non-zero, the new session GUID will be randomly generated. This method is only available the "root" state.  The primary use of this method is to support a collection of reports where each report represents a different dataset that is part of a parameter study.  The root parameters are recorded in the tags string and a new session GUID is generated from that string, simplifying the eventual aggregation and exploitation of the data items in Nexus.

Attributes:

• DESCRIPTION: This is the name of the state.  When the state is used to create a report, this name will be used to title the section of the report that contains the CHILDREN ENS_SOURCE object the state contains.
• CHILDREN: This is a list of the ENS_SOURCE children of the state.
• HTML: A text string in HTML formatting that is placed after the title of the section of the report the state represents.
• TAGS: A string of Nexus tags. When the ENS_SOURCE children generate Nexus objects, this string will be included in the tags of each of the generated Nexus data items.
• TIMETRACK: A boolean flag.  If true and this state is applied, the current session timestep will be changed to match the one recorded in the state.  If false (the default), the state will record, but not apply the timestep.
• USE_LOGO: If true, any report will include a banner logo image.
• LOGO_DATA: This contains the current banner logo image (if any) as a Python string containing the logo as an (in memory) png image.
• CMDLANG_REFERENCE: This property returns the name of this ENS_STATE object as a valid Python and command language string.  For example, after creating an initial state under the root state, the command: ensight.objs.core.STATES[0].CHILDREN[0].CMDLANG_REFERENCE returns:

"ensight.objs.core.STATES[0].CHILDREN['New state'][0]"

• TEMPLATE_NAME: If a report is generated, this string property will be used to name the report template in Nexus.  Note: only the value on the root state (ensight.objs.core.states[0]) is used.
• CREATE_REPORT_TEMPLATE: If true, the Nexus report template will be re-generated if a report is generated.  If false, only the data items are pushed into Nexus.  Note: only the value on the root state (ensight.objs.core.states[0]) is used.