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=None)¶

Creates a new n-dimensional dataObject array.

The dataObject represents a multidimensional array of fixed-size items (integer, floating-point or complex values) and contains further, optional, meta information, like units, axis descriptions, scalings, general tags, … Recently the following data types (dtype) are supported:

Integer (int8, uint8, int16, uint16, int32),
Floating point (float32, float64 (=> double)),
Complex (complex64 (2x float32), complex128 (2x float64)).
Color (rgba32 (uint32 or uint[4] containing the four 8bit values [R, G, B, Alpha])).
Datetime and Timedelta (datetime, timedelta).

Arrays can also be constructed using some of the static pre-initialization methods zeros(), ones(), rand() or randN() (refer to the See Also section below).

Parameters

dimssequence of int, optional: dims is a list or tuple indicating the size of each dimension. The length of this sequence defines the dimension of this dataObject. As an example, dims = [2, 3] creates a two-dimensional dataObject with two rows and three columns. If dims is not given, an empty data object is created.
dtypestr, optional: Data type of each element in the array. Possible values are: ‘int8’, ‘uint8’, ‘int16’, ‘uint16’, ‘int32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’, ‘datetime’ or ‘timedelta’.
continuousint, optional: The last two dimensions of a dataObject are always stored as continuous junk of memory, denoted as plane. If continuous is set to 1, even a dataObject with a dimension n > 2 will allocate one big block of memory and continuously stores the matrix data there. If continuous is 0, different junks of memory are allocated for each plane, the planes are referenced by means of an index vector. This is recommended for large arrays, since the operating system might get trouble allocated one very big continuous junk of memory, instead of multiple smaller ones.
dataint or float or complex or rgba or datetime.datetime or datetime.timedelta or sequence of int or sequence of float or sequence of complex or dataObject or np.ndarray, optional: If data is a single value, all values in the dataObject are set to this single value. Else, the sequence or array-like object must have the same number of values than the data object. These values will then be assigned to the new data object (filled row by row).

See also

ones: Static method to construct a data object filled with ones.
zeros: Static method to construct a data object filled with zeros.
nans: Static method to construct a data object (float or complex only) with NaNs.
rand: Static method to construct a randomly filled data object (uniform distribution).
randN: Static method to construct a randomly filled data object (gaussian distribution).

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 matrix-plane) is two-dimensional and covers data of the last two dimensions. In C++-context each of these matrix-planes is of type cv::Mat_<type> and can be used with every operator given by the openCV-framework (version 2.3.1 or higher).

The dimensions of the matrix are structured descending. So if we assume to have a n-dimensional 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_(n-1), s_(n-2), …, s_y, s_x].

In order to make the data object compatible to continuously organized data structures, like numpy-arrays, it is also possible to have all matrix-planes in one data-block in memory (not recommended for huge matrices). Nevertheless, the indicated data structure with the two-dimensional sub-matrix-planes is still existing. The data organization is equal to the one of openCV, hence, two-dimensional matrices are stored row-by-row (C-style)…

In addition to OpenCV, itom.dataObject supports complex valued data types for all operators and methods.

Warning ‘uint32’ is currently not available, since it is not fully supported by the underlying OpenCV matrices.

Deep Copy, Shallow Copy and ROI

It is possible to set a n-dimensional 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 itom-dataObject 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 copy-constructor ‘dataObject(anyArray : Union[dataObject, np.ndarray], dtype : str = ‘’, continuous : int = 0)’, where ‘anyArray’ must be any array-like structure which can be parsed by the numpy-interface. If a dtype is given or if continuous is 1, the new data object will be a type-casted (and / or continuous) copy of ‘anyArray’.

abs() → dataObject¶

Returns a new dataObject with the absolute values of this object.

The absolute values in the resulting dataObject are determined for both real (integer and floating point) and complex data types of this object. This method raises a TypeError for a rgba32 data type.

Returns

absObjdataObject: Array with the same size than this object, that contains the absolute values of this object. If the data type of this object is complex, the returned object has the corresponding floating point data type. Else, the data type is unchanged. If this dataObject has an unsigned integer data type, its shallow copy is returned without any changes.

Raises

TypeError: if this method is called for a dataObject of data type rgba32.

addToProtocol(newLine)¶

Appends one string entry to the protocol list.

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

newLinestr: The text to be added to the protocol.

adj()¶

Adjugates this dataObject (plane-by-plane).

Every plane (spanned by the last two axes) is transposed and every element is replaced by its complex conjugate value. This is done in-line.

Raises

TypeError: if the data type of this data object is not complex.

See also

adjugate: does the same operation but returns the resulting data object

adjugate() → dataObject¶

Returns the plane-wise adjugated array of this dataObject.

If this data object has a complex type, the transposed data object is returned where every element is complex conjugated. For data objects with more than two dimensions the transposition is done plane-wise, hence, only the last two dimensions are permuted.

Returns

dataObject: adjugate of this dataObject.

Raises

TypeError: if the data type of this data object is not complex.

See also

adj: does the same operation but manipulates this object inline.

