Spaces:
Sleeping
Sleeping
Download testing/create_protocol_doc.py from arish7/coolride-telegram: direct link, hf CLI and curl.
- Browser
- Download file 13.8 kB
-
https://huggingface.co/spaces/arish7/coolride-telegram/resolve/main/testing/create_protocol_doc.py
- Command line
-
hf download hf://spaces/arish7/coolride-telegram/testing/create_protocol_doc.py
-
curl -L -o create_protocol_doc.py https://huggingface.co/spaces/arish7/coolride-telegram/resolve/main/testing/create_protocol_doc.py
13.8 kB
| """ | |
| 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.") | |