Skip to content

Commit a4f82b8

Browse files
DocGarbanzoclaude
DocGarbanzo
and
claude
committed
Add user documentation for segment features in IMU path visualizer
Creates a comprehensive user guide for segment-based performance analysis, accessible via a help link in the web UI. Documents controls, performance ranking, custom statistics, and training integration. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent b4a5e04 commit a4f82b8

File tree

3 files changed

+336
-0
lines changed

3 files changed

+336
-0
lines changed

‎donkeycar/parts/web_controller/templates/imupath.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,24 @@
103103
background-color: #f1c40f;
104104
}
105105

106+
.help-link {
107+
display: inline-block;
108+
margin-top: 6px;
109+
padding: 2px 8px;
110+
color: #64B5F6;
111+
text-decoration: none;
112+
font-size: 10px;
113+
border: 1px solid #64B5F6;
114+
border-radius: 3px;
115+
transition: background-color 0.2s;
116+
}
117+
118+
.help-link:hover {
119+
background-color: #1a3a4a;
120+
color: #90CAF9;
121+
border-color: #90CAF9;
122+
}
123+
106124
.position-panel {
107125
flex: 1;
108126
background-color: #2a2a2a;
@@ -285,6 +303,7 @@
285303
<div class="shutdown-box">
286304
<button class="shutdown-btn" id="shutdown-btn">Shutdown</button>
287305
<button class="restart-btn" id="restart-btn">Server Restart</button>
306+
<a href="/imupath/docs" target="_blank" class="help-link">📖 User Guide</a>
288307
</div>
289308
<div class="position-panel">
290309
<div class="info-title">Current Position</div>

‎donkeycar/parts/web_controller/templates/imupath_docs.html‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta name="viewport" content="width=device-width, initial-scale=1">
5+
<title>IMU Path Visualizer - User Guide</title>
6+
<style>
7+
body {
8+
background-color: #1a1a1a;
9+
color: #e0e0e0;
10+
font-family: 'Courier New', monospace;
11+
margin: 0;
12+
padding: 20px;
13+
font-size: 12px;
14+
line-height: 1.6;
15+
}
16+
17+
.container {
18+
max-width: 900px;
19+
margin: 0 auto;
20+
background-color: #2a2a2a;
21+
padding: 30px;
22+
border-radius: 8px;
23+
}
24+
25+
h1 {
26+
color: #4CAF50;
27+
border-bottom: 2px solid #4CAF50;
28+
padding-bottom: 10px;
29+
margin-top: 0;
30+
}
31+
32+
h2 {
33+
color: #64B5F6;
34+
margin-top: 30px;
35+
border-bottom: 1px solid #444;
36+
padding-bottom: 5px;
37+
}
38+
39+
h3 {
40+
color: #FFB74D;
41+
margin-top: 20px;
42+
}
43+
44+
code {
45+
background-color: #1a1a1a;
46+
padding: 2px 6px;
47+
border-radius: 3px;
48+
color: #4CAF50;
49+
}
50+
51+
.feature-box {
52+
background-color: #333;
53+
padding: 15px;
54+
margin: 15px 0;
55+
border-left: 3px solid #4CAF50;
56+
border-radius: 4px;
57+
}
58+
59+
.control-desc {
60+
background-color: #1a1a1a;
61+
padding: 10px;
62+
margin: 10px 0;
63+
border-radius: 4px;
64+
}
65+
66+
.control-name {
67+
color: #FFB74D;
68+
font-weight: bold;
69+
}
70+
71+
ul, ol {
72+
margin: 10px 0;
73+
}
74+
75+
li {
76+
margin: 5px 0;
77+
}
78+
79+
.back-link {
80+
display: inline-block;
81+
margin-top: 30px;
82+
padding: 8px 16px;
83+
background-color: #4CAF50;
84+
color: white;
85+
text-decoration: none;
86+
border-radius: 4px;
87+
}
88+
89+
.back-link:hover {
90+
background-color: #66BB6A;
91+
}
92+
93+
.tip {
94+
background-color: #1a3a4a;
95+
border-left: 3px solid #64B5F6;
96+
padding: 10px;
97+
margin: 15px 0;
98+
}
99+
100+
.warning {
101+
background-color: #4a2a1a;
102+
border-left: 3px solid #FFB74D;
103+
padding: 10px;
104+
margin: 15px 0;
105+
}
106+
</style>
107+
</head>
108+
<body>
109+
<div class="container">
110+
<h1>📊 IMU Path Visualizer - User Guide</h1>
111+
112+
<h2>Overview</h2>
113+
<p>
114+
The IMU Path Visualizer helps you analyze your car's recorded driving
115+
sessions. It displays your driving path, detects laps automatically,
116+
segments the course into sections, and ranks your performance in each
117+
segment.
118+
</p>
119+
120+
<h2>Basic Controls</h2>
121+
122+
<div class="control-desc">
123+
<span class="control-name">Play/Pause Button</span><br>
124+
Start or stop automatic playback through your recorded path.
125+
</div>
126+
127+
<div class="control-desc">
128+
<span class="control-name">Time Slider</span><br>
129+
Drag to navigate to any point in your recording. You can also use
130+
keyboard arrow keys (← →) for frame-by-frame navigation.
131+
</div>
132+
133+
<div class="control-desc">
134+
<span class="control-name">Laps Selector</span><br>
135+
Choose how many laps to use for computing the mean reference course.
136+
The mean course is shown in cyan and represents the average path across
137+
the selected number of laps.
138+
</div>
139+
140+
<div class="control-desc">
141+
<span class="control-name">Segments Selector</span><br>
142+
Choose the algorithm for dividing the course into segments:
143+
<ul>
144+
<li><b>Threshold</b>: Segments based on curvature thresholds</li>
145+
<li><b>Extrema</b>: Segments at curvature peaks/valleys</li>
146+
<li><b>Gradient</b>: Segments where curvature changes rapidly</li>
147+
<li><b>Hybrid</b>: Combines multiple methods (recommended)</li>
148+
</ul>
149+
</div>
150+
151+
<div class="control-desc">
152+
<span class="control-name">Path/Mean Checkboxes</span><br>
153+
Toggle visibility of the driven path (your actual recording) and mean
154+
course (reference line).
155+
</div>
156+
157+
<h2>Segment Performance Analysis</h2>
158+
159+
<div class="feature-box">
160+
<h3>What are Segments?</h3>
161+
<p>
162+
Segments are geometric sections of your course (straights, turns,
163+
chicanes). The visualizer automatically divides your course into
164+
segments based on curvature analysis.
165+
</p>
166+
</div>
167+
168+
<div class="feature-box">
169+
<h3>How Performance Ranking Works</h3>
170+
<p>
171+
For each segment, the visualizer compares how you drove it across
172+
different laps. It ranks each instance from 0% (worst) to 100% (best)
173+
based on the selected field and aggregation method.
174+
</p>
175+
<p>
176+
<b>Example:</b> If you drove segment 3 in three laps with times of
177+
2.1s, 1.8s, and 2.0s, the rankings would be:<br>
178+
Lap 1: 0% (slowest), Lap 2: 100% (fastest), Lap 3: 50% (middle)
179+
</p>
180+
</div>
181+
182+
<h2>Advanced: Custom Segment Statistics</h2>
183+
184+
<p>
185+
When viewing Tub data (recorded driving sessions), you can analyze
186+
segment performance using any numeric field from your recordings.
187+
</p>
188+
189+
<div class="control-desc">
190+
<span class="control-name">Field Selector</span><br>
191+
Choose which data field to analyze:
192+
<ul>
193+
<li><code>time</code> - Time spent in segment (built-in)</li>
194+
<li><code>distance</code> - Distance traveled (built-in)</li>
195+
<li><code>car/speed</code> - Vehicle speed data</li>
196+
<li><code>imu/gyr</code> - Gyroscope data (smoothness)</li>
197+
<li><code>imu/acl</code> - Accelerometer data</li>
198+
<li>... any numeric field from your tub</li>
199+
</ul>
200+
</div>
201+
202+
<div class="control-desc">
203+
<span class="control-name">Method Selector</span><br>
204+
Choose how to aggregate the field values within each segment:
205+
<ul>
206+
<li><code>delta</code> - Last minus first (for time, distance)</li>
207+
<li><code>mean_abs</code> - Average of absolute values</li>
208+
<li><code>sum_abs</code> - Sum of absolute values</li>
209+
<li><code>max</code> - Maximum value in segment</li>
210+
<li><code>min</code> - Minimum value in segment</li>
211+
<li><code>norm</code> - Euclidean magnitude (for vectors)</li>
212+
</ul>
213+
</div>
214+
215+
<div class="control-desc">
216+
<span class="control-name">Dimension Selector</span><br>
217+
For vector fields (like IMU data), choose which component to analyze:
218+
<ul>
219+
<li><code>X</code> - First component</li>
220+
<li><code>Y</code> - Second component</li>
221+
<li><code>Z</code> - Third component</li>
222+
<li><code>Magnitude</code> - Combined length of vector</li>
223+
</ul>
224+
</div>
225+
226+
<div class="tip">
227+
<b>💡 Tip:</b> Use <code>imu/gyr</code> Z-axis with <code>sum_abs</code>
228+
to measure driving smoothness. Lower values = smoother steering.
229+
</div>
230+
231+
<h2>Understanding the Display</h2>
232+
233+
<div class="feature-box">
234+
<h3>Current Position Panel</h3>
235+
<p>
236+
Shows real-time information about the current position on the path:
237+
</p>
238+
<ul>
239+
<li><b>Date/Time:</b> Recording timestamp</li>
240+
<li><b>Index:</b> Data point number</li>
241+
<li><b>Lap:</b> Current lap number (0-based)</li>
242+
<li><b>Segment:</b> Current segment ID</li>
243+
<li><b>Speed:</b> Vehicle speed in m/s</li>
244+
<li><b>IMU Yaw:</b> Heading angle from IMU</li>
245+
<li><b>X/Y:</b> Position coordinates in meters</li>
246+
<li><b>Total Dist:</b> Cumulative distance traveled</li>
247+
<li><b>Lap Dist:</b> Distance within current lap</li>
248+
<li><b>Seg Rank:</b> Performance ranking (0-100%)</li>
249+
</ul>
250+
</div>
251+
252+
<div class="feature-box">
253+
<h3>Path Visualization</h3>
254+
<ul>
255+
<li><b>Color-coded points:</b> Each point shows segment ranking by
256+
color (red = worst, green = best)</li>
257+
<li><b>Segment boundaries:</b> White lines perpendicular to the
258+
course</li>
259+
<li><b>Mean course:</b> Cyan line showing average path</li>
260+
<li><b>Current position marker:</b> Red circle with white border</li>
261+
</ul>
262+
</div>
263+
264+
<h2>Training with Segment Performance</h2>
265+
266+
<div class="feature-box">
267+
<p>
268+
After analyzing your data, you can use segment-based training to
269+
create a model that learns from the best-driven instance of each
270+
segment, rather than just the best complete lap.
271+
</p>
272+
<ol>
273+
<li>Record multiple laps with varied performance</li>
274+
<li>Run: <code>donkey segment --tub ./data/</code></li>
275+
<li>Enable in config: <code>SEGMENT_PCT_MODE = True</code></li>
276+
<li>Train: <code>python manage.py train --tub ./data/</code></li>
277+
</ol>
278+
<p>
279+
The model will learn a "synthetic perfect lap" combining the best
280+
driving from each segment across all your laps.
281+
</p>
282+
</div>
283+
284+
<div class="warning">
285+
<b>⚠️ Note:</b> Segment-based training requires segmentation data
286+
to be computed first using <code>donkey segment</code> command.
287+
</div>
288+
289+
<h2>Keyboard Shortcuts</h2>
290+
<ul>
291+
<li><b>←</b> (Left Arrow): Go to previous frame</li>
292+
<li><b>→</b> (Right Arrow): Go to next frame</li>
293+
<li><b>Space:</b> Play/Pause (when plot is focused)</li>
294+
</ul>
295+
296+
<h2>Configuration</h2>
297+
298+
<div class="tip">
299+
<b>💡 Advanced:</b> You can configure which fields are available
300+
for segment analysis by editing <code>FIELD_AGGREGATIONS</code>
301+
in your <code>config.py</code> file. Pass <code>--config
302+
/path/to/config.py</code> when starting the visualizer.
303+
</div>
304+
305+
<a href="/imupath" class="back-link">← Back to Visualizer</a>
306+
</div>
307+
</body>
308+
</html>

‎donkeycar/parts/web_controller/web.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ def __init__(self, port=8887, mode='user'):
137137
(r"/video", VideoAPI),
138138
(r"/wsTest", WsTest),
139139
(r"/imupath", IMUPathHandler),
140+
(r"/imupath/docs", IMUPathDocsHandler),
140141
(r"/api/imupath/data", IMUPathDataAPI),
141142
(r"/api/imupath/fields", IMUPathFieldsAPI),
142143
(r"/api/imupath/stats", IMUPathStatsAPI),
@@ -414,6 +415,14 @@ async def get(self):
414415
await self.render("templates/imupath.html", **data)
415416

416417

418+
class IMUPathDocsHandler(RequestHandler):
419+
"""Serves the IMU path visualizer user documentation."""
420+
421+
async def get(self):
422+
data = {}
423+
await self.render("templates/imupath_docs.html", **data)
424+
425+
417426
class IMUPathFieldsAPI(RequestHandler):
418427
"""
419428
API endpoint for getting available fields from tub data.

0 commit comments

Comments
 (0)