🌍 Manual GCP Georeferencing Tool

A desktop application for georeferencing aerial/drone images using Ground Control Points (GCPs)

Features • Installation • Usage • Examples • FAQ

📋 Table of Contents

Overview
Features
Installation
Quick Start
Detailed Usage
Technical Details
Use Cases
Tips & Best Practices
Troubleshooting
Roadmap
Contributing
License

🎯 Overview

Transform non-georeferenced images (historical aerial photos, drone imagery, or scanned maps) into georeferenced GeoTIFF files compatible with GIS software like QGIS and ArcGIS.

What is Georeferencing?

Georeferencing assigns real-world coordinates to an image, enabling spatial analysis and overlay with other geographic data.

✨ Features

✅ KML/KMZ Support - Load boundary files directly from Google Earth
✅ Automatic Satellite Download - Fetches reference imagery from Google Maps
✅ Side-by-Side Interface - Interactive point selection on dual canvases
✅ Flexible Transformation - Perspective (4 points) or Homography (4+ points with RANSAC)
✅ GeoTIFF Export - Properly georeferenced output with WGS84 coordinate system
✅ Multi-Format Support - JPG, PNG, TIFF input images

🛠️ Installation

Prerequisites

Python 3.8 or higher

Step 1: Clone the Repository

git clone https://github.com/yourusername/georeferencing-tool.git
cd georeferencing-tool

Step 2: Install Dependencies

Using pip

pip install -r requirements.txt

Manual Installation

pip install pillow numpy opencv-python rasterio requests

For macOS Users

If tkinter is not available:

brew install python-tk@3.11

🚀 Quick Start

1. Prepare Your Data

KML/KMZ file: Create a boundary polygon in Google Earth
Input image: Your aerial/drone photo (JPG, PNG, or TIFF)

2. Run the Application

python app.py

3. Three-Step Workflow

Step	Action	Description
1	Load KML/KMZ	Automatically downloads satellite reference image
2	Load Image	Select your input image to georeference
3	Mark Points	Click matching points on both images (min. 4 pairs)
4	Apply	Export georeferenced GeoTIFF

📖 Detailed Usage

Interface Overview

┌─────────────────────────────────────────────────────────────┐
│  [1. Select KML/KMZ]  [2. Select Image]  [Clear]  [Apply]  │
└─────────────────────────────────────────────────────────────┘
┌───────────────────────────┬───────────────────────────────┐
│                           │                               │
│    Input Image            │    Satellite Image            │
│    (Your Photo)           │    (Reference)                │
│                           │                               │
│    Points: 4              │    Points: 4                  │
│                           │                               │
└───────────────────────────┴───────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│  Status: Ready to georeference (4 point pairs)              │
└─────────────────────────────────────────────────────────────┘

Selecting Ground Control Points (GCPs)

Good GCP locations:

🏢 Building corners
🛣️ Road intersections
🌉 Bridge endpoints
⛲ Permanent landmarks

Point distribution:

┌─────────────────┐
│ 1             2 │  ← Cover all corners
│                 │
│                 │
│                 │
│ 4             3 │
└─────────────────┘

Keyboard Shortcuts

Note: Currently manual workflow only. Keyboard shortcuts coming soon!

📐 Technical Details

Coordinate Systems

Component	CRS	Details
Output	WGS84 (EPSG:4326)	Standard GPS coordinates
Satellite Tiles	Google Maps	Zoom level 17 (±4.77m/pixel)

Transformation Pipeline

graph LR
    A[Input Image] --> B[GCP Selection]
    C[Satellite Image] --> B
    B --> D[Homography Matrix]
    D --> E[Image Warping]
    E --> F[GeoTIFF Export]

Algorithms Used

4 points: cv2.getPerspectiveTransform() - Direct perspective transformation
5+ points: cv2.findHomography() with RANSAC - Robust outlier rejection

Image Processing Steps

Load and normalize images
Collect GCP pairs from user clicks
Convert display coordinates to image coordinates
Calculate transformation matrix
Warp input image to match satellite geometry
Export with geospatial metadata

🎯 Use Cases

Use Case	Description	Example
🗺️ Historical Maps	Digitize and georeference old paper maps	City plans from 1940s
🚁 Drone Imagery	Align photos without GPS metadata	Agricultural surveys
📸 Aerial Photos	Rectify oblique aerial photographs	Urban planning analysis
🕰️ Time-Series	Prepare multi-temporal datasets	Land use change detection
🏛️ Heritage	Archive historical aerial imagery	Cultural heritage preservation

💡 Tips & Best Practices

✅ Do's

Use 6-10 GCPs for optimal accuracy
Distribute points evenly across the entire image
Choose permanent features that exist in both images
Verify correspondence before applying transformation
Save intermediate results during complex projects

❌ Don'ts

Don't cluster all points in one area
Don't use temporary features (cars, people)
Don't rush the point selection process
Don't use too few points (<4)
Don't ignore point distribution warnings

Accuracy Tips

Number of Points → Accuracy:
4 points   → Basic alignment
6-8 points → Good accuracy  ⭐
10+ points → Excellent precision ⭐⭐⭐

🔧 Troubleshooting

❌ Satellite image not loading

Possible causes:

No internet connection
Invalid KML coordinates
Area too large (>10km²)

Solutions:

1. Check internet connectivity
2. Verify KML file in Google Earth
3. Reduce area of interest
4. Try different zoom level

❌ Poor georeferencing results

Possible causes:

Insufficient GCP points
Uneven point distribution
Incorrect point correspondence

Solutions:

1. Add more GCPs (8-12 recommended)
2. Distribute points to all corners
3. Clear and restart point selection
4. Verify each point pair carefully

❌ Application crashes on Mac

Solution:

# Install tkinter
brew install python-tk@3.11

# Verify installation
python3 -m tkinter

❌ "ModuleNotFoundError: rasterio"

Solution:

# Install GDAL first (macOS)
brew install gdal

# Then install rasterio
pip install rasterio

🌟 Roadmap

Phase 1: Current Version ✅

Manual GCP selection
KML/KMZ support
Satellite image download
GeoTIFF export

Phase 2: Semi-Automated (In Progress) 🚧

Deep learning-based point matching (SuperGlue)
ROI selection tool
Manual refinement interface
Batch processing

Phase 3: Advanced Features 🔮

Multi-temporal registration (60+ year gap)
Quality assessment metrics
Point cloud support
Web-based interface

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone repository
git clone https://github.com/mahdiBahramshahi/Python-Georefrencer-app.git

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

# Install dependencies
pip install -r requirements.txt


---

## 👨‍💻 Author

**Mahdi Bahramshahi**
- GitHub: [@mahdibahramshahi](https://github.com/mahdiBahramshahi)
- LinkedIn: (https://www.linkedin.com/in/mahdi-bahramshahi/)

---

## 🙏 Acknowledgments

- Google Maps API for satellite imagery
- OpenCV community for computer vision tools
- Rasterio for geospatial raster processing

---

## 📞 Support

- 📧 Email: bahramshahimahdi92@gmail.com
---

<div align="center">

### ⭐ Star this repository if you find it helpful!

Made with ❤️ for the GIS community

</div>

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.DS_Store		.DS_Store
.gitignore		.gitignore
README.md		README.md
app.py		app.py
requirements.txt		requirements.txt

mahdiBahramshahi/Python-Georefrencer-app

Folders and files

Latest commit

History

Repository files navigation