10.6. dataObject¶
This section contains the script reference to the main array class dataObject of itom. Read the overview document for more details about the Python interface of the class dataObject.

class
itom.
dataObject
([dims [, dtype='uint8'[, continuous = 0][, data = valueOrSequence]]]) → constructor to get a new dataObject.¶ The itom.dataObject represents a multidimensional array of fixedsize items with corresponding meta information (units, axes descriptions, scalings, tags, protocol…). Recently the following data types (dtype) are supported:
 Integertype (int8, uint8, int16, uint16, int32, uint32),
 Floatingtype (float32, float64 (=> double)),
 Complextype (complex64 (2x float32), complex128 (2x float64)).
 Colortype (rgba32 (uint32 or uint[4] containing the four 8bit values [R, G, B, Alpha])).
Arrays can also be constructed using some of the static preinitialization methods ‘zeros’, ‘ones’, ‘rand’ or ‘randN’ (refer to the See Also section below).
Parameters: dims : {sequence of integers}, optional
‘dims’ is a list or tuple indicating the size of each dimension, e.g. [2,3] is a matrix with 2 rows and 3 columns. If not given, an empty data object is created.
dtype : {str}, optional
‘dtype’ is the data type of each element, possible values: ‘int8’,’uint8’,…,’int32’,’uint32’,’float32’,’float64’,’complex64’,’complex128’, ‘rgba32’
continuous : {int}, optional
‘continuous’ [01] defines whether the data block should be continuously allocated in memory [1] or in different smaller blocks [0] (recommended for huge matrices).
data : {str}, optional
‘data’ is a single value or a sequence with the same amount of values than the data object. The values from data will be assigned to the new data object (filled row by row).
Notes
The itom.dataObject is a direct wrapper for the underlying C++ class dataObject. This array class mainly is based on the class Mat of the computer vision library (OpenCV).
In order to handle huge matrices, the data object can divide one array into chunks in memory. Each subpart (called matrixplane) is twodimensional and covers data of the last two dimensions. In c++context each of these matrixplanes is of type cv::Mat_<type> and can be used with every operator given by the openCVframework (version 2.3.1 or higher).
The dimensions of the matrix are structured descending. So if we assume to have a ndimensional matrix A, where each dimension has its size s_i, the dimensions order is n, .., z, y, x and the corresponding sizes of A are [s_n, s_(n1), s_(n2), …, s_y, s_x].
In order to make the data object compatible to continuously organized data structures, like numpyarrays, it is also possible to have all matrixplanes in one datablock in memory (not recommended for huge matrices). Nevertheless, the indicated data structure with the twodimensional submatrixplanes is still existing. The data organization is equal to the one of openCV, hence, twodimensional matrices are stored rowbyrow (Cstyle)…
In addition to OpenCV, itom.dataObject supports complex valued data types for all operators and methods.
Warning ‘uint32’ is not fully openCVcompatible and hence causes instability!
Deep Copy, Shallow Copy and ROI
It is possible to set a ndimensional region of interest (ROI) to each matrix, the virtual dimensions, which will be delivered if the user asks for the matrix size. To avoid copy operations where possible a simple =_Operator will also make a shallow copy of the object. Shallow copies share the same data (elements and meta data) with the original object, hence manipulations of one object will affect the original object and all shallow copies.
The opposite a deep copy of a dataObject (by sourceObject.copy()) creates a complete mew matrix with own meta data object.
Example:
#Create an object dObj = dataObject([5, 10, 10], 'int8') # Make a shallow copy dObjShallow = dObj # Make a shallow copy on ROI dObjROI = dObj[1, :, :] # Set the value of element [1, 0, 0] to 0 dObj[1, 0, 0] = 0 # Make a deep copy of the dObjROI dObjROICopy = dObjROI.copy() # Set the value of dObjROICopy element [0, 0, 0] to 127 without effecting other objects dObjROICopy[0, 0, 0] = 127
Constructor
The function dataObject([dims [, dtype=’uint8’[, continuous = 0][, data = valueOrSequence]]]) creates a new itomdataObject filled with undefined data. If no parameters are given, an uninitilized DataObject (dims = 0, no sizes) is created.
As second possibility you can also use the copyconstructor ‘dataObject(AnyArray)’, where AnyArray must be any arraylike structure which is parsable by the numpyinterface.

