Crowd monitoring

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

@@ -0,0 +1,60 @@
+# Python cache and build artifacts
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg-info/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Notebook and editor artifacts
+.ipynb_checkpoints/
+.vscode/
+.idea/
+
+# Test and coverage output
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Logs and local environment files
+*.log
+.env
+.env.*
+
+# Model artifacts
+*.pt
+*.pth
+*.onnx
+
+# Data and generated outputs
+data/
+outputs/
+results/
+runs/
+checkpoints/
+temp/
+tmp/
+
+# Media artifacts
+*.mp4
+*.avi
+*.mov
+*.mkv
+*.png
+*.jpg
+*.jpeg
+*.csv
+*.json
+
+# OS files
+.DS_Store
+Thumbs.db

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

@@ -0,0 +1,185 @@
+# Crowd Monitoring Module (Orion Project)
+
+## Overview
+
+This folder contains the Crowd Monitoring module for the Orion project.
+
+The module is organised into:
+
+- 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 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
+
+## Pipeline
+
+```text
+Video Input
+    ->
+Video Processing
+    ->
+Crowd Detection
+    ->
+Density Zoning
+    ->
+Heatmap
+    ->
+Crowd Behaviour Analytics
+    ->
+Crowd Allocation / Risk Zone
+```
+
+## Tech Stack
+
+- Python
+- FastAPI
+- Uvicorn
+- YOLOv8 (Ultralytics)
+- OpenCV
+- NumPy
+- Pandas
+
+## 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:
+
+- `video_processing/`
+- `crowd_detection/`
+- `density_zoning/`
+- `heatmap/`
+- `analytics_output/`
+- `crowd_behaviour_analytics/`
+- `crowd_allocation_risk_zone/`
+- `prediction_optional/`
+
+## Shared Folder
+
+### `shared/config/`
+
+Contains shared settings such as thresholds, paths, and common configuration values.
+
+### `shared/schemas/`
+
+Contains the agreed request and response JSON contracts for the 3 services.
+
+### `shared/services/`
+
+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
+
+## Current Structure
+
+```text
+2026_T1/
+|- 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:
+
+- `POST /process-detection`
+- `POST /process-analytics`
+- `POST /process-intelligence`
+
+These endpoints use typed FastAPI models so Swagger can show clear request and response formats.
+
+## Working Rule
+
+- 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
+
+## 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
+```
+
+## 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 Notes
+
+- 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

@@ -0,0 +1,71 @@
+# Analytics Output
+
+## Objective
+
+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
+- Define a clean schema for crowd metrics
+- Prepare data for backend and frontend integration
+
+## Inputs
+
+- Detection results
+- Density and zoning summaries
+- Heatmap metadata if relevant
+
+## Outputs
+
+- JSON files
+- CSV files
+- A documented output structure
+
+## Implementation Notes
+
+- Keep field names stable and descriptive
+- 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 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

26_T1/afl_player_tracking_and_crowd_monitoring/Crowd_Monitoring/2026_T1/analytics_output/main.py

@@ -0,0 +1,12 @@
+"""Minimal entry point for the analytics output task."""
+
+
+def export_results(input_data):
+    """Export analysis outputs into structured files."""
+    # Implement JSON or CSV export here.
+    pass
+
+
+if __name__ == "__main__":
+    # Add a simple local test call here when implementation starts.
+    pass