Upload 8 files

Dockerfile

@@ -0,0 +1,26 @@
+# Dockerfile for Hugging Face Spaces (Docker SDK).
+# Hugging Face Spaces no longer supports Streamlit as a native built-in SDK,
+# so Streamlit apps run inside a small Docker container instead. This file
+# does exactly what "streamlit run app.py" does locally, just packaged so
+# Hugging Face knows how to build and start it.
+
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# System libraries OpenCV sometimes needs even in "headless" mode.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Hugging Face Spaces expects the app to listen on port 7860 by default
+# for Docker-based Spaces (set via app_port in the Space's README.md).
+EXPOSE 7860
+
+CMD ["streamlit", "run", "app.py", "--server.port=7860", "--server.address=0.0.0.0"]

README.md

@@ -1,10 +1,19 @@
 ---
-title: Detection
-emoji: 🌍
-colorFrom: blue
-colorTo: yellow
+title: Traffic Scene Interpretation System
+emoji: 🚦
+colorFrom: yellow
+colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Traffic Scene Interpretation System
+
+A Streamlit application that uses YOLOv8 to detect vehicles and pedestrians
+in traffic images and video, and reports a basic interpretation of the scene
+(free flowing / moderate / congested).
+
+Upload an image or a short video clip in the tabs above to try it.
+
+Built with Streamlit, Ultralytics YOLOv8, and OpenCV.

app.py