abs
() → return a new data object with the absolute values of the source¶ This method calculates the abs value of each element in source and writes the result to the output object.In case of floating point or real object, the type of the output will not change. For complex valuesthe type is changes to the corresponding floating type value.
Returns: res : {dataObject}
output dataObject of same shape but the type may be changed.

addToProtocol
(newLine) → Appends a protocol line to the protocol.¶ Appends a line of text to the protocol string of this data object. If this data object has got a region of interest defined, the rectangle of the ROI is automatically appended to newLine. The protocol string ends with a newline character.
Address the content of the protocol by obj.tags[“protocol”]. The protocol is contained in the ordinary tag dictionary of this data object under the key ‘protocol’.
Parameters: newLine : {str}
The text to be added to the protocol.

adj
() → Adjugate all elements¶ Every plane (spanned by the last two axes) is transposed and every element is replaced by its complex conjugate value.
Raises: TypeError : :
if data type of this data object is not complex.
See also

adjugate
() → returns the planewise adjugated array of this dataObject.¶ If this data object has a complex type, the tranposed data object is returned where every element is complex conjugated. For data objects with more than two dimensions the tranposition is done planewise, hence, only the last two dimensions are permutated.
Returns: out : {dataObject}
adjugate of this dataObject
Raises: TypeError : :
if data type of this data object is not complex.
See also

adjustROI
(offsetList) → adjust the size and position of the region of interest of this data object¶ For every data object, it is possible to define a region of interest such that subsequent commands only refer to this subpart. However, if values within the region of interest (ROI) are changed, this also affects the original data object due to the shallow copy principal of python. Use this command to adjust the current size and position of this region of interest by passing an offset list, that contains integer numbers with twice the size than the number of dimensions.
Example:
d = dataObject([5,4]) droi = d droi.adjustROI([2,0,1,1])
Now droi is a region of interest of the original data object whose first value is equal to d[2,1] and its size is (3,2)
Parameters: offsetList : {list of integers}
This list must have twice as many values than the number of dimensions of this data object. A pair of numbers indicates the shift of the current boundaries of the region of interest in every dimension. The first value of each pair is the offset of the ‘left’ boundary, the second the shift of the right boundary. A positive value means a growth of the region of interest, a negative one let the region of interest shrink towards the center.
See also

arg
() → return a new data object with the argument values of the source¶ This method calculates the argument value of each element in source and writes the result to the output object.This object must be of complex type (complex128 or complex64). The output value will be float type (float64 or float32).
Returns: res : {dataObject}
output dataObject of same shape but the type is changed.

astype
(typestring) → converts this data object to another type¶ Converts this data object to a new data object with another type, given by the string newTypestring (e.g. ‘uint8’). The converted data object is a deep copy of this object if the new type does not correspond to the current type, else a shallow copy of this object is returned.
Parameters: typestring : {str}
Type string indicating the new type (‘uint8’,…’float32’,..,’complex64’)
Returns: c : {dataObject}
typeconverted data object
Notes
This method mainly uses the method convertTo of OpenCV.

conj
() → complexconjugates all elements of this dataObject (inline).¶ Every value of this dataObject is replaced by its complexconjugate value.
Raises: TypeError : :
if data type of this data object is not complex.
See also

conjugate
() → return a copy of this dataObject where every element is complexconjugated.¶ Returns: out : {dataObject}
elementwise complex conjugate of this data object
Raises: TypeError : :
if data type of this data object is not complex.
See also

copy
(regionOnly=0) → return a deep copy of this dataObject¶ Parameters: regionOnly : {bool}, optional
If regionOnly is 1, only the current region of interest of this dataObject is copied, else the entire dataObject including the current settings concerning the region of interest are deeply copied [default].
Returns: cpy : {dataObject}
Deep copy of this dataObject

copyMetaInfo
(sourceObj[, copyAxisInfo = True, copyTags = False]) → Copy the meta information of sourceObj.¶ All meta information(axis scales, offsets, descriptions, units, tags…) of the sourceObj are copied to the dataObject.
Parameters: sourceObj : {dataObject}
whose meta information is copied in this dataObject.
copyAxisInfo : {bool}, optional
If ‘copyAxisInfo’ is True, the ‘axis scales’, ‘offsets’, ‘descriptions’, ‘units’ are copied.
copyTags : {bool}, optional
If ‘copyTags’ is True, the ‘tags’ are copied.
Raises: RuntimeError : :
if the given sourceObj is not a dataObject
See also
metaDict
 this attribute can directly be used to print the meta information of a dataobject.

