IPSDK Concepts documentation See full documentation

What is a data item?

Several IPSDK algorithms use or return complex data as input or output arguments called data item. A data item is a structure aggregating heterogeneous data.

It can contain :

• a Leaf, which is a single scalar value,
• a Node, which is another data item,
• a Leaf Collection (LeafColl), which is a collection of scalar values,
• a Node Collection (NodeColl), which is a collection of nodes.

How to use a data item?

First of all, let us consider the following data item :

This data item is composed by four fields :

• MyValue, a scalar value (a leaf) ,
• MyNode, a node (i.e. another data item) ,
• MyLeafColl, a collection of leaves with values ,
• MyNodeNode, a collection of nodes with values .

Data Item declaration

For some data items, creation wrappers allow to instantiate them and fill their data. Such functionalities, when they exist, are described in the IPL documentation.

Let's take as an example the Range data item, from the IPSDKIPLAttributes library. This simple data item contains two Real64 leaves : Min and Max. We can create an instance of this data item by specifying the values of the leaves to the function createRange. This is done in C++ with the instruction :

RangePtr pMyRange = ipdsk::imaproc::attr::createRange(0, 255)

In Python, the command is :

myRange = PyIPSDK.createRange(0, 255)

This creation wrapper does not exist for all the data items. In this case, the data item can only be created and returned by an IPSDK algorithm. This is the case of GaussianNoiseStats for instance, which is returned, among others, by the gaussianNoiseMsr algorithm. The following instruction shows how to compute a GaussianNoiseStats in C++ :

GaussianNoiseStatsPtr pGaussNoiseStats = gaussianNoiseMsr(pInImg);

The equivalent command in Python is :

import PyIPSDK
import PyIPSDK.IPSDKIPLGlobalMeasure as glbmsr

gaussNoiseStats = glbmsr.gaussianNoiseMsr(inImg)

Access to the data item elements : example in C++

Access to a leaf

The getValue<>() and setValue<>() methods have to be used to access to a data item leaf. We consider in the following example that the leaf MyValue in MyDataItem has type T.

T myVal = pMyDataItem->getValue<MyDataItem::MyValue>();
pMyDataItem->setValue<MyDataItem::MyValue>(myVal);

Access to a node

The simplest way to access to a node is to store its reference (in terms of C++) in a local variable :

MyOtherDataItem& myNode = pMyDataItem->getNode<MyDataItem::MyNode>();

myNode can then be used as a classical data item by accessing to its components in the same way than for pMyDataItem. The modifications applyed to myNode will be repercuted to the node contained in pMyDataItem.

Access to a leaf collection

In the same way, using a reference (in terms of C++) of the STL container gives access to a leaf collection. We consider in the following examples that MyLeafColl is a collection of values with type T :

std::vector<T>& myLeafColl = pMyDataItem->getLeafColl<MyDataItem::MyLeafColl>();

The modifications applyed to myLeafColl will be repercuted to the collection contained in pMyDataItem.

Access to a node collection

Just like for leaf collections, the simplest way to access to a node collection is to retrieve the reference (in terms of C++) of the STL container. This collection contains shared pointers to the nodes instances. We consider in the following examples that MyNodeColl is a collection of data item with type MyOtherDataItem :

std::vector< boost::shared_ptr<MyOtherDataItem> >& myNodeColl = pMyDataItem->getNodeColl<MyDataItem::MyNodeColl>();

The modifications applyed to myNodeColl will be repercuted to the collection contained in pMyDataItem.

Access to the data item elements : example in Python

To use IPSDK in a Python script, the PyIPSDK package must be imported :

import PyIPSDK

We also consider here that the data item is stored in a variable called myDataItem.

Accessing to a leaf, a node, etc., we just need to specify the object name followed by a '.' (dot) character and the name of the data item component :

# Retrieve the leaf
myValue = myDataItem.myValue

# Retrieve the node
myNode = myDataItem.myNode

# Retrieve the leaf collection
myLeafColl = myDataItem.myLeafColl
firstValInColl = myLeafColl[0] # First value in the collection

# Retrieve the node collection
myNodeColl = myDataItem.myNodeColl
firstNodeInColl = myNodeColl[0] # First node in the collection

It is important to note that the data item component's name begins by a capital letter whereas the python accessor begins by a lower case character.

It is also possible to easily convert the data item into a python dictionary thanks to the method toPyDict. This allows for instance to display the data item. We use once more the data item range to show how to use this function :

import PyIPSDK

myRange = PyIPSDK.createRange(0, 255)
PyIPSDK.toPyDict(myRange)

This will display :

{'Max': 255.0, 'Min': 0.0}

Read and write a data item

Read and write a data item in C++

To use the functions, you will need to add the following instruction :

#include <IPSDKSerialization/Archive/FileSerializationUtils.h>

It can be useful to save a data item in a file, to store the result of an algorithm for instance. To do so, the data item must be written in a XML file. In C++, this is done with the following instruction :

BoolResult bTestWritten = writeToXmlFile(xmlFilePath, pMyDataItem);

The functions returns false if a problem occurred. You can check the bTestWritten value to check if an error occured.

To read a data item from an existing XML file, this is only necessary to use the following instruction :

BoolResult bResultRead = readFromXmlFile(xmlFilePath, pMyDataItem);

Once again, the value of bResultRead can be tested to check if an error occured.

Note

It is also possible to read and write the shared pointer to the data item, passing *pMyDataItem instead of pMyDataItem to the writeToXmlFile or readFromXmlFile function. However, this approach is not recommended since it is incompatible with a python script.

Read and write a data item in Python

Reading and writing a data item in a Python environment can be done with the following command lines :

# Write a data item
PyIPSDK.writeToXmlFile(xmlFilePath, myDataItem)

# Read a data item
bResultRead = PyIPSDK.readFromXmlFile(xmlFilePath)
boolResult = bResultRead[1]
myDataItem = bResultRead[0]

bResultRead is a tuple with two elements : the data item and the result informing whether the data item has been correctly read. If boolResult.getResult() returns False, it means that an error occured and more details can be obtained with boolResult.getMsg().

Conclusion

This page presented the data items and the most common way to use it. For a more specific use of a data item, please refer to its documentation page.