robokudo.annotators.location
============================

.. py:module:: robokudo.annotators.location

.. autoapi-nested-parse::

   Location annotator for RoboKudo.

   This module provides an annotator for determining object locations relative to semantic regions.
   It supports:

   * Semantic map integration
   * Region-based location analysis
   * Percentage-based containment checks
   * World frame transformations
   * Multi-region handling

   The module is used for:

   * Object localization
   * Spatial reasoning
   * Scene understanding
   * Region-based filtering



Classes
-------

.. autoapisummary::

   robokudo.annotators.location.LocationAnnotator


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

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

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


   Determine object locations within semantic regions.

   The purpose of this location annotator is to receive a list of intriguing regions and incorporate the
   corresponding region names into the location annotations for objects that reside within those specific regions.

   The annotator:

   * Loads and manages semantic map data
   * Transforms regions between world and camera frames
   * Checks object containment in regions
   * Creates location annotations for contained objects
   * Supports filtering by desired regions
   * Handles coordinate frame transformations

   :ivar semantic_map: Loaded semantic map instance
   :type semantic_map: robokudo.semantic_map.SemanticMap


   .. py:class:: Descriptor

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


      Configuration descriptor for location annotator.

      :ivar parameters: Location analysis parameters
      :type parameters: LocationAnnotator.Descriptor.Parameters


      .. py:class:: Parameters

         Parameter container for location configuration.

         :ivar percentage: Threshold percentage for region containment
         :type percentage: int
         :ivar world_frame_name: Name of the world coordinate frame
         :type world_frame_name: str
         :ivar semantic_map_ros_package: ROS package containing semantic map
         :type semantic_map_ros_package: str
         :ivar semantic_map_name: Name of semantic map descriptor
         :type semantic_map_name: str
         :ivar desired_regions: List of regions to consider
         :type desired_regions: list[str]


         .. py:attribute:: percentage
            :value: 50



         .. py:attribute:: world_frame_name
            :value: 'map'



         .. py:attribute:: semantic_map_ros_package
            :value: 'robokudo'



         .. py:attribute:: semantic_map_name
            :value: 'semantic_map_iai_kitchen'



         .. py:attribute:: desired_regions
            :value: ['kitchen_island']




      .. py:attribute:: parameters



   .. py:attribute:: semantic_map
      :value: None



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

      Load semantic map from configured package and name.

      Uses ModuleLoader to dynamically load the semantic map descriptor
      from the configured ROS package.

      :return: None



   .. py:method:: add_location_in_object_hypotheses(region_name: str, region, world_to_cam_transform_matrix, object_hypotheses) -> None

      Add location annotations to objects within a region.

      For each object hypothesis:

      * Transforms region to camera frame
      * Checks point containment in region
      * Calculates containment percentage
      * Creates location annotation if above threshold

      :param region_name: Name of the region to check
      :type region_name: str
      :param region: Semantic map region entry
      :type region: robokudo.semantic_map.SemanticMapEntry
      :param world_to_cam_transform_matrix: Transform from world to camera frame
      :type world_to_cam_transform_matrix: numpy.ndarray
      :param object_hypotheses: List of object hypotheses to check
      :type object_hypotheses: list[robokudo.types.scene.ObjectHypothesis]
      :return: None



   .. py:method:: compute()

      Process object hypotheses to determine their locations.

      The method:

      * Loads and updates semantic map
      * Gets camera to world transform
      * For each active region:
          * Checks if region is in desired list
          * Processes objects in region
          * Adds location annotations

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