This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. It covers the concrete code structure: workspace layout, packages, files, the node/topic graph, and build/run commands. For project purpose and current status see doc/design.md; for the ML training process see doc/ml-flow.md.
Note on the Korean lines in this file: they are HTML comments (<!-- -->) placed only for Korean-speaking human readers. They are not additional instructions — do not parse, translate, or derive behavior from them. Treat the English text as the sole operative content.
This English-body + Korean-comment pattern applies to any bilingual doc in this repo, not just this file.
Before finalizing a bilingual doc, re-read the diff and verify two things:
A new bilingual doc needs its own copy of this whole note at the top — this note is self-referential to this file and does not automatically extend to other files.
This is a colcon (ROS 2 Jazzy) workspace on Gazebo Harmonic (gz sim). ROS 2 packages live under src/; build/, install/, log/ are build artifacts and are gitignored.
Signal-Simulation/
├── CLAUDE.md # personal local prompt (gitignored); @imports doc/*.md
├── README.md # short public description of the repo
├── doc/ # team-shared prompts (committed)
│ ├── AGENT.md # this file — project structure
│ ├── design.md # project overview & current status
│ ├── ml-flow.md # machine-learning training process (currently empty)
│ └── work.md # work log (currently empty)
├── docs/ # long-form working guides (committed, bilingual)
│ ├── camera_node_refactory.md # camera_node responsibility split & handoff notes
│ └── gazebo-control-guide.md # moving transport equipment on tracks
├── examples/ # separate scratch workspace of ROS 2 practice packages
├── scripts/ # build/run entry points + external-repo source vendoring
├── src/
│ ├── robot_control/ # the robot's body and wiring: urdf + config, no nodes
│ ├── signal_vision/ # gesture recognition: camera_node + the vendored model source
│ ├── auto_drive/ # autonomous driving: mission_follower (+ legacy waypoint_follower) + scan_rays viewer
│ └── knavi_bringup/ # assembly only: the top-level launch, no nodes of its own
├── tools/ # offline track editing / SDF generation (see requirements.txt)
└── worlds/
└── navi_factory/ # the world bringup uses
├── models/ # warehouse props
└── world/navi_factory/
├── navi_factory.sdf # the world itself
└── tracks.yaml # dispatch routes & zone coords — single source of truth
Four layout facts that differ from a plain ROS 2 workspace:
src/. worlds/navi_factory/models/ holds the warehouse props (AWS RoboMaker warehouse models, OGV, cones, carts, shelves) and worlds/navi_factory/world/navi_factory/navi_factory.sdf is the world itself. Gazebo finds them through GZ_SIM_RESOURCE_PATH, which the launch file sets from the workspace root.
aws-robomaker-small-warehouse-world-ros2 package is gone from src/; its models were folded into worlds/navi_factory/models/.
tracks.yaml sits next to the world SDF, not in any package. Its coordinates are measured off navi_factory.sdf's track_* tile poses, and tools/tracks_to_{markers,actors}.py generate discs and actors from it straight back into that same SDF — it is a world-bound layout description, not a package's tuning parameters. Two packages read it (auto_drive for routes, signal_vision for the gesture-zone gate), so neither can own it; the launch file resolves the path and passes it to both as the tracks_yaml_path parameter.
knavi_bringup holds the launch but no urdf and no config; robot_control holds urdf and config but starts nothing. Expect to edit two packages for one change.
Four ament_python packages, split by responsibility rather than by file type. Every one of them excludes the world — the world is injected through the launch world argument, so no package installs world files.
| Package | Owns | Runs |
|---|---|---|
robot_control | urdf/ (mecanum_lift_robot.urdf.xacro is the one in use; robot.urdf.xacro sits next to it but nothing reads it), config/ (bridge.yaml, twist_mux.yaml, flat_ground.sdf) | nothing — no console script, no launch |
signal_vision | camera_node/, the vendored vision_hand/, metrics.py, models/ (weights) | camera_node |
auto_drive | patrol/mission_follower.py, patrol/waypoint_follower.py, viz/scan_rays.py | mission_follower, waypoint_follower (legacy), scan_rays |
knavi_bringup | launch/bringup.launch.py | nothing of its own — it starts the other three |
Because robot_control executes nothing, its package.xml declares only xacro — the one tool without which its own files cannot even be read. Everything needed to actually start nodes (rclpy, robot_state_publisher, ros_gz_sim, ros_gz_bridge, twist_mux, the message packages) is declared by knavi_bringup, which is what runs them.
Each package also carries test/, which is style checks only: ament_copyright, ament_flake8, ament_pep257.
camera_node file splitOne node, one process, several files. node.py only wires the parts together and owns the threads; it imports neither cv2 nor Twist.
node.py — assembly, parameters, one capture+inference worker thread and one render worker thread
frame_source.py — webcam capture (v4l2 by default; any, avfoundation, dshow also selectable)
image_publisher.py — publishes image_webcam (sensor_msgs/Image), disabled by default
inference.py — runs the vendored gesture model and produces an immutable render payload
command_publisher.py — maps a label to gesture (std_msgs/String), motion labels to cmd_vel_gesture (geometry_msgs/Twist), and dispatch labels to signal_dispatch (std_msgs/String, a zone name)
labels.py — the single source of truth for labels: motion STOP (the only one left), dispatch LEFT→zone_nw / RIGHT→zone_ne
shutdown.py, swap_frame.py — shutdown detection and frame handoff helpers
signal_vision/vision_hand/ is a vendored copy produced by scripts/setup_infer_env.py, not code owned by this repo. Refresh it from the source repository instead of editing it here; see doc/design.md.
That directory is excluded from the linters, because enforcing this repo's style on someone else's code is pointless when the next refresh overwrites it. The exclusion needs two mechanisms: ament_flake8 honours the AMENT_IGNORE marker file that setup_infer_env.py re-creates after every copy, while ament_pep257 ignores that marker and is told through --exclude in signal_vision/test/test_pep257.py.
What knavi_bringup/launch/bringup.launch.py actually starts. One robot is spawned today: robot2, the mecanum_lift_robot. robot1 was removed from the robot_info list because running two physical robots in this mesh-heavy world costs too much, and robot2 is the one carrying the lidar and camera.
| Component | Count | Lifetime | Role |
|---|---|---|---|
robot_state_publisher (ns /robot2) | one per robot | resident | expands URDF, publishes link tf and robot_description |
ros_gz_sim create (robot) | one per robot | one-shot | reads robot_description from the topic and spawns the model |
ros_gz_sim create (flat_ground) | one | one-shot | spawns the collision-only ground plate at z = 0.25, unless enable_flat_ground:=false |
twist_mux (ns /robot2) | one per robot | resident | passes through the highest-priority live velocity source |
mission_follower (ns /robot2) | one per robot | resident | waits at the signal point, drives a tracks.yaml route to the zone named on signal_dispatch and returns; publishes cmd_vel_auto; off with enable_patrol:=false |
camera_node (ns /robot2) | one per robot | resident | one physical webcam per robot; off with enable_camera:=false |
scan_rays (ns /robot2) | one per robot | resident | redraws scan as ray line segments on scan_rays; starts only when RViz does |
ros_gz_bridge bridge_node | one for the whole system | resident | translates the topics listed in config/bridge.yaml |
rviz2 | one for the whole system | resident | views /tf, <ns>/scan and <ns>/scan_rays; off with enable_rviz:=false, which is the only argument that closes it |
gz sim process | one | resident | physics; not a ROS node, so it never appears in ros2 node list |
Inside the Gazebo process, not separate nodes: the DiffDrive plugin (subscribes cmd_vel, publishes odom and odom → base_link tf), the JointStatePublisher plugin, the simulated camera sensor, and the gpu_lidar sensor.
Startup order: set GZ_SIM_RESOURCE_PATH → gz sim → robot_state_publisher → spawn → ground plate → bridge → camera_node → rviz2.
Adding a robot means adding one entry to the robot_info list at the top of the launch file; the bridge and gz sim stay at one each, and only bridge.yaml grows.
camera_node scales with the robots too: one webcam per robot, each node inside that robot's namespace. That is what makes the wiring self-consistent — a namespaced node publishes <ns>/cmd_vel_gesture, which the twist_mux in the same namespace already subscribes to, so no remap is involved and there is no second place for the two to drift apart.
Which webcam goes with which robot is the fifth field of a robot_info entry, a /dev/video<N> index. The camera_device_id launch argument overrides that field for the first robot only, and defaults to empty so that leaving it alone keeps every robot on its own configured value.
Running N robots therefore needs N webcams physically plugged in. When a device is missing only that robot's camera_node fails; the other robots and the simulation keep running.
Bridged between ROS 2 and Gazebo (config/bridge.yaml):
| Topic | Direction | ROS type | Gazebo type |
|---|---|---|---|
/clock | gz → ROS | rosgraph_msgs/Clock | gz.msgs.Clock |
<ns>/cmd_vel | ROS → gz | geometry_msgs/Twist | gz.msgs.Twist |
<ns>/odom | gz → ROS | nav_msgs/Odometry | gz.msgs.Odometry |
<ns>/joint_states | gz → ROS | sensor_msgs/JointState | gz.msgs.Model |
<ns>/scan | gz → ROS | sensor_msgs/LaserScan | gz.msgs.LaserScan |
/tf (gz side <ns>/tf) | gz → ROS | tf2_msgs/TFMessage | gz.msgs.Pose_V |
/robot2/pose_gt | gz → ROS | geometry_msgs/Pose | gz.msgs.Pose |
The file spells the namespace out per robot. It used to carry a full /robot1 set alongside the /robot2 set even though only robot2 is spawned; that block is now commented out, because a live-looking config for a robot that does not exist is what makes readers ask why the single robot is numbered two. Restoring it means adding the entry back to robot_info and uncommenting the block.
/robot2/pose_gt is the exception to the namespace pattern: its Gazebo side is /model/mecanum_lift_robot/pose, keyed by model name rather than namespace, because that is what the pose-publisher system emits. waypoint_follower subscribes to it instead of odom because wheel odometry drifts under slip.
/clock deliberately carries no namespace — it is world-wide, not per-robot. The simulated camera publishes to <ns>/camera/image inside Gazebo but is not bridged, because the gesture pipeline uses a real webcam instead.
tf is the other topic with no namespace, and unlike /clock that is not a choice this repo made. tf2_ros hard-codes the topic names as absolute paths — "/tf" and "/tf_static" with a leading slash, in transform_broadcaster.hpp and transform_listener.hpp — so a node's namespace never applies to them. The namespaced robot_state_publisher has always published its link transforms to the global /tf; only the bridged Gazebo side was named <ns>/tf, and nothing subscribed to it, which left odom → base_link missing from the tf tree every tool actually reads.
Robots are therefore separated in tf by frame name, not by topic. robot_state_publisher gets frame_prefix: <ns>/, and the URDF spells the same prefix into the DiffDrive plugin's frame_id / child_frame_id and into every sensor's gz_frame_id, so the frames are robot2/odom, robot2/base_link, robot2/lidar_link, and so on. Both halves must use the identical string or the tree breaks in two at base_link.
Velocity sources arbitrated by twist_mux, highest priority first:
| Input topic | Priority | Timeout | Publisher today |
|---|---|---|---|
cmd_vel_estop | 100 | 0.3 s | none yet |
cmd_vel_gesture | 50 | 0.5 s | that robot's own camera_node, in the same namespace |
cmd_vel_teleop | 20 | 0.5 s | teleop_twist_keyboard, for manual checks |
cmd_vel_auto | 10 | 0.5 s | mission_follower when enable_patrol is on (only while driving a dispatch route) |
Because twist_mux owns the output, nothing else may publish to <ns>/cmd_vel directly — manual driving goes into cmd_vel_teleop:
ros2 run teleop_twist_keyboard teleop_twist_keyboard \
--ros-args -r /cmd_vel:=/robot2/cmd_vel_teleop
Driving by hand while enable_patrol is on means fighting the follower for the mux, since teleop only outranks it — pass enable_patrol:=false for a clean manual check.
<ns>/scan_rays (visualization_msgs/MarkerArray) is not bridged either — scan_rays builds it inside ROS from the scan that was already bridged, so it is a second view of existing data rather than a new sensor.
camera_node itself publishes <ns>/gesture (std_msgs/String, the recognized label, for logging and latency measurement), <ns>/cmd_vel_gesture (geometry_msgs/Twist, motion labels only), <ns>/signal_dispatch (std_msgs/String, the destination zone for dispatch labels, read by mission_follower), and <ns>/image_webcam (sensor_msgs/Image, off by default). These carry the robot namespace because bringup starts the node inside it; started bare with ros2 run the same topics appear at the root instead.
From the repo root:
colcon build --symlink-install # also picks up examples/src practice packages
colcon build --packages-select robot_control signal_vision auto_drive knavi_bringup
source install/setup.bash
Moving or renaming a file that data_files installs leaves a dangling symlink in build/ and install/ under --symlink-install, and the next build fails with error: can't copy ...: doesn't exist. Delete that package's stale directory under build/ and install/ and build again.
Launching:
ros2 launch knavi_bringup bringup.launch.py
ros2 launch knavi_bringup bringup.launch.py headless:=true enable_camera:=false
ros2 launch knavi_bringup bringup.launch.py camera_device_id:=1
ros2 launch knavi_bringup bringup.launch.py enable_rviz:=false
ros2 run signal_vision camera_node --ros-args -p enable_inference:=false
Launch arguments: world (defaults to navi_factory.sdf, path computed from the workspace root), use_sim_time (true), headless (false), enable_camera (true), camera_device_id (empty), enable_patrol (true), enable_flat_ground (true), enable_rviz (true).
enable_rviz is on by default, so a plain bringup opens RViz2 on config/knavi.rviz next to the gz sim window: the lidar scan as points, the same scan again as ray line segments, the tf axes, fixed frame robot2/odom. It is part of bringup rather than a separate step because the gz sim window only draws the sensor's own rays and cannot tell you whether the scan reached ROS at all.
The ray line segments come from scan_rays, which starts and stops with RViz because it is a viewer aid and nothing else reads it. RViz's LaserScan display puts a point only where a return came back, so a ray that hit nothing within range draws nothing at all — measured on the 180° scan, 283 of 360 rays were inf, leaving most of the fan blank and no way to tell "the sensor does not look there" from "it looked and the space is empty". scan_rays republishes the same scan on <ns>/scan_rays as two Marker line lists, returns in red and misses drawn out to range in cyan. It never rewrites <ns>/scan itself: turning inf into a range value there would read as a wall at 10 m to the estop node and to Nav2 later.
One argument closes it: enable_rviz:=false. headless does not, because it only closes the gz sim window — the two windows are turned off separately, and a run with the simulator window closed still usually wants RViz, since with gz sim headless RViz is the only window left that shows anything. Closing every window therefore takes both: headless:=true enable_rviz:=false.
That config carries no RobotModel display: the only link with a visual is chassis, and its mesh URI is model://mecanum_lift/..., which RViz's resource retriever cannot resolve — it handles package://, file:// and http:// only.
enable_flat_ground must stay on in the merged world: the current warehouse model carries no <collision> at all, so with the plate off the robot falls through the floor forever (measured: z below −3000 within seconds). The old advice to turn it off dated from the previous world, whose defective STL floor still existed as a collision.
ls /dev/video* shows which webcam index exists; re-plugging a USB camera renumbers it.
Shell entry points in scripts/, each also bound to a VS Code task:
build_workspace.sh — installs ROS 2 Jazzy if missing, then builds
run_gazebo.sh — the world alone, no ROS side
run_full_stack.sh — rosbridge_server plus gz sim, for driving the sim from the Signal-Vision repo over the rosbridge websocket
run_bringup.sh — the full robot bringup
run_camera_node.sh — camera_node alone, as a webcam-to-gesture unit check
setup_infer_env.py — shallow-clones Signal-Vision at its latest tag, vendors that source into signal_vision/vision_hand/, and installs the runtime libraries into system python3.12. It builds no venv.
setup_perception_env.py, setup_repo_venv.py — build .venv-perception for the Signal-transport-perception repository; setup_repo_venv.py holds the shared venv logic
A venv cannot serve ros2 run: colcon writes console scripts with a /usr/bin/python3 shebang no matter which environment is active, so the libraries a node imports have to be in system python3.12. That is why setup_infer_env.py installs there and why run_camera_node.sh activates nothing.
Tests are style checks only, run with colcon test --packages-select robot_control signal_vision auto_drive knavi_bringup.
GUI programs (gz sim with rendering, RViz) must be started from the user's own desktop terminal — launching them from an agent shell fails for lack of a GL context.
Python 3.12. Naming:
PascalCase (e.g. RobotController)
snake_case (e.g. publish_image)
Source comments and docstrings inside src/ are written in Korean and explain why, not what. The English-body plus Korean-comment rule at the top of this file applies to markdown docs, not to code comments.
ament_flake8 and ament_pep257 run as tests, so import order and docstring style are enforced — keep new code passing them.
아직 댓글이 없습니다.
로그인 후 댓글을 남길 수 있어요