README.md

metadata

title: ProjectX
emoji: 🏗️
colorFrom: red
colorTo: gray
sdk: docker
pinned: false

🏗️ Illegal Construction Detector

AI-powered satellite/aerial image analysis for detecting buildings in restricted zones using semantic segmentation.

---

📌 Overview

This project uses a deep learning segmentation model to automatically identify buildings in aerial or satellite imagery and flag those that fall within user-defined restricted/zoning areas. It is designed for urban planning, land administration, and regulatory compliance workflows.

Key capabilities:

• Semantic segmentation of buildings from high-resolution aerial images
• Patch-based inference for large images of arbitrary size
• Zoning mask overlay to classify buildings as legal or illegal
• REST API backend (Flask) with base64 image response for easy frontend integration
• Visual overlay output highlighting illegal structures in red and legal structures in green

---

🧠 Model Architecture

Component	Detail
Architecture	U-Net
Encoder	EfficientNet-B3 (ImageNet pretrained)
Loss Function	Dice Loss (binary)
Optimizer	Adam (lr = 1e-4)
LR Scheduler	ReduceLROnPlateau (patience=3, factor=0.5)
Input	RGB patches of 256 × 256 px
Output	Binary segmentation mask (building / non-building)

The model was trained on the Massachusetts Buildings Dataset for 30 epochs with augmentations including horizontal/vertical flips, random 90° rotation, and brightness/contrast jitter.

---

🗂️ Repository Structure

├── app.py                  # Flask API server
├── best_model.pth          # Trained model weights
├── requirements.txt        # Python dependencies
├── sourcecode.ipynb        # Model training notebook (Kaggle)
├── inference_script.ipynb  # Standalone inference & visualization notebook
├── static/
│   └── index.html          # Frontend UI (served by Flask)
└── README.md

---

⚙️ Installation

Prerequisites

• Python 3.8+
• CUDA-compatible GPU (optional but recommended)

Steps

# 1. Clone the repository
git clone https://github.com/your-username/illegal-construction-detector.git
cd illegal-construction-detector

# 2. Create and activate a virtual environment
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Place the model weights in the project root
#    Ensure best_model.pth is present (download from Releases or train your own)

---

🚀 Usage

Option 1 — Flask Web API

python app.py

The server starts at http://localhost:5000. Navigate there in your browser to use the UI, or send requests directly:

curl -X POST http://localhost:5000/predict \
  -F "image=@/path/to/aerial_image.png"

Response JSON:

{
  "verdict": "ILLEGAL CONSTRUCTION DETECTED",
  "illegal_count": 3,
  "legal_count": 12,
  "total_count": 15,
  "illegal_percent": 8.42,
  "device": "cuda",
  "original": "<base64_png>",
  "mask": "<base64_png>",
  "overlay": "<base64_png>"
}

Option 2 — Jupyter Notebook Inference

Open inference_script.ipynb and update the following variables:

MODEL_PATH = "best_model.pth"    # path to weights
IMAGE_PATH = "test_image.png"    # path to your aerial image

Run all cells to generate the building mask, zoning overlay, and illegal building highlights.

---

🗺️ Zoning Configuration

By default, the right half of any image is treated as a restricted zone. To customise this, modify the create_zoning_mask function in app.py or the inference notebook:

def create_zoning_mask(shape):
    h, w = shape
    zoning = np.zeros((h, w), dtype=np.uint8)
    # Example: mark a rectangular region as restricted
    zoning[100:400, 200:600] = 1
    return zoning

Any building whose pixels overlap with the restricted zone (zoning == 1) is classified as illegal.

---

🏋️ Training

The full training pipeline is available in sourcecode.ipynb, designed to run on Kaggle with GPU acceleration.

Dataset: Massachusetts Buildings Dataset

Training configuration:

PATCH_SIZE  = 256
BATCH_SIZE  = 8
EPOCHS      = 30
LEARNING_RATE = 1e-4

Augmentations: Horizontal flip, vertical flip, random 90° rotation, brightness/contrast jitter

Metrics tracked: Dice Loss · IoU Score

To retrain, update BASE_PATH in the notebook to your dataset location and run all cells. The best-performing checkpoint (highest IoU) is saved as best_model.pth.

---

📊 Results

Metric	Value
Validation IoU	Tracked per epoch
Inference mode	Patch-based (256×256), supports arbitrary image sizes
Supported formats	PNG, JPG, TIFF

---

🔧 Dependencies

flask
torch
torchvision
segmentation-models-pytorch
albumentations
opencv-python
pillow
numpy

Install all with:

pip install -r requirements.txt

Note for Windows users: If you encounter a fbgemm.dll error when importing PyTorch, ensure you have the Microsoft Visual C++ Redistributable installed.

---

🤝 Contributing

Contributions are welcome. Please open an issue first to discuss proposed changes, then submit a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m 'Add your feature')
4. Push and open a Pull Request

---

📄 License

See the LICENSE file for details.

---

🙏 Acknowledgements

• Massachusetts Buildings Dataset by Balraj Ashwath
• segmentation-models-pytorch by Pavel Iakubovskii
• Albumentations augmentation library