Object model (`cdl.obj`)#

The cdl.obj module aims at providing all the necessary classes and functions to create and manipulate DataLab signal and image objects.

Those classes and functions are defined in other modules:

cdl.core.model.base
cdl.core.model.image
cdl.core.model.signal
cdl.core.io

The cdl.obj module is thus a convenient way to import all the objects at once. As a matter of fact, the following import statement is equivalent to the previous one:

# Original import statement
from cdl.core.model.signal import SignalObj
from cdl.core.model.image import ImageObj

# Equivalent import statement
from cdl.obj import SignalObj, ImageObj

Common objects#

class cdl.obj.ResultProperties(title: str, array: ndarray, labels: list[str] | None, item_json: str = '')[source]#

Object representing properties serializable in signal/image metadata.

Result array is a NumPy 2-D array: each row is a list of properties, optionnally associated to a ROI (first column value).

ROI index is starting at 0 (or is simply 0 if there is no ROI).

Parameters:

title – properties title
array – properties array
labels – properties labels (one label per column of result array)
item_json – JSON string of label item associated to this obj

Note

The array argument can be a list of lists or a NumPy array. For instance, the following are equivalent:

array = [[1, 2], [3, 4]]
array = np.array([[1, 2], [3, 4]])

Or for only one line (one single result), the following are equivalent:

array = [1, 2]
array = [[1, 2]]
array = np.array([[1, 2]])

property category: str#: Return result category

property headers: list[str] | None#: Return result headers (one header per column of result array)

property shown_array: ndarray#

Return array of shown results, i.e. including complementary array (if any)

Returns:: Array of shown results

update_obj_metadata_from_item(obj: BaseObj, item: LabelItem | None) → None[source]#

Update object metadata with label item

Parameters:

obj – object (signal/image)
item – label item

property label_contents: tuple[tuple[int, str], ...]#: Return label contents, i.e. a tuple of couples of (index, text) where index is the column of raw_data and text is the associated label format string

create_label_item(obj: BaseObj) → LabelItem | None[source]#

Create label item

Parameters:: obj – object (signal/image)
Returns:: Label item

Note

The signal or image object is required as argument to create the label item because the label text may contain format strings that need to be filled with the object properties. For instance, the label text may contain the signal or image units.

get_label_item(obj: BaseObj) → LabelItem | None[source]#

Return label item associated to this result

Parameters:: obj – object (signal/image)
Returns:: Label item

Note

The signal or image object is required as argument to eventually create the label item if it has not been created yet. See create_label_item().

class cdl.obj.ResultShape(title: str, array: ndarray, shape: Literal['rectangle', 'circle', 'ellipse', 'segment', 'marker', 'point', 'polygon'], item_json: str = '', add_label: bool = False)[source]#

Object representing a geometrical shape serializable in signal/image metadata.

Result array is a NumPy 2-D array: each row is a result, optionnally associated to a ROI (first column value).

ROI index is starting at 0 (or is simply 0 if there is no ROI).

Parameters:

title – result shape title
array – shape coordinates (multiple shapes: one shape per row), first column is ROI index (0 if there is no ROI)
shape – shape kind
item_json – JSON string of label item associated to this obj
add_label – if True, add a label item (and the geometrical shape) to plot (default to False)

Raises:

AssertionError – invalid argument

Note

The array argument can be a list of lists or a NumPy array. For instance, the following are equivalent:

array = [[1, 2], [3, 4]]
array = np.array([[1, 2], [3, 4]])

Or for only one line (one single result), the following are equivalent:

array = [1, 2]
array = [[1, 2]]
array = np.array([[1, 2]])

property category: str#: Return result category

check_array() → None[source]#

Check if array attribute is valid

Raises:: AssertionError – invalid array

property headers: list[str] | None#: Return result headers (one header per column of result array)

property shown_array: ndarray#

Return array of shown results, i.e. including complementary array (if any)

Returns:: Array of shown results

property label_contents: tuple[tuple[int, str], ...]#: Return label contents, i.e. a tuple of couples of (index, text) where index is the column of raw_data and text is the associated label format string

create_label_item(obj: BaseObj) → LabelItem | None[source]#

Create label item

Returns:: Label item

merge_with(obj: BaseObj, other_obj: BaseObj | None = None)[source]#: Merge object resultshape with another’s: obj <– other_obj or simply merge this resultshape with obj if other_obj is None

transform_coordinates(func: Callable[[ndarray], None]) → None[source]#

Transform shape coordinates.

Parameters:: func – function to transform coordinates

iterate_plot_items(fmt: str, lbl: bool, option: str) → Iterable[source]#

Iterate over metadata shape plot items.

Parameters:

fmt – numeric format (e.g. “%.3f”)
lbl – if True, show shape labels
option – shape style option (e.g. “shape/drag”)

Yields:

Plot item

Make geometrical shape plot item adapted to the shape type.

Parameters:

coords – shape data
fmt – numeric format (e.g. “%.3f”)
lbl – if True, show shape labels
option – shape style option (e.g. “shape/drag”)

Returns:

Plot item

class cdl.obj.ShapeTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Shape types for image metadata

RECTANGLE = '_rec_'#: Rectangle shape

CIRCLE = '_cir_'#: Circle shape

ELLIPSE = '_ell_'#: Ellipse shape

SEGMENT = '_seg_'#: Segment shape

MARKER = '_mar_'#: Marker shape

POINT = '_poi_'#: Point shape

POLYGON = '_pol_'#: Polygon shape

class cdl.obj.UniformRandomParam(title=None, comment=None, icon='')[source]#

Uniform-law random signal/image parameters

apply_integer_range(vmin, vmax)[source]#: Do something in case of integer min-max range

class cdl.obj.NormalRandomParam(title=None, comment=None, icon='')[source]#

Normal-law random signal/image parameters

apply_integer_range(vmin, vmax)[source]#: Do something in case of integer min-max range

class cdl.obj.BaseProcParam(title=None, comment=None, icon='')[source]#

