grasp_closeness
===============

.. py:module:: grasp_closeness


Classes
-------

.. autoapisummary::

   grasp_closeness.GraspCloseness
   grasp_closeness.GraspsByCloseness


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

.. py:class:: GraspCloseness

   How close a grasp is to where the robot stands: a grasp nearer by horizontal
   distance is closer, and of two equally near grasps the one approached more directly
   from the standing position is.


   .. py:attribute:: horizontal_distance
      :type:  float

      The horizontal distance from the standing position to the grasp, in meters.



   .. py:attribute:: approach_angle
      :type:  float

      The angle between the direction the grasp is approached along and the direction from
      the standing position to it, in radians.



   .. py:method:: from_grasp(grasp: semantic_digital_twin.grasping.grasp_candidates.GraspCandidate, world_T_object: numpy.typing.NDArray[numpy.float64], world_P_standing: numpy.typing.NDArray[numpy.float64]) -> GraspCloseness
      :classmethod:


      :param grasp: A grasp on the object.
      :param world_T_object: The object's root frame in the world frame.
      :param world_P_standing: Where the robot stands, as a homogeneous point in the
          world frame.
      :return: How close `grasp` is to the standing position.



.. py:class:: GraspsByCloseness

   Bases: :py:obj:`krrood.entity_query_language.predicate.SymbolicFunction`


   The grasps an object offers, ordered by their :class:`GraspCloseness` to a standing
   position, the closest first, and at most :attr:`number_of_grasps` of them.


   .. py:attribute:: graspable
      :type:  semantic_digital_twin.semantic_annotations.mixins.HasGraspCandidates

      The object offering the grasps.



   .. py:attribute:: standing_position
      :type:  krrood_spatial_math.spatial_types.Pose

      Where the robot stands while taking one of the grasps, read when the grasps are
      ranked, so a pose relative to the robot is where the robot stands then.



   .. py:attribute:: number_of_grasps
      :type:  int | None
      :value: 3


      How many of the closest grasps are kept, all of them if None.



   .. py:method:: __call__() -> list[semantic_digital_twin.grasping.grasp_candidates.GraspCandidate]

      Compute the value for the supplied arguments.



   .. py:method:: _verbalization_fragment_(fields: krrood.entity_query_language.predicate.RenderedFields) -> krrood.entity_query_language.verbalization.fragments.base.VerbalizationFragment
      :classmethod:


      :param fields: The rendered fragment for each field.
      :return: The noun phrase *"the grasps by closeness of <graspable> and <standing
          position>"*.