dcnum.segm

Submodules

• dcnum.segm.segm_thresh
• dcnum.segm.segm_torch
• dcnum.segm.segmenter
• dcnum.segm.segmenter_manager_thread
• dcnum.segm.segmenter_mpo
• dcnum.segm.segmenter_sto

Exceptions

SegmenterNotApplicableError

Initialize self. See help(type(self)) for accurate signature.

Classes

Segmenter	Base segmenter class
MPOSegmenter	Segmenter with multiprocessing operation
STOSegmenter	Segmenter with single thread operation
SegmenterManagerThread	Manage the segmentation of image data

Functions

get_segmenters()
get_available_segmenters()	Return dictionary of available segmenters

Package Contents

class dcnum.segm.Segmenter(*, kwargs_mask: dict | None = None, debug: bool = False, **kwargs)

Bases: abc.ABC

Base segmenter class

This is the base segmenter class for the multiprocessing operation segmenter segmenter_mpo.MPOSegmenter (multiple subprocesses are spawned and each of them works on a queue of images) and the single-threaded operation segmenter segmenter_sto.STOSegmenter (e.g. for batch segmentation on a GPU).

Parameters:

• kwargs_mask (dict) – Keyword arguments for mask post-processing (see process_labels)

• debug (bool) – Enable debugging mode (e.g. CPU segmenter runs in one thread)

• kwargs – Additional, optional keyword arguments for segment_batch.

hardware_processor = 'none'

Required hardware (“cpu” or “gpu”) defined in first-level subclass.

mask_postprocessing = True

Whether to enable mask post-processing. If disabled, you should make sure that your mask is properly defined and cleaned or you have to call process_labels in your segment_algorithm implementation.

mask_default_kwargs

Default keyword arguments for mask post-processing. See process_labels for available options.

requires_background_correction = False

Whether the segmenter requires a background-corrected image

debug = False

logger

kwargs

custom keyword arguments for the subclassing segmenter

kwargs_mask

keyword arguments for mask post-processing

static get_border(shape)

Cached boolean image with outer pixels set to True

static get_disk(radius)

Cached skimage.morphology.disk(radius)

get_ppid()

Return a unique segmentation pipeline identifier

The pipeline identifier is universally applicable and must be backwards-compatible (future versions of dcnum will correctly acknowledge the ID).

The segmenter pipeline ID is defined as:

KEY:KW_APPROACH:KW_MASK

Where KEY is e.g. “legacy” or “watershed”, and KW_APPROACH is a list of keyword arguments for segment_algorithm, e.g.:

thresh=-6^blur=0

which may be abbreviated to:

t=-6^b=0

KW_MASK represents keyword arguments for process_labels.

classmethod get_ppid_code()

The unique code/name of this segmenter class

classmethod get_ppid_from_ppkw(kwargs, kwargs_mask=None)

Return the pipeline ID from given keyword arguments

See also

get_ppid

Same method for class instances

static get_ppkw_from_ppid(segm_ppid)

Return keyword arguments for this pipeline identifier

static is_available()

Subclasses may override this method e.g. if dependencies exist

log_info(logger)

Allow segmenter to write informative log messages

static process_labels(labels, *, clear_border: bool = True, fill_holes: bool = True, closing_disk: int = 5)

Post-process retrieved mask image

This is an optional convenience method that is called for each subclass individually. To enable mask post-processing, set mask_postprocessing=True in the subclass and specify default mask_default_kwargs.

Parameters:

• labels (2d uint16 or boolean ndarray) – Labeled input (contains blobs consisting of unique numbers)

• clear_border (bool) – clear the image boarder using an equivalent of skimage.segmentation.clear_border()

• fill_holes (bool) – binary-fill-holes in the binary mask image using scipy.ndimage.binary_fill_holes()

• closing_disk (int or None) – if > 0, perform a binary closing with a disk of that radius in pixels

static segment_algorithm(image) → numpy.ndarray

Abstractmethod:

The segmentation algorithm implemented in the subclass

Perform segmentation and return boolean mask image

segment_algorithm_wrapper()

Wraps self.segment_algorithm to only accept an image

The static method self.segment_algorithm may optionally accept keyword arguments self.kwargs. This wrapper returns the wrapped method that only accepts the image as an argument. This makes sense if you want to unify

abstractmethod segment_batch(images, bg_off=None)

Return the bollean mask for an entire batch

This is implemented in the MPO and STO segmenters.

segment_batch_with_labeling(images, bg_off=None)

Return the processed label image for an image batch

This is intended for testing only. The logic pipeline uses UniversalWorkers to perform labeling and label processing.

segment_chunk(chunk: int, slot_list: list)

Segment the image data of one ChunkSlot