Base class for processing parameters

apply_integer_range(vmin, vmax)[source]#: Do something in case of integer min-max range

apply_float_range(vmin, vmax)[source]#: Do something in case of float min-max range

set_from_datatype(dtype)[source]#: Set min/max range from NumPy datatype

Signal model#

class cdl.obj.SignalObj[source]#

Signal object

uuid#

Default: None.

Type:: guidata.dataset.dataitems.StringItem

xydata#

Default: None.

Type:: guidata.dataset.dataitems.FloatArrayItem

metadata#

Default: {}.

Type:: guidata.dataset.dataitems.DictItem

title#

Signal title. Default: ‘Untitled’.

Type:: guidata.dataset.dataitems.StringItem

xlabel#

Title. Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

xunit#

Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

ylabel#

Title. Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

yunit#

Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

autoscale#

Default: True.

Type:: guidata.dataset.dataitems.BoolItem

xscalelog#

Default: False.

Type:: guidata.dataset.dataitems.BoolItem

xscalemin#

Lower bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

xscalemax#

Upper bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

yscalelog#

Default: False.

Type:: guidata.dataset.dataitems.BoolItem

yscalemin#

Lower bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

yscalemax#

Upper bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

classmethod create(uuid: str, xydata: numpy.ndarray, metadata: dict, title: str, xlabel: str, xunit: str, ylabel: str, yunit: str, autoscale: bool, xscalelog: bool, xscalemin: float, xscalemax: float, yscalelog: bool, yscalemin: float, yscalemax: float) → cdl.core.model.signal.SignalObj#

Returns a new instance of SignalObj with the fields set to the given values.

Parameters:

uuid (str) – Default: None.
xydata (numpy.ndarray) – Default: None.
metadata (dict) – Default: {}.
title (str) – Signal title. Default: ‘Untitled’.
xlabel (str) – Title. Default: ‘’.
xunit (str) – Default: ‘’.
ylabel (str) – Title. Default: ‘’.
yunit (str) – Default: ‘’.
autoscale (bool) – Default: True.
xscalelog (bool) – Default: False.
xscalemin (float) – Lower bound. Default: None.
xscalemax (float) – Upper bound. Default: None.
yscalelog (bool) – Default: False.
yscalemin (float) – Lower bound. Default: None.
yscalemax (float) – Upper bound. Default: None.

Returns:

New instance of SignalObj.

regenerate_uuid()[source]#

Regenerate UUID

This method is used to regenerate UUID after loading the object from a file. This is required to avoid UUID conflicts when loading objects from file without clearing the workspace first.

copy(title: str | None = None, dtype: dtype | None = None) → SignalObj[source]#

Copy object.

Parameters:

title – title
dtype – data type

Returns:

Copied object

set_data_type(dtype: dtype) → None[source]#

Change data type.

Parameters:: type (Data) –

Set xy data

Parameters:

x – x data
y – y data
dx – dx data (optional: error bars)
dy – dy data (optional: error bars)

property x: ndarray | None#: Get x data

property y: ndarray | None#: Get y data

property data: ndarray | None#: Get y data

property dx: ndarray | None#: Get dx data

property dy: ndarray | None#: Get dy data

get_data(roi_index: int | None = None) → tuple[ndarray, ndarray][source]#

Return original data (if ROI is not defined or roi_index is None), or ROI data (if both ROI and roi_index are defined).

Parameters:: roi_index – ROI index
Returns:: Data

update_plot_item_parameters(item: CurveItem) → None[source]#

Update plot item parameters from object data/metadata

Takes into account a subset of plot item parameters. Those parameters may have been overriden by object metadata entries or other object data. The goal is to update the plot item accordingly.

This is almost the inverse operation of update_metadata_from_plot_item.

Parameters:: item – plot item

update_metadata_from_plot_item(item: CurveItem) → None[source]#

Update metadata from plot item.

Takes into account a subset of plot item parameters. Those parameters may have been modified by the user through the plot item GUI. The goal is to update the metadata accordingly.

This is almost the inverse operation of update_plot_item_parameters.

Parameters:: item – plot item

make_item(update_from: CurveItem = None) → CurveItem[source]#

Make plot item from data.

Parameters:: update_from – plot item to update from
Returns:: Plot item

update_item(item: CurveItem, data_changed: bool = True) → None[source]#

Update plot item from data.

Parameters:

item – plot item
data_changed – if True, data has changed

roi_coords_to_indexes(coords: list) → ndarray[source]#

Convert ROI coordinates to indexes.

Parameters:: coords – coordinates
Returns:: Indexes

get_roi_param(title: str, *defaults: int) → ROI1DParam[source]#

Return ROI parameters dataset (converting ROI point indexes to coordinates)

Parameters:

title – title
*defaults – default values (first, last point indexes)

Returns:

first and last X)

Return type:

ROI parameters dataset (containing the ROI coordinates

params_to_roidata(params: DataSetGroup) → ndarray[source]#

Convert ROI dataset group to ROI array data.

Parameters:: params – ROI dataset group
Returns:: ROI array data

new_roi_item(fmt: str, lbl: bool, editable: bool)[source]#

Return a new ROI item from scratch

Parameters:

fmt – format string
lbl – if True, add label
editable – if True, ROI is editable

iterate_roi_items(fmt: str, lbl: bool, editable: bool = True)[source]#

Make plot item representing a Region of Interest.

Parameters:

fmt – format string
lbl – if True, add label
editable – if True, ROI is editable

Yields:

Plot item

add_label_with_title(title: str | None = None) → None[source]#

Add label with title annotation

Parameters:: title – title (if None, use signal title)

accept(vis: object) → None#

Helper function that passes the visitor to the accept methods of all the items in this dataset

Parameters:: vis (object) – visitor object

add_annotations_from_file(filename: str) → None#

Add object annotations from file (JSON).

Parameters:: filename – filename

add_annotations_from_items(items: list) → None#

Add object annotations (annotation plot items).

Parameters:: items – annotation plot items

property annotations: str#: Get object annotations (JSON string describing annotation plot items)

check() → list[str]#

Check the dataset item values

Returns:: list of errors
Return type:: list[str]

check_data()#

Check if data is valid, raise an exception if that’s not the case

Raises:: TypeError – if data type is not supported

delete_results() → None#: Delete all object results (shapes and properties)

deserialize(reader: HDF5Reader | JSONReader | INIReader) → None#

Deserialize the dataset

Parameters:: reader (HDF5Reader | JSONReader | INIReader) – reader object

edit(parent: QWidget | None = None, apply: Callable | None = None, wordwrap: bool = True, size: QSize | tuple[int, int] | None = None) → DataSetEditDialog#

Open a dialog box to edit data set

Parameters:

parent – parent widget (default is None, meaning no parent)
apply – apply callback (default is None)
wordwrap – if True, comment text is wordwrapped
size – dialog size (QSize object or integer tuple (width, height))

get_comment() → str | None#

Return data set comment

Returns:: comment
Return type:: str | None

get_icon() → str | None#

Return data set icon

Returns:: icon
Return type:: str | None

get_items(copy=False) → list[DataItem]#

Returns all the DataItem objects from the DataSet instance. Ignore private items that have a name starting with an underscore (e.g. ‘_private_item = …’)

Parameters:

copy – If True, deepcopy the DataItem list, else return the original.
False. (Defaults to) –

Returns:

_description_

get_metadata_option(name: str) → Any#

Return metadata option value

A metadata option is a metadata entry starting with an underscore. It is a way to store application-specific options in object metadata.

Parameters:: name – option name
Returns:: Option value

Valid option names:: ‘format’: format string ‘showlabel’: show label

get_title() → str#

Return data set title

Returns:: title
Return type:: str

classmethod get_valid_dtypenames() → list[str]#

Get valid data type names

Returns:: Valid data type names supported by this class

iterate_resultproperties() → Iterable[ResultProperties]#

Iterate over object result properties.

Yields:: Result properties

iterate_resultshapes() → Iterable[ResultShape]#

Iterate over object result shapes.

Yields:: Result shape

iterate_roi_indexes()#: Iterate over object ROI indexes ([0] if there is no ROI)

iterate_shape_items(editable: bool = False)#

Iterate over computing items encoded in metadata (if any).

Parameters:: editable – if True, annotations are editable
Yields:: Plot item

property number: int#: Return object number (used for short ID)

read_config(conf: UserConfig, section: str, option: str) → None#

Read configuration from a UserConfig instance

Parameters:

conf (UserConfig) – UserConfig instance
section (str) – section name
option (str) – option name

remove_all_shapes() → None#: Remove metadata shapes and ROIs

reset_metadata_to_defaults() → None#: Reset metadata to default values

restore_attr_from_metadata(attrname: str, default: Any) → None#

Restore attribute from metadata

Parameters:

attrname – attribute name
default – default value

property roi: ndarray | None#

Return object regions of interest array (one ROI per line).

Returns:: Regions of interest array

roi_has_changed() → bool#

Return True if ROI has changed since last call to this method.

The first call to this method will return True if ROI has not yet been set, or if ROI has been set and has changed since the last call to this method. The next call to this method will always return False if ROI has not changed in the meantime.

Returns:: True if ROI has changed

roidata_to_params(roidata: ndarray | list[list[int]]) → DataSetGroup#

Convert ROI array data to ROI dataset group.

Parameters:: roidata – ROI array data (array or list of lists, floating point values are accepted and will be converted to integers)
Returns:: ROI dataset group

save_attr_to_metadata(attrname: str, new_value: Any) → None#

Save attribute to metadata

Parameters:

attrname – attribute name
new_value – new value

serialize(writer: HDF5Writer | JSONWriter | INIWriter) → None#

Serialize the dataset

Parameters:: writer (HDF5Writer | JSONWriter | INIWriter) – writer object

set_defaults() → None#: Set default values

classmethod set_global_prop(realm: str, **kwargs) → None#

Set global properties for all data items in the dataset

Parameters:

realm (str) – realm name
kwargs (dict) – properties to set

set_metadata_option(name: str, value: Any) → None#

Set metadata option value

A metadata option is a metadata entry starting with an underscore. It is a way to store application-specific options in object metadata.

Parameters:

name – option name
value – option value

Valid option names:: ‘format’: format string ‘showlabel’: show label

property short_id#: Short object ID

text_edit() → None#: Edit data set with text input only

to_string(debug: bool | None = False, indent: str | None = None, align: bool | None = False, show_hidden: bool | None = True) → str#

Return readable string representation of the data set If debug is True, add more details on data items

Parameters:

debug (bool) – if True, add more details on data items
indent (str) – indentation string (default is None, meaning no indentation)
align (bool) – if True, align data items (default is False)
show_hidden (bool) – if True, show hidden data items (default is True)

Returns:

string representation of the data set

Return type:

str

transform_shapes(orig, func, param=None)#

Apply transform function to result shape / annotations coordinates.

Parameters:

orig – original object
func – transform function
param – transform function parameter

update_metadata_view_settings() → None#: Update metadata view settings from Conf.view

update_resultshapes_from(other: BaseObj) → None#

Update geometric shape from another object (merge metadata).

Parameters:: other – other object, from which to update this object

view(parent: QWidget | None = None, wordwrap: bool = True, size: QSize | tuple[int, int] | None = None) → None#

Open a dialog box to view data set

Parameters:

parent – parent widget (default is None, meaning no parent)
wordwrap – if True, comment text is wordwrapped
size – dialog size (QSize object or integer tuple (width, height))

write_config(conf: UserConfig, section: str, option: str) → None#

Write configuration to a UserConfig instance

Parameters:

conf (UserConfig) – UserConfig instance
section (str) – section name
option (str) – option name

cdl.obj.read_signal(filename: str) → SignalObj[source]#

Read a signal from a file.

Parameters:: filename – File name.
Returns:: Signal.

cdl.obj.read_signals(filename: str) → list[SignalObj][source]#

Read a list of signals from a file.

Parameters:: filename – File name.
Returns:: List of signals.

Create a new Signal object.

Parameters:

title – signal title
x – X data
y – Y data
dx – dX data (optional: error bars)
dy – dY data (optional: error bars)
metadata – signal metadata
units – X, Y units (tuple of strings)
labels – X, Y labels (tuple of strings)

Returns:

Signal object

cdl.obj.create_signal_from_param(newparam: NewSignalParam, addparam: DataSet | None = None, edit: bool = False, parent: QWidget | None = None) → SignalObj | None[source]#

Create a new Signal object from a dialog box.

Parameters:

newparam – new signal parameters
addparam – additional parameters
edit – Open a dialog box to edit parameters (default: False)
parent – parent widget

Returns:

Signal object or None if canceled

Create a new Signal dataset instance.

Parameters:

title – dataset title (default: None, uses default title)
stype – signal type (default: None, uses default type)
xmin – X min (default: None, uses default value)
xmax – X max (default: None, uses default value)
size – signal size (default: None, uses default value)

Returns:

new signal dataset instance

Return type:

NewSignalParam

class cdl.obj.SignalTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Signal types

ZEROS = 'zeros'#: Signal filled with zeros

GAUSS = 'gaussian'#: Gaussian function

LORENTZ = 'lorentzian'#: Lorentzian function

VOIGT = 'Voigt'#: Voigt function

UNIFORMRANDOM = 'random (uniform law)'#: Random signal (uniform law)

NORMALRANDOM = 'random (normal law)'#: Random signal (normal law)

SINUS = 'sinus'#: Sinusoid

COSINUS = 'cosinus'#: Cosinusoid

SAWTOOTH = 'sawtooth'#: Sawtooth function

TRIANGLE = 'triangle'#: Triangle function

SQUARE = 'square'#: Square function

SINC = 'cardinal sine'#: Cardinal sine

STEP = 'step'#: Step function

EXPONENTIAL = 'exponential'#: Exponential function

PULSE = 'pulse'#: Pulse function

POLYNOMIAL = 'polynomial'#: Polynomial function

EXPERIMENTAL = 'experimental'#: Experimental function

class cdl.obj.NewSignalParam[source]#

New signal dataset

title#

Default: None.

Type:: guidata.dataset.dataitems.StringItem

xmin#

Default: -10.0.

Type:: guidata.dataset.dataitems.FloatItem

xmax#

Default: 10.0.

Type:: guidata.dataset.dataitems.FloatItem

size#

Signal size (total number of points). Integer higher than 1. Default: 500.

Type:: guidata.dataset.dataitems.IntItem

stype#

Single choice from: SignalTypes.ZEROS, SignalTypes.GAUSS, SignalTypes.LORENTZ, SignalTypes.VOIGT, SignalTypes.UNIFORMRANDOM, SignalTypes.NORMALRANDOM, SignalTypes.SINUS, SignalTypes.COSINUS, SignalTypes.SAWTOOTH, SignalTypes.TRIANGLE, SignalTypes.SQUARE, SignalTypes.SINC, SignalTypes.STEP, SignalTypes.EXPONENTIAL, SignalTypes.PULSE, SignalTypes.POLYNOMIAL, SignalTypes.EXPERIMENTAL. Default: SignalTypes.ZEROS.

Type:: guidata.dataset.dataitems.ChoiceItem

classmethod create(title: str, xmin: float, xmax: float, size: int, stype: cdl.core.model.signal.SignalTypes) → cdl.core.model.signal.NewSignalParam#

Returns a new instance of NewSignalParam with the fields set to the given values.

Parameters:

title (str) – Default: None.
xmin (float) – Default: -10.0.
xmax (float) – Default: 10.0.
size (int) – Signal size (total number of points). Integer higher than 1. Default: 500.
stype (cdl.core.model.signal.SignalTypes) – Single choice from: SignalTypes.ZEROS, SignalTypes.GAUSS, SignalTypes.LORENTZ, SignalTypes.VOIGT, SignalTypes.UNIFORMRANDOM, SignalTypes.NORMALRANDOM, SignalTypes.SINUS, SignalTypes.COSINUS, SignalTypes.SAWTOOTH, SignalTypes.TRIANGLE, SignalTypes.SQUARE, SignalTypes.SINC, SignalTypes.STEP, SignalTypes.EXPONENTIAL, SignalTypes.PULSE, SignalTypes.POLYNOMIAL, SignalTypes.EXPERIMENTAL. Default: SignalTypes.ZEROS.

Returns:

New instance of NewSignalParam.

class cdl.obj.GaussLorentzVoigtParam[source]#

Parameters for Gaussian and Lorentzian functions

a#

Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

ymin#

Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

sigma#

σ. Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

mu#

μ. Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

classmethod create(a: float, ymin: float, sigma: float, mu: float) → cdl.core.model.signal.GaussLorentzVoigtParam#

Returns a new instance of GaussLorentzVoigtParam with the fields set to the given values.

Parameters:

a (float) – Default: 1.0.
ymin (float) – Default: 0.0.
sigma (float) – σ. Default: 1.0.
mu (float) – μ. Default: 0.0.

Returns:

New instance of GaussLorentzVoigtParam.

class cdl.obj.StepParam[source]#

Parameters for step function

a1#

Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

a2#

Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

x0#

Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

classmethod create(a1: float, a2: float, x0: float) → cdl.core.model.signal.StepParam#

Returns a new instance of StepParam with the fields set to the given values.

Parameters:

a1 (float) – Default: 0.0.
a2 (float) – Default: 1.0.
x0 (float) – Default: 0.0.

Returns:

New instance of StepParam.

class cdl.obj.PeriodicParam[source]#

Parameters for periodic functions

a#

Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

ymin#

Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

freq#

Frequency. Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

freq_unit#

Single choice from: FreqUnits.HZ, FreqUnits.KHZ, FreqUnits.MHZ, FreqUnits.GHZ. Default: FreqUnits.HZ.

Type:: guidata.dataset.dataitems.ChoiceItem

phase#

Float, unit: °. Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

classmethod create(a: float, ymin: float, freq: float, freq_unit: cdl.core.model.signal.FreqUnits, phase: float) → cdl.core.model.signal.PeriodicParam#

Returns a new instance of PeriodicParam with the fields set to the given values.

Parameters:

a (float) – Default: 1.0.
ymin (float) – Default: 0.0.
freq (float) – Frequency. Default: 1.0.
freq_unit (cdl.core.model.signal.FreqUnits) – Single choice from: FreqUnits.HZ, FreqUnits.KHZ, FreqUnits.MHZ, FreqUnits.GHZ. Default: FreqUnits.HZ.
phase (float) – Float, unit: °. Default: 0.0.

Returns:

New instance of PeriodicParam.

get_frequency_in_hz()[source]#: Return frequency in Hz

class cdl.obj.ROI1DParam[source]#

Signal ROI parameters

xmin#

First point coordinate. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

xmax#

Last point coordinate. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

classmethod create(xmin: float, xmax: float) → cdl.core.model.signal.ROI1DParam#

Returns a new instance of ROI1DParam with the fields set to the given values.

Parameters:

xmin (float) – First point coordinate. Default: None.
xmax (float) – Last point coordinate. Default: None.

Returns:

New instance of ROI1DParam.

get_data(obj: SignalObj) → ndarray[source]#

Get signal data in ROI

Parameters:: obj – signal object
Returns:: Data in ROI

Image model#

class cdl.obj.ImageObj[source]#

Image object

uuid#

Default: None.

Type:: guidata.dataset.dataitems.StringItem

data#

Default: None.

Type:: guidata.dataset.dataitems.FloatArrayItem

metadata#

Default: {}.

Type:: guidata.dataset.dataitems.DictItem

x0#

X₀. Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

y0#

Y₀. Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

dx#

Δx. Float, non zero. Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

dy#

Δy. Float, non zero. Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

title#

Image title. Default: ‘Untitled’.

Type:: guidata.dataset.dataitems.StringItem

xlabel#

Title. Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

xunit#

Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

ylabel#

Title. Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

yunit#

Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

zlabel#

Title. Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

zunit#

Default: ‘’.

Type:: guidata.dataset.dataitems.StringItem

autoscale#

Default: True.

Type:: guidata.dataset.dataitems.BoolItem

xscalelog#

Default: False.

Type:: guidata.dataset.dataitems.BoolItem

xscalemin#

Lower bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

xscalemax#

Upper bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

yscalelog#

Default: False.

Type:: guidata.dataset.dataitems.BoolItem

yscalemin#

Lower bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

yscalemax#

Upper bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

zscalemin#

Lower bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

zscalemax#

Upper bound. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

classmethod create(uuid: str, data: numpy.ndarray, metadata: dict, x0: float, y0: float, dx: float, dy: float, title: str, xlabel: str, xunit: str, ylabel: str, yunit: str, zlabel: str, zunit: str, autoscale: bool, xscalelog: bool, xscalemin: float, xscalemax: float, yscalelog: bool, yscalemin: float, yscalemax: float, zscalemin: float, zscalemax: float) → cdl.core.model.image.ImageObj#

Returns a new instance of ImageObj with the fields set to the given values.

Parameters:

uuid (str) – Default: None.
data (numpy.ndarray) – Default: None.
metadata (dict) – Default: {}.
x0 (float) – X₀. Default: 0.0.
y0 (float) – Y₀. Default: 0.0.
dx (float) – Δx. Float, non zero. Default: 1.0.
dy (float) – Δy. Float, non zero. Default: 1.0.
title (str) – Image title. Default: ‘Untitled’.
xlabel (str) – Title. Default: ‘’.
xunit (str) – Default: ‘’.
ylabel (str) – Title. Default: ‘’.
yunit (str) – Default: ‘’.
zlabel (str) – Title. Default: ‘’.
zunit (str) – Default: ‘’.
autoscale (bool) – Default: True.
xscalelog (bool) – Default: False.
xscalemin (float) – Lower bound. Default: None.
xscalemax (float) – Upper bound. Default: None.
yscalelog (bool) – Default: False.
yscalemin (float) – Lower bound. Default: None.
yscalemax (float) – Upper bound. Default: None.
zscalemin (float) – Lower bound. Default: None.
zscalemax (float) – Upper bound. Default: None.

Returns:

New instance of ImageObj.

regenerate_uuid()[source]#

Regenerate UUID

This method is used to regenerate UUID after loading the object from a file. This is required to avoid UUID conflicts when loading objects from file without clearing the workspace first.

set_metadata_from(obj: Mapping | dict) → None[source]#

Set metadata from object: dict-like (only string keys are considered) or any other object (iterating over supported attributes)

Parameters:: obj – object

property dicom_template#: Get DICOM template

property xc: float#: Return image center X-axis coordinate

property yc: float#: Return image center Y-axis coordinate

get_data(roi_index: int | None = None) → ndarray[source]#

Return original data (if ROI is not defined or roi_index is None), or ROI data (if both ROI and roi_index are defined).

Parameters:: roi_index – ROI index
Returns:: Masked data

copy(title: str | None = None, dtype: dtype | None = None) → ImageObj[source]#

Copy object.

Parameters:

title – title
dtype – data type

Returns:

Copied object

set_data_type(dtype: dtype) → None[source]#

Change data type.

Parameters:: type (Data) –

update_plot_item_parameters(item: MaskedImageItem) → None[source]#

Update plot item parameters from object data/metadata

Takes into account a subset of plot item parameters. Those parameters may have been overriden by object metadata entries or other object data. The goal is to update the plot item accordingly.

This is almost the inverse operation of update_metadata_from_plot_item.

Parameters:: item – plot item

update_metadata_from_plot_item(item: MaskedImageItem) → None[source]#

Update metadata from plot item.

Takes into account a subset of plot item parameters. Those parameters may have been modified by the user through the plot item GUI. The goal is to update the metadata accordingly.

This is almost the inverse operation of update_plot_item_parameters.

Parameters:: item – plot item

make_item(update_from: MaskedImageItem | None = None) → MaskedImageItem[source]#

Make plot item from data.

Parameters:: update_from – update from plot item
Returns:: Plot item

update_item(item: MaskedImageItem, data_changed: bool = True) → None[source]#

Update plot item from data.

Parameters:

item – plot item
data_changed – if True, data has changed

get_roi_param(title, *defaults: int) → DataSet[source]#

Return ROI parameters dataset.

Parameters:

title – title
*defaults – default values

params_to_roidata(params: DataSetGroup) → ndarray | None[source]#

Convert ROI dataset group to ROI array data.

Parameters:: params – ROI dataset group
Returns:: ROI array data

new_roi_item(fmt: str, lbl: bool, editable: bool, geometry: RoiDataGeometries) → MaskedImageItem[source]#

Return a new ROI item from scratch

Parameters:

fmt – format string
lbl – if True, add label
editable – if True, ROI is editable
geometry – ROI geometry

roi_coords_to_indexes(coords: list) → ndarray[source]#

Convert ROI coordinates to indexes.

Parameters:: coords – coordinates
Returns:: Indexes

iterate_roi_items(fmt: str, lbl: bool, editable: bool = True) → Iterator[source]#

Make plot item representing a Region of Interest.

Parameters:

fmt – format string
lbl – if True, add label
editable – if True, ROI is editable

Yields:

Plot item

property maskdata: ndarray#

Return masked data (areas outside defined regions of interest)

Returns:: Masked data

get_masked_view() → MaskedArray[source]#

Return masked view for data

Returns:: Masked view

invalidate_maskdata_cache() → None[source]#: Invalidate mask data cache: force to rebuild it

add_label_with_title(title: str | None = None) → None[source]#

Add label with title annotation

Parameters:: title – title (if None, use image title)

accept(vis: object) → None#

Helper function that passes the visitor to the accept methods of all the items in this dataset

Parameters:: vis (object) – visitor object

add_annotations_from_file(filename: str) → None#

Add object annotations from file (JSON).

Parameters:: filename – filename

add_annotations_from_items(items: list) → None#

Add object annotations (annotation plot items).

Parameters:: items – annotation plot items

property annotations: str#: Get object annotations (JSON string describing annotation plot items)

check() → list[str]#

Check the dataset item values

Returns:: list of errors
Return type:: list[str]

check_data()#

Check if data is valid, raise an exception if that’s not the case

Raises:: TypeError – if data type is not supported

delete_results() → None#: Delete all object results (shapes and properties)

deserialize(reader: HDF5Reader | JSONReader | INIReader) → None#

Deserialize the dataset

Parameters:: reader (HDF5Reader | JSONReader | INIReader) – reader object

edit(parent: QWidget | None = None, apply: Callable | None = None, wordwrap: bool = True, size: QSize | tuple[int, int] | None = None) → DataSetEditDialog#

Open a dialog box to edit data set

Parameters:

parent – parent widget (default is None, meaning no parent)
apply – apply callback (default is None)
wordwrap – if True, comment text is wordwrapped
size – dialog size (QSize object or integer tuple (width, height))

get_comment() → str | None#

Return data set comment

Returns:: comment
Return type:: str | None

get_icon() → str | None#

Return data set icon

Returns:: icon
Return type:: str | None

get_items(copy=False) → list[DataItem]#

Returns all the DataItem objects from the DataSet instance. Ignore private items that have a name starting with an underscore (e.g. ‘_private_item = …’)

Parameters:

copy – If True, deepcopy the DataItem list, else return the original.
False. (Defaults to) –

Returns:

_description_

get_metadata_option(name: str) → Any#

Return metadata option value

A metadata option is a metadata entry starting with an underscore. It is a way to store application-specific options in object metadata.

Parameters:: name – option name
Returns:: Option value

Valid option names:: ‘format’: format string ‘showlabel’: show label

get_title() → str#

Return data set title

Returns:: title
Return type:: str

classmethod get_valid_dtypenames() → list[str]#

Get valid data type names

Returns:: Valid data type names supported by this class

iterate_resultproperties() → Iterable[ResultProperties]#

Iterate over object result properties.

Yields:: Result properties

iterate_resultshapes() → Iterable[ResultShape]#

Iterate over object result shapes.

Yields:: Result shape

iterate_roi_indexes()#: Iterate over object ROI indexes ([0] if there is no ROI)

iterate_shape_items(editable: bool = False)#

Iterate over computing items encoded in metadata (if any).

Parameters:: editable – if True, annotations are editable
Yields:: Plot item

property number: int#: Return object number (used for short ID)

read_config(conf: UserConfig, section: str, option: str) → None#

Read configuration from a UserConfig instance

Parameters:

conf (UserConfig) – UserConfig instance
section (str) – section name
option (str) – option name

remove_all_shapes() → None#: Remove metadata shapes and ROIs

reset_metadata_to_defaults() → None#: Reset metadata to default values

restore_attr_from_metadata(attrname: str, default: Any) → None#

Restore attribute from metadata

Parameters:

attrname – attribute name
default – default value

property roi: ndarray | None#

Return object regions of interest array (one ROI per line).

Returns:: Regions of interest array

roi_has_changed() → bool#

Return True if ROI has changed since last call to this method.

Returns:: True if ROI has changed

roidata_to_params(roidata: ndarray | list[list[int]]) → DataSetGroup#

Convert ROI array data to ROI dataset group.

Parameters:: roidata – ROI array data (array or list of lists, floating point values are accepted and will be converted to integers)
Returns:: ROI dataset group

save_attr_to_metadata(attrname: str, new_value: Any) → None#

Save attribute to metadata

Parameters:

attrname – attribute name
new_value – new value

serialize(writer: HDF5Writer | JSONWriter | INIWriter) → None#

Serialize the dataset

Parameters:: writer (HDF5Writer | JSONWriter | INIWriter) – writer object

set_defaults() → None#: Set default values

classmethod set_global_prop(realm: str, **kwargs) → None#

Set global properties for all data items in the dataset

Parameters:

realm (str) – realm name
kwargs (dict) – properties to set

set_metadata_option(name: str, value: Any) → None#

Set metadata option value

A metadata option is a metadata entry starting with an underscore. It is a way to store application-specific options in object metadata.

Parameters:

name – option name
value – option value

Valid option names:: ‘format’: format string ‘showlabel’: show label

property short_id#: Short object ID

text_edit() → None#: Edit data set with text input only

to_string(debug: bool | None = False, indent: str | None = None, align: bool | None = False, show_hidden: bool | None = True) → str#

Return readable string representation of the data set If debug is True, add more details on data items

Parameters:

debug (bool) – if True, add more details on data items
indent (str) – indentation string (default is None, meaning no indentation)
align (bool) – if True, align data items (default is False)
show_hidden (bool) – if True, show hidden data items (default is True)

Returns:

string representation of the data set

Return type:

str

transform_shapes(orig, func, param=None)#

Apply transform function to result shape / annotations coordinates.

Parameters:

orig – original object
func – transform function
param – transform function parameter

update_metadata_view_settings() → None#: Update metadata view settings from Conf.view

update_resultshapes_from(other: BaseObj) → None#

Update geometric shape from another object (merge metadata).

Parameters:: other – other object, from which to update this object

view(parent: QWidget | None = None, wordwrap: bool = True, size: QSize | tuple[int, int] | None = None) → None#

Open a dialog box to view data set

Parameters:

parent – parent widget (default is None, meaning no parent)
wordwrap – if True, comment text is wordwrapped
size – dialog size (QSize object or integer tuple (width, height))

write_config(conf: UserConfig, section: str, option: str) → None#

Write configuration to a UserConfig instance

Parameters:

conf (UserConfig) – UserConfig instance
section (str) – section name
option (str) – option name

cdl.obj.read_image(filename: str) → ImageObj[source]#

Read an image from a file.

Parameters:: filename – File name.
Returns:: Image.

cdl.obj.read_images(filename: str) → list[ImageObj][source]#

Read a list of images from a file.

Parameters:: filename – File name.
Returns:: List of images.

cdl.obj.create_image(title: str, data: ndarray | None = None, metadata: dict | None = None, units: tuple | None = None, labels: tuple | None = None) → ImageObj[source]#

Create a new Image object

Parameters:

title – image title
data – image data
metadata – image metadata
units – X, Y, Z units (tuple of strings)
labels – X, Y, Z labels (tuple of strings)

Returns:

Image object

cdl.obj.create_image_from_param(newparam: NewImageParam, addparam: gds.DataSet | None = None, edit: bool = False, parent: QW.QWidget | None = None) → ImageObj | None[source]#

Create a new Image object from dialog box.

Parameters:

newparam – new image parameters
addparam – additional parameters
edit – Open a dialog box to edit parameters (default: False)
parent – parent widget

Returns:

New image object or None if user cancelled

Create a new Image dataset instance.

Parameters:

title – dataset title (default: None, uses default title)
itype – image type (default: None, uses default type)
height – image height (default: None, uses default height)
width – image width (default: None, uses default width)
dtype – image data type (default: None, uses default data type)

Returns:

New image dataset instance

class cdl.obj.ImageTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Image types

ZEROS = 'zeros'#: Image filled with zeros

EMPTY = 'empty'#: Empty image (filled with data from memory state)

GAUSS = 'gaussian'#: 2D Gaussian image

UNIFORMRANDOM = 'random (uniform law)'#: Image filled with random data (uniform law)

NORMALRANDOM = 'random (normal law)'#: Image filled with random data (normal law)

class cdl.obj.NewImageParam[source]#

New image dataset

title#

Default: None.

Type:: guidata.dataset.dataitems.StringItem

height#

Image height (total number of rows). Integer higher than 1. Default: None.

Type:: guidata.dataset.dataitems.IntItem

width#

Image width (total number of columns). Integer higher than 1. Default: None.

Type:: guidata.dataset.dataitems.IntItem

dtype#

Data type. Single choice from: ImageDatatypes.UINT8, ImageDatatypes.UINT16, ImageDatatypes.INT16, ImageDatatypes.FLOAT32, ImageDatatypes.FLOAT64. Default: ImageDatatypes.UINT8.

Type:: guidata.dataset.dataitems.ChoiceItem

itype#

Single choice from: ImageTypes.ZEROS, ImageTypes.EMPTY, ImageTypes.GAUSS, ImageTypes.UNIFORMRANDOM, ImageTypes.NORMALRANDOM. Default: ImageTypes.ZEROS.

Type:: guidata.dataset.dataitems.ChoiceItem

classmethod create(title: str, height: int, width: int, dtype: cdl.core.model.image.ImageDatatypes, itype: cdl.core.model.image.ImageTypes) → cdl.core.model.image.NewImageParam#

Returns a new instance of NewImageParam with the fields set to the given values.

Parameters:

title (str) – Default: None.
height (int) – Image height (total number of rows). Integer higher than 1. Default: None.
width (int) – Image width (total number of columns). Integer higher than 1. Default: None.
dtype (cdl.core.model.image.ImageDatatypes) – Data type. Single choice from: ImageDatatypes.UINT8, ImageDatatypes.UINT16, ImageDatatypes.INT16, ImageDatatypes.FLOAT32, ImageDatatypes.FLOAT64. Default: ImageDatatypes.UINT8.
itype (cdl.core.model.image.ImageTypes) – Single choice from: ImageTypes.ZEROS, ImageTypes.EMPTY, ImageTypes.GAUSS, ImageTypes.UNIFORMRANDOM, ImageTypes.NORMALRANDOM. Default: ImageTypes.ZEROS.

Returns:

New instance of NewImageParam.

class cdl.obj.Gauss2DParam[source]#

2D Gaussian parameters

a#

Norm. Default: None.

Type:: guidata.dataset.dataitems.FloatItem

xmin#

Default: -10.

Type:: guidata.dataset.dataitems.FloatItem

sigma#

σ. Default: 1.0.

Type:: guidata.dataset.dataitems.FloatItem

xmax#

Default: 10.

Type:: guidata.dataset.dataitems.FloatItem

mu#

μ. Default: 0.0.

Type:: guidata.dataset.dataitems.FloatItem

ymin#

Default: -10.

Type:: guidata.dataset.dataitems.FloatItem

x0#

Default: 0.

Type:: guidata.dataset.dataitems.FloatItem

ymax#

Default: 10.

Type:: guidata.dataset.dataitems.FloatItem

y0#

Default: 0.

Type:: guidata.dataset.dataitems.FloatItem

classmethod create(a: float, xmin: float, sigma: float, xmax: float, mu: float, ymin: float, x0: float, ymax: float, y0: float) → cdl.core.model.image.Gauss2DParam#

Returns a new instance of Gauss2DParam with the fields set to the given values.

Parameters:

a (float) – Norm. Default: None.
xmin (float) – Default: -10.
sigma (float) – σ. Default: 1.0.
xmax (float) – Default: 10.
mu (float) – μ. Default: 0.0.
ymin (float) – Default: -10.
x0 (float) – Default: 0.
ymax (float) – Default: 10.
y0 (float) – Default: 0.

Returns:

New instance of Gauss2DParam.

class cdl.obj.RoiDataGeometries(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#: ROI data geometry types

class cdl.obj.ROI2DParam[source]#

Image ROI parameters

geometry#

Single choice from: RoiDataGeometries.RECTANGLE, RoiDataGeometries.CIRCLE. Default: RoiDataGeometries.RECTANGLE.

Type:: guidata.dataset.dataitems.ChoiceItem

xr0#

X₀. Integer, unit: pixel. Default: None.

Type:: guidata.dataset.dataitems.IntItem

yr0#

Y₀. Integer, unit: pixel. Default: None.

Type:: guidata.dataset.dataitems.IntItem

xr1#

X₁. Integer, unit: pixel. Default: None.

Type:: guidata.dataset.dataitems.IntItem

yr1#

Y₁. Integer, unit: pixel. Default: None.

Type:: guidata.dataset.dataitems.IntItem

xc#

X_C. Integer, unit: pixel. Default: None.

Type:: guidata.dataset.dataitems.IntItem

yc#

Y_C. Integer, unit: pixel. Default: None.

Type:: guidata.dataset.dataitems.IntItem

r#

Radius. Integer, unit: pixel. Default: None.

Type:: guidata.dataset.dataitems.IntItem

classmethod create(geometry: cdl.core.model.image.RoiDataGeometries, xr0: int, yr0: int, xr1: int, yr1: int, xc: int, yc: int, r: int) → cdl.core.model.image.ROI2DParam#

Returns a new instance of ROI2DParam with the fields set to the given values.

Parameters:

geometry (cdl.core.model.image.RoiDataGeometries) – Single choice from: RoiDataGeometries.RECTANGLE, RoiDataGeometries.CIRCLE. Default: RoiDataGeometries.RECTANGLE.
xr0 (int) – X₀. Integer, unit: pixel. Default: None.
yr0 (int) – Y₀. Integer, unit: pixel. Default: None.
xr1 (int) – X₁. Integer, unit: pixel. Default: None.
yr1 (int) – Y₁. Integer, unit: pixel. Default: None.
xc (int) – X_C. Integer, unit: pixel. Default: None.
yc (int) – Y_C. Integer, unit: pixel. Default: None.
r (int) – Radius. Integer, unit: pixel. Default: None.

Returns:

New instance of ROI2DParam.

get_suffix() → str[source]#: Get suffix text representation for ROI extraction

get_coords() → tuple[int, int, int, int][source]#: Get ROI coordinates

get_single_roi() → ndarray | None[source]#: Get single ROI, i.e. after extracting ROI from image

get_rect_indexes() → tuple[int, int, int, int][source]#: Get rectangle indexes

get_data(obj: ImageObj) → ndarray[source]#

Get data in ROI

Parameters:: obj – image object
Returns:: Data in ROI

class cdl.obj.ImageDatatypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Image data types

classmethod from_dtype(dtype)[source]#: Return member from NumPy dtype

classmethod check()[source]#: Check if data types are valid

UINT8 = 'uint8'#: Unsigned integer number stored with 8 bits

UINT16 = 'uint16'#: Unsigned integer number stored with 16 bits

INT16 = 'int16'#: Signed integer number stored with 16 bits

FLOAT32 = 'float32'#: Float number stored with 32 bits

FLOAT64 = 'float64'#: Float number stored with 64 bits

class cdl.obj.ImageRoiDataItem(data: ndarray | list | tuple)[source]#

Object representing an image ROI.

Parameters:: data – ROI data

classmethod from_image(obj: ImageObj, geometry: RoiDataGeometries) → ImageRoiDataItem[source]#

Construct roi data item from image object: called for making new ROI items

Parameters:

obj – image object
geometry – ROI geometry

property geometry: RoiDataGeometries#: ROI geometry

get_rect() → tuple[int, int, int, int][source]#: Get rectangle coordinates

get_image_masked_view(obj: ImageObj) → ndarray[source]#

Return masked view for data

Parameters:: obj – image object

apply_mask(data: ndarray, yxratio: float) → ndarray[source]#

Apply ROI to data as a mask and return masked array

Parameters:

data – data
yxratio – Y/X ratio

make_roi_item(index: int | None, fmt: str, lbl: bool, editable: bool = True)[source]#

Make ROI plot item

Parameters:

index – ROI index
fmt – format string
lbl – if True, show label
editable – if True, ROI is editable

Object model (cdl.obj)#

Common objects#

Signal model#

Image model#

Object model (`cdl.obj`)#