createMask
(shapes[, inverse = False]) → return a uint8 data object of the same size where all pixels belonging to any shape are masked.¶ The destination data object has the same size than this data object and the real type given by destinationType. The pixel  wise conversion is done using the formula : gray = 0.299 * red + 0.587 * green + 0.114 * blue.
Parameters: shapes : {shape or seq. of shapes}
The union of all shapes (polygons, rectangles, squares, circles and ellipes are considered, only) are marked within the mask
inverse : {bool}
If False (default) the shape areas are marked with 255 and the outer areas with 0, if True the behaviour is viceversa.
Returns: dataObj : {dataObject}
uint8 data object as mask with the same size, scales and offsets than this object. The mask is applied to all planes.

data
() → prints the content of the dataObject to the command line in a readable form.¶

deleteTag
(key) → Delete a tag specified by key from the tag dictionary.¶ Checks whether a tag with the given key exists in the tag dictionary and if so deletes it.
Parameters: key : {str}
the name of the tag to be deleted
Returns: success : {bool}:
True if tag with given key existed and could be deleted, else False

div
(obj) → a.div(b) return result of element wise division of a./b¶ All meta information (axis scales, offsets, descriptions, units, tags…) of the resulting object are copied from this data object.
Parameters: obj : {dataObject}
Every value in this data object is divided by the corresponding value in obj.
Returns: c : {dataObject}
Resulting divided data object.

static
dstack
(objects) → returns a stacked data object containing a stack of all planes given by this and obj.¶ The returned dataObject contains layers of the same shape and type like the given ones. The different layers will be located along the first axis.
Parameters: obj : {sequence of dataObjects}
Sequence (list) of dataObjects containig planes that will be stacked together. All dataObjects must be of the same type and have the same shape of planes (last two dimesnions). Only one of the (n2) dimensions of each input dataObject is allowed to have a size greater one.
Returns: dataObj : {dataObject}
dataObject of the same type. The different planes are located along the first axis.

existTag
(key) → return True if tag with given key exists, else False¶ Checks whether a tag with the given key exists in tag dictionary of this data object and returns True if such a tag exists, else False.
Parameters: key : {str}
the key of the tag
Returns: result : {bool}
True if tag exists, else False

static
eye
(size[, dtype='uint8']) → creates a 2D, square, eyematrix.¶ Static method for creating a twodimensional, square, eyematrix of type itom.dataObject.
Parameters: size : {int},
the size of the square matrix (single value)
dtype : {str}, optional
‘dtype’ is the data type of each element, possible values: ‘int8’, ‘uint8’, …, ‘int32’, ‘uint32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’
Returns: I : {dataObject} of shape (size,size)
An array where all elements are equal to zero, except for the ‘kth diagonal, whose values are equal to one.

static
fromNumpyColor
(array) → creates a rgba32 dataObject from a threedimensional numpy array whose liast dimension has the size 3 or 4.¶ Static method for creating a twodimensional dataObject of type ‘rgba32’ from a threedimensional numpy.array (uint8 only). The size of the dataObject corresponds to the first two dimensions of the numpy.array. The last dimension of the numpy.array must have a size of 3 (blue, green, red and alpha = 255) or 4 (blue, green, red, alpha).
This method can especially be used to convert numpy.arrays that are obtained by methods from packages like OpenCV (cv2) or PIL to dataObjects.
Parameters: array : {numpy.array},
[MxNx3] or [MxNx4], uint8 numpy.array
Returns: I : {dataObject} of shape (M,N) and type ‘rgba32’
The last dimension of the numpy.array corresponds to blue, green, red and optional alpha of the rgba32 value.

getTagListSize
() → returns the number of tags in the tag dictionary¶ Every data object can have an arbitrary number of tags stored in the tag dictionary. This method returns the number of different tags, where the protocol is also one tag with the key ‘protocol’.
Returns: length : {int}:
size of the tag dictionary. The optional protocol also counts as one item.

