robot.table_map
===============

.. py:module:: robot.table_map

.. autoapi-nested-parse::

   Table map model for Botball field geometry.

   Stores line and wall segments from the .ftmap vector format and provides
   spatial queries (point-on-line, point-on-wall, distance-to-nearest-line).

   The coordinate system matches the Botball field: origin at bottom-left,
   X right, Y up, all values in centimeters.

   Example usage::

       from raccoon.robot.table_map import TableMap

       # Load from ftmap dict (as stored in raccoon.project.yml)
       table_map = TableMap.from_ftmap(config["robot"]["physical"]["table_map"])

       # Load from .ftmap file
       table_map = TableMap.load("config/table_map.ftmap")

       # Query
       table_map.is_on_line(50.0, 30.0)       # True/False
       table_map.is_on_wall(0.0, 50.0)        # True/False
       table_map.distance_to_nearest_line(50.0, 30.0)  # cm



Classes
-------

.. autoapisummary::

   robot.table_map.MapSegment
   robot.table_map.TableMap


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

.. py:class:: MapSegment

   A single line or wall segment on the field, in centimeters.


   .. py:attribute:: start_x
      :type:  float


   .. py:attribute:: start_y
      :type:  float


   .. py:attribute:: end_x
      :type:  float


   .. py:attribute:: end_y
      :type:  float


   .. py:attribute:: width_cm
      :type:  float


   .. py:attribute:: kind
      :type:  str


   .. py:property:: length
      :type: float



.. py:class:: TableMap(width_cm: float, height_cm: float, segments: Sequence[MapSegment] = ())

   Botball field table map with line and wall segments.

   All coordinates are in centimeters with origin at bottom-left of the field.


   .. py:attribute:: width_cm


   .. py:attribute:: height_cm


   .. py:property:: lines
      :type: List[MapSegment]



   .. py:property:: walls
      :type: List[MapSegment]



   .. py:property:: all_segments
      :type: List[MapSegment]



   .. py:method:: from_ftmap(data: Dict[str, Any]) -> TableMap
      :classmethod:


      Create a TableMap from an ftmap dict (as stored in project config).

      :param data: Dict with keys ``format``, ``version``, ``table``, ``lines``.

      :returns: A populated TableMap instance.

      :raises ValueError: If the format or version is unsupported.



   .. py:method:: load(path: str | pathlib.Path) -> TableMap
      :classmethod:


      Load a TableMap from a ``.ftmap`` JSON file.

      :param path: Path to the .ftmap file.

      :returns: A populated TableMap instance.



   .. py:method:: to_ftmap() -> Dict[str, Any]

      Serialize this TableMap back to the ftmap dict format.



   .. py:method:: distance_to_nearest_line(x_cm: float, y_cm: float) -> float

      Shortest distance from a point to any line segment centerline.

      :param x_cm: X position on field (cm from left).
      :param y_cm: Y position on field (cm from bottom).

      :returns: Distance in cm, or ``float('inf')`` if there are no lines.



   .. py:method:: distance_to_nearest_wall(x_cm: float, y_cm: float) -> float

      Shortest distance from a point to any wall segment centerline.

      :param x_cm: X position on field (cm from left).
      :param y_cm: Y position on field (cm from bottom).

      :returns: Distance in cm, or ``float('inf')`` if there are no walls.



   .. py:method:: is_on_line(x_cm: float, y_cm: float) -> bool

      Check if a point is within any line segment's width.

      A point is "on" a line if its perpendicular distance to the segment
      centerline is less than half the line's width.

      :param x_cm: X position on field (cm from left).
      :param y_cm: Y position on field (cm from bottom).

      :returns: True if the point overlaps a line.



   .. py:method:: is_on_wall(x_cm: float, y_cm: float) -> bool

      Check if a point is within any wall segment's width.

      :param x_cm: X position on field (cm from left).
      :param y_cm: Y position on field (cm from bottom).

      :returns: True if the point overlaps a wall.



   .. py:method:: sensor_field_position(robot_x_cm: float, robot_y_cm: float, robot_heading_rad: float, sensor: raccoon.robot.geometry.SensorPosition) -> tuple[float, float]

      Compute the field position of a sensor given robot pose.

      The robot pose is in field coordinates (origin bottom-left, heading 0 = +X, CCW positive).
      The sensor position is in robot-relative coordinates (forward/strafe from geometric center).

      :param robot_x_cm: Robot center X on field (cm).
      :param robot_y_cm: Robot center Y on field (cm).
      :param robot_heading_rad: Robot heading (radians, 0 = +X, CCW positive).
      :param sensor: SensorPosition with forward_cm and strafe_cm offsets.

      :returns: Tuple of (field_x_cm, field_y_cm) for the sensor.



   .. py:method:: sensor_is_on_line(robot_x_cm: float, robot_y_cm: float, robot_heading_rad: float, sensor: raccoon.robot.geometry.SensorPosition) -> bool

      Check if a sensor would be over a black line given current robot pose.

      :param robot_x_cm: Robot center X on field (cm).
      :param robot_y_cm: Robot center Y on field (cm).
      :param robot_heading_rad: Robot heading (radians).
      :param sensor: SensorPosition offset from robot center.

      :returns: True if the sensor's field position overlaps a line.



   .. py:method:: sensor_is_on_wall(robot_x_cm: float, robot_y_cm: float, robot_heading_rad: float, sensor: raccoon.robot.geometry.SensorPosition) -> bool

      Check if a sensor would be over a wall given current robot pose.

      :param robot_x_cm: Robot center X on field (cm).
      :param robot_y_cm: Robot center Y on field (cm).
      :param robot_heading_rad: Robot heading (radians).
      :param sensor: SensorPosition offset from robot center.

      :returns: True if the sensor's field position overlaps a wall.