adjustROI(offsets)¶

Adjusts the size and position of the region of interest of this object.

In Python, it is common to use slices of other objects, like lists, tuples, numpy.ndarray among others. This slice represents a subpart of the original object, however the values within the slice are still the same than in the original object.

The same holds for dataObject, where a slice will return a shallow copy of the original object with a maybe reduced size. This is denoted as region of interest (ROI). Here an example:

org = dataObject.ones([100, 200], 'float32') 
roi = org[10:20, 5:9]  # slicing 

roi[0, 0] = 100  # change one value in roi 
print(org[10, 5])  # returns 100 

Although the first value in roi is changed, its corresponding value in org is changed, too. This is the principle of shallow copies and slicing / region of interests.

This method is used to change to offset and / or size of the current ROI of this object. Of course, this ROI can never be bigger than the original array data. In order to change the position and / or size of the current region of interest, pass a sequence (list or tuple) of integer values. The length of this sequence must be 2 * ndim, where ndim is the number of dimensions of this object. Always two adjacent values in this sequence refer to one axis, starting with the first axis index and ending with the last one. The first value of such a pair of two values indicate the offset of the region of interest with respect to one border of this axis (e.g. the left or top border), the 2nd value is the offset with respect to the other side of this axis (e.g. the right or bottom border). Negative values decrease the size of the ROI towards the center, positive values will increase its current size.

Example:

d = dataObject([5, 4]) 
droi = dataObject(d)  # make a shallow copy 
droi.adjustROI([-2, 0, -1, -1]) 

Now, droi has a ROI, whose first value is equal to d[2, 1] and its shape is (3, 2).

Parameters

offsetslist of int or tuple of int: This sequence must have twice as many values than the number of dimensions of this dataObject. 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.

Raises

RuntimeError: if desired, new ROI exceeds the original shape of this dataObject.

See also

locateROI: method to get the borders of the current ROI

arg() → dataObject¶

Returns a new data object with the argument values of this complex type dataObject.

This method calculates the argument value of each element in this dataObject and returns these values as new dataObject with the same shape than this object. This object must be of complex data type (complex128 or complex64). The output data type will be float then (float64 or float32).

Returns

argObjdataObject: is the argument function applied to all values of this dataObject.

astype(typestring) → dataObject¶

Converts this dataObject to another data type.

Converts this dataObject to a new dataObject with another data type, given by the string typestring (e.g. ‘uint8’). The converted dataObject 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

typestringstr: Type string indicating the new type (uint8, …, float32, …, complex128).

Returns

dataObject: The converted dataObject.

conj()¶

Converts this dataObject into its complex-conjugate (inline).

Every value of this dataObject is replaced by its complex-conjugate value.

Raises

TypeError: if the data type of this data object is not complex.

See also

conjugate: does the same operation but returns a complex-conjugated copy of this data object

conjugate() → dataObject¶

Returns a copy of this dataObject where every element is complex-conjugated.

Returns

dataObject: element-wise complex conjugate of this data object

Raises

TypeError: if the data type of this data object is not complex.

See also

conj: does the same operation but manipulates this object inline.

copy(regionOnly=False) → dataObject¶

Returns a deep copy of this dataObject

Parameters

regionOnlybool, optional: If regionOnly is True, only the current region of interest of this dataObject is copied, else the entire dataObject including the shaded areas outside of the current region of interest are copied, including the ROI settings [default].

Returns

dataObject: Deep copy of this dataObject.

See also

locateROI

copyMetaInfo(sourceObj, copyAxisInfo=True, copyTags=False)¶

Copies meta information of another dataObject to this object.

This method can be used to copy all or parts of meta information of the dataObject sourceObj to this object. The following things are copied, depending on the arguments of this method:

Axis meta information:

axis scaling and offset (see axisScales and axisOffsets)
axis descriptions and units (see axisDescriptions and axisUnits)

Tags:

the entire tag map (string key vs. string or float value), including the protocol string. The existing tag map in this object is deleted first.

Parameters

sourceObjdataObject: source object, where meta information is copied from.
copyAxisInfobool, optional: If True, all axis meta information is copied.
copyTagsbool, optional: If True, the tags of this data object are cleared and then set to a copy of the tags of sourceObj.

See also

metaDict: this attribute can directly be used to print meta information of a dataObject.

createMask(shapes, inverse=False) → dataObject¶

Returns an uint8 mask dataObject where all pixels of this object that are contained in any shape are masked.

The returned dataObject has the same shape than this object and the data type uint8. All pixels in this object, that are contained in any of the given shape will be set to 255 in the returned array, otherwise 0.

New in itom 5.0: always return a 2d dataObject (see return value below)

Parameters

shapesshape or list of shape or tuple of shape: The union of all given shapes (polygons, rectangles, squares, circles and ellipes are considered, only) is used to determine if any pixel should be masked in the returned mask (value 255) or not.
inversebool: If True, masked values are set to 0 (instead of 255) and all other values are set to 255 (instead of 0). The default is False (masked = 255).

Returns

