larvaworld.lib.param.spatial

Classes

`Pos2D`	2D spatial position with tracking of position history.
`Pos2DPixel`	2D spatial position in pixel coordinates.
`RadiallyExtended`	2D position with a circular spatial extent defined by radius.
`OrientedPoint`	2D position with orientation and rotation tracking.
`MobilePoint`	Oriented point with velocity and motion tracking.
`MobileVector`	Mobile point with length representing a 1D body segment.
`LineExtended`	A line defined by vertices with configurable width and closure.
`LineClosed`	A closed line (polygon) defined by vertices.
`Area2D`	2D rectangular area with dimension and centering parameters.
`Area2DPixel`	2D rectangular area in pixel coordinates.
`Area`	2D area with configurable geometry and topology.
`PosPixelRel2Point`	Pixel position defined relative to a reference point.
`PosPixelRel2Area`	Pixel position defined relative to an area's dimensions.
`BoundedArea`	Area with explicit boundary vertices forming a closed polygon.

Module Contents

class larvaworld.lib.param.spatial.Pos2D(**kwargs)

Bases: 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

pos

initial_pos

last_pos

get_position() → tuple[float, float]

set_position(pos) → None

property x: float

property y: float

property last_delta_pos: float

class larvaworld.lib.param.spatial.Pos2DPixel(**kwargs)

Bases: 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

pos

class larvaworld.lib.param.spatial.RadiallyExtended(**kwargs)

Bases: 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))

radius

get_shape(scale=1) → shapely.geometry.Point | None

contained(point) → bool

class larvaworld.lib.param.spatial.OrientedPoint(**kwargs)

Bases: 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))

orientation

initial_orientation

last_orientation

property rotationMatrix: numpy.ndarray

translate(point) → tuple | list[tuple]

set_orientation(orientation) → None

get_orientation() → float

get_pose() → tuple[numpy.ndarray, float]

update_pose(pos, orientation) → None

property last_delta_orientation: float

class larvaworld.lib.param.spatial.MobilePoint(**kwargs)

Bases: 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)

lin_vel = 0.0

ang_vel = 0.0

ang_acc = 0.0

cum_dst = 0.0

dst = 0.0

get_angularvelocity() → float

get_linearvelocity() → float

set_linearvelocity(lin_vel) → None

set_angularvelocity(ang_vel) → None

update_all(pos, orientation, lin_vel, ang_vel) → None

class larvaworld.lib.param.spatial.MobileVector(**kwargs)

Bases: 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

length

property front_end: tuple

property rear_end: tuple

drag_to_front(fp, d_or=0) → None

class larvaworld.lib.param.spatial.LineExtended(**kwargs: Any)

Bases: 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

width

vertices

closed

property Nvertices: int

class larvaworld.lib.param.spatial.LineClosed(**kwargs: Any)

Bases: 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

closed

class larvaworld.lib.param.spatial.Area2D(**kwargs: Any)

Bases: 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

dims

centered

property w: float

property h: float

property range: numpy.ndarray

adjust_pos_to_area(pos, area, scaling_factor=1) → tuple | None

class larvaworld.lib.param.spatial.Area2DPixel(**kwargs: Any)

Bases: 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))

dims

get_rect_at_pos(pos=(0, 0), area=None, **kwargs)

get_relative_pos(pos_scale, reference=None) → tuple[int, int]

get_relative_font_size(font_size_scale) → int

class larvaworld.lib.param.spatial.Area(**kwargs: Any)

Bases: 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)

geometry

torus

class larvaworld.lib.param.spatial.PosPixelRel2Point(**kwargs)

Bases: 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)

reference_point

pos_scale

update_pos() → None

class larvaworld.lib.param.spatial.PosPixelRel2Area(**kwargs)

Bases: 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

reference_area

pos_scale

update_pos() → None

class larvaworld.lib.param.spatial.BoundedArea(vertices=None, **kwargs)

Bases: Area, 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

boundary_margin

property polygon: shapely.Polygon

in_area(p) → bool