larvaworld.lib.param.spatial
============================

.. py:module:: larvaworld.lib.param.spatial


Classes
-------

.. autoapisummary::

   larvaworld.lib.param.spatial.Pos2D
   larvaworld.lib.param.spatial.Pos2DPixel
   larvaworld.lib.param.spatial.RadiallyExtended
   larvaworld.lib.param.spatial.OrientedPoint
   larvaworld.lib.param.spatial.MobilePoint
   larvaworld.lib.param.spatial.MobileVector
   larvaworld.lib.param.spatial.LineExtended
   larvaworld.lib.param.spatial.LineClosed
   larvaworld.lib.param.spatial.Area2D
   larvaworld.lib.param.spatial.Area2DPixel
   larvaworld.lib.param.spatial.Area
   larvaworld.lib.param.spatial.PosPixelRel2Point
   larvaworld.lib.param.spatial.PosPixelRel2Area
   larvaworld.lib.param.spatial.BoundedArea


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

.. py:class:: Pos2D(**kwargs)

   Bases: :py:obj:`larvaworld.lib.param.nested_parameter_group.NestedConf`


   2D spatial position with tracking of position history.

   Tracks the current position as well as the initial and last positions,
   allowing computation of displacement between positions.

   Attributes:
       pos: The xy spatial position coordinates as (x, y) tuple
       initial_pos: The initial position when object was created
       last_pos: The previous position before the most recent update

   Example:
       >>> pos2d = Pos2D(pos=(1.0, 2.0))
       >>> pos2d.set_position((3.0, 4.0))
       >>> displacement = pos2d.last_delta_pos


   .. py:attribute:: pos


   .. py:attribute:: initial_pos


   .. py:attribute:: last_pos


   .. py:method:: get_position() -> tuple[float, float]


   .. py:method:: set_position(pos) -> None


   .. py:property:: x
      :type: float



   .. py:property:: y
      :type: float



   .. py:property:: last_delta_pos
      :type: float



.. py:class:: Pos2DPixel(**kwargs)

   Bases: :py:obj:`Pos2D`


   2D spatial position in pixel coordinates.

   Inherits all position tracking functionality from Pos2D but constrains
   coordinates to integer pixel values instead of floating-point meters.

   Attributes:
       pos: The xy spatial position coordinates as integer (x, y) tuple

   Example:
       >>> pixel_pos = Pos2DPixel(pos=(100, 200))
       >>> pixel_pos.x  # Returns 100


   .. py:attribute:: pos


.. py:class:: RadiallyExtended(**kwargs)

   Bases: :py:obj:`Pos2D`


   2D position with a circular spatial extent defined by radius.

   Extends a point position with a radius parameter, creating a circular
   region that can test point containment and generate shapely geometries.

   Attributes:
       radius: The spatial radius of the circular region in meters

   Example:
       >>> source = RadiallyExtended(pos=(0.0, 0.0), radius=0.01)
       >>> shape = source.get_shape()
       >>> is_inside = source.contained((0.005, 0.005))


   .. py:attribute:: radius


   .. py:method:: get_shape(scale=1) -> shapely.geometry.Point | None


   .. py:method:: contained(point) -> bool


.. py:class:: OrientedPoint(**kwargs)

   Bases: :py:obj:`Pos2D`


   2D position with orientation and rotation tracking.

   Extends Pos2D with orientation (heading angle) and provides methods for
   rotation transformations, pose updates, and tracking orientation changes.

   Attributes:
       orientation: The absolute orientation angle in radians
       initial_orientation: The initial orientation when object was created
       last_orientation: The previous orientation before most recent update

   Example:
       >>> point = OrientedPoint(pos=(0.0, 0.0), orientation=0.0)
       >>> point.update_pose((1.0, 1.0), np.pi/4)
       >>> rotated = point.translate((1.0, 0.0))


   .. py:attribute:: orientation


   .. py:attribute:: initial_orientation


   .. py:attribute:: last_orientation


   .. py:property:: rotationMatrix
      :type: numpy.ndarray



   .. py:method:: translate(point) -> tuple | list[tuple]


   .. py:method:: set_orientation(orientation) -> None


   .. py:method:: get_orientation() -> float


   .. py:method:: get_pose() -> tuple[numpy.ndarray, float]


   .. py:method:: update_pose(pos, orientation) -> None


   .. py:property:: last_delta_orientation
      :type: float



