Detectron2 Instance Segmentation

Two-stage object detection and instance segmentation using Facebook's Detectron2 framework with Mask R-CNN. Provides pixel-perfect instance masks alongside bounding box detections, enabling precise object boundary delineation for applications requiring fine-grained spatial understanding.

Architecture

Input Image
    |
    v
ResNet-50/101 Backbone + FPN (Feature Pyramid Network)
    |
    v
Region Proposal Network (RPN)
    |
    v
RoI Align
    |
    +---> Box Head ---> Class Labels + Bounding Boxes
    |
    +---> Mask Head ---> Per-Instance Binary Masks

Comparison with YOLOv8 (Primary Approach)

Feature	Detectron2 Mask R-CNN (this project)	YOLOv8 (yolov8-object-detection)
Architecture	Two-stage (RPN + heads)	Single-stage
Output	Boxes + Instance Masks	Boxes (+ optional masks)
Inference Speed	~5-10 FPS (GPU)	~30-100+ FPS (GPU)
Mask Quality	High (pixel-accurate)	Moderate
COCO mAP	~38-42 (box), ~35-38 (mask)	~50+ (box)
Training Complexity	High (many hyperparameters)	Low (integrated pipeline)
Deployment	Complex (heavy dependencies)	Simple (export to ONNX/TensorRT)

Speed and mAP figures are approximate public model-zoo reference values, not measurements from this repository.

Decision: YOLOv8 was selected as the primary approach for its faster real-time inference and simpler deployment. Detectron2 remains the preferred choice for offline analysis tasks where mask quality is paramount and latency constraints are relaxed.

Setup

Prerequisites

• Python 3.10+
• CUDA 11.8+ (for GPU inference)
• PyTorch 2.0+

Installation

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configuration

Edit configs/config.yaml to customize model settings, training parameters, and augmentation options.

Running

# Start API server
uvicorn src.api:app --host 0.0.0.0 --port 8000 --reload

# Training
python -m src.model --train --dataset path/to/dataset --config configs/config.yaml

API Endpoints

Method	Endpoint	Description
POST	/detect	Upload image, returns detections with masks
POST	/segment	Returns segmentation masks as PNG
GET	/model/info	Model configuration and metadata
GET	/health	Service health check

Usage Example

import requests

# Object detection with instance masks
with open("image.jpg", "rb") as f:
    response = requests.post(
        "http://localhost:8000/detect",
        files={"image": f},
        data={"threshold": 0.5}
    )

detections = response.json()["detections"]
for det in detections:
    print(f"Class: {det['class']}, Score: {det['score']:.2f}")
    print(f"  Box: {det['bbox']}")
    print(f"  Mask pixels: {det['mask_area']}")

Project Structure

detectron2-instance-segmentation/
├── src/
│   ├── model.py           # Detectron2 model wrapper
│   ├── dataset.py         # Dataset management
│   ├── evaluator.py       # Evaluation metrics
│   └── api.py             # FastAPI application
├── configs/
│   └── config.yaml        # Configuration
├── requirements.txt
└── README.md

License

MIT License