Satellite Image CBIR System - Backend

This repository contains the backend code for the AI-Powered Satellite Image Content-Based Retrieval (CBIR) System. This web server uses deep learning to analyze a large-scale archive of satellite images and provides a RESTful API for finding visually similar images.

This backend is designed to serve the corresponding frontend application.

Features

• Deep Learning Feature Extraction: Utilizes a pre-trained ResNet-50 model (via PyTorch) to extract rich, 2048-dimensional feature vectors (embeddings) that capture the semantic content of each image.
• High-Performance Similarity Search: Employs an in-memory index and optimized NumPy calculations to perform near-instantaneous cosine similarity searches against tens of thousands of images.
• Efficient Indexing: On the first run, the system automatically builds a feature index from the dataset and saves it as a binary file (cbir_index.bin) for extremely fast subsequent startups.
• Semantic Knowledge Graph: Constructs a graph of the dataset using NetworkX, modeling relationships between images (e.g., images from the same category) to provide richer metadata.
• RESTful API: Exposes a clean and simple API built with FastAPI for querying, retrieving metadata, and handling image previews.
• On-the-Fly Image Conversion: Intelligently handles .tif images by converting them to web-safe JPEG format in memory, ensuring compatibility with all web browsers.

Architecture & Tech Stack

The backend is built with a modern Python stack, emphasizing performance, scalability, and maintainability.

• Python Version: Python 3.10
• Package Manager: uv
• Web Framework: FastAPI
• Deep Learning: PyTorch & Torchvision
• Data Handling & Computation: NumPy, Pillow (PIL)
• Knowledge Graph: NetworkX
• Configuration Management: Pydantic
• ASGI Server: Uvicorn

Dataset Used:

1. SEN12MS (Multispectral, SAR, Optical): The SEN12MS dataset contains 180,662 patch triplets of corresponding Sentinel-1 dual-pol SAR data, Sentinel-2 multi-spectral images, and MODIS-derived land cover maps. The patches are distributed across the land masses of the Earth and spread over all four meteorological seasons
2. LandCover.ai (Optical): The LandCover.ai (Land Cover from Aerial Imagery) dataset is a dataset for the automatic mapping of buildings, woodlands, water, and roads from aerial images.

Project and Dataset Structure

The project expects a specific directory structure. The backend and dataset folders must be in the same root directory.

project-root/
├── .venv/           # Virtual environment created by uv
├── .python-version      # Specifies Python 3.10 for tools like pyenv
├── pyproject.toml   # Project dependencies for uv
├── backend/             # This codebase
│   ├── cbir.py          # Core CBIR service logic
│   ├── config.py        # Pydantic-based configuration management
│   ├── dataset.py       # Utility for gathering image paths
│   ├── exceptions.py    # Custom application exceptions
│   ├── graph.py         # Knowledge graph service logic
│   ├── main.py          # FastAPI application entrypoint
│   ├── models.py        # Pydantic API models
│   └──  utils.py         # Common utility functions
│
│
└── dataset/
    ├── cbir_index.bin         # **Generated File:** Binary index of ResNet50 features.
    ├── knowledge_graph.pkl    # **Generated File:** Pickled NetworkX graph.
    ├── landcover/
    │   └── images/
    │       ├── img_1.tif
    │       └── ...
    └── sentinel/
        ├── agri/
        │   ├── s1/
        │   └── s2/
        │       ├── img_s2_1.png
        │       └── ...
        ├── barrenland/
        │   ├── s1/
        │   └── s2/
        └── ... (other categories)

Setup and Installation

Follow these steps to set up and run the backend server locally using the uv package manager.

1. Clone the Repository

git clone git@github.com:iampujan/satellitle-image-retrieval-for-earth-observation.git
cd <repository-folder>

2. Create a Python Virtual Environment with uv

It is highly recommended to use a virtual environment. uv makes this process extremely fast.

uv venv
source .venv/bin/activate
# On Windows, use: .venv\Scripts\activate

This command will create a virtual environment in a .venv directory, using the Python version specified (e.g., in .python-version or your system's default).

3. Install Dependencies with uv

Install the required Python packages from the pyproject.toml file and create a uv.lock file for reproducible builds.

uv pip sync

4. Prepare the Dataset

Ensure the dataset folder is placed in the project root, alongside the backend folder, and follows the structure described above.

5. Run the Server

Launch the application using Uvicorn. The server should be run from the project's root directory .

uvicorn backend.main:app --reload