maskdataObject: uint8 dataObject mask (0: not contained, else: contained) whose shape is equal to the last two dimensions of this object. The tags axisScales, axisOffsets, axisDescriptions and axisUnits are accordingly copied from the last two axes of this object.

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

deleteTag(key) → bool¶

Deletes a tag specified by key from the tag dictionary.

Parameters

keystr: the name of the tag to be deleted.

Returns

successbool: True if tag with given key existed and could be deleted, otherwise False.

div(otherObj) → dataObject¶

Returns the result of the element-wise division of this dataObject by otherObj.

This dataObject and otherObj must have the same shape and dtype for the element-wise division.

All meta information (axis scales, offsets, descriptions, units, tags…) of the resulting object are copied from this data object.

Parameters

otherObjdataObject: The returned dataObject contains the result of the element-wise division of all values in this object by otherObj. Must have the same shape and data type than this object.

Returns

resultdataObject: Resulting divided data object. Values, that exceed the range of the current data type, will be set to the result modulo max(dtype).

Raises

RuntimeError: if a division by zero occurs for integer or complex data types.

static dstack(objects, copyAxisInfo=False) → dataObject¶

Returns a 3D dataObject with the stacked dataObjects in the objects sequence.

The given dataObjects must all have the same type as well as the same size of both last axes / dimensions. This method then returns a 3d dataObject of the same type, whose size of the two last axes correspond to those of the input objects. The returned 3D dataObject contains then a stacked representation of all given input dataObjects depth wise (along first axis).

If any of the input dataObjects has more than two dimensions, all contained planes (x,y-matrices) are also stacked in the resulting object.

Parameters

objectslist of dataObject or tuple of dataObject: Sequence (list) of dataObjects containing planes that will be stacked together. All dataObjects must be of the same type and have the same shape of planes (last two dimensions).
copyAxisInfobool: If True, the axis information (description, unit, scale, offset) is copied from the first dataObject in objects to the returned object. If the first dataObject has less dimensions than the returned 3D object, only the axis information of the last two dimensions is copied. The description and unit of the first axis (z) is an empty string (default) and the scale and offset of this first axis is set to the default values 1.0 and 0.0 respectively.

Returns

stackdataObject: If objects is an empty list or tuple, an empty dataObject is returned. Else if objects only contains one array, this array is returned. Otherwise, all dataObjects (2D or 3D) in objects are vertically stacked along the first axis, which is prepended to the existing axes before.

existTag(key) → bool¶

Checks if a certain tag key exists.

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

keystr: the key of the tag.

Returns

bool: True if tag exists, else False

static eye(size, dtype='uint8') → dataObject¶

Creates a two-dimensional, squared eye matrix.

An eye matrix is an array where all elements are equal to zero, except for the diagonal values which are set to 1. For dtype == rgba32, the diagonal values are r = 0, g = 0, b = 1, alpha = 0.

Parameters

sizeint: The size of the squared matrix (single integer value).
dtypestr, optional: The desired data type for the elements in the returned dataObject. Possible values are: int8, uint8, …, int32, float32, float64, complex64, complex128, rgba32.

Returns

eyeMatrixdataObject: The created eye-matrix as size x size dataObject.

See also

ones: method for creating a matrix filled with ones
zeros: method for creating a matrix filled with zeros

static fromNumpyColor(array) → dataObject¶

Creates a rgba32 dataObject from a three-dimensional numpy.ndarray.