imag
() → return a new data object with the imaginary part of the source¶ This method extracts the imaginary part of each element in source and writes the result to the output object.This object must be of complex type (complex128 or complex64). The output value will be float type (float64 or float32).
Returns: res : {dataObject}
output dataObject of same shape but the type is changed.

lineCut
(coordinates) → returns a data object of the same type containing a lineCut calculated by the use of a Bresenham algorithm.¶ The returned dataObject contains a lineCut across the 2d source dataObject.
Parameters: obj : {sequence of double}
Sequence (list) containing four floatingpoint values representing the physical coordinates of the start and endpoint. The values are interpreted as followed: [x0,y0,x1,y1]
Returns: dataObj : {dataObject}
one dimensional dataObject of the same type.

locateROI
() → returns information about the current region of interest of this data object¶ A region of interest (ROI) of a data object is defined by the two values per axis. The first element always indicates the size between the real border of the data object and the region of interest on the left / top … side and the second value the margin of the right / bottom … side.
This method returns a tuple with two elements: The first is a list with the original sizes of this data object, the second is a list with the offsets from the original data object to the first value in the current region of interest
If no region of interest is set (hence: full region of interest), the first list corresponds to the one returned by size(), the second list is a zerovector.
See also

makeContinuous
() → return continuous representation of dataObject¶ Per default a dataObject with more than two dimensions allocates separated chunks of memory for every plane, where a plane is always the matrix given by the last two dimensions. This separated storage usually allows allocating more memory for huge for instance three dimensional matrices. However, in order to generate a dataObject that is directly compatible to Numpy or other Cstyle matrix structures, the entire allocated memory must be in one block, that is called continuous. If you create a Numpy array from a dataObject that is not continuous, this function is implicitely called in order to firstly make the dataObject continuous before passing to Numpy.
Returns: obj : {dataObject}
continuous dataObject
Notes
if this dataObject already is continuous, a simple shallow copy is returned

mul
(obj) → a.mul(b) returns element wise multiplication of a*b¶ All meta information (axis scales, offsets, descriptions, units, tags…) of the resulting object are copied from this data object.
Parameters: obj : {dataObject}
dataObject whose values are elementwisely multiplied with the values in this dataObject.
Returns: c : {dataObject}
Resulting multiplied data object.
For a mathematical multiplication see the *operator. :

name
() > returns the name of this object (dataObject)¶

normalize
([minValue=0.0, maxValue=1.0, typestring='']) → returns the normalization of this dataObject¶ Returns the normalized version of this data object, where the values lie in the range [minValue,maxValue]. Additionally it is also possible to convert the resulting data object to another type (given by the parameter typestring). As default no type conversion is executed.
Parameters: minValue : {double}
minimum value of the normalized range
maxValue : {double}
maximum value of the normalized range
typestring : {String}
Type string indicating the new type (‘uint8’,…’float32’,..,’complex64’), default: ‘’ (no type conversion)
Returns: normalized : {dataObject}
normalized data object

static
ones
(dims[, dtype='uint8'[, continuous = 0]]) → creates new dataObject filled with ones.¶ Static method for creating a new ndimensional itom.dataObject with given number of dimensions and dtype, filled with ones.
Parameters: dims : {integer list}
‘dims’ is list indicating the size of each dimension, e.g. [2,3] is a matrix with 2 rows and 3 columns
dtype : {str}, optional
‘dtype’ is the data type of each element, possible values: ‘int8’, ‘uint8’, …, ‘int32’, ‘uint32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’
continuous : {int}, optional
‘continuous’ [01] defines whether the data block should be continuously allocated in memory [1] or in different smaller blocks [0] (recommended for huge matrices).
Returns: I : {dataObject} of shape (size,size)
An array where all elements are equal to one.
Notes
For colortypes (rgba32) every item / cell will be white: [r=255 g=255 b=255 a=255].

