Construction Hazard Detection
Enhances construction site safety using YOLO for object detection, identifying hazards like workers without helmets or safety vests, and proximity to machinery or vehicles. HDBSCAN clusters safety cone coordinates to create monitored zones. Post-processing algorithms improve detection accuracy.
Installation
npx construction-hazard-detectionAsk AI about Construction Hazard Detection
Powered by Claude ยท Grounded in docs
I know everything about Construction Hazard Detection. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
๐ฌ๐ง English | ๐น๐ผ ็น้ซไธญๆ
"Construction-Hazard-Detection" is an AI-powered tool designed to enhance safety on construction sites. By leveraging the YOLO26 model and self-developed algorithms for object detection, it identifies potential hazards such as:
- Workers without helmets
- Workers without safety vests
- Workers near machinery or vehicles
- Workers in restricted areas, restricted areas will be automatically generated by computing and clustering the coordinates of safety cones.
- Machineries or vehicles near utility poles
Post-processing algorithms further improve detection accuracy. The system is built for real-time deployment, offering instant analysis and alerts for identified hazards.
Additionally, the system integrates AI recognition results in real-time via a web interface. It can send notifications and real-time on-site images through messaging apps like LINE, Messenger, WeChat, and Telegram for prompt alerts and reminders. The system also supports multiple languages, enabling users to receive notifications and interact with the interface in their preferred language. Supported languages include:
- ๐น๐ผ Traditional Chinese (Taiwan)
- ๐จ๐ณ Simplified Chinese (Mainland China)
- ๐ซ๐ท French
- ๐ฌ๐ง English
- ๐น๐ญ Thai
- ๐ป๐ณ Vietnamese
- ๐ฎ๐ฉ Indonesian
This multi-language support makes the system accessible to a global audience, improving usability across different regions.
Contents
- Hazard Detection Examples
- MCP Server (Agent Tools)
- Usage
- Database Configuration and Management
- Environment Variables
- Additional Information
- Dataset Information
- Contributing
- Development Roadmap
- License
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
MCP Server (Agent Tools)
This repository includes a Model Context Protocol (MCP) server at examples/mcp_server that exposes agent-ready tools for detection, hazard analysis, notifications, records, streaming, model management, and utilities using FastMCP.
-
Highlights:
inference.detect_frame,hazard.detect_violations,violations.search/get/get_image/my_sites,notify.line_push/telegram_send/broadcast_send,record.send_violation/batch_send_violations/sync_pending/get_statistics,streaming.start_detection/stop_detection/capture_frame/get_status,model.fetch/update/list_available/get_local, and geometry utils. -
Transports: stdio, SSE, and streamable-HTTP (default).
-
Quick run from project root:
- HTTP transport:
python -m examples.mcp_server.main - stdio transport:
MCP_TRANSPORT=stdio python -m examples.mcp_server.main
- HTTP transport:
See examples/mcp_server/README.md for full details and configuration.
Quick Start (Recommended)
Before running the application, complete the following quick start and environment variable setup steps. Preparing a JSON stream configuration file config/configuration.json is optional and generally not recommended; the default Database Mode centrally manages streams. If you need file-based multi-stream config for advanced use cases, see the optional example below.
[
{
"video_url": "https://cctv1.kctmc.nat.gov.tw/6e559e58/",
"site": "Kaohsiung",
"stream_name": "Test",
"model_key": "yolo11n",
"notifications": {
"line_token_1": "language_1",
"line_token_2": "language_2"
},
"detect_with_server": true,
"expire_date": "2024-12-31T23:59:59",
"detection_items": {
"detect_no_safety_vest_or_helmet": true,
"detect_near_machinery_or_vehicle": true,
"detect_in_restricted_area": true
},
"work_start_hour": 0,
"work_end_hour": 24,
"store_in_redis": true
}
]
โ Startup Steps (Complete in Order)
-
Install Docker (Required) Please install [Docker Desktop / Docker Engine] on your computer first.
-
Start Redis with Docker
docker run -d --name my-redis -p 6379:6379 \ redis:latest redis-server --requirepass "password" -
Start MySQL with Docker (Windows / Linux)
docker run -d --name my-mysql -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=ChangeMe! \ -e MYSQL_DATABASE=construction_hazard_detection \ -e MYSQL_USER=username \ -e MYSQL_PASSWORD=password \ mysql:latest \ --default-authentication-plugin=mysql_native_password \ --character-set-server=utf8mb4 \ --collation-server=utf8mb4_unicode_ci -
Import Database Schema (First Time Only)
-
Windows PowerShell / CMD:
type .\scripts\init.sql | docker exec -i my-mysql \ mysql -u username -p"password" --default-character-set=utf8mb4 construction_hazard_detection -
Linux / macOS:
cat ./scripts/init.sql | docker exec -i my-mysql \ mysql -u username -p"password" --default-character-set=utf8mb4 construction_hazard_detection
-
Install Required Python Packages:
-
Recommended (uv):
# install uv once curl -LsSf https://astral.sh/uv/install.sh | sh # create a project virtualenv (.venv) and sync from pyproject uv sync -
Alternative (pip; uses pyproject via uv export):
# generate a requirements file from pyproject uv export --format=requirements-txt --no-dev -o requirements.lock pip install -r requirements.lock-
Enable optional TensorRT (CUDA 12) packages when needed:
# add TensorRT dependency group uv sync --extra tensorrt # or: install only the extra into existing env uv pip install '.[tensorrt]'
-
-
-
Download YOLO26 weights from Hugging Face (to models/pt):
-
CLI (places files under
./models/pt):Hugging Face model repo: https://huggingface.co/yihong1120/Construction-Hazard-Detection
hf download \ yihong1120/Construction-Hazard-Detection \ --repo-type model \ --include "models/pt/*.pt" \ --local-dir . -
Python (same effect):
from huggingface_hub import snapshot_download snapshot_download( repo_id="yihong1120/Construction-Hazard-Detection", repo_type="model", local_dir=".", local_dir_use_symlinks=False, allow_patterns=["models/pt/*.pt"], )
- Start Each API (from project root, use separate terminals for each)
-
Data Management (DB Management)
uvicorn examples.db_management.app:app --host 127.0.0.1 --port 8005 --workers 2 -
Notification Server (FCM / Local Notification)
uvicorn examples.local_notification_server.app:app --host 127.0.0.1 --port 8003 --workers 2 -
Streaming Web Backend
uvicorn examples.streaming_web.backend.app:app --host 127.0.0.1 --port 8800 --workers 2 -
Violation Records API
uvicorn examples.violation_records.app:app --host 127.0.0.1 --port 8002 --workers 2 -
YOLO Detection API
uvicorn examples.YOLO_server_api.backend.app:app --host 127.0.0.1 --port 8000 --workers 2
- Start the Main Program (Two Modes)
Choose one mode only; do not run Database Mode and JSON Mode at the same time.
-
Database Mode (Default)
main.pywill poll thestream_configstable and dynamically start/restart/stop stream subprocesses.python main.py # Optional: adjust polling interval (default 10 seconds) python main.py --poll 5 -
JSON Mode (File-based Multi-stream Config) โ Optional, advanced; not recommended for most users Use
--configto specify the JSON file path; the main program will start a subprocess for each stream config in the array. This mode is mutually exclusive with Database Mode.python main.py --config config/configuration.json
To stop: Press
Ctrl + Cto gracefully terminate all subprocesses and release resources..envwill be loaded automatically at startup (python-dotenv).
- Frontend Page (Cloud Demo)
Open: https://visionnaire-cda17.web.app
Login:
user/password
Before using, please open the Web Settings and configure API endpoints first (e.g., DETECT_API_URL, STREAMING_API_URL, DB_MANAGEMENT_API_URL, FCM_API_URL) to match your environment; then proceed with login and operations.
iOS App
Note: For complete notification functionality, please contact us.
Database Configuration and Management
The system uses MySQL to store stream, site, violation, and user data.
Database name: construction_hazard_detection
Main tables:
stream_configs: Stream settings (URL, site, model, notifications, detection items, work hours, etc.)sites: Site informationusers: System usersviolations: Violation records
See
scripts/init.sqlfor full SQL schema. Please complete the "Import Database Schema" step above before first run.
Environment Variables
Create a .env file in the project root as follows (adjust as needed):
# Database
DATABASE_URL='mysql+aiomysql://username:password@127.0.0.1/construction_hazard_detection'
# API Credentials
API_USERNAME='user'
API_PASSWORD='password'
# API URLs
DETECT_API_URL="http://127.0.0.1:8000"
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"
DB_MANAGEMENT_API_URL="http://127.0.0.1:8005"
# Redis
REDIS_HOST='127.0.0.1'
REDIS_PORT=6379
REDIS_PASSWORD='password'
# Firebase
FIREBASE_CRED_PATH='examples/local_notification_server/your-firebase-adminsdk.json'
project_id='your-project-id'
# (Optional) LINE / Cloudinary credentials, add if integrated:
# LINE_CHANNEL_ACCESS_TOKEN='YOUR_LINE_CHANNEL_ACCESS_TOKEN'
# CLOUDINARY_CLOUD_NAME='YOUR_CLOUDINARY_CLOUD_NAME'
# CLOUDINARY_API_KEY='YOUR_CLOUD_API_KEY'
# CLOUDINARY_API_SECRET='YOUR_CLOUD_API_SECRET'
Note
- If services are deployed on different hosts or containers, change
127.0.0.1to the accessible address.- MySQL and Redis credentials must match your Docker environment variables (e.g.,
MYSQL_USER,MYSQL_PASSWORD,--requirepass).- Be sure to complete the
scripts/init.sqlimport before first run.
Additional Information
- The system logs are available within the Docker container and can be accessed for debugging purposes.
- The output images with detections (if enabled) will be saved to the specified output path.
- Notifications will be sent through LINE messaging API during the specified hours if hazards are detected.
Notes
- Ensure that the
Dockerfileis present in the root directory of the project and is properly configured as per your application's requirements.
For more information on Docker usage and commands, refer to the Docker documentation.
Dataset Information
The primary dataset for training this model is the Construction Site Safety Image Dataset from Roboflow. We have enriched this dataset with additional annotations and made it openly accessible on Roboflow. The enhanced dataset can be found here: Construction Hazard Detection on Roboflow. This dataset includes the following 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'
Models for detection
| Model | size (pixels) | mAPval 50 | mAPval 50-95 | params (M) | FLOPs (B) |
|---|---|---|---|---|---|
| YOLO26n | 640 | 60.1 | 38.4 | 2.8 | 7.2 |
| YOLO26s | 640 | 72.4 | 51.3 | 10.2 | 24.8 |
| YOLO26m | 640 | 78.1 | 58.9 | 21.7 | 73.5 |
| YOLO26l | 640 | 79.5 | 60.9 | 27.1 | 95.3 |
| YOLO26x | 640 | 93.4 | 85.1 | 61.2 | 215.7 |
Our comprehensive dataset ensures that the model is well-equipped to identify a wide range of potential hazards commonly found in construction environments.
License
This project is licensed under the AGPL-3.0 License.
