robokudo.annotators.cluster_position
====================================

.. py:module:: robokudo.annotators.cluster_position

.. autoapi-nested-parse::

   3D position estimation for object hypotheses.

   This module provides an annotator for:

   * Calculating 3D positions for object hypotheses
   * Supporting different analysis scopes
   * Computing centroids from point clouds
   * Generating visualization markers

   The module uses:

   * Point cloud centroid computation
   * Covariance analysis
   * Open3D visualization tools
   * Flexible annotation types

   .. note::
      Can analyze either ObjectHypothesis or CloudAnnotation data.



Classes
-------

.. autoapisummary::

   robokudo.annotators.cluster_position.ClusterPositionAnnotator


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

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

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


   3D position estimation for object hypotheses.

   This annotator:

   * Calculates 3D positions from point clouds
   * Supports multiple analysis scopes
   * Computes centroids and covariance
   * Creates position annotations
   * Generates visualization markers

   .. note::
      Can process either ObjectHypothesis or CloudAnnotation data.


   .. py:class:: Descriptor

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


      Configuration descriptor for position estimation.


      .. py:class:: Parameters

         Parameters for configuring position estimation.

         Analysis parameters:

         :ivar analysis_scope: Type of data to analyze (ObjectHypothesis or CloudAnnotation), defaults to ObjectHypothesis
         :type analysis_scope: type

         Visualization:

         :ivar visualizer_point_radius: Radius of centroid sphere markers in meters, defaults to 0.04
         :type visualizer_point_radius: float


         .. py:attribute:: analysis_scope


         .. py:attribute:: visualizer_point_radius
            :value: 0.04





   .. py:method:: update()

      Process object hypotheses and estimate positions.

      The method:

      * Loads point cloud from CAS
      * For each object hypothesis:
        * Gets appropriate point cloud data
        * Computes centroid and covariance
        * Creates position annotation
        * Creates visualization marker

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



   .. py:method:: position_annotation_from_centroid(centroid)

      Create position annotation from centroid.

      :param centroid: 3D centroid coordinates
      :type centroid: numpy.ndarray
      :return: Position annotation with centroid as translation
      :rtype: robokudo.types.annotation.PositionAnnotation



   .. py:method:: add_centroid_to_vis(centroid, centroids_to_visualize)

      Add centroid visualization marker.

      Creates a colored sphere at the centroid position.

      :param centroid: 3D centroid coordinates
      :type centroid: numpy.ndarray
      :param centroids_to_visualize: List to append visualization marker to
      :type centroids_to_visualize: list