9.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 fixed-size items with corresponding meta information (units, axes descriptions, scalings, tags, protocol…). Recently the following data types (dtype) are supported:

  • Integer-type (int8, uint8, int16, uint16, int32),

  • Floating-type (float32, float64 (=> double)),

  • Complex-type (complex64 (2x float32), complex128 (2x float64)).

  • Color-type (rgba32 (uint32 or uint[4] containing the four 8bit values [R, G, B, Alpha])).

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

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’,’float32’,’float64’,’complex64’,’complex128’, ‘rgba32’.

continuous : {int}, optional

‘continuous’ [0|1] defines whether the data block should be continuously allocated in memory [1] or in different smaller blocks [0] (recommended for huge matrices).

data : {int, float, complex, sequence of numbers, array-like object}, optional

If ‘data’ is a single number, all values in the dataObject are set to this 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, zeros, nans, rand, randN

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 is parsable 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() → 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

adjugate() → returns the plane-wise 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 plane-wise, 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

adj

adjustROI(offsets) → 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

offsets : {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

locateROI

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}

type-converted data object

Notes

This method mainly uses the method convertTo of OpenCV.

conj() → complex-conjugates all elements of this dataObject (inline).

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

Raises

TypeError : :

if data type of this data object is not complex.

See also

conjugate

conjugate() → return a copy of this dataObject where every element is complex-conjugated.
Returns

out : {dataObject}

element-wise complex conjugate of this data object

Raises

TypeError : :

if data type of this data object is not complex.

See also

conj

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 vice-versa.

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) → return a 3d dataObject with stacked arrays in sequence depth wise (along first axis).

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. This 3d dataObject contain 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

objects : {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).

Returns :

——- :

dataObj : {dataObject}

If objects only contains one array, this array is returned. If objects contains more than one array, these arrays are vertically stacked along the first axis, which is prepended to the existing axes before.

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, eye-matrix.

Static method for creating a two-dimensional, square, eye-matrix 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’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’

Returns

I : {dataObject} of shape (size,size)

An array where all elements are equal to zero, except for the ‘k-th diagonal, whose values are equal to one.

See also

ones

method for creating a matrix filled with ones

zeros

method for creating a matrix filled with zeros

static fromNumpyColor(array) → creates a rgba32 dataObject from a three-dimensional numpy array whose liast dimension has the size 3 or 4.

Static method for creating a two-dimensional dataObject of type ‘rgba32’ from a three-dimensional 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.

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 floating-point 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 zero-vector.

See also

adjustROI

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 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

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 element-wisely 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)
static nans(dims, dtype='float32', continuous=0) → creates new dataObject filled with NaNs.

Static method for creating a new n-dimensional itom.dataObject with given number of dimensions and dtype, filled with NaNs.

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: ‘float32’, ‘float64’, ‘complex64’, ‘complex128’

continuous : {int}, optional

‘continuous’ [0|1] 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 NaNs.

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='') → 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 n-dimensional 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’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’

continuous : {int}, optional

‘continuous’ [0|1] 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.

See also

eye

method for creating an eye matrix

zeros

method for creating a matrix filled with zeros

Notes

For color-types (rgba32) every item / cell will be white: [r=255 g=255 b=255 a=255].

physToPix(values, axes=0) → 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, float-tuple}

One single physical coordinate or a tuple of physical coordinates.

axes : {int, int-tuple}, 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 float-tuple 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=0) → 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, float-tuple}

One single pixel coordinate or a tuple of pixel coordinates.

axes : {int, int-tuple}, 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 float-tuple 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’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’

continuous : {int}, optional

‘continuous’ [0|1] 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 (max-min/)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’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’

continuous : {int}, optional

‘continuous’ [0|1] 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

reshape(shape) → 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

shape : {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 (px-Coordinate - 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 XML-save.

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 read-only 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 deep-copy 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 gray-scale object

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

destinationType : {str}

Type string indicating the new real type (‘uint8’,…’float32’,’float64’ - no complex)

Returns

dataObj : {dataObject}

converted gray-scale 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 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.

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 n-dimensional 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’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’

continuous : {int}, optional

‘continuous’ [0|1] 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.

See also

eye

method for creating an eye matrix

ones

method for creating a matrix filled with ones

Notes

For color-types (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 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

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 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

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

read-only

dims

number of dimensions of this data object

Notes

read-only 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’, ‘int32’, ‘float32’, ‘float64’, ‘complex64’, ‘complex128’, ‘rgba32’

Notes

This attribute is read-only

imag

imag -> return a new data object with the imaginary part of the source or set the values of the imaginary part of the data object.

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).

This method also changes the real part of the complex data object. In the case of a complex128 data object type, the input must be float64. In the case of a complex64 data object type, the input must be float32. The input can be a data object or numpy.array of the same shape as the data object. If a scalar of an integer or float datatype is given, all real values will be changed to this value.

Parameters

value : {numpy.array, dataObject, int, float32, float64}

Input value (‘float32’, ‘float64’)

Returns

res : {dataObject}

output dataObject of same shape and same type with changed imaginary part of complex object.

Notes

read / write

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

read-only property, this property is readable both by the attributes ndim and dims.

real

real -> return a new data object with the real part of the source or set the values of the real part of the data object.

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).

This method also changes the real part of the complex data object. In the case of a complex128 data object type, the input must be float64. In the case of a complex64 data object type, the input must be float32. The input can be a data object or numpy.array of the same shape as the data object. If a scalar of an integer or float datatype is given, all real values will be changed to this value.

Parameters

value : {numpy.array, dataObject, int, float32, float64}

Input value (‘float32’, ‘float64’)

Returns

res : {dataObject}

output dataObject of same shape and same type with changed real part of complex object.

Notes

read / write

shape

tuple with the sizes of each dimension / axis of this data object.

See also

size

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). Read-only.

tags

tag dictionary 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 string or a double 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(key,value) or you can delete tags using deleteTag(key).

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

Notes

read-only / write only for fully new dictionary

value

get/set the values within the ROI as a one-dimensional 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 (row-wise). 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 metaData-Tagspace. The getter method retuns a 3x3-Array deep copied from the internal matrix, Implemented to offer compability to x3p format.

Notes

{3x3 array of doubles} : ReadWrite