physToPix
(values[, axes]) → returns the pixel coordinates for the given physical coordinates.¶ This method transforms a physical axis coordinate into its corresponding pixel coordinate. The transformation is influenced by the offset and scaling of each axis:
phys = (pix  offset) * scaling
If no axes parameter is given, the values are assumed to belong the the ascending axis list (0,1,2,3…). The returned pixel value is clipped by the real size of the data object in the requested dimension [0, shape[axis]1].
Parameters: values : {float, floattuple}
One single physical coordinate or a tuple of physical coordinates.
axes : {int, inttuple}, optional
If this is given, the values are mapped to the axis indices given by this value or tuple. Else, an ascending list starting with index 0 is assumed.
Returns: Float or floattuple with the pixel coordinates for each physical coordinate at the given axis index. :
Raises: Value error : :
if the given axes is invalid (out of range)
Runtime warning : :
if requested physical unit is outside of the range of the requested axis. The returned pixel value is clipped to the closest boundary value.

pixToPhys
(values[, axes]) → returns the physical coordinates for the given pixel coordinates.¶ This method transforms a pixel coordinate into its corresponding physical coordinate. The transformation is influenced by the offset and scaling of each axis:
pix = (phys / scaling) + offset
If no axes parameter is given, the values are assumed to belong the the ascending axis list (0,1,2,3…).
Parameters: values : {float, floattuple}
One single pixel coordinate or a tuple of pixel coordinates.
axes : {int, inttuple}, optional
If this is given, the values are mapped to the axis indices given by this value or tuple. Else, an ascending list starting with index 0 is assumed.
Returns: Float or floattuple with the physical coordinates for each pixel coordinate at the given axis index. :
Raises: Value error : :
if the given axes is invalid (out of range)

static
rand
([dims[, dtype='uint8'[, continuous = 0]]]) → creates new dataObject filled with uniformly distributed random values.¶ Static method to create a new itom.dataObject filled with uniformly distributed random numbers. In case of an integer type, the uniform noise is from min<ObjectType>(inclusiv) to max<ObjectType>(inclusiv). For floating point types, the noise is between 0(inclusiv) and 1(exclusiv).
Parameters: dims : {integer list}
‘dims’ is list indicating the size of each dimension, e.g. [2,3] is a matrix with 2 rows and 3 columns.
dtype : {str}, optional
‘dtype’ is the data type of each element, possible values: ‘int8’, ‘uint8’, …, ‘int32’, ‘uint32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’
continuous : {int}, optional
‘continuous’ [01] defines whether the data block should be continuously allocated in memory [1] or in different smaller blocks [0] (recommended for huge matrices).
Returns: out : {dataObject}
Array of random numbers with the given dimensions, dtype.
See also
randN
 method for creating a matrix filled with gaussian distributed values

static
randN
(dims[, dtype='uint8'[, continuous = 0]]) → creates dataObject filled with gaussian distributed random values.¶ Static method to create a new itom.dataObject filled with gaussian distributed random numbers. In case of an integer type, the gausian noise mean value is (max+min)/2.0 and the standard deviation is (maxmin/)6.0 to max. For floating point types, the noise mean value is 0 and the standard deviation is 1.0/3.0.
Parameters: dims : {integer list}
‘dims’ is list indicating the size of each dimension, e.g. [2,3] is a matrix with 2 rows and 3 columns.
dtype : {str}, optional
‘dtype’ is the data type of each element, possible values: ‘int8’, ‘uint8’, …, ‘int32’, ‘uint32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’
continuous : {int}, optional
‘continuous’ [01] defines whether the data block should be continuously allocated in memory [1] or in different smaller blocks [0] (recommended for huge matrices).
Returns: out : {dataObject}
Array of random numbers with the given dimensions, dtype.
See also
rand
 method for creating a matrix filled with unformly distributed values

real
() → return a new data object with the real part of the source¶ This method extracts the real part of each element in source and writes the result to the output object.This object must be of complex type (complex128 or complex64). The output value will be float type (float64 or float32).
Returns: res : {dataObject}
output dataObject of same shape but the type is changed.

reshape
(newShape) → return a reshaped shallow copy (if possible) of this dataObject.¶ This method returns a shallow or deep copy if this data object where the type and data is unchanged. The shape of the returned object corresponds to the parameter ‘newShape’. The number of values must therefore not be changed. If the last two dimensions of ‘newShape’ and this object are the same and if the data is not continously organized, a shallow copy can be returned, else a deep copy has to be created. Tags and the rotation matrix are copied, the axis tags are only copied for all axes whose size will not change beginning from the last axis (‘x’). This axis copying is stopped after the first axis with a different new size.
Parameters: newShape : {seq. of int}
New shape of the returned object. A minimal size of this list or tuple is two.
Returns: reshaped : {dataObject}
The reshaped data object.
Notes
This method is similar to numpy.reshape

