scatter_in_bbox

Function

scatter_in_bbox(
    states: list[State],
    x: float,
    y: float,
    width: float,
    height: float,
    seed: Optional[int] = None,
    alignment: ElementAlignment = <ElementAlignment.PRESERVE: 'preserve'>,
    element_rotation_offset: float = 0
) -> list[State]

Arrange states randomly within a bounding box.

Alternative specification to scatter() for users who think in terms of bounding boxes rather than min/max ranges. Elements will be randomly placed within the specified rectangle.

Parameters

states: List of states to arrange
x: X coordinate of bounding box top-left corner
y: Y coordinate of bounding box top-left corner
width: Width of bounding box
height: Height of bounding box
seed: Optional random seed for reproducibility
alignment: How to align each element relative to the layout
element_rotation_offset: Additional rotation in degrees added to the alignment base

Returns

New list of states with random positions Raises: ValueError: If width or height is zero or negative

Examples

# Random scatter in 400x300 box
    scatter_in_bbox(states, 0, 0, 400, 300, seed=42)

    # Reproducible scatter in square area
    scatter_in_bbox(states, -200, -200, 400, 400, seed=123)

    # Equivalent to scatter() with ranges:
    # scatter_in_bbox(states, 0, 0, 400, 300, seed=42)
    # == scatter(states, x_range=(0, 400), y_range=(0, 300), seed=42)