larvaworld.lib.screen.drawing ============================= .. py:module:: larvaworld.lib.screen.drawing .. autoapi-nested-parse:: Screen management for pygame-based simulation visualization Classes ------- .. autoapisummary:: larvaworld.lib.screen.drawing.MediaDrawOps larvaworld.lib.screen.drawing.AgentDrawOps larvaworld.lib.screen.drawing.ColorDrawOps larvaworld.lib.screen.drawing.ScreenOps larvaworld.lib.screen.drawing.ScreenManager larvaworld.lib.screen.drawing.GA_ScreenManager Module Contents --------------- .. py:class:: MediaDrawOps Bases: :py:obj:`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) .. py:attribute:: image_mode .. py:attribute:: image_file .. py:attribute:: snapshot_interval_in_sec .. py:attribute:: video_file .. py:attribute:: media_dir .. py:attribute:: fps .. py:attribute:: save_video .. py:attribute:: vis_mode .. py:attribute:: show_display .. py:attribute:: pygame_keys .. py:attribute:: display_every_n_steps .. py:property:: active :type: bool .. py:property:: video_filepath :type: str | None .. py:property:: image_filepath :type: str | None .. py:property:: overlap_mode :type: bool .. py:method:: new_video_writer(fps: int, video_filepath: str | None = None) -> Any | None .. py:method:: new_image_writer(image_filepath: str | None = None) -> Any | None .. py:class:: AgentDrawOps Bases: :py:obj:`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 .. py:attribute:: visible_trails .. py:attribute:: trail_dt .. py:attribute:: trail_color .. py:attribute:: draw_sensors .. py:attribute:: draw_contour .. py:attribute:: draw_segs .. py:attribute:: draw_midline .. py:attribute:: draw_centroid .. py:attribute:: draw_head .. py:attribute:: draw_orientations .. py:class:: ColorDrawOps Bases: :py:obj:`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 .. py:attribute:: intro_text .. py:attribute:: odor_aura .. py:attribute:: allow_clicks .. py:attribute:: black_background .. py:attribute:: random_colors .. py:attribute:: color_behavior .. py:attribute:: panel_width .. py:class:: ScreenOps Bases: :py:obj:`ColorDrawOps`, :py:obj:`AgentDrawOps`, :py:obj:`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 .. py:class:: ScreenManager(**kwargs: Any) Bases: :py:obj:`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 .. py:attribute:: selected_type :value: '' .. py:attribute:: selected_agents :value: [] .. py:attribute:: selection_color :value: 'red' .. py:attribute:: dynamic_graphs :value: [] .. py:attribute:: focus_mode :value: False .. py:attribute:: snapshot_interval .. py:attribute:: snapshot_counter :value: 0 .. py:attribute:: odorscape_counter :value: 0 .. py:attribute:: vid_writer :value: None .. py:attribute:: img_writer :value: None .. py:attribute:: initialized :value: False .. py:attribute:: closed :value: False .. py:method:: increase_fps() -> None .. py:method:: decrease_fps() -> None .. py:method:: draw_agents() -> None Draw the agents on the screen .. py:method:: check(**kwargs: Any) -> None Check whether to initialize or close the display .. py:method:: 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. .. py:method:: 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). .. py:method:: render(**kwargs: Any) -> None Draw the display and evaluate user-input .. py:property:: display_only_mode :type: bool .. py:property:: should_draw_live_frame :type: bool .. py:method:: initialize(**kwargs: Any) -> None Initialize the pygame display .. py:method:: evaluate_graphs() -> None Evaluation of dynamic graphs on the screen. .. py:property:: screen_color :type: tuple[int, int, int] .. py:property:: tank_color :type: Any .. py:property:: sidepanel_color :type: Any .. py:property:: snapshot_tick :type: bool .. py:property:: snapshot_valid :type: bool .. py:property:: render_valid :type: bool .. py:method:: step() -> None .. py:method:: draw_arena_tank() -> None Draw the tank of the arena with optional background .. py:method:: 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 .. py:method:: evaluate_input() -> None Evaluation of user input through keyboard and mouse. .. py:method:: eval_keypress(k: str) -> None Evaluation of keyboard input. .. py:method:: eval_selection(p: Any, ctrl: Any) -> bool Selection of items on the screen by mouse-clicks. .. py:method:: build_aux() -> None Generate additional items on screen .. py:method:: capture_snapshot() -> None Capture an image snapshot of the current display .. py:method:: draw_arena() -> None Draw the arena and sensory landscapes .. py:method:: item_pos(item: str) -> tuple[int, int] .. py:method:: item_textfonts() -> None .. py:method:: draw_aux() -> None Draw additional items on screen .. py:method:: load_scene_from_file(file_path: str, m: Any) -> list[Any] .. py:method:: finalize() -> None Apply final actions before closing the screen manager .. py:class:: GA_ScreenManager(model: Any, panel_width: int = 600, scene: str = 'no_boxes', **kwargs: Any) Bases: :py:obj:`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