Graph Planner Interfaces

Introduction

Graph Planner Interfaces:
Provides path planning based on a Road Network Graph. Used to find optimal paths between two points on a predefined road network structure, suitable for multi-node navigation planning in large-scale environments.

Purpose	Python
Build Road Network Graph	✔
Load / Save Road Network Graph	✔
Path Planning	✔

Road Network Structure

Python Interface

RoadNetworkGraphBuilder

Function Description
Road network graph builder. Uses chained methods to add waypoints and edges, then generates a RoadNetworkGraph via build().

Example

from daystar_api.lowlevel_skills.path_planner import RoadNetworkGraphBuilder

builder = RoadNetworkGraphBuilder()

# Add waypoints (reference saved location names)
builder.add_waypoint("A")
builder.add_waypoint("B")
builder.add_waypoint("C")

# Add edges (bidirectional connections)
builder.add_edge("A", "B", is_bidirectional=True)
builder.add_edge("B", "C", is_bidirectional=True)

# Build and save road network graph
graph = builder.build()
graph.to_yaml_file("warehouse_graph.yaml")

Key Methods:

Method	Description
add_waypoint(id, x=None, y=None, z=None)	Add a waypoint. id corresponds to a saved location name, or specify coordinates to create a temporary waypoint.
add_edge(from_wp, to_wp, is_bidirectional=True, weight=None)	Add a connection edge between waypoints. weight is an optional cost weight.
build()	Generate and return the RoadNetworkGraph object.

---

RoadNetworkGraph

Function Description
Road network graph data structure containing the complete definition of waypoints and edges. Supports loading from and saving to YAML files.

Example

from daystar_api.lowlevel_skills.path_planner import RoadNetworkGraph

# Load road network graph from YAML file
graph = RoadNetworkGraph.from_yaml_file("warehouse_graph.yaml")

# Save to file
graph.to_yaml_file("updated_graph.yaml")

Key Methods:

Method	Description
from_yaml_file(path)	Load road network graph from a YAML file (class method).
to_yaml_file(path)	Save the road network graph to a YAML file.
add_waypoint(id, ...)	Add a waypoint.
add_edge(from_wp, to_wp, ...)	Add an edge.
get_waypoint(id)	Get information for a specified waypoint.
validate()	Validate whether the road network graph data is valid.

Path Planner

Python Interface

PathPlanner

Function Description
Execute shortest path planning based on a loaded road network graph. After loading the graph, call path_plan to find the optimal path between start and goal (passing through optional intermediate keypoints).

Example

from daystar_api.lowlevel_skills.path_planner import PathPlanner, RoadNetworkGraph

# Create planner and load road network graph
planner = PathPlanner()
graph = RoadNetworkGraph.from_yaml_file("warehouse_graph.yaml")
success, msg, waypoints = planner.load_graph(graph)

if success:
    # Plan path from A to C, passing through B
    success, path, msg = planner.path_plan(
        start_point="A",
        goal_point="C",
        keypoints=["B"]  # Optional intermediate keypoints
    )

    if success:
        print(f"Planned path: {' -> '.join(path)}")
        # Navigate through waypoints in order
        from daystar_api.lowlevel_skills import navigation_to_location
        for point in path:
            navigation_to_location(point)

Key Methods:

Method	Return Value	Description
load_graph(graph)	(success: bool, msg: str, waypoints: list)	Load road network graph into the planner.
path_plan(start_point, goal_point, keypoints=[])	(success: bool, path: list[str], msg: str)	Plan path, returns list of waypoint IDs traversed (including start and goal).

---

Road Network YAML Format

Road network graphs are defined in YAML format:

# Method 1: Reference saved locations (recommended)
waypoints:
  - id: A          # Automatically loads from /root/data/daystar_api/points/A.yaml
  - id: B
  - id: C

edges:
  - id:
      from_waypoint: A
      to_waypoint: B
    is_bidirectional: true
  - id:
      from_waypoint: B
      to_waypoint: C
    is_bidirectional: true

# Method 2: Specify coordinates directly (for temporary waypoints)
waypoints:
  - id: wp_001
    position:
      x: -1.28
      y: 3.52
      z: 0.0