Spaces:
Sleeping
Sleeping
File size: 13,805 Bytes
3f68f4c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 | """
CoolRide — Field Test Protocol Document Generator
===================================================
Generates a formatted .docx briefing document for testers.
Usage:
python testing/create_protocol_doc.py
"""
import os
from datetime import datetime
try:
from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
HAS_DOCX = True
except ImportError:
HAS_DOCX = False
ROOT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
OUTPUT_DIR = os.path.join(ROOT_DIR, "output")
os.makedirs(OUTPUT_DIR, exist_ok=True)
# ============================================================
# DOCUMENT CONTENT
# ============================================================
def generate_docx():
doc = Document()
# --- Title ---
title = doc.add_heading("CoolRide Field Test Protocol", level=0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER
subtitle = doc.add_heading("Round 2: Kent Ridge Blind A/B Test", level=1)
subtitle.alignment = WD_ALIGN_PARAGRAPH.CENTER
doc.add_paragraph(
f"Date: Tuesday, February 10, 2026 | Time: 3:00 PM — 5:00 PM\n"
f"Location: Kent Ridge Park → Buona Vista\n"
f"Document Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}"
)
doc.add_paragraph("") # spacer
# --- Objective ---
doc.add_heading("1. Objective", level=2)
doc.add_paragraph(
'Validate the "Sweat Factor" algorithm by testing whether the '
"elevation-aware Cool route produces measurably lower thermal stress "
"and perceived exertion compared to the standard shortest-distance route. "
"This is a BLIND test — testers do NOT know which route is optimized."
)
# --- Roles ---
doc.add_heading("2. Team Assignment", level=2)
table = doc.add_table(rows=3, cols=3)
table.style = "Table Grid"
# Header
for i, text in enumerate(["", "Team Blue", "Team Red"]):
table.rows[0].cells[i].text = text
for p in table.rows[0].cells[i].paragraphs:
for r in p.runs:
r.bold = True
# Data
table.rows[1].cells[0].text = "Route Code"
table.rows[1].cells[1].text = "KR-BLIND-A"
table.rows[1].cells[2].text = "KR-BLIND-B"
table.rows[2].cells[0].text = "KML File"
table.rows[2].cells[1].text = "Route_A_Blue.kml"
table.rows[2].cells[2].text = "Route_B_Red.kml"
doc.add_paragraph("")
# --- Route Codes for Google Form ---
doc.add_heading("3. Route Codes (For Google Form)", level=2)
doc.add_paragraph(
"When filling out the data collection Google Form after each checkpoint:"
)
p = doc.add_paragraph()
p.add_run("Team Blue: ").bold = True
p.add_run('Select "KR-BLIND-A" in the Route ID field.')
p = doc.add_paragraph()
p.add_run("Team Red: ").bold = True
p.add_run('Select "KR-BLIND-B" in the Route ID field.')
# --- The Blind Rule ---
doc.add_heading("4. The Blind Rule", level=2)
p = doc.add_paragraph()
run = p.add_run(
"IMPORTANT: Testers do NOT know which route is the 'Cool' route. "
"Do NOT discuss route characteristics with the other team until "
"AFTER all data has been collected and submitted."
)
run.bold = True
doc.add_paragraph(
"Follow your assigned colored line strictly. Do not deviate or "
"take shortcuts, even if you see a 'better' path. The integrity "
"of the A/B test depends on each tester completing their assigned route."
)
# --- Navigation ---
doc.add_heading("5. Navigation Instructions", level=2)
doc.add_paragraph(
"Load your assigned KML file on Google Maps (or Google Earth). "
"Your route will appear as a colored overlay on the map."
)
p = doc.add_paragraph()
run = p.add_run('DO NOT press "Start Navigation". ')
run.bold = True
p.add_run(
'Use the "Blue Dot" method: follow your position (blue dot) along '
"the colored route line. This prevents Google Maps from rerouting "
"you onto its own path, which would invalidate the test."
)
doc.add_paragraph("Steps to load KML on phone:", style="List Bullet")
doc.add_paragraph("Open the KML file sent via Telegram/WhatsApp.", style="List Bullet 2")
doc.add_paragraph("It will open in Google Earth or Maps automatically.", style="List Bullet 2")
doc.add_paragraph("Your route appears as a colored line with numbered pins.", style="List Bullet 2")
doc.add_paragraph("Follow the line using your GPS blue dot.", style="List Bullet 2")
# --- Checkpoint Protocol ---
doc.add_heading("6. Checkpoint Protocol (Stop & Log)", level=2)
doc.add_paragraph(
"Your route has 5 pins: START, Checkpoint 1 (25%), Checkpoint 2 (50%), "
"Checkpoint 3 (75%), and FINISH. At each numbered checkpoint (1, 2, 3):"
)
doc.add_paragraph("STOP completely. Park your bike safely.", style="List Number")
doc.add_paragraph("Log WBGT reading (if sensor available) or note perceived temperature.", style="List Number")
doc.add_paragraph("Rate your RPE (Rate of Perceived Exertion) on a scale of 1-10.", style="List Number")
doc.add_paragraph("Take the mandatory photos/videos (see Section 7).", style="List Number")
doc.add_paragraph("Submit the Google Form entry for this checkpoint.", style="List Number")
doc.add_paragraph("Continue to the next checkpoint.", style="List Number")
# --- Media Requirements ---
doc.add_heading("7. Media Requirements (MANDATORY)", level=2)
p = doc.add_paragraph()
p.add_run("At EVERY checkpoint, capture ALL of the following:").bold = True
doc.add_paragraph("")
media_table = doc.add_table(rows=4, cols=3)
media_table.style = "Table Grid"
headers = ["#", "Type", "Details"]
for i, h in enumerate(headers):
media_table.rows[0].cells[i].text = h
for p in media_table.rows[0].cells[i].paragraphs:
for r in p.runs:
r.bold = True
media_data = [
("1", "Selfie", "You at the checkpoint location. Must show surroundings (shade/sun)."),
("2", "Video", "5-10 second clip of the route environment (road surface, shade, traffic)."),
("3", "Environment Photo", "Photo looking DOWN the route ahead. Focus on slope/shade/road type."),
]
for row_idx, (num, typ, detail) in enumerate(media_data, 1):
media_table.rows[row_idx].cells[0].text = num
media_table.rows[row_idx].cells[1].text = typ
media_table.rows[row_idx].cells[2].text = detail
doc.add_paragraph("")
doc.add_paragraph(
"Name files with format: [TeamColor]_CP[Number]_[type].[ext]\n"
"Example: Blue_CP2_selfie.jpg, Red_CP1_video.mp4"
)
# --- RPE Scale ---
doc.add_heading("8. RPE Scale Reference", level=2)
rpe_table = doc.add_table(rows=6, cols=2)
rpe_table.style = "Table Grid"
rpe_table.rows[0].cells[0].text = "RPE"
rpe_table.rows[0].cells[1].text = "Description"
for p in rpe_table.rows[0].cells[0].paragraphs:
for r in p.runs: r.bold = True
for p in rpe_table.rows[0].cells[1].paragraphs:
for r in p.runs: r.bold = True
rpe_data = [
("1-2", "Very easy. Barely any effort. Chatting comfortably."),
("3-4", "Easy. Breathing slightly harder. Could sustain for hours."),
("5-6", "Moderate. Noticeable effort. Breathing heavier. Some sweating."),
("7-8", "Hard. Significant effort. Heavy sweating. Difficult to talk."),
("9-10", "Maximum. Cannot sustain. Gasping. Want to stop immediately."),
]
for row_idx, (rpe, desc) in enumerate(rpe_data, 1):
rpe_table.rows[row_idx].cells[0].text = rpe
rpe_table.rows[row_idx].cells[1].text = desc
# --- Safety ---
doc.add_heading("9. Safety Briefing", level=2)
p = doc.add_paragraph()
p.add_run("Kent Ridge has winding roads with vehicle traffic. ").bold = True
p.add_run("Exercise caution at all times.")
doc.add_paragraph("Wear a helmet at all times while cycling.", style="List Bullet")
doc.add_paragraph("Carry at least 500ml of water. Hydrate at every checkpoint.", style="List Bullet")
doc.add_paragraph("Watch for cars on South Buona Vista Road and Kent Ridge Crescent.", style="List Bullet")
doc.add_paragraph("Use hand signals when turning. Make eye contact with drivers.", style="List Bullet")
doc.add_paragraph("If you feel dizzy, nauseous, or overheated — STOP immediately and message the group chat.", style="List Bullet")
doc.add_paragraph("Emergency: Call 995 (Ambulance) or 999 (Police).", style="List Bullet")
p = doc.add_paragraph()
run = p.add_run("ABORT PROTOCOL: ")
run.bold = True
p.add_run(
'If any tester reports heat distress, BOTH teams stop. '
'Send location pin to group chat. Safety > Data.'
)
# --- Timeline ---
doc.add_heading("10. Timeline", level=2)
timeline_table = doc.add_table(rows=7, cols=2)
timeline_table.style = "Table Grid"
timeline_table.rows[0].cells[0].text = "Time"
timeline_table.rows[0].cells[1].text = "Activity"
for p in timeline_table.rows[0].cells[0].paragraphs:
for r in p.runs: r.bold = True
for p in timeline_table.rows[0].cells[1].paragraphs:
for r in p.runs: r.bold = True
timeline = [
("2:45 PM", "Meet at Start Point (Kent Ridge Park). Load KMLs. Brief."),
("3:00 PM", "Both teams depart simultaneously. Start timers."),
("3:00-3:45 PM", "Ride assigned routes. Stop at each checkpoint."),
("3:45 PM", "Expected arrival at Finish (Buona Vista). Final checkpoint."),
("3:45-4:00 PM", "Submit all Google Form entries. Upload media."),
("4:00 PM", "Debrief. Reveal blind key. Discuss experience."),
]
for row_idx, (t, activity) in enumerate(timeline, 1):
timeline_table.rows[row_idx].cells[0].text = t
timeline_table.rows[row_idx].cells[1].text = activity
# --- Footer ---
doc.add_paragraph("")
p = doc.add_paragraph()
p.alignment = WD_ALIGN_PARAGRAPH.CENTER
run = p.add_run("CoolRide — YDCT Project 2026")
run.italic = True
run.font.color.rgb = RGBColor(128, 128, 128)
return doc
# ============================================================
# FALLBACK: Plain text if python-docx unavailable
# ============================================================
def generate_txt():
content = """
================================================================
COOLRIDE FIELD TEST PROTOCOL
Round 2: Kent Ridge Blind A/B Test
================================================================
Date: Tuesday, February 10, 2026 | Time: 3:00 PM - 5:00 PM
Location: Kent Ridge Park -> Buona Vista
1. OBJECTIVE
Validate "Sweat Factor" algorithm by testing elevation-aware
Cool route vs standard shortest-distance route. BLIND test.
2. TEAM ASSIGNMENT
Team Blue: Route KR-BLIND-A | File: Route_A_Blue.kml
Team Red: Route KR-BLIND-B | File: Route_B_Red.kml
3. ROUTE CODES (FOR GOOGLE FORM)
Team Blue: Select "KR-BLIND-A"
Team Red: Select "KR-BLIND-B"
4. THE BLIND RULE
Testers do NOT know which route is 'Cool'.
Follow your assigned colored line STRICTLY.
Do NOT discuss route characteristics until AFTER data submission.
5. NAVIGATION
DO NOT press "Start Navigation".
Use the "Blue Dot" method: follow your GPS position along
the colored route line on Google Maps/Earth.
6. CHECKPOINT PROTOCOL (STOP & LOG)
At each numbered checkpoint (1, 2, 3):
1) STOP completely
2) Log WBGT reading or perceived temperature
3) Rate RPE (1-10)
4) Take mandatory photos/videos
5) Submit Google Form entry
6) Continue to next checkpoint
7. MEDIA REQUIREMENTS (MANDATORY)
At EVERY checkpoint:
1) 1x Selfie at checkpoint (show surroundings)
2) 1x Video of environment (5-10 seconds)
3) 1x Photo looking down route (slope/shade/road type)
8. SAFETY
- Wear helmet at all times
- Carry 500ml+ water, hydrate at every checkpoint
- Watch for cars on South Buona Vista Rd
- If dizzy/nauseous/overheated: STOP, message group chat
- Emergency: 995 (Ambulance) / 999 (Police)
- ABORT: If heat distress, BOTH teams stop. Safety > Data.
9. TIMELINE
2:45 PM Meet at Start. Load KMLs. Brief.
3:00 PM Both teams depart simultaneously.
3:00-3:45 PM Ride routes. Stop at checkpoints.
3:45 PM Arrival at Finish. Final checkpoint.
3:45-4:00 PM Submit forms. Upload media.
4:00 PM Debrief. Reveal blind key. Discuss.
================================================================
CoolRide - YDCT Project 2026
================================================================
"""
return content.strip()
# ============================================================
# MAIN
# ============================================================
if __name__ == "__main__":
print("=" * 60)
print(" PROTOCOL DOCUMENT GENERATOR")
print("=" * 60)
if HAS_DOCX:
doc = generate_docx()
filepath = os.path.join(OUTPUT_DIR, "Field_Test_Protocol_Round2.docx")
doc.save(filepath)
print(f"\n Generated (DOCX): {filepath}")
else:
print("\n python-docx not installed. Generating .txt fallback.")
content = generate_txt()
filepath = os.path.join(OUTPUT_DIR, "Field_Test_Protocol_Round2.txt")
with open(filepath, "w") as f:
f.write(content)
print(f" Generated (TXT): {filepath}")
# Always generate txt as backup
txt_content = generate_txt()
txt_path = os.path.join(OUTPUT_DIR, "Field_Test_Protocol_Round2.txt")
with open(txt_path, "w") as f:
f.write(txt_content)
print(f" Generated (TXT): {txt_path}")
print("\nDone.")
|