@@ -0,0 +1,146 @@
+"""
+app.py
+------
+Traffic Scene Interpretation System — Streamlit front end.
+
+Scope for this build (agreed scope):
+  - Image upload -> detection
+  - Video upload -> detection
+  - Vehicle counting + basic scene interpretation (congestion label)
+  - Download annotated result
+
+Webcam mode is intentionally left out of this version — image + video
+upload was confirmed to be sufficient for the supervisor's requirements.
+A `webcam_stub.py` stub is included separately with notes on how to add it
+later if needed, so it doesn't block delivery of the core system.
+
+Run with:
+    streamlit run app.py
+"""
+
+import os
+import tempfile
+
+import cv2
+import numpy as np
+import streamlit as st
+from PIL import Image
+
+import theme
+from detector import TrafficDetector
+
+st.set_page_config(page_title="Traffic Scene Interpretation System", page_icon="🚦", layout="wide")
+theme.inject()
+
+
+@st.cache_resource(show_spinner="Loading YOLO model (first run only)...")
+def load_detector() -> TrafficDetector:
+    return TrafficDetector()
+
+
+def render_stats(stats, cam_tag: str):
+    avg_counts = stats.per_frame_average()
+    theme.chip_row(avg_counts)
+
+    col1, col2 = st.columns([1, 1])
+    with col1:
+        theme.congestion_badge(stats.congestion_label())
+    with col2:
+        if stats.fps:
+            st.caption(f"PROCESSING SPEED · {stats.fps} FPS")
+
+
+def image_tab(detector: TrafficDetector):
+    uploaded = st.file_uploader("Upload an image", type=["jpg", "jpeg", "png"], key="img")
+
+    if uploaded is not None:
+        pil_image = Image.open(uploaded).convert("RGB")
+        bgr_image = cv2.cvtColor(np.array(pil_image), cv2.COLOR_RGB2BGR)
+
+        with st.spinner("Running detection..."):
+            annotated, stats = detector.detect_image(bgr_image)
+
+        annotated_rgb = cv2.cvtColor(annotated, cv2.COLOR_BGR2RGB)
+
+        col1, col2 = st.columns(2)
+        with col1:
+            with st.container(border=True):
+                theme.feed_caption("CAM 01", "RAW FEED")
+                st.image(pil_image, use_container_width=True)
+        with col2:
+            with st.container(border=True):
+                theme.feed_caption("CAM 01", "DETECTION OVERLAY")
+                st.image(annotated_rgb, use_container_width=True)
+
+        st.markdown('<hr class="tsis-hr">', unsafe_allow_html=True)
+
+        with st.container(border=True):
+            theme.feed_caption("SUMMARY", "DETECTION READOUT")
+            render_stats(stats, "CAM 01")
+
+            result_pil = Image.fromarray(annotated_rgb)
+            buf_path = os.path.join(tempfile.gettempdir(), "annotated_result.png")
+            result_pil.save(buf_path)
+            with open(buf_path, "rb") as f:
+                st.download_button("Download result image", f, file_name="detection_result.png")
+
+
+def video_tab(detector: TrafficDetector):
+    uploaded = st.file_uploader("Upload a video", type=["mp4", "avi", "mov", "mkv"], key="vid")
+
+    if uploaded is not None:
+        # Save upload to a temp file since OpenCV needs a real file path
+        in_path = os.path.join(tempfile.gettempdir(), f"input_{uploaded.name}")
+        out_path = os.path.join(tempfile.gettempdir(), "annotated_output.mp4")
+        with open(in_path, "wb") as f:
+            f.write(uploaded.read())
+
+        progress_bar = st.progress(0, text="Starting...")
+
+        def update_progress(current, total):
+            if total:
+                progress_bar.progress(min(current / total, 1.0), text=f"Processing frame {current}/{total}")
+            else:
+                progress_bar.progress(0, text=f"Processing frame {current}")
+
+        with st.spinner("Running detection on video... this can take a while for longer clips."):
+            stats = detector.detect_video(in_path, out_path, progress_callback=update_progress)
+
+        progress_bar.empty()
+
+        with st.container(border=True):
+            theme.feed_caption("CAM 02", "DETECTION OVERLAY")
+            st.video(out_path)
+
+        st.markdown('<hr class="tsis-hr">', unsafe_allow_html=True)
+
+        with st.container(border=True):
+            theme.feed_caption("SUMMARY", "DETECTION READOUT")
+            render_stats(stats, "CAM 02")
+
+            with open(out_path, "rb") as f:
+                st.download_button("Download result video", f, file_name="detection_result.mp4")
+
+
+def main():
+    theme.masthead()
+    theme.hero(
+        eyebrow="VEHICLE DETECTION · SCENE ANALYSIS",
+        title="Traffic Scene Interpretation System",
+        subtitle=(
+            "Upload footage from a traffic camera to detect vehicles and pedestrians, "
+            "count them by class, and read the overall state of the scene."
+        ),
+    )
+
+    detector = load_detector()
+
+    tab1, tab2 = st.tabs(["Image feed", "Video feed"])
+    with tab1:
+        image_tab(detector)
+    with tab2:
+        video_tab(detector)
+
+
+if __name__ == "__main__":
+    main()

detector.py

