robokudo.annotators.image_cluster_extractor
===========================================

.. py:module:: robokudo.annotators.image_cluster_extractor

.. autoapi-nested-parse::

   Image-based object cluster extraction.

   This module provides functionality for extracting object clusters from color images using HSV color segmentation.
   The main class :class:`ImageClusterExtractor` implements color-based segmentation and contour detection to identify
   object clusters in RGB images.

   Key features:

   * HSV color space thresholding
   * Contour detection and filtering
   * 3D point cloud generation from depth data
   * ROI and mask generation
   * Query-based color parameter adjustment
   * Visualization of detected clusters



Classes
-------

.. autoapisummary::

   robokudo.annotators.image_cluster_extractor.ImageClusterExtractor


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

.. py:class:: ImageClusterExtractor(name: str = 'ImageClusterExtractor', descriptor: ImageClusterExtractor | None = None)

   Bases: :py:obj:`robokudo.annotators.core.BaseAnnotator`


   Extract object clusters from images using color segmentation.

   This annotator performs the following steps:

   * Converts RGB image to HSV color space
   * Applies HSV thresholding based on configured parameters
   * Detects and filters contours based on size
   * Generates point clouds from depth data for each contour
   * Creates ObjectHypothesis annotations with ROIs and masks
   * Provides visualization of detected clusters

   The HSV thresholds can be adjusted dynamically based on color queries.


   .. py:class:: ViewMode

      Visualization modes for the annotator output.


      .. py:attribute:: masked_object
         :type:  int
         :value: 1


         Show masked RGB image of detected objects.



      .. py:attribute:: depth_mask
         :type:  int
         :value: 2


         Show depth mask of detected objects.




   .. py:class:: Descriptor

      Bases: :py:obj:`robokudo.annotators.core.BaseAnnotator.Descriptor`


      Configuration descriptor for ImageClusterExtractor.

      Parameters:

      * HSV thresholding ranges
      * Contour filtering parameters
      * Point cloud generation settings
      * Color name to HSV range mappings
      * Outlier removal parameters


      .. py:class:: Parameters

         Parameter class containing all configurable settings.


         .. py:attribute:: hsv_min
            :type:  typing_extensions.Tuple[int, int, int]
            :value: (150, 130, 85)



         .. py:attribute:: hsv_max
            :type:  typing_extensions.Tuple[int, int, int]
            :value: (200, 255, 255)



         .. py:attribute:: erosion_iterations
            :type:  int
            :value: 2



         .. py:attribute:: contour_min_size
            :type:  int
            :value: 1000



         .. py:attribute:: color_name_to_hsv_range
            :type:  typing_extensions.Dict[str, typing_extensions.Dict[str, typing_extensions.Tuple[int, int, int]]]


         .. py:attribute:: outlier_removal
            :type:  bool
            :value: True



         .. py:attribute:: outlier_removal_nb_neighbors
            :type:  int
            :value: 20



         .. py:attribute:: outlier_removal_std_ratio
            :type:  float
            :value: 2.0



         .. py:attribute:: num_of_objects
            :type:  int
            :value: 2



         .. py:attribute:: min_points_threshold
            :type:  int
            :value: 62




      .. py:attribute:: parameters



   .. py:attribute:: color
      :type:  typing_extensions.Optional[numpy.typing.NDArray]
      :value: None



   .. py:attribute:: depth
      :type:  typing_extensions.Optional[numpy.typing.NDArray]
      :value: None



   .. py:attribute:: query
      :value: None



   .. py:attribute:: camera_intrinsics
      :value: None



   .. py:attribute:: display_mode
      :value: 1



   .. py:method:: adjust_hsv_threshold_to_query() -> None

      Adjust HSV thresholds based on color query.

      Checks for a color query in the CAS and updates the HSV thresholding parameters
      if a matching color is found in the color_name_to_hsv_range mapping.



   .. py:method:: _threshold_hsv(hsv_min: typing_extensions.Tuple[int, int, int], hsv_max: typing_extensions.Tuple[int, int, int]) -> numpy.typing.NDArray

      Threshold ``self.hsv`` to the given bounds, wrapping the hue channel around the
      0/255 seam when ``hsv_min``'s hue exceeds ``hsv_max``'s.

      True red sits exactly at that seam, so a single contiguous hue range only ever
      catches one side of it (confirmed live: a plain ``[215,255]`` range matched 124
      of 101760 pixels on a red object; wrapping recovered 1748 by also matching the
      pixels that wrapped to just above 0).

      :param hsv_min: Lower HSV bound.
      :param hsv_max: Upper HSV bound. A hue lower than ``hsv_min``'s signals wraparound.
      :return: Binary mask of pixels within the (possibly wrapped) bounds.



   .. py:method:: update() -> py_trees.common.Status

      Process input images to detect and annotate object clusters.

      The method:

      * Scales color image to match depth image
      * Converts to HSV and applies thresholding
      * Detects and filters contours
      * Generates point clouds for each contour
      * Creates ObjectHypothesis annotations
      * Generates visualization output

      :return: SUCCESS if clusters found, FAILURE if no clusters
      :raises ImageContourMissing: If no contours are found



   .. py:method:: key_callback(key: int) -> None

      Handle keyboard input to change visualization mode.

      :param key: ASCII value of pressed key