Static method for creating a 2D M x N dataObject of data type rgba32 from a three-dimensional, uint8 numpy.ndarray`. This array must have the shape M x N x 3 or M x N x 4. Each vector array[i, j, :] is then used to create one rgba32 value in the returned dataObject. The meaning of this vector is:

(blue, green, red) if array consists of three channels (last dimension). The rgba32 value then gets an alpha value set to 255 everywhere.
(blue, green, red, alpha) if array consists of four channels (last dimension).

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

arraynumpy.ndarray: M x N x 3 or M x N x 4, uint8 numpy.ndarray

Returns

dataObject: Coloured dataObject of shape M x N and data type rgba32.

getTagListSize() → int¶

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

lengthint: Size of the tag dictionary. The optional protocol also counts as one item.

lineCut(coordinates) → dataObject¶

Returns a dataObject with the values of this object along a line with the given coordinates.

This method uses the Bresenham algorithm to get the nearest values along a line, whose start- and end-point is given by coordinates. These values are returned in a new dataObject with the same data type than this object.

This method can be applied to 2D and 3D dataObjects. In the case of a 3D object, the line cut is defined plane-by-plane and the values are put in one row for each plane of this object.

Parameters

coordinateslist of float or tuple of float: A sequence of 4 float values, that define the physical coordinates of the start- and end point of the desired line along which the nearest values should be gathered. The values are: [x0, y0, x1, y1].

Returns

lineCutdataObject: An array of the same data type than this object and shape P x N, that contains the nearest values along the given line coordinates. If this dataObject has two dimensions, P = 1, else P is equal to the size of the first dimension (shape[0]). N corresponds to the number of points along the line, defined by the used Bresenham algorithm.

Raises

RuntimeError: if this dataObject has more than three dimensions.

locateROI() → Tuple[List[int], List[int]]¶

Returns information about the current region of interest of this dataObject.

In Python, it is common to use slices of other objects, like lists, tuples, numpy.ndarray among others. This slice represents a subpart of the original object, however the values within the slice are still the same than in the original object.

The same holds for dataObject, where a slice will return a shallow copy of the original object with a maybe reduced size. This is denoted as region of interest (ROI). Here an example:

org = dataObject.ones([100, 200], 'float32') 
roi = org[10:20, 5:9]  # slicing 

roi[0, 0] = 100  # change one value in roi 
print(org[10, 5])  # returns 100 

Although the first value in roi is changed, its corresponding value in org is changed, too. This is the principle of shallow copies and slicing / region of interests.

This method returns information about the exact position of the region of interest within its original dataObject. This is defined by two values for each axis. The first value indicates the distance between the left, top, etc. border of the original object and the border of this object. If no region of interest is set, these values are 0 everywhere.

The second values define the distances between the right, bottom, … margins of this object and its original object (or 0 everywhere, too).

This method returns a tuple with two elements: The first is a list with the original sizes of this data object (if no ROI would have been set), 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 shape, the 2nd list contains 0 everyhwere.

The output of the example above would be:

print(roi.locateROI()) 
# >>> ([100, 200], [10, 5]) 

Returns

orgSizelist of int: The original sizes of this object (without ROI). This is equal to shape of the original object.
offsetslist of int: A list with N values, where N is the number of dimensions of this object. Each value n = 1 .. N is the offset of the first value of axis n in this object with respect to the original object.

See also

adjustROI: method to change the current region of interest

makeContinuous() → dataObject¶

Returns a continuous representation of this 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 C-style 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

dataObject: If this dataObject is not continuous, its continuous representation is returned as deep copy. A deep copy is also returned if this object is already continuous.

mul(otherObj) → dataObject¶

Returns the result of the element-wise multiplication of this dataObject with otherObj.

This dataObject and otherObj must have the same shape and dtype for the element-wise multiplication.

All meta information (axis scales, offsets, descriptions, units, tags…) of the resulting object are copied from this data object.

Parameters

otherObjdataObject: The returned dataObject contains the result of the element-wise multiplication of all values in this object and otherObj. Must have the same shape and data type than this object.

Returns

resultdataObject: Resulting multiplied data object. Values, that exceed the range of the current data type, will be set to the result modulo max(dtype).

Notes

For a mathematical multiplication see the @-operator.

name() → str¶

Returns the name of this object

Returns

str: the name of this object (dataObject)

static nans(dims, dtype='float32', continuous=0) → dataObject¶

Creates a floating-point dataObject filled with NaN values.

Parameters

dimstuple of int or list of int: dims is the shape of the new dataObject. The length of this list or tuple defines the number of dimensions, e.g. [2, 3] creates a 2D dataObject with two rows and three columns.
dtypestr, optional: The desired data type for the elements in the returned dataObject. Possible values are: float32, float64, complex64, complex128.
continuousint, optional: This value defines if the planes (each sub-array of the last two dimensions) are continuously allocated in memory (1) or distributed in various smaller junks (0, default). The latter is recommended for huge, n-dimensional matrices. This argument is only considered for len(dims) > 2.

Returns

arraydataObject: The newly created dataObject of shape dims and data type dtype, filled with NaN.

See also

eye: method for creating an eye matrix
zeros: method for creating a matrix filled with zeros
ones: method for creating a matrix filled with ones.

normalize(minValue=0.0, maxValue=1.0, typestring='') → dataObject¶

Returns a normalized version of this dataObject.

All values in the returned dataObject are normalized with respect to the given range [minValue, maxValue]. Additionally it is also possible to convert the resulting data object to another data type (given by the parameter typestring). Per default, no such a type conversion is done (empty typestring argument).

For the normalization, the current minimum and maximum value of this object is determined:

\[min_{cur} = min(thisObj) max_{cur} = max(thisObj) \]

Each value v is then normalized by:

\[v_{norm} = minValue + (v - min_{cur}) * (maxValue - minValue) / (max_{cur} - min_{cur}) \]

Parameters

minValuefloat: minimum value of the normalized range.
maxValuefloat: maximum value of the normalized range.
typestringstr: Data type for an optional type conversion. If an empty str is given, no such a conversion is done. Else possible values are (among others): (uint8, …, float32, …, complex128).

Returns

normalizeddataObject: normalized data object

Raises

RuntimeError: if a DateTime or TimeDelta dataObject should be normalized. Not supported.

Notes

For complex data types, the current minimum and maximum values are calculated based on the absolute value of the complex values. Therefore, the normalization can have a different result, than maybe expected.

static ones(dims, dtype='uint8', continuous=0) → dataObject¶

Creates a dataObject filled ones.

Parameters

dimstuple of int or list of int: dims is the shape of the new dataObject. The length of this list or tuple defines the number of dimensions, e.g. [2, 3] creates a 2D dataObject with two rows and three columns.
dtypestr, optional: The desired data type for the elements in the returned dataObject. Possible values are: int8, uint8, …, int32, float32, float64, complex64, complex128, rgba32.
continuousint, optional: This value defines if the planes (each sub-array of the last two dimensions) are continuously allocated in memory (1) or distributed in various smaller junks (0, default). The latter is recommended for huge, n-dimensional matrices. This argument is only considered for len(dims) > 2.

Returns

arraydataObject: The newly created dataObject of shape dims and data type dtype, filled with ones.

See also

eye: method for creating an eye matrix
zeros: method for creating a matrix filled with zeros

Notes

For the color data type rgba32, every value will be white: (r=255, g=255, b=255, alpha=255).

physToPix(values, axes=0) → Union[float, Tuple[float]]¶

Returns transformed values from physical to pixel coordinates.

This method transforms a physical axis coordinate into its corresponding pixel coordinate. The transformation is defined by the current offset and scale value of the specific 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

valuesfloat or sequence of float: One single physical coordinate or a tuple of physical coordinates.
axesint or sequence of int, optional: If values is a single value, axes must be None or one integer, that defines the axis for which the transformation should be calculated. If values is a tuple of float values, axes can be one single value (all values are transformed with respect to the same axis), or a tuple of int, whose size must be equal to the size of the axes tuple. Each value is then transformed with the corresponding value in axes. If None is given, axes is assumed to be an ascending list of values 0, 1, 2, ....

Returns

float or tuple of float: The transformed physical coordinates for the given axes to pixel coordinates.

Raises

ValueError: if the given axes is out of range
RuntimeWarning: 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=0) → Union[float, Tuple[float]]¶

Returns transformed values from pixel to physical coordinates.

This method transforms a pixel axis coordinate into its corresponding physical coordinate. The transformation is defined by the current offset and scale value of the specific 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…). The returned pixel value is clipped by the real size of the data object in the requested dimension [0, shape[axis] - 1].

Parameters

valuesfloat or sequence of float: One single pixel coordinate or a tuple of pixel coordinates.
axesint or sequence of int, optional: If values is a single value, axes must be None or one integer, that defines the axis for which the transformation should be calculated. If values is a tuple of float values, axes can be one single value (all values are transformed with respect to the same axis), or a tuple of int, whose size must be equal to the size of the axes tuple. Each value is then transformed with the corresponding value in axes. If None is given, axes is assumed to be an ascending list of values 0, 1, 2, ....

Returns

float or tuple of float: The transformed pixel coordinates for the given axes to physical coordinates.

Raises

ValueError: if the given axes is out of range.

static rand(dims, dtype='uint8', continuous=0) → dataObject¶

Creates a dataObject filled with uniformly distributed random values.

The value range of the random numbers depend on the desired data type dtype:

integer types: The random values are in the range [min(dtype), max(dtype)].
floating point types: The random values are in the range [0, 1).
rgba32: All colours as well as the alpha value is independently distributed in the range [0, 255].
complex types: Both the real as well as imaginary part is independently distributed in the range [0, 1).

Parameters

dimstuple of int or list of int: dims is the shape of the new dataObject. The length of this list or tuple defines the number of dimensions, e.g. [2, 3] creates a 2D dataObject with two rows and three columns.
dtypestr, optional: The desired data type for the elements in the returned dataObject. Possible values are: int8, uint8, …, int32, float32, float64, complex64, complex128, rgba32.
continuousint, optional: This value defines if the planes (each sub-array of the last two dimensions) are continuously allocated in memory (1) or distributed in various smaller junks (0, default). The latter is recommended for huge, n-dimensional matrices. This argument is only considered for len(dims) > 2.

Returns

arraydataObject: The newly created dataObject of shape dims and data type dtype, filled with random numbers.

See also

randN: method for creating a matrix filled with gaussian distributed values

static randN(dims, dtype='uint8', continuous=0) → dataObject¶

Creates a dataObject filled with Gaussian distributed random values.

The value range of the random numbers depend on the desired data type dtype:

integer types: The random values are in the range [min(dtype), max(dtype)].
floating point types: The random values are in the range [0, 1).
rgba32: All colours as well as the alpha value is independently distributed in the range [0, 255].
complex types: Both the real as well as imaginary part is independently distributed in the range [0, 1).

The mean m and standard deviation s of the Gaussian distribution is as follows:

For integer and rgba32 types holds: m = (min + max) / 2.0 and s = (max - min) / 6.0.
For all floating point types holds: m = 0.0 and s = 1/3.

Parameters

dimstuple of int or list of int: dims is the shape of the new dataObject. The length of this list or tuple defines the number of dimensions, e.g. [2, 3] creates a 2D dataObject with two rows and three columns.
dtypestr, optional: The desired data type for the elements in the returned dataObject. Possible values are: int8, uint8, …, int32, float32, float64, complex64, complex128, rgba32.
continuousint, optional: This value defines if the planes (each sub-array of the last two dimensions) are continuously allocated in memory (1) or distributed in various smaller junks (0, default). The latter is recommended for huge, n-dimensional matrices. This argument is only considered for len(dims) > 2.

Returns

arraydataObject: The newly created dataObject of shape dims and data type dtype, filled with random numbers.

See also

rand: method for creating a matrix filled with unformly distributed values

reshape(shape) → dataObject¶

Returns a reshaped (shallow) copy of this dataObject.

Reshaping means, that the shape (and optionally number of dimensions) of a dataObject might be changed, unless the total number of elements is not changed. The reshaped and returned dataObject has the same data type and data than this dataObject.

The shape of the returned object corresponds to the parameter shape. If the last two dimensions of shape and of this object are equal 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). Copying the axis meta information is stopped after the first axis with a differing new size.

Parameters

shapesequence of int: New shape of the returned object. A minimal size of this list or tuple is two.

Returns

reshapeddataObject: The reshaped data object.

Notes

This method is similar to numpy.reshape().

setAxisDescription(axisNum, axisDescription)¶

Sets the axis description of one axis.

Each axis in the data object can get a specific description string (e.g. ‘x-axis’).

Parameters

axisNumint: The axis index in the range [0, n), where n is the dimension of this dataObject.
axisDescriptionstr: New axis description.

Raises

RuntimeError: if the given axisNum is out of range

See also

axisDescriptions: this attribute can directly be used to get or set the axis description(s) of single or all axes

setAxisOffset(axisNum, axisOffset)¶

Sets the offset value of one specific axis of this dataObject.

Each axis in the data object can get a specific offset value, given in pixels. The offset value for one axis can be set by this method. Getting or setting single or all offset values for all axis can also be achieved by the attribute axisOffsets.

The conversion between physical and pixel units is:

physical_value = (pixel_value - axisOffset) * axisScale

Parameters

axisNumint: The axis index in the range [0, n), where n is the dimension of this dataObject.
axisOffsetfloat: New axis offset value in pixels.

Raises

RuntimeError: if the given axisNum is out of range.

See also

axisOffsets: this attribute can directly be used to get or set the axis offset(s) of single or all axes

setAxisScale(axisNum, axisScale)¶

Sets the scaling value of one specific axis of this dataObject.

Each axis in the data object can get a specific scale value, given in axisUnits per pixels. The scale value for one axis can be set by this method. Getting or setting single or all scaling values for all axis can also be achieved by the attribute axisScales.

The conversion between physical and pixel units is:

physical_value = (pixel_value - axisOffset) * axisScale

Parameters

axisNumint: The axis index in the range [0, n), where n is the dimension of this dataObject.
axisScalefloat: New scale value for this axis in [unit/px].

Raises

RuntimeError: if the given axisNum is out of range.

See also

axisScales: this attribute can directly be used to get or set the axis scale(s) of single or all axes

setAxisUnit(axisNum, axisUnit)¶

Sets the unit of the specified axis.

Each axis in the data object can get a specific unit string (e.g. ‘mm’).

Parameters

axisNumint: The axis index in the range [0, n), where n is the dimension of this dataObject.
axisUnitstr: New axis unit.

Raises

RuntimeError: if the given axisNum is out of range.

See also

axisUnits: this attribute can directly be used to get or set the axis unit(s) of single or all axes

setTag(key, value)¶

Set the value of a tag with the given key name.

If a tag with the given key exists, its value is overwritten. Else, a tag with that key is added to the tags.

Parameters

keystr: the name of the tag.
tagvaluestr or float: The new value of the tag. Must be a str or a float value.

Notes

Do NOT use ‘special character’ within the tag key because they are not XML-save.

size(axisIndex=None) → Union[int, Tuple[int]]¶

Returns the size of the selected axis of this dataObject or the entire shape tuple, if no specific axis is given.

Parameters

axisIndexint, optional: If axisIndex is given, only the size of the indicated axis is returned as single number.

Returns

int or tuple of int: A tuple containing the sizes of all dimensions or one single size value if axisIndex is given.

Raises

DeprecatedWarning: This method is deprecated. For a more consistent syntax with numpy.ndarray objects, use shape instead.

See also

shape: the read-only attribute shape is equal to size().

splitColor(color, destinationType='uint8') → dataObject¶

Splits selected color channels from this coloured rgba32 dataObject.

A rgba32 coloured dataObject contains color values for each item. Each color value contains a red, green, blue and alpha (transparancy) component (uint8 each). This method allows extracting one or several of these components from this dataObject. These components are then returned in single slices of a new, first axis of the returned dataObject.

The returned dataObject has one axis more than this object. This new axis is prepended to the existing axes, that have the same shape than this object. The data type of the returned object is destinationType.

The size of the first, new axis is equal to the number of letters in color. Each letter must be one of the characters b, r, g or a, that stand for the available channels of the color, that can be extracted.

Example:

color = dataObject.zeros([20, 10], 'rgba32') 
split_colors = color.splitColor("rgb") 
print(split_colors.shape, split_colors.dtype) 
# printout: [3, 20, 10], "uint8" 

In this example, the shape of split_colors is [3, 20, 10], since three channels (red, green and blue) should have been splitted, such that split_colors[0, :, :] contains the red component, etc.

Parameters

colorstr: Desired color string, that indicates the type and order of extracted color components. This string can consist of the following letters: ('b', 'r', 'g', 'a'). It is possible to combine different channels, like "arg" which extracts the alpha channel, followed by red and gree.
destinationType{“uint8”, “int8”, “uint16”, “int16”, “int32”, “float32”, “float64”}, optional: Desired data type of the returned dataObject (only real value data types allowed).

Returns

dataObject: containing the selected channel values

Raises

TypeError: if this dataObject is no rgba32 object or if destinationType is no real data type.

squeeze() → dataObject¶

Returns 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 sub-arrays, spanned by the last two dimensions (denoted as planes), are not affected by the squeeze operation and if the data block in the dataObject is not continuous. Else a deep copy has to be returned due to an overall re-alignment of the matrix. The returned object can never have less than two dimensions. If this is the case, the last or second to last dimensions with a size of 1 is not deleted. If :this method returns a shallow copy, a change in a value will change the same value in the original object, too.

Returns

squeezeddataObject: The squeezed data object.

Notes

This method is similar to numpy.squeeze().

toGray(destinationType='uint8') → dataObject¶

Converts this rgba32 coloured dataObject into a gray-scale dataObject.

The returned dataObject has the same size than this dataObject and the real-value data type, that is given by destinationType. The pixel-wise conversion is done using the formula:

Parameters

destinationType{“uint8”, “int8”, “uint16”, “int16”, “int32”, “float32”, “float64”}, optional: Desired data type of the returned dataObject (only real value data types allowed).

Returns

graydataObject: converted gray-scale data object of desired type.

Raises

TypeError: if this dataObject is no rgba32 object or if the destinationType is invalid.

toNumpyColor(addAlphaChannel=0) → np.ndarray¶

Converts a 2D dataObject of type rgba32 to a 3D numpy.ndarray of type uint8.

Many Python packages, e.g. OpenCV (cv2) or PIL store coloured array such that the color components are stored in an additional axis, which is the last axis of all axes. Hence, there is no specific rgba2 data type for numpy.ndarray, like it is the case for dataObject.

This method converts a coloured dataObject of dtype rgba32 to a compatible numpy.ndarray, where the color components are stored in an additional last axis. The size of this last axis is either 3 if addAlphaChannel = 0 or 4 otherwise. The order of this last axis is blue, green, red and optional alpha. The remaining first axes of the returned object have the same shape than this dataObject.

Parameters

addAlphaChannelint, optional: If 0, the last dimension of the returned numpy.ndarray has a size of 3 and contains the blue, green and red value, whereas 1 adds the alpha value as fourth value.

Returns

arrnumpy.ndarray: The 3D numpy.ndarray of dtype uint8. The shape is [*obj.shape, 3] or [*obj.shape, 4], depending on addAlphaChannel, where obj is this dataObject.

tolist() → list¶

Returns a nested list with all values of this dataObject.

An empty dataObject with zero dimensions will return an empty list. Else, the depth of the nested list corresponds to the number of dimensions of this dataObject. The innermost level corresponds to one row of this dataObject, or in general, to one set of values along the last axis of this object. This innermost list contains all these values.

Returns

list: Nested list with values of data object. The data types depend on the dtype of this dataObject and can be int, float, complex or rgba.

trans() → dataObject¶

Returns the (plane-wise) 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. The shape of the returned dataObject is then equal to the shape of this dataObject, but the last two values in the shape tuple are swapped.

Returns

dataObject: A copy of this dataObject is returned where every plane is its transposed plane.

See also

T: this method is equal to the attribute dataObject.T.

static zeros()¶

dims, dtype= “uint8”, continuous = 0) -> dataObject

Creates a dataObject filled with zeros.

Parameters

dimstuple of int or list of int: dims is the shape of the new dataObject. The length of this list or tuple defines the number of dimensions, e.g. [2, 3] creates a 2D dataObject with two rows and three columns.
dtypestr, optional: The desired data type for the elements in the returned dataObject. Possible values are: int8, uint8, …, int32, float32, float64, complex64, complex128, rgba32.
continuousint, optional: This value defines if the planes (each sub-array of the last two dimensions) are continuously allocated in memory (1) or distributed in various smaller junks (0, default). The latter is recommended for huge, n-dimensional matrices. This argument is only considered for len(dims) > 2.

Returns

arraydataObject: The newly created dataObject of shape dims and data type dtype, filled with zeros.

See also

eye: method for creating an eye matrix
ones: method for creating a matrix filled with ones

Notes

For the color data type rgba32, every value will be black and transparent: (r=0, g=0, b=0, alpha=0).

T¶

dataObject : Returns a copy of this dataObject where the two last dimensions are swapped.

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. The shape of the returned dataObject is then equal to the shape of this dataObject, but the last two values in the shape tuple are swapped.

This attribute was added with itom 5.0.

See also

trans: This method is equal to the method dataObject.trans().

axisDescriptions¶

tuple of str : Gets or sets the optional description of each axis.

This tuple contains the description of each axis. The length of this tuple is equal to the number of dimensions of the dataObject.

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.

axisOffsets¶

tuple of float : Gets or sets the optional offset values for each axis [px].

This attribute gives access to the internal axis offsets [px] expressed as a tuple of float values. The i-th value in the tuple corresponds to the pixel-offset of the i-th 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 = (px-Coordinate - offset)* scale

If the data object is plot with offsets != 0, the scaled (physical) units are displayed in the plot.

See also

setAxisOffset: Alternative method to set the offset value of one single axis

axisScales¶

tuple of float : Gets or sets the optional scale values for each axis [unit/px].

This attribute gives access to the internal axis scales [unit/px] expressed as a tuple of float values. The i-th value in the tuple corresponds to the scaling factor of the i-th 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 = (px-Coordinate - offset)* scale

If the data object is plot with scalings != 1, the scaled (physical) units are displayed in the plot.

See also

setAxisScale: Alternative method to set the scale value of one single axis

axisUnits¶

tuple of str : Gets or sets the optional unit value of each axis.

This tuple contains the unit value of each axis. The length of this tuple is equal to the number of dimensions of the dataObject.

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

setAxisDescriptions: alternative method to change the description string of one single axis.

base¶: None or dataObject or np.ndarray : Optional base object, this object shares its memory with (read-only).

continuous¶

bool : Returns True if this dataObject is continuous, otherwise 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.

dims¶: int : Gets the number of dimensions of this data object.

dtype¶

str : Gets the data type name of the values in this dataObject.

This type string has one of these values: uint8, int8, uint16, int16, int32, float32, float64, complex64, complex128, rgba32, datetime or timedelta.

imag¶

dataObject : Gets or sets the imag part of this complex64 or complex128 object.

The imaginary part object has the same shape than this dataObject. If the data type of this object is complex64, the imag part object has the data type float32. For a complex128 object, the imag part is float64.

If an imaginary part object is set to this attribute, it can be either a numpy.ndarray or a dataObject with the same shape than this object and the appropriate data type. However, it is also possible to pass an int or float value. This value is then assigned to the imaginary part of all complex values.

Raises

TypeError: if this dataObject has no complex data type.

metaDict¶

dict : Gets or sets a dictionary with all meta information of this dataObject.

The dictionary contains the following key-value-pairs. If a new dictionary is set to this attribute, all these values must be contained in the dict:

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.

This attribute was read-only until itom 4.0. It is settable from itom 4.1 on.

See also

addToProtocol, axisOffsets, axisScales, axisUnits, axisDescriptions
valueUnit, valueDescription, tags

ndim¶: int : Gets the number of dimensions of this data object.

real¶

dataObject : Gets or sets the real part of this complex64 or complex128 object.

The real part object has the same shape than this dataObject. If the data type of this object is complex64, the real part object has the data type float32. For a complex128 object, the real part is float64.

If a real part object is set to this attribute, it can be either a numpy.ndarray or a dataObject with the same shape than this object and the appropriate data type. However, it is also possible to pass an int or float value. This value is then assigned to the real part of all complex values.

Raises

TypeError: if this dataObject has no complex data type.

shape¶

tuple of int : Gets the shape of this data object.

The shape is a tuple where each element is the size of one dimension of this dataObject. As an example shape = [2, 3] corresponds to a 2 x 3 dataObject.

See also

size: Alternative method to return the size of all or any specific axis

Notes

In difference to the shape attribute of numpy.ndarray, this attribute cannot be set.

tags¶

types.MappingProxyType : Gets or sets a dictionary with tags of this data object.

This attribute returns a dict_proxy object of the tag dictionary of this data object. This object is read-only. 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 str or a float value.

Special tags are the key protocol that contains the newline-separated 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() or you can delete tags using deleteTag().

Do NOT use special character within the tag key because they are not XML-save.

value¶

tuple : Gets or sets the values of this dataObject, defined as flattened tuple

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 (row-wise). The values in the tuple depend on the dtype of this dataObject and can be int, float, complex, rgba, datetime.datetime or datetime.timedelta. Analog to this, pass a new tuple of number values and the correct size to change the values of this dataObject. The size and shape of the object cannot be changed.

Currently, the setter is only implemented for scalar number types.

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 addressed with b[idx].

valueDescription¶

str : Gets or sets the description of the values of the dataObject.

The value description is considered if the dataObject is plotted.

valueOffset¶: float : Gets the offset value for the values. This value is always 0.0.

valueScale¶: float : Gets the scaling factor for the values. This value is always 1.0.

valueUnit¶

str : Gets or sets the unit of the values of the dataObject.

The value unit is considered if the dataObject is plotted.

xyRotationalMatrix¶

list of list of float : Gets or sets the 3x3 rotation matrix of this dataObject.

This rotation matrix is part of the meta information section and is not used for any other purposes.

The rotation matrix is given as nested list of three elements. Each element is another list of three float values and correspond to one row in the 3 x 3 rotation matrix.