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 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]])
- check_array() None [source]#
Check if array attribute is valid
- Raises:
AssertionError – invalid 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
- 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: Literal['s', 'i']) 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 (“s” for signal, “i” for image)
- Yields:
Plot item
- create_shape_item(coords: np.ndarray, fmt: str, lbl: bool, option: Literal['s', 'i']) AnnotatedPoint | Marker | AnnotatedRectangle | AnnotatedCircle | AnnotatedSegment | AnnotatedEllipse | PolygonShape | None [source]#
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 (“s” for signal, “i” for image)
- 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
- class cdl.obj.NormalRandomParam(title=None, comment=None, icon='')[source]#
Normal-law random signal/image parameters
Signal model#
- class cdl.obj.SignalObj[source]#
Signal object
- uuid#
Default: None.
- xydata#
Default: None.
- metadata#
Default: {}.
- title#
Signal title. Default: ‘Untitled’.
- xlabel#
Title. Default: ‘’.
- xunit#
Default: ‘’.
- ylabel#
Title. Default: ‘’.
- yunit#
Default: ‘’.
- autoscale#
Default: True.
- xscalelog#
Default: False.
- xscalemin#
Lower bound. Default: None.
- xscalemax#
Upper bound. Default: None.
- yscalelog#
Default: False.
- yscalemin#
Lower bound. Default: None.
- yscalemax#
Upper bound. Default: None.
- 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_xydata(x: ndarray | list, y: ndarray | list, dx: ndarray | list | None = None, dy: ndarray | list | None = None) None [source]#
Set xy data
- Parameters:
x – x data
y – y data
dx – dx data (optional: error bars)
dy – dy data (optional: error bars)
- 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 = 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
- physical_to_indices(coords: list[float] | ndarray) ndarray [source]#
Convert coordinates from physical (real world) to (array) indices (pixel)
- Parameters:
coords – coordinates
- Returns:
Indices
- indices_to_physical(indices: list[int] | ndarray) ndarray [source]#
Convert coordinates from (array) indices to physical (real world)
- Parameters:
indices – indices
- Returns:
Coordinates
- 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
- check_data()#
Check if data is valid, raise an exception if that’s not the case
- Raises:
TypeError – if data type is not supported
- 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_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_masked_view() MaskedArray #
Return masked view for data
- Returns:
Masked view
- 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
- 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_indices() Generator[int | None, None, None] #
Iterate over object ROI indices (if there is no ROI, yield None)
- iterate_shape_items(editable: bool = False)#
Iterate over shape items encoded in metadata (if any).
- Parameters:
editable – if True, annotations are editable
- Yields:
Plot item
- property maskdata: ndarray#
Return masked data (areas outside defined regions of interest)
- Returns:
Masked data
- read_config(conf: UserConfig, section: str, option: str) None #
Read configuration from a UserConfig instance
- restore_attr_from_metadata(attrname: str, default: Any) None #
Restore attribute from metadata
- Parameters:
attrname – attribute name
default – default value
- property roi: TypeROI | None#
Return object regions of interest object.
- Returns:
Regions of interest object
- 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
- 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
- classmethod set_global_prop(realm: str, **kwargs) None #
Set global properties for all data items in the dataset
- 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
- 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:
- Returns:
string representation of the data set
- Return type:
- 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_resultshapes_from(other: TypeObj) 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))
- 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.
- cdl.obj.create_signal_roi(coords: ndarray | list[float, float] | list[list[float, float]], indices: bool = False, singleobj: bool | None = None, inverse: bool = False, title: str = '') SignalROI [source]#
Create Signal Regions of Interest (ROI) object. More ROIs can be added to the object after creation, using the add_roi method.
- Parameters:
coords – single ROI coordinates [xmin, xmax], or multiple ROIs coordinates [[xmin1, xmax1], [xmin2, xmax2], …] (lists or NumPy arrays)
indices – if True, coordinates are indices, if False, they are physical values (default to False for signals)
singleobj – if True, when extracting data defined by ROIs, only one object is created (default to True). If False, one object is created per single ROI. If None, the value is get from the user configuration
inverse – if True, ROI is outside the region
title – title
- Returns:
Regions of Interest (ROI) object
- Raises:
ValueError – if the number of coordinates is not even
- cdl.obj.create_signal(title: str, x: ndarray | None = None, y: ndarray | None = None, dx: ndarray | None = None, dy: ndarray | None = None, metadata: dict | None = None, units: tuple[str, str] | None = None, labels: tuple[str, str] | None = None) SignalObj [source]#
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
- cdl.obj.new_signal_param(title: str | None = None, stype: str | None = None, xmin: float | None = None, xmax: float | None = None, size: int | None = None) NewSignalParam [source]#
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:
- 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.
- xmin#
Default: -10.0.
- xmax#
Default: 10.0.
- size#
Signal size (total number of points). Integer higher than 1. Default: 500.
- 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.
- 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.
- ymin#
Default: 0.0.
- sigma#
σ. Default: 1.0.
- mu#
μ. Default: 0.0.
- 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:
- Returns:
New instance of
GaussLorentzVoigtParam
.
- class cdl.obj.StepParam[source]#
Parameters for step function
- a1#
Default: 0.0.
- a2#
Default: 1.0.
- x0#
Default: 0.0.
- class cdl.obj.PeriodicParam[source]#
Parameters for periodic functions
- a#
Default: 1.0.
- ymin#
Default: 0.0.
- freq#
Frequency. Default: 1.0.
- freq_unit#
Single choice from: FreqUnits.HZ, FreqUnits.KHZ, FreqUnits.MHZ, FreqUnits.GHZ. Default: FreqUnits.HZ.
- phase#
Float, unit: °. Default: 0.0.
- 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:
- Returns:
New instance of
PeriodicParam
.
- class cdl.obj.ROI1DParam[source]#
Signal ROI parameters
- xmin#
First point coordinate. Default: None.
- xmax#
Last point coordinate. Default: None.
- 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:
- Returns:
New instance of
ROI1DParam
.
- class cdl.obj.SignalROI(singleobj: bool | None = None, inverse: bool = False)[source]#
Signal Regions of Interest
- Parameters:
singleobj – if True, when extracting data defined by ROIs, only one object is created (default to True). If False, one object is created per single ROI. If None, the value is get from the user configuration
inverse – if True, ROI is outside the region
Image model#
- class cdl.obj.ImageObj[source]#
Image object
- uuid#
Default: None.
- data#
Default: None.
- metadata#
Default: {}.
- x0#
X0. Default: 0.0.
- y0#
Y0. Default: 0.0.
- dx#
Δx. Float, non zero. Default: 1.0.
- dy#
Δy. Float, non zero. Default: 1.0.
- title#
Image title. Default: ‘Untitled’.
- xlabel#
Title. Default: ‘’.
- xunit#
Default: ‘’.
- ylabel#
Title. Default: ‘’.
- yunit#
Default: ‘’.
- zlabel#
Title. Default: ‘’.
- zunit#
Default: ‘’.
- autoscale#
Default: True.
- xscalelog#
Default: False.
- xscalemin#
Lower bound. Default: None.
- xscalemax#
Upper bound. Default: None.
- yscalelog#
Default: False.
- yscalemin#
Lower bound. Default: None.
- yscalemax#
Upper bound. Default: None.
- zscalemin#
Lower bound. Default: None.
- zscalemax#
Upper bound. Default: None.
- 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) – X0. Default: 0.0.
y0 (float) – Y0. 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
- 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. If data type is integer, clip values to the new data type’s range, thus avoiding overflow or underflow.
- 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
- physical_to_indices(coords: list[float]) ndarray [source]#
Convert coordinates from physical (real world) to (array) indices (pixel)
- Parameters:
coords – coordinates
- Returns:
Indices
- indices_to_physical(indices: list[float | int] | ndarray) ndarray [source]#
Convert coordinates from (array) indices to physical (real world)
- Parameters:
indices – indices
- Returns:
Coordinates
- 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
- check_data()#
Check if data is valid, raise an exception if that’s not the case
- Raises:
TypeError – if data type is not supported
- 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_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_masked_view() MaskedArray #
Return masked view for data
- Returns:
Masked view
- 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
- 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_indices() Generator[int | None, None, None] #
Iterate over object ROI indices (if there is no ROI, yield None)
- iterate_shape_items(editable: bool = False)#
Iterate over shape items encoded in metadata (if any).
- Parameters:
editable – if True, annotations are editable
- Yields:
Plot item
- property maskdata: ndarray#
Return masked data (areas outside defined regions of interest)
- Returns:
Masked data
- read_config(conf: UserConfig, section: str, option: str) None #
Read configuration from a UserConfig instance
- restore_attr_from_metadata(attrname: str, default: Any) None #
Restore attribute from metadata
- Parameters:
attrname – attribute name
default – default value
- property roi: TypeROI | None#
Return object regions of interest object.
- Returns:
Regions of interest object
- 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
- 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
- classmethod set_global_prop(realm: str, **kwargs) None #
Set global properties for all data items in the dataset
- 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
- 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:
- Returns:
string representation of the data set
- Return type:
- 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_resultshapes_from(other: TypeObj) 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))
- 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_roi(geometry: Literal['rectangle', 'circle', 'polygon'], coords: ndarray | list[float] | list[list[float]], indices: bool = True, singleobj: bool | None = None, inverse: bool = False, title: str = '') ImageROI [source]#
Create Image Regions of Interest (ROI) object. More ROIs can be added to the object after creation, using the add_roi method.
- Parameters:
geometry – ROI type (‘rectangle’, ‘circle’, ‘polygon’)
coords – ROI coords (physical coordinates), [x0, y0, dx, dy] for a rectangle, [xc, yc, r] for a circle, or [x0, y0, x1, y1, …] for a polygon (lists or NumPy arrays are accepted). For multiple ROIs, nested lists or NumPy arrays are accepted but with a common geometry type (e.g. [[xc1, yc1, r1], [xc2, yc2, r2], …] for circles).
indices – if True, coordinates are indices, if False, they are physical values (default to True for images)
singleobj – if True, when extracting data defined by ROIs, only one object is created (default to True). If False, one object is created per single ROI. If None, the value is get from the user configuration
inverse – if True, ROI is outside the region
title – title
- Returns:
Regions of Interest (ROI) object
- Raises:
ValueError – if ROI type is unknown or if the number of coordinates is invalid
- 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
- cdl.obj.new_image_param(title: str | None = None, itype: ImageTypes | None = None, height: int | None = None, width: int | None = None, dtype: ImageDatatypes | None = None) NewImageParam [source]#
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.
- height#
Image height (total number of rows). Integer higher than 1. Default: None.
- width#
Image width (total number of columns). Integer higher than 1. Default: None.
- dtype#
Data type. Single choice from: ImageDatatypes.UINT8, ImageDatatypes.UINT16, ImageDatatypes.INT16, ImageDatatypes.FLOAT32, ImageDatatypes.FLOAT64. Default: ImageDatatypes.UINT8.
- itype#
Single choice from: ImageTypes.ZEROS, ImageTypes.EMPTY, ImageTypes.GAUSS, ImageTypes.UNIFORMRANDOM, ImageTypes.NORMALRANDOM. Default: ImageTypes.ZEROS.
- 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.
- xmin#
Default: -10.
- sigma#
σ. Default: 1.0.
- xmax#
Default: 10.
- mu#
μ. Default: 0.0.
- ymin#
Default: -10.
- x0#
Default: 0.
- ymax#
Default: 10.
- y0#
Default: 0.
- 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:
- Returns:
New instance of
Gauss2DParam
.
- class cdl.obj.ROI2DParam[source]#
Image ROI parameters
- geometry#
Single choice from: ‘rectangle’, ‘circle’, ‘polygon’. Default: ‘rectangle’.
- x0#
X0. Integer, unit: pixels. Default: None.
- y0#
Y0. Integer, unit: pixels. Default: None.
- dx#
ΔX. Integer, unit: pixels. Default: None.
- dy#
ΔY. Integer, unit: pixels. Default: None.
- xc#
XC. Integer, unit: pixels. Default: None.
- yc#
YC. Integer, unit: pixels. Default: None.
- r#
Radius. Integer, unit: pixels. Default: None.
- points#
Coordinates (pixels). Default: None.
- classmethod create(geometry: str, x0: int, y0: int, dx: int, dy: int, xc: int, yc: int, r: int, points: numpy.ndarray) cdl.core.model.image.ROI2DParam #
Returns a new instance of
ROI2DParam
with the fields set to the given values.- Parameters:
geometry (str) – Single choice from: ‘rectangle’, ‘circle’, ‘polygon’. Default: ‘rectangle’.
x0 (int) – X0. Integer, unit: pixels. Default: None.
y0 (int) – Y0. Integer, unit: pixels. Default: None.
dx (int) – ΔX. Integer, unit: pixels. Default: None.
dy (int) – ΔY. Integer, unit: pixels. Default: None.
xc (int) – XC. Integer, unit: pixels. Default: None.
yc (int) – YC. Integer, unit: pixels. Default: None.
r (int) – Radius. Integer, unit: pixels. Default: None.
points (numpy.ndarray) – Coordinates (pixels). Default: None.
- Returns:
New instance of
ROI2DParam
.
- to_single_roi(obj: ImageObj, title: str = '') PolygonalROI | RectangularROI | CircularROI [source]#
Convert parameters to single ROI
- Parameters:
obj – image object (used for conversion of pixel to physical coordinates)
title – ROI title
- Returns:
Single ROI
- get_extracted_roi(obj: ImageObj) ImageROI | None [source]#
Get extracted ROI, i.e. the remaining ROI after extracting ROI from image.
- Parameters:
obj – image object (used for conversion of pixel to physical coordinates)
When extracting ROIs from an image to multiple images (i.e. one image per ROI), this method returns the ROI that has to be kept in the destination image. This is not necessary for a rectangular ROI: the destination image is simply a crop of the source image according to the ROI coordinates. But for a circular ROI or a polygonal ROI, the destination image is a crop of the source image according to the bounding box of the ROI. Thus, to avoid any loss of information, a ROI has to be defined for the destination image: this is the ROI returned by this method. It’s simply the same as the source ROI, but with coordinates adjusted to the destination image. One may called this ROI the “extracted ROI”.
- class cdl.obj.ImageROI(singleobj: bool | None = None, inverse: bool = False)[source]#
Image Regions of Interest
- Parameters:
singleobj – if True, when extracting data defined by ROIs, only one object is created (default to True). If False, one object is created per single ROI. If None, the value is get from the user configuration
inverse – if True, ROI is outside the region
- class cdl.obj.ImageDatatypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#
Image data types
- 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