larvaworld.lib.screen.drawing

Screen management for pygame-based simulation visualization

Classes

`MediaDrawOps`	Configuration for media output during simulation visualization.
`AgentDrawOps`	Configuration for agent rendering in pygame visualization.
`ColorDrawOps`	Configuration for color and display modes in visualization.
`ScreenOps`	Combined configuration for all screen rendering options.
`ScreenManager`	Main screen manager for pygame-based simulation visualization.
`GA_ScreenManager`	Specialized screen manager for Genetic Algorithm visualizations.

Module Contents

class larvaworld.lib.screen.drawing.MediaDrawOps

Bases: larvaworld.lib.param.NestedConf

Configuration for media output during simulation visualization.

Controls image and video recording options, including when to save (final, snapshots, overlap), file paths, and video parameters.

Attributes:

image_mode: When to save images (‘final’, ‘snapshots’, ‘overlap’) image_file: Filename for saved images (without .png extension) snapshot_interval_in_sec: Seconds between snapshots video_file: Filename for saved videos (without .mp4 extension) media_dir: Directory for saving media files fps: Video frames per second save_video: Whether to save video output vis_mode: Screen visualization mode (‘video’ or ‘image’) show_display: Whether to launch pygame visualization display_every_n_steps: Live display redraw cadence in simulation steps

(used only in display-only mode)

Example:

>>> media_ops = MediaDrawOps(save_video=True, fps=30, video_file='sim')
>>> media_ops.active  # True if any media output is enabled
>>> writer = media_ops.new_video_writer(fps=30)

image_mode

image_file

snapshot_interval_in_sec

video_file

media_dir

fps

save_video

vis_mode

show_display

pygame_keys

display_every_n_steps

property active: bool

property video_filepath: str | None

property image_filepath: str | None

property overlap_mode: bool

new_video_writer(fps: int, video_filepath: str | None = None) → Any | None

new_image_writer(image_filepath: str | None = None) → Any | None

class larvaworld.lib.screen.drawing.AgentDrawOps

Bases: larvaworld.lib.param.NestedConf

Configuration for agent rendering in pygame visualization.

Controls which agent features are drawn (trails, sensors, body parts) and their visual properties during simulation display.

Attributes:

visible_trails: Whether to draw agent trajectories trail_dt: Duration of trajectory trails in seconds trail_color: Trail coloring mode (‘normal’, ‘linear’, ‘angular’) draw_sensors: Whether to draw agent sensors draw_contour: Whether to draw agent body contour draw_segs: Whether to draw body segments draw_midline: Whether to draw body midline draw_centroid: Whether to draw centroid point draw_head: Whether to draw head point draw_orientations: Whether to draw body vector orientations

Example:

>>> agent_ops = AgentDrawOps(visible_trails=True, draw_sensors=True)
>>> agent_ops.trail_dt = 30.0  # 30 second trails

visible_trails

trail_dt

trail_color

draw_sensors

draw_contour

draw_segs

draw_midline

draw_centroid

draw_head

draw_orientations

class larvaworld.lib.screen.drawing.ColorDrawOps

Bases: larvaworld.lib.param.NestedConf

Configuration for color and display modes in visualization.

Controls coloring schemes, background settings, UI elements, and interactive features for pygame simulation display.

Attributes:

intro_text: Whether to show introductory configuration screen odor_aura: Whether to draw aura around odor sources allow_clicks: Whether to allow mouse/keyboard input black_background: Whether to use black background random_colors: Whether to use random agent colors color_behavior: Whether to color agents by behavior panel_width: Side panel width in pixels

Example:

>>> color_ops = ColorDrawOps(black_background=True, color_behavior=True)
>>> color_ops.panel_width = 400  # Set side panel width

intro_text

odor_aura

allow_clicks

black_background

random_colors

color_behavior

panel_width

class larvaworld.lib.screen.drawing.ScreenOps

Bases: ColorDrawOps, AgentDrawOps, MediaDrawOps

