🇬🇧 English | 🇹🇼 繁體中文

Construction Hazard Detection

Server API | MCP Server | FCM Notification Server | Violation Records Server | Web BFF | Data Management Server | Streaming Web | Data Augmentation | Evaluation | Train

AI-assisted construction-site safety monitoring for live cameras. The current runtime is centred on main.py, src/stream_processor.py, local YOLO worker processes, MediaMTX live publishing, PostgreSQL records, Redis coordination, and FastAPI services for management, notifications, streaming metadata, and violation records.

What It Detects

• Workers without hard hats.
• Workers without safety vests.
• Workers too close to machinery or vehicles.
• Workers inside cone-derived controlled areas.
• Machinery or vehicles too close to utility poles.

Supported label and notification languages include Traditional Chinese, Simplified Chinese, English, French, Thai, Vietnamese, Indonesian, and Japanese.

Hazard Detection Examples

Below are examples of real-time hazard detection by the system.

Workers without helmets or safety vests

Workers near machinery or vehicles

Workers in restricted areas

Runtime Architecture

The diagram summarises the live data path, the 11 configured detection classes, the safety-warning rules, and the video/metadata outputs. Redis is not used to store live video frames; MediaMTX owns live playback, while Redis keeps only small coordination state such as authentication cache, FCM token cache, compact warning metadata, overlay demand keys, and overlay ready keys.

Repository Map

• main.py: supervises configured streams and worker processes.
• src/: production runtime modules.
• examples/bff/: Web session, CSRF, media capability, and API gateway.
• examples/db_management/: users, groups, sites, stream configuration API.
• examples/local_notification_server/: FCM token and site notification API.
• examples/streaming_web/: labels, playback URLs, metadata channels, media-session auth, and WebRTC ICE settings.
• examples/violation_records/: violation record and image API.
• examples/YOLO_server_api/: optional standalone YOLO API.
• examples/mcp_server/: FastMCP tools for agents.
• examples/YOLO_train/, examples/YOLO_evaluation/, examples/YOLO_data_augmentation/: model development utilities.
• scripts/: database initialisation and TensorRT rebuild helpers.

Recommended Runtime

Use database mode unless you are testing a short-lived local JSON config.

1. PostgreSQL stores sites, users, stream configurations, and violations.
2. Redis stores auth/session cache, notification token cache, and compact live coordination keys.
3. MediaMTX serves RTSP ingest plus HLS/WebRTC playback.
4. main.py polls stream configuration and starts one stream process per active camera.
5. Local YOLO workers share GPU inference across cameras through shared memory.

The standalone YOLO server remains available for API testing or separate deployment, but the recommended high-throughput local path is the YOLO worker mode in src/yolo_worker.py.

Quick Start

1. Prepare Python

The project currently targets Python >=3.12,<3.13.

uv sync

If you use pip instead:

uv export --format=requirements-txt --no-dev -o requirements.lock
pip install -r requirements.lock

2. Download Models

hf download yihong1120/Construction-Hazard-Detection \
  --repo-type model \
  --include "models/pt/*.pt" \
  --local-dir .

Expected worker model filenames are models/pt/best_<model_key>.pt, for example models/pt/best_yolo26n.pt.

3. Create .env

Start from .env.example, then adjust hostnames and secrets.

Important values:

DATABASE_URL='postgresql+asyncpg://username:password@127.0.0.1/construction_hazard_detection'

REDIS_HOST='127.0.0.1'
REDIS_PORT=6379
REDIS_PASSWORD='password'

JWT_SECRET_KEY='replace-with-a-long-random-secret'

DB_MANAGEMENT_API_URL='http://127.0.0.1:8005'
FCM_API_URL='http://127.0.0.1:8003'
VIOLATION_RECORD_API_URL='http://127.0.0.1:8002'
STREAMING_API_URL='http://127.0.0.1:8800'

YOLO_WORKER_ENABLED=true
YOLO_WORKER_COUNT=2
YOLO_WORKER_DEVICES=cuda:0,cuda:0
YOLO_WORKER_QUEUE_SIZE=64
YOLO_WORKER_BATCH_SIZE=8
YOLO_WORKER_BATCH_WAIT_MS=10
YOLO_WORKER_PRECISION=f16
# f32/f16 use models/pt/*.pt; int8 uses models/int8_engine/*.engine.

MEDIA_PUBLISH_RTSP_BASE_URL='rtsp://127.0.0.1:8554'
MEDIA_PUBLIC_HLS_BASE_URL='/hazard/media'
MEDIA_PUBLIC_WEBRTC_BASE_URL='/hazard/media/webrtc'
MEDIA_PUBLISH_CLEAN_STREAM=true
MEDIA_PUBLISH_ANNOTATED_STREAM=true

Use one stable, high-entropy JWT_SECRET_KEY for a deployment. Do not commit real secrets.

4. Start Infrastructure

Redis, PostgreSQL, and MediaMTX are required for the normal database-backed runtime:

docker compose up -d redis postgres media-server

Check that the containers are running:

docker compose ps redis postgres media-server
docker compose logs -f redis postgres media-server

When the Python services run on the host, use local addresses in .env:

DATABASE_URL='postgresql+asyncpg://username:password@127.0.0.1/construction_hazard_detection'
REDIS_HOST='127.0.0.1'
REDIS_PORT=6379
REDIS_PASSWORD='password'
MEDIA_PUBLISH_RTSP_BASE_URL='rtsp://127.0.0.1:8554'