setAxisDescription
(axisNum, axisDescription) → Set the description of the specified axis.¶ Each axis in the data object can get a specific axisDescription string (e.g. mm). Use this method to set the axisDescription of one specific axis.
Parameters: axisNum : {int}
The addressed axis index
axisDescription : {str}
New axis description
Raises: RuntimeError : :
if the given axisNum is invalid (out of range)
See also
axisDescriptions
 this attribute can directly be used to read/write the axis description(s) of single or all axes

setAxisOffset
(axisNum, axisOffset) → Set the offset of the specified axis.¶ Each axis in the data object can get a specific scale value, described in axisUnits per pixel. Use this method to set the scale of one specific axis. The value of each pixel in its physical unit is the (pxCoordinate  axisOffset) * axisScale
Parameters: axisNum : {int}
The addressed axis index
axisOffset : {double}
New axis offset in [px]
Raises: RuntimeError : :
if the given axisNum is invalid (out of range)
See also
axisOffsets
 this attribute can directly be used to read/write the axis offset(s) of single or all axes

setAxisScale
(axisNum, axisScale) → Set the scale value of the specified axis.¶ Each axis in the data object can get a specific scale value, described in axisUnits per pixel. Use this method to set the scale of one specific axis.
Parameters: axisNum : {int}
The addressed axis index
axisScale : {double}
New axis scale in axisUnit/px
Raises: RuntimeError : :
if the given axisNum is invalid (out of range)
See also
axisScales
 this attribute can directly be used to read/write the axis scale(s) of single or all axes

setAxisUnit
(axisNum, axisUnit) → Set the unit of the specified axis.¶ Each axis in the data object can get a specific unit string (e.g. mm). Use this method to set the unit of one specific axis.
Parameters: axisNum : {int}
The addressed axis index
axisUnit : {str}
New axis unit
Raises: RuntimeError : :
if the given axisNum is invalid (out of range)
See also
axisUnits
 this attribute can directly be used to read/write the axis unit(s) of single or all axes

setTag
(key, tagvalue) → Set the value of tag specified by key.¶ Sets the value of an existing tag (defined by key) in the tag dictionary to the string or double tagvalue or adds a new item with key.
Parameters: key : {str}
the name of the tag to set
tagvalue : {str or double}
the new value of the tag, either string or double value
Notes
Do NOT use ‘special character’ within the tag key because they are not XMLsave.

size
([index]) → returns the size of this dataObject (tuple of the sizes in all dimensions or size in dimension indicated by optional axis index).¶ Parameters: index : {int}, optional
If index is given, only the size of the indicated dimension is returned as single number (0 <= index < number of dimensions)
Returns: A tuple containing the sizes of all dimensions or one single size value if ‘index’ is indicated. :
See also
shape
 the readonly attribute shape is equal to size()
Notes
For a more consistent syntax with respect to numpy arrays, the same result is obtained by the attribute shape. Please use the attribute shape for future implementations since this method is marked as deprecated.

splitColor
(color[, destinationType='uint8']) → returns a seperated color channel of a rgba32 color data object¶ The destination data object has the same size than this data object if only one color is extracted. The output will have one dimension more if there are more than one colors extracted.Each element of the new dimension corrspomnds to one color. DestinationType defines the type of the output object.
Parameters: color : {str}
Color string indicating the color(s) to be extracted (‘b’,’r’,’g’,’a’). It is possible to combine the colors for ex. ‘rgb’,
so that each color corresponds to one elemnt of the first dimension of the output dataObject :
destinationType : {str}
Type string indicating the new real type (‘int8’,…’float32’,’float64’  no complex)
Returns: dataObj : {dataObject}
containing the selected channel values

squeeze
() → return a squeezed shallow copy (if possible) of this dataObject.¶ This method removes every dimension with size equal to 1. A shallow copy is only returned, if the last two dimensions (called plane) are not affected by the squeeze operation and if the data block in the dataObject is not continuous. Else a deepcopy has to be returned due to a overall re aligment of the matrix. The returned object can never have less then two dimensions. If this is the case, the last or second to last dimensions with a size of 1 is not deleted. If squeeze() returns a shallow copy, a change in a value will change the same value in the original object, too.
Returns: squeezed : {dataObject}
The squeezed data object.
Notes
This method is similar to numpy.squeeze

