dcnum.segm.segmenter ==================== .. py:module:: dcnum.segm.segmenter Attributes ---------- .. autoapisummary:: dcnum.segm.segmenter.cv2 dcnum.segm.segmenter.ndi dcnum.segm.segmenter.STRUCTURING_ELEMENT Exceptions ---------- .. autoapisummary:: dcnum.segm.segmenter.SegmenterNotApplicableError Classes ------- .. autoapisummary:: dcnum.segm.segmenter.Segmenter Functions --------- .. autoapisummary:: dcnum.segm.segmenter.assert_labels dcnum.segm.segmenter.get_segmenters dcnum.segm.segmenter.get_available_segmenters Module Contents --------------- .. py:data:: cv2 .. py:data:: ndi .. py:data:: STRUCTURING_ELEMENT .. py:exception:: SegmenterNotApplicableError(segmenter_class, reasons_list) Bases: :py:obj:`BaseException` Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: reasons_list .. py:attribute:: segmenter_class .. py:class:: Segmenter(*, kwargs_mask: dict | None = None, debug: bool = False, **kwargs) Bases: :py:obj:`abc.ABC` Base segmenter class This is the base segmenter class for the multiprocessing operation segmenter :class:`.segmenter_mpo.MPOSegmenter` (multiple subprocesses are spawned and each of them works on a queue of images) and the single-threaded operation segmenter :class:`.segmenter_sto.STOSegmenter` (e.g. for batch segmentation on a GPU). :param kwargs_mask: Keyword arguments for mask post-processing (see `process_labels`) :type kwargs_mask: dict :param debug: Enable debugging mode (e.g. CPU segmenter runs in one thread) :type debug: bool :param kwargs: Additional, optional keyword arguments for `segment_batch`. .. py:attribute:: hardware_processor :value: 'none' Required hardware ("cpu" or "gpu") defined in first-level subclass. .. py:attribute:: mask_postprocessing :value: 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. .. py:attribute:: mask_default_kwargs Default keyword arguments for mask post-processing. See `process_labels` for available options. .. py:attribute:: requires_background_correction :value: False Whether the segmenter requires a background-corrected image .. py:attribute:: debug :value: False .. py:attribute:: logger .. py:attribute:: kwargs custom keyword arguments for the subclassing segmenter .. py:attribute:: kwargs_mask keyword arguments for mask post-processing .. py:method:: get_border(shape) :staticmethod: Cached boolean image with outer pixels set to True .. py:method:: get_disk(radius) :staticmethod: Cached `skimage.morphology.disk(radius)` .. py:method:: 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`. .. py:method:: get_ppid_code() :classmethod: The unique code/name of this segmenter class .. py:method:: get_ppid_from_ppkw(kwargs, kwargs_mask=None) :classmethod: Return the pipeline ID from given keyword arguments .. seealso:: :py:obj:`get_ppid` Same method for class instances .. py:method:: get_ppkw_from_ppid(segm_ppid) :staticmethod: Return keyword arguments for this pipeline identifier .. py:method:: is_available() :staticmethod: Subclasses may override this method e.g. if dependencies exist .. py:method:: log_info(logger) Allow segmenter to write informative log messages .. py:method:: process_labels(labels, *, clear_border: bool = True, fill_holes: bool = True, closing_disk: int = 5) :staticmethod: 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`. :param labels: Labeled input (contains blobs consisting of unique numbers) :type labels: 2d uint16 or boolean ndarray :param clear_border: clear the image boarder using an equivalent of :func:`skimage.segmentation.clear_border` :type clear_border: bool :param fill_holes: binary-fill-holes in the binary mask image using :func:`scipy.ndimage.binary_fill_holes` :type fill_holes: bool :param closing_disk: if > 0, perform a binary closing with a disk of that radius in pixels :type closing_disk: int or None .. py:method:: segment_algorithm(image) -> numpy.ndarray :staticmethod: :abstractmethod: The segmentation algorithm implemented in the subclass Perform segmentation and return boolean mask image .. py:method:: 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 .. py:method:: segment_batch(images, bg_off=None) :abstractmethod: Return the bollean mask for an entire batch This is implemented in the MPO and STO segmenters. .. py:method:: 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. .. py:method:: 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`. :param chunk_slot: The data chunk to perform segmentation on :type chunk_slot: ChunkSlot :returns: **mask** -- The `chunk_slot.mask` numpy view on the shared mask array. :rtype: np.array .. py:method:: segment_single(image, bg_off: float | None = None) :abstractmethod: Return the boolean mask for one image This is implemented in the MPO and STO segmenters. .. py:method:: 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. .. py:method:: close() Subclasses can implement clean-up code here .. py:method:: validate_applicability(segmenter_kwargs: dict, meta: dict | None = None, logs: dict | None = None) :classmethod: Validate the applicability of this segmenter for a dataset :param segmenter_kwargs: Keyword arguments for the segmenter :type segmenter_kwargs: dict :param meta: Dictionary of metadata from an :class:`.hdf5_data.HDF5Data` instance :type meta: dict :param logs: Dictionary of logs from an :class:`.hdf5_data.HDF5Data` instance :type logs: dict :returns: **applicable** -- True if the segmenter is applicable to the dataset :rtype: bool :raises SegmenterNotApplicableError: If the segmenter is not applicable to the dataset .. py:function:: assert_labels(arr) Make sure a labeling array is returned If `arr``is a boolean array, it is processed with `ndi.label`. .. py:function:: get_segmenters() .. py:function:: get_available_segmenters() Return dictionary of available segmenters