.. py:class:: MobilePoint(**kwargs)

   Bases: :py:obj:`OrientedPoint`


   Oriented point with velocity and motion tracking.

   Extends OrientedPoint with linear and angular velocities, accelerations,
   and cumulative distance tracking for moving entities.

   Attributes:
       lin_vel: Linear velocity in meters/second
       ang_vel: Angular velocity in radians/second
       ang_acc: Angular acceleration in radians/second²
       cum_dst: Cumulative distance traveled
       dst: Current distance from origin

   Example:
       >>> mobile = MobilePoint(pos=(0.0, 0.0), orientation=0.0)
       >>> mobile.update_all((1.0, 0.0), 0.1, 0.01, 0.1)


   .. py:attribute:: lin_vel
      :value: 0.0



   .. py:attribute:: ang_vel
      :value: 0.0



   .. py:attribute:: ang_acc
      :value: 0.0



   .. py:attribute:: cum_dst
      :value: 0.0



   .. py:attribute:: dst
      :value: 0.0



   .. py:method:: get_angularvelocity() -> float


   .. py:method:: get_linearvelocity() -> float


   .. py:method:: set_linearvelocity(lin_vel) -> None


   .. py:method:: set_angularvelocity(ang_vel) -> None


   .. py:method:: update_all(pos, orientation, lin_vel, ang_vel) -> None


.. py:class:: MobileVector(**kwargs)

   Bases: :py:obj:`MobilePoint`


   Mobile point with length representing a 1D body segment.

   Extends MobilePoint with a length parameter, providing front and rear
   end positions based on orientation and length.

   Attributes:
       length: The length of the body segment in meters

   Example:
       >>> vector = MobileVector(pos=(0.0, 0.0), orientation=0.0, length=0.01)
       >>> front = vector.front_end
       >>> rear = vector.rear_end


   .. py:attribute:: length


   .. py:property:: front_end
      :type: tuple



   .. py:property:: rear_end
      :type: tuple



   .. py:method:: drag_to_front(fp, d_or=0) -> None


.. py:class:: LineExtended(**kwargs: Any)

   Bases: :py:obj:`larvaworld.lib.param.nested_parameter_group.NestedConf`


   A line defined by vertices with configurable width and closure.

   Represents a polyline or polygon defined by a sequence of 2D vertices.
   Can be open or closed, and provides edge computation.

   Attributes:
       width: The width of the line for rendering/collision
       vertices: List of (x, y) coordinate tuples defining the line
       closed: Whether the line forms a closed loop

   Example:
       >>> line = LineExtended(vertices=[(0, 0), (1, 0), (1, 1)], width=0.01)
       >>> edges = line._edges


   .. py:attribute:: width


   .. py:attribute:: vertices


   .. py:attribute:: closed


   .. py:property:: Nvertices
      :type: int



.. py:class:: LineClosed(**kwargs: Any)

   Bases: :py:obj:`LineExtended`


   A closed line (polygon) defined by vertices.

   Inherits from LineExtended but enforces that the line is always closed,
   forming a polygon where the last vertex connects to the first.

   Example:
       >>> polygon = LineClosed(vertices=[(0, 0), (1, 0), (1, 1), (0, 1)])
       >>> polygon.closed  # Always True


   .. py:attribute:: closed