@@ -0,0 +1,233 @@
+"""
+detector.py
+-----------
+Core AI module for the Traffic Scene Interpretation System.
+
+Responsibilities:
+- Load a YOLO model (Ultralytics) once and reuse it.
+- Run detection on a single image (numpy array / PIL image).
+- Run detection on a video file, frame by frame, and write an annotated
+  output video.
+- Aggregate per-frame detections into simple traffic-scene statistics
+  (vehicle counts, congestion level) — this is the "scene interpretation"
+  layer on top of raw object detection.
+
+Kept deliberately simple and well-commented so it's easy to explain
+during a project defense.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import Counter
+from dataclasses import dataclass, field
+
+import cv2
+import numpy as np
+from ultralytics import YOLO
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+# Classes from the COCO dataset (what pretrained YOLO already knows) that are
+# relevant to a traffic scene. No custom training needed for the MVP.
+VEHICLE_CLASSES = {
+    "car": "Cars",
+    "bus": "Buses",
+    "truck": "Trucks",
+    "motorcycle": "Motorcycles",
+    "bicycle": "Bicycles",
+    "person": "Pedestrians",
+}
+
+# Thresholds used to translate a raw vehicle count into a human-readable
+# "scene interpretation" label. Tune these once you see real results.
+CONGESTION_THRESHOLDS = {
+    "free": 5,       # 0-5 vehicles  -> Free flowing
+    "moderate": 15,  # 6-15 vehicles -> Moderate traffic
+    # >15 vehicles -> Congested
+}
+
+IMAGE_MODEL = "yolov8m.pt"   # Used for single-image detection. Accuracy matters more than
+                              # speed here since it only runs once per upload.
+VIDEO_MODEL = "yolov8m.pt"   # Bumped up from yolov8s for better accuracy, per testing feedback.
+                              # This is noticeably slower (roughly 2-3x the compute of yolov8s).
+                              # Frame skipping + reduced imgsz below help offset that cost.
+                              # If processing time becomes uncomfortable, drop back to "yolov8s.pt".
+VIDEO_IMGSZ = 480             # Shrinking the frame before detection speeds video up further.
+                              # Lower = faster but less accurate on small/distant objects.
+                              # Try 384 if still too slow; try 640 (native) if you have room to spare.
+VIDEO_FRAME_SKIP = 2          # Run detection on 1 out of every N frames; reuse the previous
+                              # frame's boxes for the skipped ones. 2 = run detection on half
+                              # the frames (~2x faster). Set to 1 to disable (detect every frame).
+CONFIDENCE_THRESHOLD = 0.25    # Lowered from 0.35 to catch smaller/more distant vehicles.
+                                # If you start seeing false detections (boxes on things that aren't
+                                # vehicles), raise this back up toward 0.35-0.4.
+
+
+@dataclass
+class SceneStats:
+    """Aggregated statistics for one image or one video."""
+    counts: Counter = field(default_factory=Counter)
+    total_frames: int = 1
+    fps: float = 0.0
+
+    def per_frame_average(self) -> Counter:
+        if self.total_frames <= 0:
+            return self.counts
+        return Counter({k: round(v / self.total_frames, 1) for k, v in self.counts.items()})
+
+    def congestion_label(self) -> str:
+        vehicle_count = sum(
+            v for k, v in self.per_frame_average().items() if k != "Pedestrians"
+        )
+        if vehicle_count <= CONGESTION_THRESHOLDS["free"]:
+            return "Free flowing"
+        elif vehicle_count <= CONGESTION_THRESHOLDS["moderate"]:
+            return "Moderate traffic"
+        else:
+            return "Congested"
+
+
+class TrafficDetector:
+    """
+    Wraps two YOLO models:
+      - self.image_model: larger/more accurate, used for single-image detection.
+      - self.video_model: smaller/faster, used for video (and would be used for
+        webcam too, if that's added later) since it runs once per frame.
+    Both are loaded once at startup and reused.
+    """
+
+    def __init__(
+        self,
+        image_model_path: str = IMAGE_MODEL,
+        video_model_path: str = VIDEO_MODEL,
+        conf: float = CONFIDENCE_THRESHOLD,
+    ):
+        self.image_model = YOLO(image_model_path)
+        # Avoid loading the same weights twice if someone sets both to the same file.
+        self.video_model = (
+            self.image_model if video_model_path == image_model_path else YOLO(video_model_path)
+        )
+        self.conf = conf
+
+    # -- Image -------------------------------------------------------------
+
+    def detect_image(self, image: np.ndarray) -> tuple[np.ndarray, SceneStats]:
+        """
+        Run detection on a single BGR image (as read by cv2).
+        Returns (annotated_image, stats).
+        """
+        results = self.image_model.predict(image, conf=self.conf, verbose=False)
+        result = results[0]
+
+        counts = self._count_from_result(result)
+        annotated = result.plot()  # draws boxes + labels + confidence
+
+        stats = SceneStats(counts=counts, total_frames=1)
+        return annotated, stats
+
+    # -- Video ---------------------------------------------------------------
+
+    def detect_video(self, input_path: str, output_path: str, progress_callback=None) -> SceneStats:
+        """
+        Process a video file frame-by-frame:
+          read frame -> YOLO detect -> draw boxes -> write frame to output.
+        Uses the faster video_model + a reduced inference size (VIDEO_IMGSZ) to
+        keep processing time reasonable without a GPU.
+
+        Frame skipping (VIDEO_FRAME_SKIP): to save time, detection only runs on
+        every Nth frame. For the frames in between, we reuse the last detected
+        boxes and re-draw them onto the new frame. Since consecutive frames are
+        1/25th-1/30th of a second apart, objects barely move between them, so
+        this looks smooth while cutting detection calls (the expensive part)
+        roughly in half.
+
+        progress_callback(current_frame, total_frames) is called after each
+        frame if provided, so a Streamlit progress bar can be updated.
+        """
+        cap = cv2.VideoCapture(input_path)
+        if not cap.isOpened():
+            raise RuntimeError(f"Could not open video: {input_path}")
+
+        fps = cap.get(cv2.CAP_PROP_FPS) or 25.0
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT)) or None
+
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        writer = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+
+        total_counts: Counter = Counter()
+        frame_idx = 0
+        detected_frame_count = 0  # frames actually run through YOLO (for stats averaging)
+        start_time = time.time()
+
+        last_result = None  # cached YOLO result, reused on skipped frames
+
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                break
+
+            run_detection = (frame_idx % VIDEO_FRAME_SKIP == 0) or (last_result is None)
+
+            if run_detection:
+                results = self.video_model.predict(frame, conf=self.conf, imgsz=VIDEO_IMGSZ, verbose=False)
+                last_result = results[0]
+                total_counts.update(self._count_from_result(last_result))
+                detected_frame_count += 1
+                annotated = last_result.plot()
+            else:
+                # Re-draw the previous frame's boxes onto the current frame.
+                # plot(img=...) lets us reuse a YOLO result's boxes on a new image.
+                annotated = last_result.plot(img=frame)
+
+            writer.write(annotated)
+
+            frame_idx += 1
+            if progress_callback:
+                progress_callback(frame_idx, total_frames)
+
+        cap.release()
+        writer.release()
+
+        elapsed = max(time.time() - start_time, 1e-6)
+        processing_fps = frame_idx / elapsed
+
+        return SceneStats(
+            counts=total_counts,
+            total_frames=max(detected_frame_count, 1),
+            fps=round(processing_fps, 1),
+        )
+
+    # -- Webcam (single-frame step, called repeatedly by the UI layer) -----
+
+    def detect_frame(self, frame: np.ndarray) -> tuple[np.ndarray, Counter]:
+        """
+        Used for live webcam mode: process exactly one frame and return it
+        annotated, plus its own counts. Uses the fast video_model, same
+        reasoning as detect_video above. The caller (app.py) is responsible
+        for the capture loop, since Streamlit needs to own that loop to
+        keep the UI responsive.
+        """
+        results = self.video_model.predict(frame, conf=self.conf, imgsz=VIDEO_IMGSZ, verbose=False)
+        result = results[0]
+        counts = self._count_from_result(result)
+        return result.plot(), counts
+
+    # -- Helpers -------------------------------------------------------------
+
+    def _count_from_result(self, result) -> Counter:
+        """Turn one YOLO result into a Counter of {readable_label: count}."""
+        counts: Counter = Counter()
+        names = result.names
+        if result.boxes is None:
+            return counts
+        for cls_id in result.boxes.cls.tolist():
+            raw_name = names[int(cls_id)]
+            label = VEHICLE_CLASSES.get(raw_name)
+            if label:
+                counts[label] += 1
+        return counts

requirements.txt

@@ -0,0 +1,5 @@
+streamlit>=1.35
+ultralytics>=8.2
+opencv-python-headless>=4.9
+numpy>=1.26
+Pillow>=10.0

theme.py

@@ -0,0 +1,293 @@
+"""
+theme.py
+--------
+Visual design system for the Traffic Scene Interpretation System UI.
+
+Design direction: a dark traffic-monitoring "control room" console rather
+than a generic AI demo page. Colors are drawn from real traffic signals
+(green/amber/red) so the congestion badge means something, not just
+decorates. Stat readouts use a monospace face to evoke CCTV on-screen
+text. Panels are captioned like camera feeds (e.g. "CAM 01 · RAW").
+
+Token system:
+  Color   bg-primary #0B0E13, bg-panel #141A22, border #232B35,
+          accent-amber #FFB020, signal-green #35D399, signal-red #FF5C5C,
+          text-primary #E8ECF1, text-muted #8B95A3
+  Type    Display: Space Grotesk · Body: Inter · Data/mono: IBM Plex Mono
+"""
+
+import streamlit as st
+
+CSS = """
+<style>
+@import url('https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Inter:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500;600&display=swap');
+
+:root {
+    --bg-primary: #0B0E13;
+    --bg-panel: #141A22;
+    --bg-panel-alt: #10151C;
+    --border-hairline: #232B35;
+    --accent-amber: #FFB020;
+    --signal-green: #35D399;
+    --signal-red: #FF5C5C;
+    --text-primary: #E8ECF1;
+    --text-muted: #8B95A3;
+}
+
+/* Base typography */
+html, body, [class*="css"] {
+    font-family: 'Inter', sans-serif;
+    color: var(--text-primary);
+}
+
+/* Tighten default Streamlit top padding, but leave room for Streamlit's own
+   fixed toolbar (Deploy button etc.) so our masthead doesn't sit underneath it */
+.block-container {
+    padding-top: 3.5rem;
+    max-width: 1100px;
+}
+
+/* ---------------- Masthead ---------------- */
+.tsis-masthead {
+    display: flex;
+    align-items: center;
+    padding: 0.6rem 1rem;
+    background: var(--bg-panel-alt);
+    border: 1px solid var(--border-hairline);
+    border-radius: 4px;
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.75rem;
+    letter-spacing: 0.04em;
+    color: var(--text-muted);
+    margin-bottom: 1.75rem;
+}
+.tsis-masthead .tsis-status {
+    color: var(--signal-green);
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+}
+.tsis-status-dot {
+    width: 7px;
+    height: 7px;
+    border-radius: 50%;
+    background: var(--signal-green);
+    box-shadow: 0 0 6px var(--signal-green);
+}
+
+/* ---------------- Hero ---------------- */
+.tsis-eyebrow {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--accent-amber);
+    margin-bottom: 0.4rem;
+}
+.tsis-title {
+    font-family: 'Space Grotesk', sans-serif;
+    font-weight: 700;
+    font-size: 2.1rem;
+    line-height: 1.15;
+    color: var(--text-primary);
+    margin-bottom: 0.5rem;
+}
+.tsis-subtitle {
+    font-family: 'Inter', sans-serif;
+    font-size: 0.95rem;
+    color: var(--text-muted);
+    max-width: 640px;
+    margin-bottom: 2rem;
+}
+
+/* ---------------- Feed panel captions ---------------- */
+.tsis-feed-caption {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.7rem;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--text-muted);
+    border-bottom: 1px solid var(--border-hairline);
+    padding-bottom: 0.4rem;
+    margin-bottom: 0.6rem;
+}
+.tsis-feed-caption .tsis-tag {
+    color: var(--accent-amber);
+}
+
+/* ---------------- Bordered containers (image/summary panels) ---------------- */
+[data-testid="stVerticalBlockBorderWrapper"] {
+    background: var(--bg-panel);
+    border: 1px solid var(--border-hairline) !important;
+    border-radius: 6px !important;
+}
+
+/* ---------------- Tabs styled like a camera/source selector ---------------- */
+[data-testid="stTabs"] button [data-testid="stMarkdownContainer"] p {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.8rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+}
+[data-testid="stTabs"] [data-baseweb="tab-list"] {
+    gap: 1.75rem;
+    border-bottom: 1px solid var(--border-hairline);
+}
+[data-testid="stTabs"] button {
+    padding: 0.5rem 0.15rem !important;
+}
+[data-testid="stTabs"] [aria-selected="true"] {
+    color: var(--accent-amber) !important;
+}
+/* The active-tab underline is a separate element from the tab button itself;
+   force its color explicitly instead of relying on the theme's primaryColor
+   cascading down (it doesn't reliably). */
+[data-testid="stTabs"] [data-baseweb="tab-highlight"] {
+    background-color: var(--accent-amber) !important;
+}
+
+/* ---------------- File uploader ---------------- */
+[data-testid="stFileUploaderDropzone"] {
+    background: var(--bg-panel-alt);
+    border: 1px dashed var(--border-hairline) !important;
+    border-radius: 6px;
+}
+
+/* ---------------- Metrics as instrument readouts ---------------- */
+[data-testid="stMetric"] {
+    background: var(--bg-panel-alt);
+    border: 1px solid var(--border-hairline);
+    border-radius: 6px;
+    padding: 0.75rem 1rem;
+}
+[data-testid="stMetricLabel"] {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.68rem;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--text-muted) !important;
+}
+[data-testid="stMetricValue"] {
+    font-family: 'IBM Plex Mono', monospace;
+    color: var(--text-primary) !important;
+}
+
+/* ---------------- Stat chips (vehicle counts) ---------------- */
+.tsis-chip-row { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-bottom: 0.75rem; }
+.tsis-chip {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.78rem;
+    background: var(--bg-panel-alt);
+    border: 1px solid var(--border-hairline);
+    border-radius: 4px;
+    padding: 0.3rem 0.65rem;
+    color: var(--text-primary);
+}
+.tsis-chip .tsis-chip-label { color: var(--text-muted); margin-right: 0.35rem; }
+
+/* ---------------- Congestion badge (traffic-signal colors) ---------------- */
+.tsis-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.85rem;
+    font-weight: 500;
+    padding: 0.45rem 0.85rem;
+    border-radius: 4px;
+    border: 1px solid var(--border-hairline);
+    background: var(--bg-panel-alt);
+}
+.tsis-badge-dot { width: 9px; height: 9px; border-radius: 50%; }
+.tsis-badge-free .tsis-badge-dot { background: var(--signal-green); box-shadow: 0 0 6px var(--signal-green); }
+.tsis-badge-free { color: var(--signal-green); }
+.tsis-badge-moderate .tsis-badge-dot { background: var(--accent-amber); box-shadow: 0 0 6px var(--accent-amber); }
+.tsis-badge-moderate { color: var(--accent-amber); }
+.tsis-badge-congested .tsis-badge-dot { background: var(--signal-red); box-shadow: 0 0 6px var(--signal-red); }
+.tsis-badge-congested { color: var(--signal-red); }
+
+/* ---------------- Buttons ---------------- */
+.stButton > button, .stDownloadButton > button {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.78rem;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    background: transparent;
+    border: 1px solid var(--accent-amber);
+    color: var(--accent-amber);
+    border-radius: 4px;
+}
+.stButton > button:hover, .stDownloadButton > button:hover {
+    background: var(--accent-amber);
+    color: var(--bg-primary);
+}
+
+/* Section divider */
+.tsis-hr {
+    border: none;
+    border-top: 1px solid var(--border-hairline);
+    margin: 1.75rem 0 1.25rem 0;
+}
+</style>
+"""
+
+
+def inject():
+    st.markdown(CSS, unsafe_allow_html=True)
+
+
+def masthead():
+    st.markdown(
+        """
+        <div class="tsis-masthead">
+            <div class="tsis-status"><span class="tsis-status-dot"></span> SYSTEM ONLINE</div>
+        </div>
+        """,
+        unsafe_allow_html=True,
+    )
+
+
+def hero(eyebrow: str, title: str, subtitle: str):
+    st.markdown(
+        f"""
+        <div class="tsis-eyebrow">{eyebrow}</div>
+        <div class="tsis-title">{title}</div>
+        <div class="tsis-subtitle">{subtitle}</div>
+        """,
+        unsafe_allow_html=True,
+    )
+
+
+def feed_caption(tag: str, label: str):
+    st.markdown(
+        f'<div class="tsis-feed-caption"><span class="tsis-tag">{tag}</span> &nbsp;{label}</div>',
+        unsafe_allow_html=True,
+    )
+
+
+def chip_row(counts: dict):
+    if not counts:
+        st.markdown(
+            '<div class="tsis-chip-row"><div class="tsis-chip">'
+            '<span class="tsis-chip-label">STATUS</span>NO OBJECTS DETECTED</div></div>',
+            unsafe_allow_html=True,
+        )
+        return
+    chips = "".join(
+        f'<div class="tsis-chip"><span class="tsis-chip-label">{label.upper()}</span>{count}</div>'
+        for label, count in sorted(counts.items(), key=lambda x: -x[1])
+    )
+    st.markdown(f'<div class="tsis-chip-row">{chips}</div>', unsafe_allow_html=True)
+
+
+def congestion_badge(label: str):
+    variant_map = {
+        "Free flowing": ("tsis-badge-free", "FREE FLOWING"),
+        "Moderate traffic": ("tsis-badge-moderate", "MODERATE TRAFFIC"),
+        "Congested": ("tsis-badge-congested", "CONGESTED"),
+    }
+    variant_class, display_text = variant_map.get(label, ("tsis-badge-moderate", label.upper()))
+    st.markdown(
+        f'<div class="tsis-badge {variant_class}"><span class="tsis-badge-dot"></span>{display_text}</div>',
+        unsafe_allow_html=True,
+    )

webcam_stub.py

@@ -0,0 +1,56 @@
+"""
+webcam_stub.py
+--------------
+NOT wired into app.py — this is a reference/starting point in case the
+supervisor later asks for live webcam detection.
+
+Streamlit does not have a built-in "video loop" the way a desktop GUI does,
+so live webcam detection needs either:
+
+  Option A (simplest, local machine only):
+      Use OpenCV directly to open the webcam (cv2.VideoCapture(0)) inside
+      a `while st.session_state.running:` loop, calling
+      st.image(...) repeatedly to refresh a placeholder. Works, but is a bit
+      choppy and only works when Streamlit runs on the SAME machine as the
+      webcam (fine for a local project demo / defense).
+
+  Option B (proper, works in a real browser/deployed app):
+      Use the `streamlit-webrtc` package, which streams frames from the
+      BROWSER's webcam to the Python backend over WebRTC. This is the
+      correct approach if the app will be accessed remotely (e.g. deployed
+      to Streamlit Cloud) rather than run locally during a defense.
+      pip install streamlit-webrtc
+
+Below is a minimal Option A example, since most project defenses happen
+on the student's own laptop.
+"""
+
+import cv2
+import streamlit as st
+
+from detector import TrafficDetector
+
+
+def webcam_tab(detector: TrafficDetector):
+    st.header("Live Webcam Detection (experimental)")
+    st.caption("Runs locally using your machine's webcam. Click Stop to end the session.")
+
+    run = st.checkbox("Start Webcam")
+    frame_placeholder = st.empty()
+
+    if run:
+        cap = cv2.VideoCapture(0)
+        while run and cap.isOpened():
+            ok, frame = cap.read()
+            if not ok:
+                st.warning("Could not read from webcam.")
+                break
+
+            annotated, _counts = detector.detect_frame(frame)
+            annotated_rgb = cv2.cvtColor(annotated, cv2.COLOR_BGR2RGB)
+            frame_placeholder.image(annotated_rgb, use_container_width=True)
+
+            # Re-check the checkbox each loop so "Stop" actually stops it.
+            run = st.session_state.get("Start Webcam", run)
+
+        cap.release()