This is a wrapper for segment_batch. The image information are extracted from the chunk_slot.image/chunk_slot.image_corr properties and the boolean mask arrays are written to ``chunk_slot.mask`.

Parameters:

chunk_slot (ChunkSlot) – The data chunk to perform segmentation on

Returns:

mask – The chunk_slot.mask numpy view on the shared mask array.

Return type:

np.array

abstractmethod segment_single(image, bg_off: float | None = None)

Return the boolean mask for one image

This is implemented in the MPO and STO segmenters.

segment_single_with_labeling(image, bg_off=None)

Return the processed label image for one image

This is intended for testing only. The logic pipeline uses UniversalWorkers to perform labeling and label processing.

close()

Subclasses can implement clean-up code here

classmethod validate_applicability(segmenter_kwargs: dict, meta: dict | None = None, logs: dict | None = None)

Validate the applicability of this segmenter for a dataset

Parameters:

• segmenter_kwargs (dict) – Keyword arguments for the segmenter

• meta (dict) – Dictionary of metadata from an hdf5_data.HDF5Data instance

• logs (dict) – Dictionary of logs from an hdf5_data.HDF5Data instance

Returns:

applicable – True if the segmenter is applicable to the dataset

Return type:

bool

Raises:

SegmenterNotApplicableError – If the segmenter is not applicable to the dataset

exception dcnum.segm.SegmenterNotApplicableError(segmenter_class, reasons_list)

Bases: BaseException

Initialize self. See help(type(self)) for accurate signature.

reasons_list

segmenter_class

dcnum.segm.get_segmenters()

dcnum.segm.get_available_segmenters()

Return dictionary of available segmenters

class dcnum.segm.MPOSegmenter(*, num_workers: int | None = None, kwargs_mask: dict | None = None, debug: bool = False, **kwargs)

Bases: dcnum.segm.segmenter.Segmenter, abc.ABC

Segmenter with multiprocessing operation

Parameters:

• num_workers – Number of workers (processes) to spawn

• kwargs_mask (dict) – Keyword arguments for mask post-processing (see process_labels)

• debug (bool) – Debugging parameters

• kwargs – Additional, optional keyword arguments for segment_algorithm defined in the subclass.

hardware_processor = 'cpu'

Required hardware (“cpu” or “gpu”) defined in first-level subclass.

num_workers

slot_list = None

List of ChunkSlot instances

mp_slot_index

The slot that is currently being worked on

mp_active

Event that defines whether the workers are allowed to do work

mp_num_workers_done

Number of workers that are done processing the slot

mp_shutdown

Shutdown event tells workers to stop when set to != 0

_worker_starter = None

_workers = []

__enter__()

__exit__(exc_type, exc_val, exc_tb)

__getstate__()

__setstate__(state)

join_workers()

Ask all workers to stop and join them

reinitialize_workers(slot_list)

segment_batch(images: numpy.ndarray, bg_off: numpy.ndarray | None = None)

Perform batch segmentation of images

Before segmentation, an optional background offset correction with bg_off is performed. After segmentation, mask postprocessing is performed according to the segmenter class definition.

Parameters:

• images (3d np.ndarray of shape (N, Y, X)) – The time-series image data. First axis is time.

• bg_off (1D np.ndarray of length N) – Optional 1D numpy array with background offset

Notes

• If the segmentation algorithm only accepts background-corrected images, then images must already be background-corrected, except for the optional bg_off.

segment_chunk(chunk: int, slot_list: list)

Segment the image data of one ChunkSlot

Parameters:

• chunk – The data chunk index to perform segmentation on

• slot_list – List of ChunkSlotData instances (e.g. SlotRegister.slots)

Returns:

mask – The chunk_slot.mask numpy view on the shared boolean mask array.

Return type:

np.array

segment_single(image, bg_off: float | None = None)

Return the boolean mask image for an input image

Before segmentation, an optional background offset correction with bg_off is performed. After segmentation, mask postprocessing is performed according to the class definition.

close()

Subclasses can implement clean-up code here

class dcnum.segm.STOSegmenter(*, num_workers: int | None = None, kwargs_mask: dict | None = None, debug: bool = False, **kwargs)

Bases: dcnum.segm.segmenter.Segmenter, abc.ABC

Segmenter with single thread operation

Parameters:

• kwargs_mask (dict) – Keyword arguments for mask post-processing (see process_labels)

• debug (bool) – Debugging parameters

• kwargs – Additional, optional keyword arguments for segment_algorithm defined in the subclass.

hardware_processor = 'gpu'

Required hardware (“cpu” or “gpu”) defined in first-level subclass.

segment_batch(images: numpy.ndarray, bg_off: numpy.ndarray | None = None)

Perform batch segmentation of images

Before segmentation, an optional background offset correction with bg_off is performed. After segmentation, mask postprocessing is performed according to the class definition.

Parameters:

• images (3d np.ndarray of shape (N, Y, X)) – The time-series image data. First axis is time.

• bg_off (1D np.ndarray of length N) – Optional 1D numpy array with background offset

Notes

• If the segmentation algorithm only accepts background-corrected images, then images must already be background-corrected, except for the optional bg_off.

segment_single(image, bg_off: float | None = None)

This is a convenience-wrapper around segment_batch

class dcnum.segm.SegmenterManagerThread(segmenter: dcnum.segm.segmenter.Segmenter, slot_register: dcnum.logic.SlotRegister, *args, **kwargs)

Bases: threading.Thread

Manage the segmentation of image data

Parameters:

• segmenter – The segmenter instance to use.

• slot_register – Manages a list of ChunkSlots, shared arrays on which to operate

Notes

The working principle of this SegmenterManagerThread allows the user to define a fixed number of slots on which the segmenter can work on. For instance, if the segmenter is a CPU-based segmenter, it does not make sense to have more than one slot (because feature extraction should not take place at the same time). But if the segmenter is a GPU-based segmenter, then it makes sense to have more than one slot, so CPU and GPU can work in parallel.

logger

segmenter

Segmenter instance

slot_register

Slot manager

t_segm = 0

Segmentation time counter

t_wait = 0

Waiting time counter

run()

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.