.. py:class:: Area2D(**kwargs: Any)

   Bases: :py:obj:`larvaworld.lib.param.nested_parameter_group.NestedConf`


   2D rectangular area with dimension and centering parameters.

   Defines a 2D rectangular region with width and height, optionally
   centered at the origin, with utilities for position transformation.

   Attributes:
       dims: The (width, height) dimensions in meters
       centered: Whether the area is centered at (0, 0)

   Example:
       >>> area = Area2D(dims=(0.2, 0.1), centered=True)
       >>> width = area.w
       >>> height = area.h


   .. py:attribute:: dims


   .. py:attribute:: centered


   .. py:property:: w
      :type: float



   .. py:property:: h
      :type: float



   .. py:property:: range
      :type: numpy.ndarray



   .. py:method:: adjust_pos_to_area(pos, area, scaling_factor=1) -> tuple | None


.. py:class:: Area2DPixel(**kwargs: Any)

   Bases: :py:obj:`Area2D`


   2D rectangular area in pixel coordinates.

   Extends Area2D with pixel-based dimensions and pygame rendering utilities.
   Provides methods for creating pygame Rects and computing relative positions.

   Attributes:
       dims: The (width, height) dimensions in integer pixels

   Example:
       >>> pixel_area = Area2DPixel(dims=(800, 600), centered=True)
       >>> rect = pixel_area.get_rect_at_pos((100, 100))


   .. py:attribute:: dims


   .. py:method:: get_rect_at_pos(pos=(0, 0), area=None, **kwargs)


   .. py:method:: get_relative_pos(pos_scale, reference=None) -> tuple[int, int]


   .. py:method:: get_relative_font_size(font_size_scale) -> int


.. py:class:: Area(**kwargs: Any)

   Bases: :py:obj:`Area2D`


   2D area with configurable geometry and topology.

   Extends Area2D with shape selection (circular/rectangular) and optional
   toroidal topology for wrap-around boundaries.

   Attributes:
       geometry: The arena shape ('circular' or 'rectangular')
       torus: Whether the space has toroidal (wrap-around) boundaries

   Example:
       >>> arena = Area(dims=(0.2, 0.2), geometry='circular', torus=False)


   .. py:attribute:: geometry


   .. py:attribute:: torus


.. py:class:: PosPixelRel2Point(**kwargs)

   Bases: :py:obj:`Pos2DPixel`


   Pixel position defined relative to a reference point.

   Automatically computes position as a scaled fraction of a reference
   point's coordinates, updating when the scale or reference changes.

   Attributes:
       reference_point: The reference Pos2DPixel instance
       pos_scale: Scale factors (w, h) applied to reference coordinates

   Example:
       >>> ref = Pos2DPixel(pos=(100, 200))
       >>> rel_pos = PosPixelRel2Point(reference_point=ref, pos_scale=(0.5, 0.5))
       >>> rel_pos.pos  # (50, 100)


   .. py:attribute:: reference_point


   .. py:attribute:: pos_scale


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


.. py:class:: PosPixelRel2Area(**kwargs)

   Bases: :py:obj:`Pos2DPixel`


   Pixel position defined relative to an area's dimensions.

   Automatically computes position as a scaled fraction of a reference
   area's width and height, updating when the scale or area changes.

   Attributes:
       reference_area: The reference Area2DPixel instance
       pos_scale: Scale factors (w, h) applied to area dimensions

   Example:
       >>> area = Area2DPixel(dims=(800, 600))
       >>> rel_pos = PosPixelRel2Area(reference_area=area, pos_scale=(0.5, 0.5))
       >>> rel_pos.pos  # (400, 300) - center of area


   .. py:attribute:: reference_area


   .. py:attribute:: pos_scale


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


.. py:class:: BoundedArea(vertices=None, **kwargs)

   Bases: :py:obj:`Area`, :py:obj:`LineClosed`


   Area with explicit boundary vertices forming a closed polygon.

   Combines Area and LineClosed to create an arena with defined geometry
   that can test point containment within its boundary polygon.

   Attributes:
       boundary_margin: Margin width relative to vertices (default 1.0)

   Example:
       >>> arena = BoundedArea(dims=(0.2, 0.2), geometry='circular')
       >>> is_inside = arena.in_area((0.05, 0.05))
       >>> polygon = arena.polygon


   .. py:attribute:: boundary_margin


   .. py:property:: polygon
      :type: shapely.Polygon



   .. py:method:: in_area(p) -> bool