Data Item Object

Parent Previous Next

report_objects.ItemREST object

This object is a Python representation of a Nexus data item object.  When this object is created, a GUID will automatically be generated for the object and the date is set to the current time/date.

Data members

The following attributes are available on an ItemREST object:



Set the tags for the item to the passed string. Multiple tags are space-separated.


Returns the tags string for this object. Multiple tags are space-separated.

item.add_tag(tag, value=None)

Adds a tag to the current tag string.  If no value is passed, the simple tag string is added to the tags string.  If a value is specified, a string of the form tag=value will be added to the tag string.


Remove the tag (and any potential associated value) from the current tag string.

has_file = item.is_file_protocol()

This method returns True if the data item refers to an actual file on the server. Currently the ItemRest.type values of ItemREST.type_img, ItemREST.type_scn, ItemREST.type_anim and ItemREST.type_file all refer to files.

Once all of the metadata attributes listed above are set, an actual data payload needs to be set for the data item.  There are convenience methods to set the item type and fill in the payload data.

content = item.get_payload_content()

For Items that have been fetched using the Server object, this method allows you to get the payload without having to manually decode the payload data.

An example of the use of this method is shown below:

import cei

from template_editor import report_remote_server, report_objects

serverobj = report_remote_server.Server("http://localhost:8000", 'nexus', 'cei')


obj_list = serverobj.get_objects(objtype=report_objects.ItemREST, query="A|i_type|cont|string;")


# Previously you had to do this to get the data of an item and then decode it to view human readable content

# import pickle

# data = pickle.loads(obj_list[0].payloaddata)


# This method gives you the human readable content directly (handles decoding internally.)

data = obj_list[0].get_payload_content()

Animation Item

item.set_payload_animation(mp4_filename, image_display)

This method sets the item payload to an animation.  The "mp4_filename" argument should be the name of a .mp4 encoded video file. Note: the file must exist on disk before this call is made and must stay on disk until the item is pushed to the Nexus server. The "image_display" argument defaults to 0.  If set to 1, the data item will be rendered as an <img> tag for the first frame of the .mp4 file instead of the <video> tag.

File Item


This method sets the item payload to the content of an arbitrary file on disk.  The argument should be the name of a file to be uploaded. Note: the file must exist on disk before this call is made and must stay on disk until the item is pushed to the Nexus server.



This will set the item payload to HTML formatted text.

Image Item


This method sets the item payload to an image.  The argument can be one of three things: the binary representation of a .png file on disk as a string, a QImage object or an enve.image object.  Examples are shown below:

               with open("example.png", 'rb') as fp:

                   img =


               from PyQt4 import QtGui

               img = QtGui.QImage("example.png")


               import enve

               img = enve.image()

               if img.load("example.png") == 0:


None Item


By default an item has no payload.  This method will reset the item to that state. It is legal to push an item without a data payload into the server.

Scene Item


This method sets the item payload to the 3D geometry found in the passed filename.  The supported geometry formats include: EnSight CSF, PLY, and STL format files.

String Item


This will set the item payload to an ASCII string.

Table Item


This will set the item payload to be a table, the table being specified in a dictionary.  Minimally, the dictionary must contain a single numpy array with the 'array' key.  There are a few restrictions on this array.  First, it must be 2D.  Second, the dtype of the array should be numpy.float32, numpy.double or a string (dtype="|S20").

Other table properties (e.g. row/column labels, text formatting, etc) can also be set in this dictionary.  A simple example:

import numpy

d = dict(array=numpy.zeros((3, 2), numpy.double),  

         rowlbls=["Row 1", "Row 2", "Row 3"],  

         collbls=["Column A", "Column B"],

         title="Simple table")


If the external Python API is being used from within EnSight, it is also possible to pass an ENS_PLOTTER object to the set_payload_table() method.  It will capture not only the data in the plots, but many of the plotter attributes. One example might be:

plot = ensight.objs.core.PLOTS[0]  # get the first ENS_PLOTTER object


Many more table properties exist and can be set as the default values for a table by setting same-named keys in the dictionary.  The properties are documented in the item properties section.  

A short-cut APIs exists for a common case:

item.set_payload_table_values(array, rowlbls=None, collbls=None, title=None)

This is a shortcut for the following two lines of python:

d = dict(array=numpy.array(array, numpy.double), rowlbls=rowlbls, collbls=collbls, title=title)

Note this can be handy for cases like:


where one does not want to work with numpy and prefers to pass lists of lists.  The core API will convert the list of lists into a 2D numpy array for the caller.

It is possible to use a table of strings.  To create a 2 row, 3 column array of strings (up to 20 characters), one might use code like this:

import numpy

arrary = numpy.array([['A','B','C'],[1,2,3]], dtype="|S20")

d = dict(array=array,  

         rowlbls=["Row 1", "Row 2"],  

         collbls=["Column A", "Column B", "Column C"],

         title="Simple ASCII table")


A numpy array of strings contains strings of all the same length.  The maximum length must be specified using the 'dtype=' named argument when the array is created.

Tree Item


A tree payload consists of a list of "entities".  Each entity is a dictionary with several required keys and potentially some optional ones. The required dictionary keys are:

optional keys include:

The following example includes examples of all of the various options:

import datetime

import enve

import uuid

image_item = server.create_item(name="An Image", source="externalAPI", sequence=0)

img = enve.image()

if img.load("example.png") == 0:


leaves = list()

for i in range(10):

    leaves.append( dict(key='leaves', name='Leaf {}'.format(i), value=i) )

children = list()

children.append( dict(key='child', name='Boolean example', value=True) )

children.append( dict(key='child', name='Integer example', value=10) )

children.append( dict(key='child', name='Float example', value=99.99 ))

children.append( dict(key='child', name='Simple string', value='Hello world!!!') )

children.append( dict(key='child', name='The current date', )

# this entity will display the image item (or a link to it) created above

children.append( dict(key='child', name='A data item guid', value=uuid.UUID(image_item.guid)) )

children.append( dict(key='child_parent', name='A child parent', value='Parents can have values',

                      children=leaves, state="expanded") )

tree = list()

tree.append( dict(key='root', name='Top Level', value=None, children=children, state="collapsed") )

item = server.create_item(name="Tree List Example", source="externalAPI", sequence=0)