toGray
([destinationType='uint8']) → returns the rgba32 color data object as a grayscale object¶ The destination data object has the same size than this data object and the real type given by destinationType. The pixelwise conversion is done using the formula: gray = 0.299 * red + 0.587 * green + 0.114 * blue.
Parameters: destinationType : {str}
Type string indicating the new real type (‘uint8’,…’float32’,’float64’  no complex)
Returns: dataObj : {dataObject}
converted grayscale data object of desired type

toNumpyColor
([addAlphaChannel = 0]) → convert a 2D dataObject of type 'rgba32' to a 3D 'uint8' numpy.array whose last dimension is 3 (no alpha channel) or 4.¶ Whereas the class ‘dataObject’ has a specific type ‘rgba32’ for colour values (which is internally a uint32 value with 4 times 8bit values for blue, green, red and alpha), numpy.arrays don’t have this. Therefore, several python packages like cv2 (OpenCV) or PIL store colour values in 3D numpy.arrays whereas the last dimension has a size of 3 (without alpha value) or 4. This method returns the coloured version of a numpy.array from the rgba32 dataObject.
Parameters: addAlphaChannel : {int}
If 0, the last dimension of the returned numpy.array has a size of 3 and contains the blue, green and red value, whereas 1 adds the alpha value as fourth value.
Returns: arr : {numpy.array}
converted 2D numpy.array of type ‘uint8’ that can for instance be used in methods of packages like cv2 (OpenCV) or PIL.

tolist
() → return the data object as a (possibly nested) list¶ This method returns a nested list with all values of this data object. The recursion level of this nested list corresponds to the number of dimensions. The outer list corresponds to the first dimension.
Returns: y : {list}
Nested list with values of data object (int, float or complex depending on type of data object)

trans
() → return a planewise transposed dataObject¶ Return a new data object with the same data type than this object and where every plane (data spanned by the last two dimensions) is transposed respectively such that the last two axes are permuted.
Returns: out : {dataObject}
A copy of this dataObject is returned where every plane is its transposed plane.

static
zeros
(dims[, dtype='uint8'[, continuous = 0]]) → creates new dataObject filled with zeros.¶ Static method for creating a new ndimensional itom.dataObject with given number of dimensions and dtype, filled with zeros.
Parameters: dims : {integer list}
‘dims’ is list indicating the size of each dimension, e.g. [2,3] is a matrix with 2 rows and 3 columns
dtype : {str}, optional
‘dtype’ is the data type of each element, possible values: ‘int8’, ‘uint8’, …, ‘int32’, ‘uint32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’
continuous : {int}, optional
‘continuous’ [01] defines whether the data block should be continuously allocated in memory [1] or in different smaller blocks [0] (recommended for huge matrices).
Returns: I : {dataObject} of shape (size,size)
An array where all elements are equal to zero.
Notes
For colortypes (rgba32) every item / cell will be black and transparent: [r=0 g=0 b=0 a=0].

axisDescriptions
¶ tuple containing the axis descriptions {str}.
This attribute gives access to the internal axis descriptions expressed as a tuple of strings. The tuple has the same length than the number of dimensions of this data object.
You can either assign a new tuple with the same length or change single values using tuple indexing.
The axis descriptions are considered if the data object is plotted.
See also
setAxisDescriptions
 alternative method to change the description string of one single axis
Notes
read / write

axisOffsets
¶ tuple containing the axis offsets [px].
This attribute gives access to the internal axis offsets [px] expressed as a tuple of double values. The ith value in the tuple corresponds to the pixeloffset of the ith axis. Either assign a new tuple with the same length than the number of dimensions or change single values using tuple indexing.
Definition: Physical unit = (pxCoordinate  offset)* scale
If the data object is plot with offsets != 0, the scaled (physical) units are displayed in the plot.
See also
Notes
read / write

