EasyEarth: Run Vision(-Language) Models for Earth Observations at Your Fingertips

EasyEarth enables seamless application of cutting-edge computer vision and vision-language models directly on Earth observation data — without writing code. The platform integrates with QGIS via a plugin GUI and provides server-side infrastructure for scalable model inference and management.

---

🔧 Key Components

1. Server-Side Infrastructure – Scalable backend to run AI models on geospatial data
2. QGIS Plugin GUI – User-friendly interface to apply models inside QGIS
3. Model Manager (in development) – Upload, version, and deploy models with ease

📽️ Watch Demo

---

Table of Contents

• Project Structure
• Get Started
  • Requirements
  • Clone Repository
  • Set Up Docker Server
    • Stop the Server
    • Useful Docker Commands
  • Install EasyEarth Plugin in QGIS
    • Method 1: Manual Installation
    • Method 2: Terminal Installation
• Available Models
• Model APIs
  • Use SAM with Prompts
  • Use Models Without Prompts
• Usage
  • Run EasyEarth in QGIS
  • Run EasyEarth Outside QGIS
  • Health Check
• Documentation
• Roadmap
• Contributing
• Author
• License

📁 Project Structure

easyearth/
├── easyearth/         # Server app – use this if you're only interested in the backend
├── easyearth_plugin/  # QGIS plugin – use this folder to install the QGIS interface
│   └── easyearth/     # Server app (same as above, for plugin integration)

---

Get Started

✅ Requirements

• Docker Compose ≥ 1.21.2 (install guide)
• Python ≥ 3.6
• QGIS
• CUDA ≥ 12.4 (download)
  ⚠️ More info on CUDA compatibility coming soon

📥 Clone Repository

# go to your download directory
cd ~/Downloads  # Specify your own path where you want to download the code
git clone https://github.com/YanCheng-go/easyearth.git
cp -r ./easyearth/easyearth_plugin easyearth_plugin

🐳 Set Up Docker Server

This will install Docker, build the image, and launch the EasyEarth server.

cd easyearth_plugin  # go to the directory where docker-compose.yml is located
chmod +x ./setup.sh  # make the setup.sh executable
./setup.sh  # run the setup.sh script

🛑 Stop the Server

cd easyearth_plugin  # go to the directory where docker-compose.yml is located
sudo docker-compose down  # stop the docker container

🛠 Useful Docker Commands

# List containers
docker ps -a
# List images
docker images
# Remove all containers
docker rm $(docker ps -a -q)
# Remove all images
docker rmi $(docker images -q)
# Remove all volumes
docker volume rm $(docker volume ls -q)
# Inspect container
sudo docker inspect <container_id>
# Access container shell
sudo docker exec -it <container_id_or_name> /usr/src/app

🧩 Install EasyEarth Plugin in QGIS

Method 1: Manual Installation

1. Open QGIS > Settings > User Profiles > Open Active Profile Folder
2. Navigate to python/plugins
3. Copy easyearth_plugin folder into this directory
4. Restart QGIS > Plugins > Manage and Install Plugins > enable EasyEarth

Method 2: Terminal Installation

cd ~/Downloads/easyearth_plugin  # go to the directory where easyearth_plugin is located
cp -r ./easyearth_plugin ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins  # copy the easyearth_plugin folder to the plugins directory

---

🚀 Usage

🛰️ Run EasyEarth in QGIS

1. Stop external Docker containers:

    cd easyearth_plugin  # go to the directory where docker-compose.yml is located
    sudo docker-compose down  # stop the docker container

2. Open QGIS, click Start Docker
3. Load an image using Browse Image
4. Click Start Drawing

---

🧠 Available Models (Adding...)

Model Name	Description	Prompt Type	Prompt Data
SAM	Segment Anything Model	Point	[[x, y], [x, y], ...]
SAM	Segment Anything Model	Box	[[x1, y1, x2, y2]]
SAM2	Segment Anything Model	Point	[[x, y], [x, y], ...]
SAM2	Segment Anything Model	Box	[[x1, y1, x2, y2]]
LangSAM	Language Model	Text	["text1", "text2"]
restor/tcd-segformer-mit-b2	Semantic Segmentation	None	[]

---

✨ Model APIs

📍 Use SAM with Prompts

curl -X POST http://127.0.0.1:3781/v1/easyearth/sam-predict \
-H "Content-Type: application/json" \
-d '{
  "image_path": "/usr/src/app/user/DJI_0108.JPG",
  "embedding_path": "/usr/src/app/user/embeddings/DJI_0108.pt", # if empty, the code will generate embeddings first
  "model_path": "facebook/sam-vit-large", # model path from huggingface
  "prompts": [{
    "type": "Point",
    "data": {
      "points": [[850, 1100]],  # can be multiple points
    }
  }]
}'

🚫 Use Models Without Prompts

curl -X POST http://127.0.0.1:3781/v1/easyearth/segment-predict \
-H "Content-Type: application/json" \
-d '{
  "image_path": "/usr/src/app/user/DJI_0108.JPG",
  "model_path": "restor/tcd-segformer-mit-b2", # model path from huggingface
  "prompts": []
}'

---

🔌 Run EasyEarth Outside QGIS

You can also run EasyEarth server headlessly:

1. Start the Docker container

cd easyearth_plugin  # go to the directory where the repo is located
sudo TEMP_DIR=/custom/temp/data DATA_DIR=/custom/data/path LOG_DIR=/custom/log/path MODEL_DIR=/custom/cache/path docker-compose up -d # start the container while mounting the custom directories.

2. Use Rest API to send requests to the server, check Model APIs for more details.

✅ Health Check

Check if the server is running, the response should be Server is alive

curl -X GET http://127.0.0.1:3781/v1/easyearth/ping

---

📚 Documentation (TO BE UPDATED)

Check out our User Guide and Developer Guide for more.

• User Guide
• Developer Guide
• API Reference
• Model Management
• QGIS Plugin
• Docker Setup

---

✅ Roadmap

• EasyEarth server for model inference
• QGIS plugin for model application
• Dockerized server for scalable model inference
• Advanced prompt-guided segmentation
• Compelet documentation
• Editing tools for segmentation
• Model Manager for uploading/updating/tracking models
• Chatbot integration for model management and reporting
• Cloud deployment templates

---

🤝 Contributing

We welcome community contributions! If you'd like to contribute, check out:

• CONTRIBUTING.md

---

🧑‍💻 Author

Developed by: Yan Cheng ([email protected]), Ankit Kariryaa ([email protected]), Lucia Gordon ([email protected])

---