When main.py or the FastAPI services run inside Docker Compose, use service names instead:

DATABASE_URL='postgresql+asyncpg://username:password@postgres/construction_hazard_detection'
REDIS_HOST='redis'
MEDIA_PUBLISH_RTSP_BASE_URL='rtsp://media-server:8554'

Infrastructure roles:

• PostgreSQL stores users, sites, stream settings, and violation records.
• Redis stores authentication cache, token cache, compact live metadata, and overlay demand keys.
• MediaMTX receives RTSP streams from main.py and exposes HLS/WebRTC playback.

Redis and MediaMTX do not store violation images or database records.

For a fresh PostgreSQL container, import the schema if it was not mounted at container creation time:

cat ./scripts/init.postgres.sql | docker exec -i postgres-container \
  psql -U username -d construction_hazard_detection

5. Configure MediaMTX

MediaMTX is the live media server. main.py publishes processed H.264 streams to MediaMTX over RTSP, and viewers play those streams through HLS or WebRTC. Redis only stores compact metadata and demand keys; it does not carry video frames.

The Docker Compose service exposes local-only ports:

127.0.0.1:8554  RTSP ingest from main.py / ffmpeg
127.0.0.1:8890  HLS playback, mapped to MediaMTX port 8888
127.0.0.1:8889  WebRTC/WHEP playback

Use these settings when main.py runs on the host:

MEDIA_PUBLISH_RTSP_BASE_URL='rtsp://127.0.0.1:8554'
MEDIA_PUBLIC_HLS_BASE_URL='/hazard/media'
MEDIA_PUBLIC_WEBRTC_BASE_URL='/hazard/media/webrtc'

Use the Compose service name when main.py runs inside Docker:

MEDIA_PUBLISH_RTSP_BASE_URL='rtsp://media-server:8554'

The streaming backend returns playback URLs shaped like:

/hazard/media/<media-path>/index.m3u8
/hazard/media/webrtc/<media-path>/whep

For public deployments, proxy MediaMTX through Nginx and protect it with examples.streaming_web media authorisation. Use examples/streaming_web/nginx.hazard-media.conf as the starting point:

Nginx /hazard/media/*        -> MediaMTX HLS port 8888
Nginx /hazard/media/webrtc/* -> MediaMTX WebRTC port 8889
Nginx /hazard/api/media-auth -> examples.streaming_web /media-auth

Recommended live-buffer defaults are already in docker-compose.yml:

MTX_HLSSEGMENTDURATION=2s
MTX_HLSSEGMENTCOUNT=14
MTX_HLSALWAYSREMUX=yes
MTX_HLSMUXERCLOSEAFTER=60s

Lower MTX_HLSSEGMENTCOUNT reduces disk and memory use. The default 14 segments (about 28 seconds at 2-second segments) gives wall tiles enough room to recover from a short publisher or network interruption.

6. Start APIs

Run each service from the repository root:

uvicorn examples.db_management.app:app --host 127.0.0.1 --port 8005 --workers 2
uvicorn examples.local_notification_server.app:app --host 127.0.0.1 --port 8003 --workers 2
uvicorn examples.violation_records.app:app --host 127.0.0.1 --port 8002 --workers 2
uvicorn examples.streaming_web.app:app --host 127.0.0.1 --port 8800 --workers 2

Optional standalone detector API:

uvicorn examples.YOLO_server_api.app:app --host 127.0.0.1 --port 8000 --workers 2

7. Start Stream Processing

python main.py

Optional polling interval:

python main.py --poll 5

Optional file-based mode for development:

python main.py --config config/configuration.json

Do not run database mode and JSON mode at the same time for the same cameras.

Live Viewing

Clients should call the streaming web backend:

• GET /labels
• GET /streams/{label}
• GET /metadata/stream-id/{label}/{stream_id} for SSE metadata
• WebSocket /ws/metadata-id/{label}/{stream_id} for metadata
• GET /webrtc/ice-servers when WebRTC needs STUN/TURN settings

Video playback comes from MediaMTX HLS/WebRTC URLs. Warning metadata is compact and usually contains only current warning state. Detection boxes, polygons, and labels are rendered into backend-published annotated video streams.

For public deployments, put MediaMTX behind Nginx auth_request and let examples.streaming_web validate JWT and site access.

Storage Retention

Violation images are stored under each service's configured static/ location. Without archive/NAS/external disk, a practical default is:

• keep images and DB records for 18 months;
• delete image files and matching database rows together;
• run cleanup during low-traffic hours;
• keep HLS segment retention short because MediaMTX HLS is a live buffer, not an archive.

Do not delete database records while keeping broken image paths, and do not delete image files while keeping records that the UI still needs to display.

Development Checks

pre-commit run -a
python -m pytest -q --tb=short

The mypy pre-commit hook checks production code (main.py, src, examples, and scripts). Tests are still validated by pytest and flake8; many test files intentionally use dynamic mocks and invalid payloads.

Dataset And Models

The project uses the Construction Hazard Detection model repository:

• Hugging Face: https://huggingface.co/yihong1120/Construction-Hazard-Detection
• Roboflow: https://universe.roboflow.com/side-projects/construction-hazard-detection

Labels:

0 Hardhat
1 Mask
2 NO-Hardhat
3 NO-Mask
4 NO-Safety Vest
5 Person
6 Safety Cone
7 Safety Vest
8 Machinery
9 Utility Pole
10 Vehicle

Licence

This project is licensed under the AGPL-3.0 Licence.