Sprint merge from lucastargett fork into upstream main

26_T1/afl_player_tracking_and_crowd_monitoring/Crowd_Monitoring/2026_T1/.gitignore

@@ -58,3 +58,14 @@ tmp/
 # OS files
 .DS_Store
 Thumbs.db
+
+# Allow our specific configuration files even if they are .json
+!shared/config/*.json
+
+# Ignore the actual heavy files
+data/raw/*.mp4
+video_processing/data/extracted_frames/*.jpg
+
+# But allow the folder structure (the .gitkeep files)
+!data/raw/.gitkeep
+!video_processing/data/extracted_frames/.gitkeep

26_T1/afl_player_tracking_and_crowd_monitoring/Crowd_Monitoring/2026_T1/README.md

@@ -2,150 +2,184 @@
 
 ## Overview
 
-This repository contains the Crowd Monitoring module for the Orion project under Redback Operations.
+This folder contains the Crowd Monitoring module for the Orion project.
 
-The purpose of this module is to analyse stadium crowd behaviour and density using computer vision and data analytics. The expected outputs include:
+The module is organised into:
 
-- crowd heatmaps
-- density metrics
-- zone-based analytics
-- behaviour insights for integration into the Orion analytics dashboard
+- task folders for implementation work
+- a shared schema layer for agreed JSON contracts
+- a shared service layer for FastAPI integration
+
+The goal is to let team members work independently while keeping inputs and outputs consistent for backend integration.
 
 ## Objectives
 
-- Detect and analyse spectators in stadium footage
-- Estimate crowd density and distribution
-- Generate zone-based crowd analytics
-- Produce crowd heatmaps and visualisations
-- Develop AI-based crowd behaviour analysis
-- Optionally predict future attendance using machine learning models
+- detect people in stadium footage
+- estimate density across zones
+- generate heatmaps
+- analyse crowd behaviour
+- identify risk zones
+- keep JSON input and output formats clear for backend work
 
-## Proposed Pipeline
+## Pipeline
 
 ```text
 Video Input
-    |
-    v
-Frame Extraction (OpenCV)
-    |
-    v
-Person Detection (YOLOv8)
-    |
-    v
-Crowd Density Estimation
-    |
-    v
-Zone-based Analysis
-    |
-    v
-Heatmap Generation
-    |
-    v
-Analytics Output (JSON / CSV)
-    |
-    v
-Behaviour Analysis / Prediction
+    ->
+Video Processing
+    ->
+Crowd Detection
+    ->
+Density Zoning
+    ->
+Heatmap
+    ->
+Crowd Behaviour Analytics
+    ->
+Crowd Allocation / Risk Zone
 ```
 
 ## Tech Stack
 
 - Python
+- FastAPI
+- Uvicorn
 - YOLOv8 (Ultralytics)
 - OpenCV
 - NumPy
 - Pandas
 
-## 👥 Team Tasks (7 Members)
+## Task Folders
+
+Each task folder is mainly for implementation.
+
+Each member should use:
+
+- `README.md` for task guidance
+- `SCHEMA.md` for exact input and output format
+- `main.py` for implementation
+- `output/` for generated files
+
+Current task folders:
 
-Each team member owns one task. Follow the README in each task folder for detailed objectives and deliverables.
+- `video_processing/`
+- `crowd_detection/`
+- `density_zoning/`
+- `heatmap/`
+- `analytics_output/`
+- `crowd_behaviour_analytics/`
+- `crowd_allocation_risk_zone/`
+- `prediction_optional/`
 
-| # | Task Folder | Team Member | Objective |
-|---|-------------|-------------|-----------|
-| 1 | **video_processing** | Member 1 | Extract frames and prepare video data |
-| 2 | **crowd_detection** | Member 2 | Detect persons using YOLOv8 |
-| 3 | **density_zoning** | Member 3 | Calculate density and zone-based analytics |
-| 4 | **heatmap** | Member 4 | Generate crowd heatmaps |
-| 5 | **analytics_output** | Member 5 | Create reports and output files (JSON/CSV) |
-| 6 | **crowd_behaviour_analytics** | Member 6 | Analyze crowd movement and behavior patterns |
-| 7 | **crowd_allocation_risk_zone** | Member 7 | Assess risk levels and crowd allocation strategy |
+## Shared Folder
 
-**Optional:** `prediction_optional/` - Attendance prediction (if time permits)
+### `shared/config/`
 
----
+Contains shared settings such as thresholds, paths, and common configuration values.
 
-## Task Guidance
+### `shared/schemas/`
 
-Each task folder contains its own `README.md` with:
+Contains the agreed request and response JSON contracts for the 3 services.
 
-- 🎯 Task objective
-- 📥 Expected inputs and outputs
-- 💡 Implementation notes
-- ✅ Suggested deliverables
+### `shared/services/`
 
-This keeps the semester plan split into smaller, easier-to-manage work packages.
+Contains the FastAPI service layer:
 
----
+- `main.py` starts the app
+- `routes.py` defines the endpoints
+- `models.py` defines typed request and response models
+- service files call functions from the task folders
 
-## Project Structure
+## Current Structure
 
 ```text
 2026_T1/
-|-- data/                           # Sample videos and frames
-|-- docs/                           # Documentation and notes
-|-- shared/                         # Common utilities and configs
-|-- requirements.txt                # Dependencies
-|-- README.md                       # This file
-|
-|-- Task Folders (one per member):
-|-- video_processing/               # Task 1: Video extraction & preparation
-|-- crowd_detection/                # Task 2: Person detection (YOLOv8)
-|-- density_zoning/                 # Task 3: Density & zone analysis
-|-- heatmap/                        # Task 4: Heatmap generation
-|-- analytics_output/               # Task 5: Report generation
-|-- crowd_behaviour_analytics/      # Task 6: Behavior analysis
-|-- crowd_allocation_risk_zone/     # Task 7: Risk assessment & allocation
-|
-|-- Optional:
-`-- prediction_optional/            # Optional: Attendance prediction
+|- README.md
+|- requirements.txt
+|- data/
+|- docs/
+|- shared/
+|  |- README.md
+|  |- config/
+|  |- schemas/
+|  `- services/
+|- video_processing/
+|- crowd_detection/
+|- density_zoning/
+|- heatmap/
+|- analytics_output/
+|- crowd_behaviour_analytics/
+|- crowd_allocation_risk_zone/
+`- prediction_optional/
 ```
 
----
+## Service Flow
+
+```text
+Frontend / Backend
+    ->
+FastAPI Routes
+    ->
+Shared Service Files
+    ->
+Task Folder Implementations
+    ->
+Schema-based JSON Response
+```
+
+## API Endpoints
+
+The current service layer exposes 3 main endpoints:
 
-## 🚀 Getting Started
+- `POST /process-detection`
+- `POST /process-analytics`
+- `POST /process-intelligence`
 
-1. **Find your task** in the table above
-2. **Read the README** in your task folder
-3. **Follow the implementation notes**
-4. **Deliver outputs** as specified
-5. **Update your README** with progress
+These endpoints use typed FastAPI models so Swagger can show clear request and response formats.
 
----
+## Working Rule
 
-## 📋 Integration Points
+- task folders contain implementation
+- task `SCHEMA.md` files define internal handoff format
+- `shared/schemas/` defines service-level contract
+- `shared/services/models.py` defines typed API models for Swagger and validation
+- service files should follow schema definitions exactly
+- do not add extra JSON wrapper layers unless the team agrees
 
-Tasks run in sequence:
+## Getting Started
 
+1. Read this root `README.md`
+2. Open your assigned task folder
+3. Read `README.md` and `SCHEMA.md`
+4. Implement your task in `main.py`
+5. Save outputs in `output/`
+6. Keep your input and output aligned with the agreed schema
+
+## Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+## Run FastAPI Service
+
+```bash
+uvicorn shared.services.main:app --reload
 ```
-video_processing (Task 1)
-         ↓
-crowd_detection (Task 2)
-         ↓
-density_zoning (Task 3)
-         ↓
-heatmap (Task 4) + analytics_output (Task 5)
-         ↓
-crowd_behaviour_analytics (Task 6)
-crowd_allocation_risk_zone (Task 7)
-         ↓
-         ↓
-Dashboard / Report Integration
+
+## Open Swagger UI
+
+After the server starts, open:
+
+```text
+http://127.0.0.1:8000/
 ```
 
----
+In the current setup, Swagger UI is served on the root URL.
 
-## 💬 Collaboration
+## Collaboration Notes
 
-- **Shared utilities:** Use files in `shared/` folder
-- **Input/Output:** Check task README for I/O specifications
-- **Questions:** Document in docs/ folder
-- **Results:** Save outputs to designated location in your task folder
+- backend team should use `shared/schemas/` as the source of truth
+- FastAPI Swagger is generated from `shared/services/models.py`
+- implementation teams should follow their task `SCHEMA.md`
+- if a field name changes, update schema first and then update service and task code

26_T1/afl_player_tracking_and_crowd_monitoring/Crowd_Monitoring/2026_T1/analytics_output/README.md

@@ -4,6 +4,39 @@
 
 Generate structured outputs that can be consumed by the Orion dashboard or related services.
 
+## Recommended Structure
+
+```text
+analytics_output/
+|- README.md
+|- main.py
+`- output/
+```
+
+### Why This Structure
+
+- `main.py` keeps the task simple and easy to understand
+- `output/` stores generated JSON, CSV, or export files
+- add `utils.py` only if `main.py` becomes messy or too long
+
+## Correct Approach
+
+- keep the real implementation for this task inside this folder
+- write the main export logic in `main.py`
+- save generated files inside `output/`
+- if helper code starts repeating, then create `utils.py`
+- the shared service layer can later call functions from this task folder
+
+## When To Add `utils.py`
+
+Create `utils.py` only when:
+
+- `main.py` becomes hard to read
+- helper functions are repeated
+- you want to separate small reusable logic such as JSON formatting or CSV writing
+
+Do not create extra files too early. Start simple, then split only when needed.
+
 ## Scope
 
 - Export analysis results in JSON and CSV formats
@@ -28,9 +61,11 @@ Generate structured outputs that can be consumed by the Orion dashboard or relat
 - Include timestamps, frame IDs, and zone metrics where useful
 - Design the structure so it can be used before full production data exists
 - Prefer simple schemas first, then extend only if needed
+- Keep the task folder minimal at the start
+- Store reusable helpers in `shared/` only if they are needed by multiple folders
 
 ## Suggested Deliverables
 
-- A serializer or export script
+- A simple `main.py` script for exporting results
 - Example JSON and CSV output
 - A short schema note in this folder or `docs/`

26_T1/afl_player_tracking_and_crowd_monitoring/Crowd_Monitoring/2026_T1/analytics_output/SCHEMA.md

@@ -0,0 +1,40 @@
+# Analytics Output Task Schema
+
+## Purpose
+
+This task exports results into files for reporting or dashboard use. It is separate from the current analytics service contract.
+
+## Input JSON
+
+```json
+{
+  "video_id": "match_01",
+  "zones": [
+    {
+      "zone_id": "A1",
+      "person_count": 8,
+      "density": 0.72
+    }
+  ],
+  "heatmap": {
+    "image_path": "output/heatmap_match_01.png"
+  },
+  "crowd_state": "increasing_density"
+}
+```
+
+## Output JSON
+
+```json
+{
+  "video_id": "match_01",
+  "json_path": "output/match_01_analytics.json",
+  "csv_path": "output/match_01_analytics.csv"
+}
+```
+
+## Notes
+
+- this task is for export only
+- it is not part of the current `crowd_analytics_service` flow
+- backend team should not depend on this task for the live analytics service response right now