Construction Hazard Detection

🇬🇧 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:

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

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)

1. Install Docker (Required) Please install [Docker Desktop / Docker Engine] on your computer first.

2. Start Redis with Docker

   docker run -d --name my-redis -p 6379:6379 \
   redis:latest redis-server --requirepass "password"
   

3. 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
   

4. 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
  

5. 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]'
       

6. 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"],
  )
  

7. 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
  

8. 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.py will poll the stream_configs table 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 --config to 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 + C to gracefully terminate all subprocesses and release resources. .env will be loaded automatically at startup (python-dotenv).

9. 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

• App Store: https://apps.apple.com/tw/app/visionnaire/id6743549024

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 information
• users: System users
• violations: Violation records

See scripts/init.sql for 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.1 to 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.sql import 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 Dockerfile is 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.