larvaworld.lib.param.xy_distro
==============================

.. py:module:: larvaworld.lib.param.xy_distro


Classes
-------

.. autoapisummary::

   larvaworld.lib.param.xy_distro.Spatial_Distro
   larvaworld.lib.param.xy_distro.Larva_Distro


Functions
---------

.. autoapisummary::

   larvaworld.lib.param.xy_distro.xy_along_circle
   larvaworld.lib.param.xy_distro.xy_along_rect
   larvaworld.lib.param.xy_distro.xy_uniform_circle
   larvaworld.lib.param.xy_distro.xy_grid
   larvaworld.lib.param.xy_distro.generate_xy_distro
   larvaworld.lib.param.xy_distro.generate_xyNor_distro


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

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

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


   2D spatial distribution configuration for agent placement.

   Defines how agents are distributed in 2D space using various shapes
   (circle, rect, oval) and placement modes (uniform, normal, periphery, grid).

   Attributes:
       shape: Distribution shape ('circle', 'rect', 'oval')
       mode: Placement mode ('uniform', 'normal', 'periphery', 'grid')
       N: Number of agents to place
       loc: Center coordinates (x, y) of the distribution
       scale: Spread or radius in (x, y) dimensions

   Example:
       >>> distro = Spatial_Distro(shape='circle', mode='uniform', N=50)
       >>> positions = distro()


   .. py:attribute:: shape


   .. py:attribute:: mode


   .. py:attribute:: N


   .. py:attribute:: loc


   .. py:attribute:: scale


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


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

   Bases: :py:obj:`Spatial_Distro`


   Spatial distribution with orientation for larva agents.

   Extends Spatial_Distro to include random orientation angles for larvae,
   generating both positions and orientations.

   Attributes:
       orientation_range: Range of orientations to sample from, in degrees

   Example:
       >>> distro = Larva_Distro(N=20, orientation_range=(0, 180))
       >>> positions, orientations = distro()


   .. py:attribute:: orientation_range


.. py:function:: xy_along_circle(N: int, loc: Tuple[float, float], radius: Tuple[float, float]) -> List[Tuple[float, float]]

   Generate N points evenly distributed along a circle/ellipse periphery.

   Args:
       N: Number of points to generate
       loc: Center coordinates (x, y)
       radius: Radius in (x, y) dimensions for ellipse

   Returns:
       List of (x, y) coordinate tuples along the periphery


.. py:function:: xy_along_rect(N: int, loc: Tuple[float, float], scale: Tuple[float, float]) -> List[Tuple[float, float]]

   Generate N points evenly distributed along rectangle periphery.

   Args:
       N: Number of points to generate
       loc: Center coordinates (x, y)
       scale: Half-dimensions (half-width, half-height)

   Returns:
       List of (x, y) coordinate tuples along the rectangle edges


.. py:function:: xy_uniform_circle(N: int, loc: Tuple[float, float], scale: Tuple[float, float]) -> List[Tuple[float, float]]

   Generate N points uniformly distributed within a circle/ellipse.

   Args:
       N: Number of points to generate
       loc: Center coordinates (x, y)
       scale: Radius in (x, y) dimensions

   Returns:
       List of (x, y) coordinate tuples within the circle


.. py:function:: xy_grid(grid_dims: Tuple[int, int], area: Tuple[float, float], loc: Tuple[float, float] = (0.0, 0.0)) -> List[Tuple[float, float]]

   Generate points arranged in a regular grid pattern.

   Args:
       grid_dims: Grid dimensions (Nx, Ny)
       area: Total area dimensions (width, height)
       loc: Center coordinates (x, y)

   Returns:
       List of (x, y) coordinate tuples in grid arrangement


.. py:function:: generate_xy_distro(mode: str, shape: str, N: int | Tuple[int, int], loc: Tuple[float, float] = (0.0, 0.0), scale: Tuple[float, float] = (0.0, 0.0), area: Optional[Tuple[float, float]] = None) -> List[Tuple[float, float]]

   Generate 2D spatial distribution of N points.

   Main distribution generator supporting multiple shapes and placement modes.

   Args:
       mode: Placement mode ('uniform', 'normal', 'periphery', 'grid')
       shape: Distribution shape ('circle', 'oval', 'rect')
       N: Number of points (or grid dimensions for grid mode)
       loc: Center coordinates (x, y)
       scale: Spread/radius in (x, y) dimensions
       area: Area dimensions for grid mode (defaults to scale)

   Returns:
       List of (x, y) coordinate tuples

   Example:
       >>> positions = generate_xy_distro('uniform', 'circle', 100, (0,0), (0.05, 0.05))


.. py:function:: generate_xyNor_distro(d: Larva_Distro) -> Tuple[List[Tuple[float, float]], List[float]]

   Generate positions and orientations for larva distribution.

   Args:
       d: Larva_Distro configuration object

   Returns:
       Tuple of (positions, orientations) where positions is list of (x,y)
       tuples and orientations is list of angles in radians

   Example:
       >>> distro = Larva_Distro(N=20, orientation_range=(0, 180))
       >>> positions, orientations = generate_xyNor_distro(distro)