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