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()
orrandN()
(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. Ifdims
is not given, an empty data object is created.- dtype
str
,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’.
- continuous
int
,optional
The last two dimensions of a dataObject are always stored as continuous junk of memory, denoted as plane. If
continuous
is set to1
, even a dataObject with a dimensionn > 2
will allocate one big block of memory and continuously stores the matrix data there. Ifcontinuous
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.- data
int
orfloat
orcomplex
orrgba
ordatetime.datetime
ordatetime.timedelta
or sequenceof
int
or sequenceof
float
or sequenceof
complex
ordataObject
ornp.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).
- dimssequence
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 ofA
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 aTypeError
for argba32
data type.- Returns
- absObj
dataObject
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.
- absObj
- 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 keyprotocol
.- Parameters
- newLine
str
The text to be added to the protocol.
- newLine
- 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 inorg
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
, wherendim
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 tod[2, 1]
and its shape is(3, 2)
.- Parameters
- offsets
list
of
int
ortuple
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.
- offsets
- 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
orcomplex64
). The output data type will be float then (float64
orfloat32
).- Returns
- argObj
dataObject
is the argument function applied to all values of this dataObject.
- argObj
- astype(typestring) dataObject ¶
Converts this dataObject to another data type.
Converts this
dataObject
to a new dataObject with another data type, given by the stringtypestring
(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
- typestring
str
Type string indicating the new type (
uint8
, …,float32
, …,complex128
).
- typestring
- 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
isTrue
, 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].
- regionOnlybool,
- Returns
dataObject
Deep copy of this dataObject.
See also
- 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
andaxisOffsets
)axis descriptions and units (see
axisDescriptions
andaxisUnits
)
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
- sourceObj
dataObject
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 ofsourceObj
.
- 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 typeuint8
. All pixels in this object, that are contained in any of the givenshape
will be set to255
in the returned array, otherwise0
.New in itom 5.0: always return a 2d dataObject (see return value below)
- Parameters
- shapes
shape
orlist
of
shape
ortuple
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 to0
(instead of255
) and all other values are set to255
(instead of0
). The default isFalse
(masked =255
).
- shapes
- Returns
- mask
dataObject
uint8
dataObject
mask (0: not contained, else: contained) whose shape is equal to the last two dimensions of this object. The tagsaxisScales
,axisOffsets
,axisDescriptions
andaxisUnits
are accordingly copied from the last two axes of this object.
- mask
- data()¶
Prints the content of the dataObject to the command line in a readable form.
- div(otherObj) dataObject ¶
Returns the result of the element-wise division of this dataObject by otherObj.
This
dataObject
andotherObj
must have the sameshape
anddtype
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
- otherObj
dataObject
The returned
dataObject
contains the result of the element-wise division of all values in this object byotherObj
. Must have the same shape and data type than this object.
- otherObj
- Returns
- result
dataObject
Resulting divided data object. Values, that exceed the range of the current data type, will be set to the
result modulo max(dtype)
.
- result
- 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 inputobjects
. The returned 3DdataObject
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
- objects
list
of
dataObject
ortuple
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 firstdataObject
inobjects
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 values1.0
and0.0
respectively.
- objects
- Returns
- stack
dataObject
If
objects
is an empty list or tuple, an emptydataObject
is returned. Else ifobjects
only contains one array, this array is returned. Otherwise, all dataObjects (2D or 3D) inobjects
are vertically stacked along the first axis, which is prepended to the existing axes before.
- stack
- 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 returnsTrue
if such a tag exists, elseFalse
.
- 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
. Fordtype == rgba32
, the diagonal values arer = 0, g = 0, b = 1, alpha = 0
.- Parameters
- size
int
The size of the squared matrix (single integer value).
- dtype
str
,optional
The desired data type for the elements in the returned
dataObject
. Possible values are:int8
,uint8
, …,int32
,float32
,float64
,complex64
,complex128
,rgba32
.
- size
- Returns
- eyeMatrix
dataObject
The created eye-matrix as
size x size
dataObject
.
- eyeMatrix
- 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 typergba32
from a three-dimensional,uint8
numpy.ndarray`
. Thisarray
must have the shapeM x N x 3
orM x N x 4
. Each vectorarray[i, j, :]
is then used to create onergba32
value in the returneddataObject
. The meaning of this vector is:(blue, green, red) if
array
consists of three channels (last dimension). Thergba32
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)
orPIL
to dataObjects.- Parameters
- array
numpy.ndarray
M x N x 3
orM x N x 4
, uint8numpy.ndarray
- array
- Returns
dataObject
Coloured dataObject of shape
M x N
and data typergba32
.
- 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
- length
int
Size of the tag dictionary. The optional protocol also counts as one item.
- length
- 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 newdataObject
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
- Returns
- lineCut
dataObject
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 thisdataObject
has two dimensions,P = 1
, elseP
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.
- lineCut
- 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 inorg
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 are0
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 contains0
everyhwere.The output of the example above would be:
print(roi.locateROI()) # >>> ([100, 200], [10, 5])
- Returns
- orgSize
list
of
int
The original sizes of this object (without ROI). This is equal to
shape
of the original object.- offsets
list
of
int
A list with
N
values, whereN
is the number of dimensions of this object. Each valuen = 1 .. N
is the offset of the first value of axisn
in this object with respect to the original object.
- orgSize
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
andotherObj
must have the sameshape
anddtype
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
- otherObj
dataObject
The returned
dataObject
contains the result of the element-wise multiplication of all values in this object andotherObj
. Must have the same shape and data type than this object.
- otherObj
- Returns
- result
dataObject
Resulting multiplied data object. Values, that exceed the range of the current data type, will be set to the
result modulo max(dtype)
.
- result
Notes
For a mathematical multiplication see the @-operator.
- static nans(dims, dtype='float32', continuous=0) dataObject ¶
Creates a floating-point dataObject filled with
NaN
values.- Parameters
- dims
tuple
of
int
orlist
of
int
dims
is the shape of the newdataObject
. 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.- dtype
str
,optional
The desired data type for the elements in the returned
dataObject
. Possible values are:float32
,float64
,complex64
,complex128
.- continuous
int
,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 forlen(dims) > 2
.
- dims
- Returns
- array
dataObject
The newly created dataObject of shape
dims
and data typedtype
, filled withNaN
.
- array
- 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 parametertypestring
). Per default, no such a type conversion is done (emptytypestring
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
- Returns
- normalized
dataObject
normalized data object
- normalized
- Raises
RuntimeError
if a
DateTime
orTimeDelta
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
- dims
tuple
of
int
orlist
of
int
dims
is the shape of the newdataObject
. 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.- dtype
str
,optional
The desired data type for the elements in the returned
dataObject
. Possible values are:int8
,uint8
, …,int32
,float32
,float64
,complex64
,complex128
,rgba32
.- continuous
int
,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 forlen(dims) > 2
.
- dims
- Returns
- array
dataObject
The newly created dataObject of shape
dims
and data typedtype
, filled with ones.
- array
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
- values
float
or sequenceof
float
One single physical coordinate or a tuple of physical coordinates.
- axes
int
or sequenceof
int
,optional
If
values
is a single value, axes must beNone
or one integer, that defines the axis for which the transformation should be calculated. Ifvalues
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 theaxes
tuple. Each value is then transformed with the corresponding value inaxes
. IfNone
is given,axes
is assumed to be an ascending list of values0, 1, 2, ...
.
- values
- Returns
- 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
- values
float
or sequenceof
float
One single pixel coordinate or a tuple of pixel coordinates.
- axes
int
or sequenceof
int
,optional
If
values
is a single value, axes must beNone
or one integer, that defines the axis for which the transformation should be calculated. Ifvalues
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 theaxes
tuple. Each value is then transformed with the corresponding value inaxes
. IfNone
is given,axes
is assumed to be an ascending list of values0, 1, 2, ...
.
- values
- Returns
- 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
- dims
tuple
of
int
orlist
of
int
dims
is the shape of the newdataObject
. 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.- dtype
str
,optional
The desired data type for the elements in the returned
dataObject
. Possible values are:int8
,uint8
, …,int32
,float32
,float64
,complex64
,complex128
,rgba32
.- continuous
int
,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 forlen(dims) > 2
.
- dims
- Returns
- array
dataObject
The newly created dataObject of shape
dims
and data typedtype
, filled with random numbers.
- array
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 deviations
of the Gaussian distribution is as follows:For integer and rgba32 types holds:
m = (min + max) / 2.0
ands = (max - min) / 6.0
.For all floating point types holds:
m = 0.0
ands = 1/3
.
- Parameters
- dims
tuple
of
int
orlist
of
int
dims
is the shape of the newdataObject
. 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.- dtype
str
,optional
The desired data type for the elements in the returned
dataObject
. Possible values are:int8
,uint8
, …,int32
,float32
,float64
,complex64
,complex128
,rgba32
.- continuous
int
,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 forlen(dims) > 2
.
- dims
- Returns
- array
dataObject
The newly created dataObject of shape
dims
and data typedtype
, filled with random numbers.
- array
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 returneddataObject
has the same data type and data than thisdataObject
.The shape of the returned object corresponds to the parameter
shape
. If the last two dimensions ofshape
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
- Returns
- reshaped
dataObject
The reshaped data object.
- reshaped
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
- 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
- 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 attributeaxisScales
.The conversion between physical and pixel units is:
physical_value = (pixel_value - axisOffset) * axisScale
- Parameters
- 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
- 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 givenkey
name.If a tag with the given
key
exists, its value is overwritten. Else, a tag with thatkey
is added to the tags.- Parameters
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
- axisIndex
int
,optional
If
axisIndex
is given, only the size of the indicated axis is returned as single number.
- axisIndex
- Returns
- Raises
DeprecatedWarning
This method is deprecated. For a more consistent syntax with
numpy.ndarray
objects, useshape
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
coloureddataObject
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 isdestinationType
.The size of the first, new axis is equal to the number of letters in
color
. Each letter must be one of the charactersb
,r
,g
ora
, 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
ofsplit_colors
is[3, 20, 10]
, since three channels (red, green and blue) should have been splitted, such thatsplit_colors[0, :, :]
contains the red component, etc.- Parameters
- color
str
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).
- color
- Returns
dataObject
containing the selected channel values
- Raises
TypeError
if this
dataObject
is norgba32
object or ifdestinationType
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 thedataObject
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 of1
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
- squeezed
dataObject
The squeezed data object.
- squeezed
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 thisdataObject
and the real-value data type, that is given bydestinationType
. 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).
- destinationType{“uint8”, “int8”, “uint16”, “int16”, “int32”, “float32”, “float64”},
- Returns
- gray
dataObject
converted gray-scale data object of desired type.
- gray
- Raises
TypeError
if this dataObject is no
rgba32
object or if thedestinationType
is invalid.
- toNumpyColor(addAlphaChannel=0) np.ndarray ¶
Converts a 2D dataObject of type
rgba32
to a 3D numpy.ndarray of typeuint8
.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 fornumpy.ndarray
, like it is the case fordataObject
.This method converts a coloured
dataObject
of dtypergba32
to a compatiblenumpy.ndarray
, where the color components are stored in an additional last axis. The size of this last axis is either3
ifaddAlphaChannel = 0
or4
otherwise. The order of this last axis isblue
,green
,red
and optionalalpha
. The remaining first axes of the returned object have the same shape than this dataObject.- Parameters
- addAlphaChannel
int
,optional
If
0
, the last dimension of the returnednumpy.ndarray
has a size of3
and contains the blue, green and red value, whereas1
adds the alpha value as fourth value.
- addAlphaChannel
- Returns
- arr
numpy.ndarray
The 3D
numpy.ndarray
of dtypeuint8
. The shape is[*obj.shape, 3]
or[*obj.shape, 4]
, depending onaddAlphaChannel
, whereobj
is thisdataObject
.
- arr
- 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 thisdataObject
. The innermost level corresponds to onerow
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.
- 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 theshape
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
- dims
tuple
of
int
orlist
of
int
dims
is the shape of the newdataObject
. 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.- dtype
str
,optional
The desired data type for the elements in the returned
dataObject
. Possible values are:int8
,uint8
, …,int32
,float32
,float64
,complex64
,complex128
,rgba32
.- continuous
int
,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 forlen(dims) > 2
.
- dims
- Returns
- array
dataObject
The newly created dataObject of shape
dims
and data typedtype
, filled with zeros.
- array
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 theshape
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
offloat
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
offloat
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
ornp.ndarray
: Optional base object, this object shares its memory with (read-only).
- continuous¶
bool
: ReturnsTrue
if this dataObject is continuous, otherwiseFalse
.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.
- 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
ortimedelta
.
- imag¶
dataObject
: Gets or sets theimag
part of thiscomplex64
orcomplex128
object.The imaginary part object has the same shape than this
dataObject
. If the data type of this object iscomplex64
, the imag part object has the data typefloat32
. For acomplex128
object, the imag part isfloat64
.If an imaginary part object is set to this attribute, it can be either a
numpy.ndarray
or adataObject
with the same shape than this object and the appropriate data type. However, it is also possible to pass anint
orfloat
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
- real¶
dataObject
: Gets or sets thereal
part of thiscomplex64
orcomplex128
object.The real part object has the same shape than this
dataObject
. If the data type of this object iscomplex64
, the real part object has the data typefloat32
. For acomplex128
object, the real part isfloat64
.If a real part object is set to this attribute, it can be either a
numpy.ndarray
or adataObject
with the same shape than this object and the appropriate data type. However, it is also possible to pass anint
orfloat
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 a2 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 astr
or afloat
value.Special tags are the key
protocol
that contains the newline-separated protocol string of the data object (see:addToProtocol()
) or the keytitle
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 usingdeleteTag()
.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 tupleIf 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 beint
,float
,complex
,rgba
,datetime.datetime
ordatetime.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.
- 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.