Skip to content

PlanViz.md

Latest commit

 

History

History
81 lines (60 loc) · 6.68 KB

PlanViz.md

File metadata and controls

81 lines (60 loc) · 6.68 KB
Raw

PlanViz

The primary purpose of PlanViz is to help participants in the League of Robot Runners competition better understand the planned paths and executed commands of their robots. PlanViz offers insights into problem solving strategies, by showing how robots move across the map, and by highlighting and exploring the errors and events given by the competition Start-Kit.

Being an offline tool, PlanViz takes as input a grid map (part of the competition problem set) and a JSON formatted log file, which is produced by the competition Start-Kit. For the 2024/2026 view, the log file describes the planned and executed actions of agents over time. In 2026 tick-based plans, the UI shows the elapsed tick index. An example of the application in action is shown in the following video.

plan_viz_gif

Visual Markers

PlanViz provides a variety of visual markers to help users understand the results of their planning strategies.

scenario

  • The map is plotted in grids with the white ones being the free spaces and black ones being obstacles.
  • An agent is plotted in a blue circle, with a number being the agent index and a dark blue dot being its heading. When delayIntervals are present in a 2026 LoRR file, delayed agents are shown in yellow during the corresponding ticks.
  • All errands of tasks are represented by colored squares. Errands for a task are initially marked in yellow, turn orange when the task is assigned to an agent, and turn to white once the errand is completed and there is no further errand at this location.

scenario

  • Right-click an agent to see/hide its path. The paths are presented with a sequence of purple squares, with the locations where the agent rotates or waits being larger.
  • Right-clicking on non-agent grids will cancel all agents selections.

scenario

  • Ctrl + Right-click an errand will show all related events.
  • Right-clicking on white grids will cancel selection.

UI Options and Controls

The user interface supports a variety of operations to control and focus the display of plans.

  • In the 2024/2026 UI, the timeline label shows the current Time. For tick-based 2026 plans, it shows Tick: current / max.
  • The i icon next to the timeline opens a solution metadata popup with the number of agents, map size, traversable cells, obstacle cells, and agentMaxCounter when available.
  • The buttons control the progress of the plan/execution:
    • Play: Auto-play the plan/execution
    • Pause: Pause the scenario at the current time
    • Fullsize: Fit the whole map into the visible canvas
    • Next: Move the scenario to the next time
    • Prev: Move the scenario to the previous time
    • Restart: Reset the scenario to time 0
  • Productivity: Open a popup that plots task or errand completion over time. The popup supports completed count, instant completion count, and throughput views, and can show either the current timeline range or the full timeline.
  • The checkboxes control what is shown in the scenario.
  • On large maps, PlanViz enables viewport mode with a minimap. Drag the map canvas or the minimap viewport to pan around the map.
  • In the 2024/2026 UI, Start time: Input the desired start time and move the scenario to it.
  • List of errors contains collisions and timeout issues from the Start-Kit. When the scenario is paused, you can double-click an error to see the invalid movements.
  • A vertex/edge collision between agents $a_i$ and $a_j$ at location $V$/edge $(U,V)$ at time $T$ is presented under the format of ai, aj, v=V/e=(U,V), t=T. Single-click the collision in List of errors can mark the colliding agents in red, and press ctrl while clicking to select multiple collisions. The Show colliding agents checkbox outlines agents that collide at any point and fills agents red when they collide at the current timestep.
  • Most recent events contains information of task assignments, errands completion and task completion. When the scenario is paused, you can double-click an event to move all the agents to the time when such event occurs.
  • The event counters show cumulative assigned, errand-finished, and task-finished counts. When a total is available, counters are shown as current / total.

Arguments

  • --map (type: str): Path to the map file (ends with .map). See example/warehouse_small.map for more information.
  • --plan (type: str): Path to the planned path file (ends with .json). See example/warehouse_small_2026.json for more information.
  • --n (type: int): Number of agents to show, starting from index 0 (default: All agents in the path file).
  • --grid (type: bool): Whether to show the grids on the map (default: True).
  • --aid (type: bool): Whether to show the agent indices (default: True).
  • --tid (type: bool): Whether to show the task indices (default: False).
  • --static: Whether to show the start locations (default: False). Set to True if specified.
  • --ca: Whether to mark all the colliding agents in red (default: False). Set to True if specified.
  • --ppm (type: int): Number of pixels per move, depending on the size of the map (default: auto-configured per map).
  • --mv (type: int): Number of moves per action; the tile size of the map is ppm $\times$ mv (default: auto-configured per map).
  • --delay (type: float): Wait time between animation updates (default: auto-configured per map).
  • --start (type: int): Start time for visualization (default: 0).
  • --end (type: int): End time for visualization (default: inf).
  • --version (type: str): Plan file version. Supported values: '2024 LoRR', '2026 LoRR', or '2023 LoRR'. If not specified, the version is read from the plan JSON file. If neither is available, defaults to 2023 LoRR (default: None).
  • --window (type: int): Number of timesteps to load from the start time. The visualization will cover timesteps from start to start + window (default: 50000).
  • --event-limit (type: int): Number of recent events to show in the event panel (default: 10).

If one is using our maps, then we have default values for ppm, mv, and delay, so the user does not need to specify them.

Run

To run PlanViz, open a terminal under the directory PlanViz/ and type the following example command:

python script/run.py --map example/warehouse_small.map --plan example/warehouse_small_2026.json

Please keep in mind the formats of JSON files are different between 2023, 2024, and 2026.