robokudo.annotators.cluster_pose_bb
===================================

.. py:module:: robokudo.annotators.cluster_pose_bb

.. autoapi-nested-parse::

   3D pose estimation using oriented bounding boxes.

   This module provides an annotator for:

   * Calculating 3D poses for object hypotheses
   * Using z-axis aligned oriented bounding boxes
   * Supporting world frame alignment
   * Generating visualization markers

   The module uses:

   * 2D projection for rotation estimation
   * Minimum area rectangles for orientation
   * Coordinate frame transformations
   * Open3D visualization tools

   .. note::
      By default, z-axis is aligned with world frame up direction.



Classes
-------

.. autoapisummary::

   robokudo.annotators.cluster_pose_bb.ClusterPoseBBAnnotator


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

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

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


   3D pose estimation using oriented bounding boxes.

   This annotator:

   * Calculates 3D poses for object point clusters
   * Uses z-axis aligned oriented bounding boxes
   * Projects points to 2D for rotation estimation
   * Creates pose and bounding box annotations
   * Supports axis alignment by box extents

   .. note::
      Default behavior aligns z-axis with world frame up direction.


   .. py:class:: Descriptor

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


      Configuration descriptor for pose estimation.


      .. py:class:: Parameters

         Parameters for configuring pose estimation.

         Alignment parameters:

         :ivar align_x_axis_by_max_bbox_extent: Whether to align x-axis with longest box side, defaults to False
         :type align_x_axis_by_max_bbox_extent: bool

         Visualization:

         :ivar bounding_box_visualization_color: RGB color for box visualization, defaults to [0,0,0]
         :type bounding_box_visualization_color: list


         .. py:attribute:: align_x_axis_by_max_bbox_extent
            :value: False



         .. py:attribute:: bounding_box_visualization_color
            :value: [0, 0, 0]




      .. py:attribute:: parameters



   .. py:method:: adjust_bb_orientation_by_bb_size(pose_orientation: numpy.typing.NDArray, bounding_box_extents: list) -> (numpy.typing.NDArray, list)

      Align bounding box axes with extent dimensions.

      Reorients the bounding box so that:

      * X-axis aligns with longest dimension
      * Y-axis aligns with second longest
      * Z-axis aligns with shortest dimension

      :param pose_orientation: Current orientation as 3x3 rotation matrix
      :type pose_orientation: numpy.ndarray
      :param bounding_box_extents: Current box dimensions [x,y,z]
      :type bounding_box_extents: list
      :return: Tuple of (aligned orientation matrix, reordered extents)
      :rtype: tuple(numpy.ndarray, list)



   .. py:method:: update()

      Process object hypotheses and estimate poses.

      The method:

      * Loads point cloud from CAS
      * For each object hypothesis:
        * Transforms points to world frame
        * Projects to 2D for orientation estimation
        * Calculates minimum area rectangle
        * Creates oriented bounding box
        * Generates pose and box annotations
        * Creates visualization markers

      :return: SUCCESS after processing, FAILURE if transform not found
      :rtype: py_trees.Status