axisScales
¶ tuple containing the axis scales [unit/px].
This attribute gives access to the internal axis scales [unit/px] expressed as a tuple of double values. The ith value in the tuple corresponds to the scaling factor of the ith axis. Either assign a new tuple with the same length than the number of dimensions or change single values using tuple indexing.
Definition: Physical unit = (pxCoordinate  offset)* scale
If the data object is plot with scalings != 1, the scaled (physical) units are displayed in the plot.
See also
Notes
read / write

axisUnits
¶ tuple containing the axis units {str}.
This attribute gives access to the internal axis units expressed as a tuple of strings. The tuple has the same length than the number of dimensions of this data object.
You can either assign a new tuple with the same length or change single values using tuple indexing.
The axis units are considered if the data object is plotted.
See also
setAxisUnit
 alternative method to change the unit string of one single axis
Notes
read / write

base
¶ base object

continuous
¶ true if matrix is continuously organized, else false.
If true, the whole matrix is allocated in one huge block in memory, hence, this data object can be transformed into a numpy representation without reallocating memory.
Notes
readonly

dims
¶ number of dimensions of this data object
Notes
readonly property, this property is readable both by the attributes ndim and dims.

dtype
¶ get type string of data in this data object
This type string has one of these values: ‘uint8’, ‘int8’, ‘uint16’, ‘int16’, ‘uint32’, ‘int32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’
Notes
This attribute is readonly

metaDict
¶ return dictionary with all meta information of this dataObject
Returns a new dictionary with the following meta information:
 axisOffsets : List with offsets of each axis
 axisScales : List with the scales of each axis
 axisUnits : List with the unit strings of each axis
 axisDescriptions : List with the description strings of each axis
 tags : Dictionary with all tags including the tag ‘protocol’ if at least one protocol entry has been added using addToProtocol
 valueOffset : Offset of each value (0.0)
 valueScale : Scale of each value (1.0)
 valueDescription : Description of the values
 valueUnit : The unit string of the values
Notes
Adding or changing values to / in the dictionary does not change the meta information of the dataObject. Use the corresponding setters like setTag… instead.

ndim
¶ number of dimensions of this data object
Notes
readonly property, this property is readable both by the attributes ndim and dims.

shape
¶ tuple with the sizes of each dimension / axis of this data object.
See also
Notes
In difference to the shape attribute of numpy arrays, no new shape tuple can be assigned to this value (used to ‘reshape’ the array). Readonly.
tag dictionary of this data object.
This attribute returns a dict_proxy object of the tag dictionary of this data object. This object is readonly. However you can assign an entire new dictionary to this attribute that fully replaces the old tag dictionary. The tag dictionary can contain arbitrary pairs of key > value where value is either a string or a double value.
Special tags are the key ‘protocol’ that contains the newlineseparated protocol string of the data object (see: addToProtocol()) or the key ‘title’ that can for instance be used as title in any plots.
You can add single elements using the method setTag(key,value) or you can delete tags using deleteTag(key).
Do NOT use ‘special character’ within the tag key because they are not XMLsave.
Notes
readonly / write only for fully new dictionary

value
¶ get/set the values within the ROI as a onedimensional tuple.
This method gets or sets the values within the ROI. If this attribute is called by means of a getter, a tuple is returned which is created by iterating through the values of the data object (rowwise). In the same way of iterating, the values are set to the data object if you provide a tuple of the size of the data object or its ROI, respectively.
Example:
b = dataObject[1,1:10,1,1].value # or for the first value b = dataObject[1,1:10,1,1].value[0] # The elements of the tuple are adressed with b[idx].

valueDescription
¶ value unit description.
Attribute to read or write the unit description string of the values in this data object.
The value description is considered if the data object is plotted.
Notes
read / write

valueOffset
¶ value offset.
This attribute gives the offset of each value in the data object. This value is always 0.0.
Notes
This attribute is read only

valueScale
¶ value scale.
This attribute gives the scaling factor of each value in the data object. This value is always 1.0.
Notes
This attribute is read only

valueUnit
¶ value unit.
Attribute to read or write the unit string of the values in this data object.
The value unit is considered if the data object is plotted.
Notes
read / write

xyRotationalMatrix
¶ Access the 3x3 rotational matrix in the dataObject tagspace
This attribute gives access to the xyRotationalMatrix in the metaDataTagspace. The getter method retuns a 3x3Array deep copied from the internal matrix, Implemented to offer compability to x3p format.
Notes
{3x3 array of doubles} : ReadWrite