""" 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.")