swarmsort.simulator module

Object motion simulator for SwarmSort testing and visualization.

This module provides tools for creating realistic object trajectories, motion patterns, and detection sequences for testing tracking algorithms.

class swarmsort.simulator.MotionType(value)

Bases: Enum

Types of motion patterns.

BROWNIAN = 'brownian'

CIRCULAR = 'circular'

FIGURE_EIGHT = 'figure_eight'

LINEAR = 'linear'

RANDOM_WALK = 'random_walk'

SINUSOIDAL = 'sinusoidal'

SPIRAL = 'spiral'

STOP_AND_GO = 'stop_and_go'

class swarmsort.simulator.ObjectMotionSimulator(config=None)

Bases: object

Simulates realistic object motion patterns.

add_object(obj)

Add an object to the simulation.

Return type:

None

base_embeddings: Dict[int, ndarray]

create_circular_motion_object(object_id, center, radius, angular_velocity, start_angle=0.0, **kwargs)

Create an object with circular motion.

Return type:

SimulatedObject

create_figure_eight_object(object_id, center, width, height, period, **kwargs)

Create an object following a figure-eight pattern.

Return type:

SimulatedObject

create_linear_motion_object(object_id, start_pos, velocity, **kwargs)

Create an object with linear motion.

Return type:

SimulatedObject

create_random_walk_object(object_id, start_pos, step_size=0.3, boundary_behavior='bounce', **kwargs)

Create an object with random walk motion.

Return type:

SimulatedObject

generate_detection(obj)

Generate a detection from an object, including noise and missing detections.

Return type:

Optional[Detection]

generate_false_positives(num_fps=None)

Generate false positive detections.

Return type:

List[Detection]

objects: List[SimulatedObject]

occlusion_state: Dict[int, int]

reset()

Reset simulation state.

run_simulation(num_frames)

Run the simulation for a specified number of frames.

Return type:

List[List[Detection]]

step()

Advance simulation by one time step and return detections.

Return type:

List[Detection]

update_object_motion(obj, dt=1.0)

Update object position based on motion type.

Return type:

None

class swarmsort.simulator.SimulatedObject(object_id, initial_position, motion_type, motion_params=<factory>, size=(20.0, 20.0), base_confidence=0.9, confidence_noise=0.1, class_id=0, spawn_frame=0, death_frame=-1, is_active=True)

Bases: object

Represents a simulated object with motion properties.

acceleration: ndarray

base_confidence: float = 0.9

class_id: int = 0

confidence_noise: float = 0.1

death_frame: int = -1

initial_position: ndarray

is_active: bool = True

motion_params: Dict[str, Any]

motion_type: MotionType

object_id: int

position: ndarray

size: Tuple[float, float] = (20.0, 20.0)

spawn_frame: int = 0

velocity: ndarray

class swarmsort.simulator.SimulationConfig(world_width=800.0, world_height=600.0, detection_probability=0.95, false_positive_rate=0.02, missed_detection_rate=0.05, position_noise_std=2.0, bbox_noise_std=1.0, use_embeddings=False, embedding_dim=128, embedding_noise_std=0.1, occlusion_probability=0.01, occlusion_duration_range=(5, 20), random_seed=None)

Bases: object

Configuration for the simulation environment.

bbox_noise_std: float = 1.0

detection_probability: float = 0.95

embedding_dim: int = 128

embedding_noise_std: float = 0.1

false_positive_rate: float = 0.02

missed_detection_rate: float = 0.05

occlusion_duration_range: Tuple[int, int] = (5, 20)

occlusion_probability: float = 0.01

position_noise_std: float = 2.0

random_seed: int | None = None

use_embeddings: bool = False

world_height: float = 600.0

world_width: float = 800.0

swarmsort.simulator.create_demo_scenario(scenario_name='crossing_paths')

Create predefined demo scenarios.

Return type:

ObjectMotionSimulator

swarmsort.simulator.create_scalability_scenario(num_objects, use_embeddings=False, world_size=None, motion_type='mixed', random_seed=None)

Create a scenario with controlled number of objects for scalability testing.

Parameters:

• num_objects (int) – Number of objects to simulate

• use_embeddings (bool) – Whether to generate embeddings for detections

• world_size (Optional[Tuple[float, float]]) – Size of simulation world (width, height). Auto-scales with object count if None

• motion_type (str) – Type of motion - “mixed”, “linear”, “circular”, or “random_walk”

• random_seed (Optional[int]) – Random seed for reproducibility

Return type:

ObjectMotionSimulator

Returns:

Configured ObjectMotionSimulator