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


Functions
---------

.. autoapisummary::

   robokudo.annotators.image_cluster_extractor.on_trackbar


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

.. py:function:: on_trackbar(x)

.. py:class:: ImageClusterExtractor(name='ImageClusterExtractor', descriptor=Descriptor())

   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.

   :ivar color: Input RGB color image
   :type color: numpy.ndarray
   :ivar depth: Input depth image
   :type depth: numpy.ndarray
   :ivar hsv: HSV converted color image
   :type hsv: numpy.ndarray
   :ivar cam_intrinsics: Camera intrinsic parameters
   :type cam_intrinsics: o3d.camera.PinholeCameraIntrinsic
   :ivar query: Current color query if any
   :type query: robokudo.types.Query
   :ivar display_mode: Current visualization mode
   :type display_mode: ImageClusterExtractor.ViewMode


   .. py:class:: ViewMode

      Visualization modes for the annotator output.

      :cvar masked_object: Show masked RGB image of detected objects
      :type masked_object: int
      :cvar depth_mask: Show depth mask of detected objects
      :type depth_mask: int


      .. py:attribute:: masked_object
         :value: 1



      .. py:attribute:: depth_mask
         :value: 2




   .. 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
            :value: (150, 130, 85)



         .. py:attribute:: hsv_max
            :value: (200, 255, 255)



         .. py:attribute:: erosion_iterations
            :value: 2



         .. py:attribute:: contour_min_size
            :value: 1000



         .. py:attribute:: color_name_to_hsv_range


         .. py:attribute:: outlier_removal
            :value: True



         .. py:attribute:: outlier_removal_nb_neighbors
            :value: 20



         .. py:attribute:: outlier_removal_std_ratio
            :value: 2.0



         .. py:attribute:: num_of_objects
            :value: 2



         .. py:attribute:: min_points_threshold
            :value: 62




      .. py:attribute:: parameters



   .. py:method:: dyn_rec_callback(config, level)


   .. py:attribute:: color
      :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.

      :return: None



   .. py:method:: update()

      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
      :rtype: py_trees.Status
      :raises Exception: If no contours found or processing fails



   .. py:method:: send_empty_query_answer()

      Send empty query result when no objects are found.

      Creates and sets an empty QueryResult message on the blackboard.

      :return: None



   .. py:method:: key_callback(key)

      Handle keyboard input to change visualization mode.

      :param key: ASCII value of pressed key
      :type key: int
      :return: None