dcnum.segm.segmenter_mpo
========================

.. py:module:: dcnum.segm.segmenter_mpo


Attributes
----------

.. autoapisummary::

   dcnum.segm.segmenter_mpo.mp_spawn


Classes
-------

.. autoapisummary::

   dcnum.segm.segmenter_mpo.MPOSegmenter
   dcnum.segm.segmenter_mpo.MPOSegmenterWorker
   dcnum.segm.segmenter_mpo.MPOSegmenterWorkerProcess
   dcnum.segm.segmenter_mpo.MPOSegmenterWorkerThread


Module Contents
---------------

.. py:data:: mp_spawn
   :value: None


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

   Bases: :py:obj:`dcnum.segm.segmenter.Segmenter`, :py:obj:`abc.ABC`


   Segmenter with multiprocessing operation

   :param num_workers: Number of workers (processes) to spawn
   :param kwargs_mask: Keyword arguments for mask post-processing (see `process_labels`)
   :type kwargs_mask: dict
   :param debug: Debugging parameters
   :type debug: bool
   :param kwargs: Additional, optional keyword arguments for ``segment_algorithm``
                  defined in the subclass.


   .. py:attribute:: hardware_processor
      :value: 'cpu'


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


   .. py:attribute:: num_workers


   .. py:attribute:: slot_list
      :value: None


      List of ChunkSlot instances


   .. py:attribute:: mp_slot_index

      The slot that is currently being worked on


   .. py:attribute:: mp_active

      Event that defines whether the workers are allowed to do work


   .. py:attribute:: mp_num_workers_done

      Number of workers that are done processing the slot


   .. py:attribute:: mp_shutdown

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


   .. py:attribute:: _worker_starter
      :value: None



   .. py:attribute:: _workers
      :value: []



   .. py:method:: __enter__()


   .. py:method:: __exit__(exc_type, exc_val, exc_tb)


   .. py:method:: __getstate__()


   .. py:method:: __setstate__(state)


   .. py:method:: join_workers()

      Ask all workers to stop and join them



   .. py:method:: reinitialize_workers(slot_list)


   .. py:method:: 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.

      :param images: The time-series image data. First axis is time.
      :type images: 3d np.ndarray of shape (N, Y, X)
      :param bg_off: Optional 1D numpy array with background offset
      :type bg_off: 1D np.ndarray of length N

      .. rubric:: Notes

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



   .. py:method:: segment_chunk(chunk: int, slot_list: list)

      Segment the image data of one `ChunkSlot`

      :param chunk: The data chunk index to perform segmentation on
      :param slot_list: List of `ChunkSlotData` instances (e.g. `SlotRegister.slots`)

      :returns: **mask** -- The `chunk_slot.mask` numpy view on the shared boolean mask array.
      :rtype: np.array



   .. py:method:: 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.



   .. py:method:: close()

      Subclasses can implement clean-up code here



.. py:class:: MPOSegmenterWorker(segmenter, sl_start: int, sl_stop: int)

   Worker process for CPU-based segmentation

   :param segmenter: The segmentation instance
   :type segmenter: .segmenter_mpo.MPOSegmenter
   :param sl_start: Start of slice of input array to process
   :type sl_start: int
   :param sl_stop: Stop of slice of input array to process
   :type sl_stop: int


   .. py:attribute:: segmenter


   .. py:attribute:: slot_list

      List of ChunkSlot instances


   .. py:attribute:: mp_slot_index

      The slot that is currently being worked on


   .. py:attribute:: mp_active

      Whether the workers are allowed to do work


   .. py:attribute:: mp_num_workers_done

      Number of workers that are done processing the slot


   .. py:attribute:: mp_shutdown

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


   .. py:attribute:: sl_start


   .. py:attribute:: sl_stop


   .. py:method:: run()


.. py:class:: MPOSegmenterWorkerProcess(*args, **kwargs)

   Bases: :py:obj:`MPOSegmenterWorker`, :py:obj:`mp_spawn`


   Worker process for CPU-based segmentation

   :param segmenter: The segmentation instance
   :type segmenter: .segmenter_mpo.MPOSegmenter
   :param sl_start: Start of slice of input array to process
   :type sl_start: int
   :param sl_stop: Stop of slice of input array to process
   :type sl_stop: int


   .. py:method:: start()

      Start child process



.. py:class:: MPOSegmenterWorkerThread(*args, **kwargs)

   Bases: :py:obj:`MPOSegmenterWorker`, :py:obj:`threading.Thread`


   Worker process for CPU-based segmentation

   :param segmenter: The segmentation instance
   :type segmenter: .segmenter_mpo.MPOSegmenter
   :param sl_start: Start of slice of input array to process
   :type sl_start: int
   :param sl_stop: Stop of slice of input array to process
   :type sl_stop: int