# yeyi58095/smart_cane architecture

> Architecture diagram of the GitHub repository yeyi58095/smart_cane, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yeyi58095/smart_cane
- Repository: https://github.com/yeyi58095/smart_cane

## Overview

This ROS 2 smart-cane project supports a user-to-landmark workflow: start a simulated robot and navigation stack, detect landmarks by combining camera and LiDAR observations, refine candidate positions for navigation, then request travel to a named landmark. Navigation and target-alignment behaviors provide motion guidance; command-velocity interfaces expose direction or direct control. The README also documents alternate bed/sign detectors, landmark visualization, SLAM, and collision guidance. Wiring beyond the sampled launch and node excerpts is shown only where documented; the tree and README support several capabilities whose implementation was not sampled.

Main entry points: [`src/smart_cane_landmarks/smart_cane_landmarks/goto_landmark.py`](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_landmarks/smart_cane_landmarks/goto_landmark.py) (Go to landmark), [`src/smart_cane_bringup/smart_cane_bringup/launch/amcl_sim.launch.py`](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_bringup/smart_cane_bringup/launch/amcl_sim.launch.py) (AMCL bringup), [`src/smart_cane_perception/smart_cane_perception/yolo_lidar_landmark.py`](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_perception/smart_cane_perception/yolo_lidar_landmark.py) (YOLO LiDAR landmarks), [`src/smart_cane_nav/smart_cane_nav/align_to_target.py`](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/align_to_target.py) (Target alignment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_world["Simulation and Bringup"]
  node_sim["Gazebo world"]
  node_bringup["AMCL bringup<br/>[amcl_sim.launch.py]"]
  node_initialpose["Initial pose publisher<br/>[initialpose_pub.py]"]
  node_slam["SLAM launch"]
end

subgraph group_perception["Perception and Mapping"]
  node_yolo["YOLO LiDAR landmarks"]
  node_detectors["Other detectors"]
end

subgraph group_landmarks["Landmark Workflow"]
  node_snapper["Goal snapper<br/>[goal_snapper.py]"]
  node_landmarkfile["Landmark positions"]
  node_goto["Go to landmark<br/>[goto_landmark.py]"]
  node_visualizer["Landmark visualizer"]
end

subgraph group_navigation["Navigation and Guidance"]
  node_nav2["Nav2 navigation"]
  node_navguidance["Nav2 guidance launch"]
  node_align["Target alignment<br/>[align_to_target.py]"]
  node_collision["Collision guidance"]
end

subgraph group_interfaces["User Interfaces"]
  node_qtui["Joystick GUI<br/>[qt_cmd_vel_ui.py]"]
  node_cliui["Velocity CLI<br/>[nav_cmd_vel_ui.py]"]
end

node_user(("Cane operator"))
node_landmarkaction["Nav2 action server"]
node_velocity["Velocity topics"]

node_user -->|"starts system"| node_bringup
node_bringup -->|"includes launch"| node_sim
node_bringup -->|"starts publisher"| node_initialpose
node_initialpose -->|"publishes initial pose"| node_velocity
node_user -->|"starts SLAM"| node_slam
node_sim -->|"provides sensor data"| node_yolo
node_yolo -->|"refines candidates"| node_snapper
node_yolo -->|"writes positions"| node_landmarkfile
node_goto -->|"reads positions"| node_landmarkfile
node_user -->|"names destination"| node_goto
node_goto -->|"sends goal"| node_landmarkaction
node_goto -->|"enables target alignment"| node_align
node_align -->|"publishes alignment velocity"| node_velocity
node_nav2 -->|"publishes motion commands"| node_velocity
node_navguidance -->|"launches alignment"| node_align
node_navguidance -->|"routes motion commands"| node_velocity
node_user -->|"controls robot"| node_qtui
node_qtui -->|"publishes and reads commands"| node_velocity
node_velocity -->|"supplies direction"| node_cliui
node_user -->|"views landmarks"| node_visualizer

click node_sim "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_sim/smart_cane_sim/launch/sim_world.launch.py"
click node_bringup "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_bringup/smart_cane_bringup/launch/amcl_sim.launch.py"
click node_initialpose "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_bringup/smart_cane_bringup/initialpose_pub.py"
click node_slam "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/launch/nav2_slam.launch.py"
click node_yolo "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_perception/smart_cane_perception/yolo_lidar_landmark.py"
click node_detectors "https://github.com/yeyi58095/smart_cane/tree/main/src/smart_cane_perception/smart_cane_perception"
click node_snapper "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_landmarks/smart_cane_landmarks/goal_snapper.py"
click node_goto "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_landmarks/smart_cane_landmarks/goto_landmark.py"
click node_visualizer "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_landmarks/smart_cane_landmarks/landmark_visualizer.py"
click node_nav2 "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/launch/nav2_autonomy.launch.py"
click node_navguidance "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/launch/nav2_guidance.launch.py"
click node_align "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/align_to_target.py"
click node_collision "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/collision_guidance.py"
click node_qtui "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/qt_cmd_vel_ui.py"
click node_cliui "https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/nav_cmd_vel_ui.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sim,node_bringup,node_initialpose,node_slam toneBlue
class node_yolo,node_detectors toneAmber
class node_snapper,node_landmarkfile,node_goto,node_visualizer,node_landmarkaction toneMint
class node_nav2,node_navguidance,node_align,node_collision toneRose
class node_qtui,node_cliui,node_user,node_velocity toneIndigo
```

## Components

### Simulation and Bringup

- [Gazebo world](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_sim/smart_cane_sim/launch/sim_world.launch.py): `src/smart_cane_sim/smart_cane_sim/launch/sim_world.launch.py`
- [AMCL bringup](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_bringup/smart_cane_bringup/launch/amcl_sim.launch.py): `src/smart_cane_bringup/smart_cane_bringup/launch/amcl_sim.launch.py`
- [Initial pose publisher](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_bringup/smart_cane_bringup/initialpose_pub.py): `src/smart_cane_bringup/smart_cane_bringup/initialpose_pub.py`
- [SLAM launch](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/launch/nav2_slam.launch.py): `src/smart_cane_nav/smart_cane_nav/launch/nav2_slam.launch.py`

### Perception and Mapping

- [YOLO LiDAR landmarks](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_perception/smart_cane_perception/yolo_lidar_landmark.py): `src/smart_cane_perception/smart_cane_perception/yolo_lidar_landmark.py`
- [Other detectors](https://github.com/yeyi58095/smart_cane/tree/main/src/smart_cane_perception/smart_cane_perception): `src/smart_cane_perception/smart_cane_perception`

### Landmark Workflow

- [Goal snapper](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_landmarks/smart_cane_landmarks/goal_snapper.py): `src/smart_cane_landmarks/smart_cane_landmarks/goal_snapper.py`
- **Landmark positions**
- [Go to landmark](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_landmarks/smart_cane_landmarks/goto_landmark.py): `src/smart_cane_landmarks/smart_cane_landmarks/goto_landmark.py`
- [Landmark visualizer](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_landmarks/smart_cane_landmarks/landmark_visualizer.py): `src/smart_cane_landmarks/smart_cane_landmarks/landmark_visualizer.py`

### Navigation and Guidance

- [Nav2 navigation](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/launch/nav2_autonomy.launch.py): `src/smart_cane_nav/smart_cane_nav/launch/nav2_autonomy.launch.py`
- [Nav2 guidance launch](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/launch/nav2_guidance.launch.py): `src/smart_cane_nav/smart_cane_nav/launch/nav2_guidance.launch.py`
- [Target alignment](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/align_to_target.py): `src/smart_cane_nav/smart_cane_nav/align_to_target.py`
- [Collision guidance](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/collision_guidance.py): `src/smart_cane_nav/smart_cane_nav/collision_guidance.py`

### User Interfaces

- [Joystick GUI](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/qt_cmd_vel_ui.py): `src/smart_cane_nav/smart_cane_nav/qt_cmd_vel_ui.py`
- [Velocity CLI](https://github.com/yeyi58095/smart_cane/blob/main/src/smart_cane_nav/smart_cane_nav/nav_cmd_vel_ui.py): `src/smart_cane_nav/smart_cane_nav/nav_cmd_vel_ui.py`

### Other components

- **Cane operator**
- **Nav2 action server**
- **Velocity topics**

## Connections

- Cane operator → AMCL bringup: starts system
- AMCL bringup → Gazebo world: includes launch
- AMCL bringup → Initial pose publisher: starts publisher
- Initial pose publisher → Velocity topics: publishes initial pose
- Cane operator → SLAM launch: starts SLAM
- Gazebo world → YOLO LiDAR landmarks: provides sensor data
- YOLO LiDAR landmarks → Goal snapper: refines candidates
- YOLO LiDAR landmarks → Landmark positions: writes positions
- Go to landmark → Landmark positions: reads positions
- Cane operator → Go to landmark: names destination
- Go to landmark → Nav2 action server: sends goal
- Go to landmark → Target alignment: enables target alignment
- Target alignment → Velocity topics: publishes alignment velocity
- Nav2 navigation → Velocity topics: publishes motion commands
- Nav2 guidance launch → Target alignment: launches alignment
- Nav2 guidance launch → Velocity topics: routes motion commands
- Cane operator → Joystick GUI: controls robot
- Joystick GUI → Velocity topics: publishes and reads commands
- Velocity topics → Velocity CLI: supplies direction
- Cane operator → Landmark visualizer: views landmarks