Arctic Orthodox Cross Scanner

A web application that scans satellite imagery to detect Orthodox cross structures in Arctic regions using computer vision.

Features

• Interactive map for selecting scan locations
• Real-time scan progress with WebSocket updates
• Template matching using OpenCV
• Export detections as GeoJSON or CSV
• Adjustable detection threshold and scan radius

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• A Mapbox account (free) for the map display

1. Clone and Setup

git clone <repo-url>
cd cross-finder

# Create Python virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install backend dependencies
pip install -r backend/requirements.txt

# Install frontend dependencies
npm install --prefix frontend

2. Configure Environment

Create frontend/.env:

VITE_MAPBOX_TOKEN=pk.your_mapbox_public_token_here
VITE_API_URL=http://localhost:8000

Get your Mapbox token at https://account.mapbox.com/access-tokens/ (use a public token starting with pk.)

3. Run the App

Terminal 1 - Backend:

source .venv/bin/activate
cd backend
uvicorn main:app --reload --port 8000

Terminal 2 - Frontend:

npm run dev --prefix frontend

Open http://localhost:5173 in your browser.

Usage

1. Enter coordinates or click on the map to select a location
2. Choose a scan radius (smaller = faster, more precise)
3. Adjust detection threshold (higher = fewer false positives)
4. Click "Start Scan" and watch detections appear in real-time
5. Click on detections to zoom to their location
6. Export results as GeoJSON or CSV

Adding Templates

Place cross template images in the templates/ folder. For best results:

• Crop templates directly from satellite imagery at the same zoom level
• Use high-contrast images
• Templates should be roughly 30-60 pixels in size
• The system automatically creates rotated and scaled variants

Project Structure

cross-finder/
├── backend/           # Python FastAPI server
│   ├── api/          # REST endpoints + WebSocket
│   ├── detection/    # OpenCV template matching
│   └── services/     # Tile fetching, coordinate conversion
├── frontend/         # React + Vite + TypeScript
│   └── src/
│       ├── components/
│       ├── hooks/
│       └── api/
└── templates/        # Cross template images

Tech Stack

• Backend: FastAPI, OpenCV, Pillow, httpx
• Frontend: React, TypeScript, Vite, Mapbox GL JS, Tailwind CSS
• Imagery: Google Satellite tiles

Docker Setup (Alternative)

For easier deployment, you can use Docker:

# 1. Copy the example env file and add your Mapbox token
cp .env.example .env
# Edit .env and add your Mapbox token

# 2. Build and run
docker-compose up --build

# 3. Open http://localhost:3000

To stop: docker-compose down

License

MIT