robokudo.annotators.cluster_color_histogram
===========================================

.. py:module:: robokudo.annotators.cluster_color_histogram

.. autoapi-nested-parse::

   Color histogram analysis for object hypotheses.

   This module provides an annotator for:

   * Calculating 2D color histograms for object hypotheses
   * Analyzing hue and saturation distributions
   * Supporting masked ROI analysis
   * Optional visualization of histogram plots

   The module uses:

   * HSV color space for analysis
   * 2D histograms for hue-saturation distributions
   * Matplotlib for optional visualization

   .. note::
      Histogram plotting is optional and can be disabled for performance.



Classes
-------

.. autoapisummary::

   robokudo.annotators.cluster_color_histogram.ClusterColorHistogramAnnotator


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

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

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


   Hue and saturation histogram analysis for object hypotheses with RGB ROI and Mask.

   This annotator:

   * Calculates 2D histograms of hue and saturation
   * Processes masked ROIs from object hypotheses
   * Normalizes histogram distributions
   * Optionally generates visualization plots

   .. warning::
      Histogram plotting can significantly impact performance (200-500ms).


   .. py:class:: Descriptor

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


      Configuration descriptor for color histogram analysis.


      .. py:class:: Parameters

         Parameters for configuring histogram calculation.

         Histogram parameters:

         :ivar histogram_cols: Number of histogram columns (hue bins), defaults to 16
         :type histogram_cols: int
         :ivar histogram_rows: Number of histogram rows (saturation bins), defaults to 16
         :type histogram_rows: int

         Visualization:

         :ivar generate_plot_output: Whether to generate histogram plots, defaults to False
         :type generate_plot_output: bool


         .. py:attribute:: histogram_cols
            :value: 16



         .. py:attribute:: histogram_rows
            :value: 16



         .. py:attribute:: generate_plot_output
            :value: False




      .. py:attribute:: parameters



   .. py:method:: update()

      Process object hypotheses and calculate color histograms.

      The method:

      * Loads point cloud and color image from CAS
      * Creates color histogram annotations
      * Updates visualization if enabled

      :return: SUCCESS after processing
      :rtype: py_trees.Status



   .. py:method:: create_color_histogram_annotations(color: numpy.typing.NDArray)

      Calculate 2D color histograms for object hypotheses.

      For each object hypothesis with a valid ROI mask:

      * Extracts color image region and mask
      * Converts to HSV color space
      * Calculates 2D histogram of hue and saturation
      * Normalizes histogram distribution
      * Creates histogram annotation
      * Optionally generates visualization plot

      :param color: Input color image
      :type color: numpy.ndarray
      :return: Combined histogram plot image if enabled, None otherwise
      :rtype: numpy.ndarray or None