Combined configuration for all screen rendering options.

Inherits from ColorDrawOps, AgentDrawOps, and MediaDrawOps to provide a unified configuration interface for all visualization settings.

Example:

>>> screen_ops = ScreenOps(
...     save_video=True, visible_trails=True, black_background=True
... )
>>> screen_ops.fps = 30
>>> screen_ops.trail_dt = 20.0

class larvaworld.lib.screen.drawing.ScreenManager(**kwargs: Any)

Bases: ScreenAreaPygame

Main screen manager for pygame-based simulation visualization.

Manages pygame display, rendering loop, user input handling, and media output (images/videos) during simulation runs.

Attributes:

selected_type: Type of currently selected item selected_agents: List of currently selected agents selection_color: Color for highlighting selections dynamic_graphs: List of dynamic graph displays focus_mode: Whether in focus/zoom mode snapshot_interval: Frames between automatic snapshots pygame_keys: Mapping of keyboard controls

Example:

>>> screen = ScreenManager(model=sim_model, show_display=True)
>>> screen.step()  # Render one frame
>>> screen.run()  # Run visualization loop

selected_type = ''

selected_agents = []

selection_color = 'red'

dynamic_graphs = []

focus_mode = False

snapshot_interval

snapshot_counter = 0

odorscape_counter = 0

vid_writer = None

img_writer = None

initialized = False

closed = False

increase_fps() → None

decrease_fps() → None

draw_agents() → None: Draw the agents on the screen

check(**kwargs: Any) → None: Check whether to initialize or close the display

close(user_requested: bool = False) → None

Close the pygame display.

Parameters

user_requested: True when the close was triggered by a user (e.g., clicking the window close button). Only in that case we set running=False and print the “Terminated by the user” message.

close_requested() → bool

Check if the user requested to close the display.

Only checks for QUIT events if show_display is True and a display window is actually open, to avoid premature termination when running headless (without display).

render(**kwargs: Any) → None: Draw the display and evaluate user-input

property display_only_mode: bool

property should_draw_live_frame: bool

initialize(**kwargs: Any) → None: Initialize the pygame display

evaluate_graphs() → None: Evaluation of dynamic graphs on the screen.

property screen_color: tuple[int, int, int]

property tank_color: Any

property sidepanel_color: Any

property snapshot_tick: bool

property snapshot_valid: bool

property render_valid: bool

step() → None

draw_arena_tank() → None: Draw the tank of the arena with optional background

toggle(name: str, value: Any | None = None, show: bool = False, minus: bool = False, plus: bool = False, disp: Any | None = None) → None: Presentation of user-input-induced changes on screen

evaluate_input() → None: Evaluation of user input through keyboard and mouse.

eval_keypress(k: str) → None: Evaluation of keyboard input.

eval_selection(p: Any, ctrl: Any) → bool: Selection of items on the screen by mouse-clicks.

build_aux() → None: Generate additional items on screen

capture_snapshot() → None: Capture an image snapshot of the current display

draw_arena() → None: Draw the arena and sensory landscapes

item_pos(item: str) → tuple[int, int]

item_textfonts() → None

draw_aux() → None: Draw additional items on screen

load_scene_from_file(file_path: str, m: Any) → list[Any]

finalize() → None: Apply final actions before closing the screen manager

class larvaworld.lib.screen.drawing.GA_ScreenManager(model: Any, panel_width: int = 600, scene: str = 'no_boxes', **kwargs: Any)

Bases: ScreenManager

Specialized screen manager for Genetic Algorithm visualizations.

Extends ScreenManager with GA-specific defaults: wider side panel for GA metrics, and simplified scene settings.

Attributes:

model: The GA simulation model black_background: Background color (default False for white background) panel_width: Side panel width (default 600px for GA metrics) scene: Scene configuration (default ‘no_boxes’)

Example:

>>> ga_screen = GA_ScreenManager(model=ga_model)
>>> ga_screen.run()  # Run GA visualization with defaults