--- title: GenEarth canonical_url: "https://www.modelscope.ai/studios/KeyanChen/GenEarth" md_url: "https://www.modelscope.ai/studios/KeyanChen/GenEarth.md" repository: KeyanChen/GenEarth chinese_name: GenEarth last_updated: 2026-10-19 sdk_type: gradio sdk_version: 6.17.3 downloads: 0 stars: 0 --- # GenEarth > GenEarth - An interactive demo by KeyanChen on ModelScope. GenEarth is an open-source research series centered on Text2Earth, a 1.3B-parameter diffusion foundation model for text-driven, resolution-controllable remote-sensing image generation, supported by… KeyanChen/GenEarth is an interactive demo (Studio) on ModelScope. built with gradio 6.17.3. - **Repository**: KeyanChen/GenEarth - **SDK**: gradio - **SDK version**: 6.17.3 - **Downloads**: 0 - **Stars**: 0 - **Last updated**: 2026-10-19 Source: https://www.modelscope.ai/studios/KeyanChen/GenEarth ---
GenEarth logo

GenEarth

简体中文 | English

Generating Earth, from pixels to worlds

Open generative foundation models, datasets, and interactive tools for Earth observation

Live demo · Project page · Text2Earth GitHub · Paper

![GenEarth research family](images/genearth_family.png) ## Overview **GenEarth** is an open research family for generative Earth observation, built around **Text2Earth**. Starting from a global-scale remote-sensing image–text dataset, the project explores controllable 2D image generation, unbounded scene expansion, multimodal Earth observation generation, and world-scale 3D scene generation. This repository provides a ready-to-run Gradio application that combines research showcases with interactive model demos. Text2Earth text-to-image generation and Text2Earth-inpainting are currently integrated. MetaEarth, MetaEarth-MM, MetaEarth3D, and other capabilities are presented as research showcases and placeholders for future integration. ## Features | Module | Capability | Status | | --- | --- | --- | | Project home | Presents the GenEarth research family, Git-10M, Text2Earth, and related work | Available | | Text-to-image | Generates remote-sensing images from English text | Real CUDA inference / CPU demo preview | | Resolution control | Controls spatial resolution from `1–64 m/px` using Google Map Level | Available | | Batch generation | Generates `1–5` images per run and records seeds and elapsed time | Available | | Inpainting | Modifies a selected image region from a text prompt | Real CUDA inference / CPU demo preview | | Mask tools | Accepts a black-and-white mask or creates a rectangular/circular mask from parameters | Available | | More capabilities | Entry points for MetaEarth, MetaEarth-MM, MetaEarth3D, super-resolution, and more | Showcase / reserved | The application supports `256 × 256` and `512 × 512` outputs, configurable inference steps and guidance scale, deterministic seeds, built-in examples, live mask previews, and runtime logs. > [!IMPORTANT] > Real Text2Earth inference requires a CUDA GPU. If CUDA is unavailable, the application automatically switches to a watermarked procedural demo mode for UI preview and interaction testing. Demo images are not model outputs. ## Quick Start ### Requirements - Python `3.10+`; Python `3.12` is recommended - A CUDA GPU for real Text2Earth inference - Access to ModelScope or Hugging Face to download model weights on first use ### Option 1: uv The included script creates a Python 3.12 virtual environment and installs all dependencies: ```bash chmod +x create_uv_env.sh ./create_uv_env.sh source .venv/bin/activate python app.py ``` If uv is not installed, the script installs it through the official installer. This requires `curl` and an internet connection. ### Option 2: venv and pip ```bash python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -r requirements.txt python app.py ``` Open [http://localhost:7860](http://localhost:7860) after startup. By default, the application listens on `0.0.0.0:7860`. ## Usage ### Text-to-image generation 1. Enter an English scene description in **Text-to-image**. The model was trained on English prompts, so English generally produces the most reliable results. 2. Select a spatial-resolution level, output size, and image count. 3. Optionally adjust the inference steps, text guidance scale, and seed under **Advanced settings**. 4. In a CUDA environment, **Real Text2Earth inference** is enabled by default. Start generation to view the results and runtime log. Example prompt: ```text Many rectangular-shaped green and tan mixed farmlands of different sizes ``` ### Inpainting 1. Upload an original remote-sensing image or load a built-in example. 2. Select a rectangular region, circular region, or uploaded black-and-white mask. 3. Check the orange region in the mask preview. For uploaded masks, **white pixels are regenerated and black pixels are preserved**. 4. Describe the desired content in English, configure the generation settings, and start inpainting. ## Spatial-resolution Conditioning Text2Earth encodes the Google Map Level in the prompt: ```text Resolution = 2^(17 - Level), Level ∈ [11, 17] model_prompt = "{Level}_GOOGLE_LEVEL_{content_prompt}" ``` The application maps levels to spatial resolutions as follows: | Level | 11 | 12 | 13 | 14 | 15 | 16 | 17 | | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | Resolution (m/px) | 64 | 32 | 16 | 8 | 4 | 2 | 1 | For example, Level 16 and the prompt `Many green trees are in a piece of forest` become: ```text 16_GOOGLE_LEVEL_Many green trees are in a piece of forest ``` ## Model Loading and Configuration Each model is loaded only when its first real inference task is triggered, then cached for the lifetime of the process. ModelScope is the default source; if its download fails, the application can automatically fall back to Hugging Face. | Environment variable | Default | Description | | --- | --- | --- | | `GENEARTH_MODEL_SOURCE` | `modelscope` | Model source; set to `huggingface` to use Hugging Face directly | | `GENEARTH_ALLOW_HF_FALLBACK` | `1` | Whether to fall back to Hugging Face after a ModelScope failure; set to `0` to disable | | `GENEARTH_DEMO_MODE` | `0` | Set to `1` to force demo preview mode even when CUDA is available | | `GENEARTH_TEXT2IMAGE_MODEL_PATH` | Empty | Local Text2Earth model directory | | `GENEARTH_INPAINTING_MODEL_PATH` | Empty | Local Text2Earth-inpainting model directory | | `GRADIO_SERVER_NAME` | `0.0.0.0` | Gradio listening address | | `GRADIO_SERVER_PORT` | `7860` | Local listening port; `PORT` takes precedence when present | Use Hugging Face as the model source: ```bash GENEARTH_MODEL_SOURCE=huggingface python app.py ``` Use local models: ```bash export GENEARTH_TEXT2IMAGE_MODEL_PATH=/path/to/Text2Earth export GENEARTH_INPAINTING_MODEL_PATH=/path/to/Text2Earth-inpainting python app.py ``` The models are loaded through custom Diffusers pipelines with `trust_remote_code=True`. Review the custom code before using an unofficial model directory. ## Deploying on ModelScope Studio 1. Create a **Programmatic / Gradio 6** Studio. 2. Push this repository to the Studio Git repository. 3. Set the SDK version to `6.17.3` and the entry file to `app.py`. 4. Select a CUDA-enabled GPU instance for real inference, then publish or restart the Studio. When ModelScope injects `PORT`, the application uses it automatically. The corresponding weights are downloaded and cached on the first real inference request, so reserve several gigabytes of storage for the model cache. ### Chinese and English routes The same Studio serves both language versions: - Chinese: root path `/` - English: `/en` Use the **中文 / English** switch in the page header to move between them. The routes are provided by Gradio multipage routing in `app.py`; ModelScope still needs only one Studio and one `app.py` entry point. Restart the Studio after pushing the code. ModelScope page settings do not automatically translate custom Gradio copy. ## Project Structure ```text GenEarth/ ├── README.md # Chinese documentation ├── README_EN.md # English documentation ├── app.py # Gradio pages, events, and runtime configuration ├── inference.py # Model resolution, pipeline loading, and inference utilities ├── ui.py # Page content, component styles, and research showcases ├── requirements.txt # Python runtime dependencies ├── create_uv_env.sh # uv environment setup script └── images/ # UI assets, paper figures, and inpainting examples ``` ## Open Resources and Research Family | Project | Description | Resources | | --- | --- | --- | | Git-10M | 10.5 million global remote-sensing image–text pairs with geolocation and resolution metadata | [ModelScope](https://modelscope.cn/datasets/lcybuaa1111/Git-10M/) · [Hugging Face](https://huggingface.co/datasets/lcybuaa/Git-10M) | | Git-RSCLIP | A foundation model for remote-sensing vision–language representation | [ModelScope](https://modelscope.cn/models/lcybuaa1111/Git-RSCLIP) · [Hugging Face](https://huggingface.co/lcybuaa/Git-RSCLIP) | | Text2Earth | Resolution-controllable, text-driven remote-sensing image generation | [ModelScope](https://modelscope.cn/models/lcybuaa1111/Text2Earth) · [Hugging Face](https://huggingface.co/lcybuaa/Text2Earth) | | Text2Earth-inpainting | Text-guided inpainting for remote-sensing images | [ModelScope](https://modelscope.cn/models/lcybuaa1111/Text2Earth-inpainting) · [Hugging Face](https://huggingface.co/lcybuaa/Text2Earth-inpainting) | | MetaEarth | Global-scale, resolution-guided unbounded remote-sensing image generation | [Paper](https://arxiv.org/abs/2405.13570) | | MetaEarth-MM | Unified multimodal remote-sensing image generation with scene-centered joint modeling | [Paper](https://arxiv.org/abs/2605.20090) | | MetaEarth3D | World-scale 3D generation through spatially scalable generative modeling | [Paper](https://arxiv.org/abs/2604.22828) | ![Text2Earth overview](images/overall.png) ## Citation If this project is useful in your research, please cite Text2Earth: ```bibtex @ARTICLE{10988859, author={Liu, Chenyang and Chen, Keyan and Zhao, Rui and Zou, Zhengxia and Shi, Zhenwei}, journal={IEEE Geoscience and Remote Sensing Magazine}, title={Text2Earth: Unlocking Text-driven Remote Sensing Image Generation with a Global-Scale Dataset and a Foundation Model}, year={2025}, volume={13}, number={3}, pages={238--259}, doi={10.1109/MGRS.2025.3560455} } ``` More papers: - [MetaEarth: A Generative Foundation Model for Global-Scale Remote Sensing Image Generation](https://arxiv.org/abs/2405.13570) - [MetaEarth-MM: Unified Multimodal Remote Sensing Image Generation with Scene-centered Joint Modeling](https://arxiv.org/abs/2605.20090) - [MetaEarth3D: Unlocking World-scale 3D Generation with Spatially Scalable Generative Modeling](https://arxiv.org/abs/2604.22828) ## Notes This project is intended for generative GeoAI research showcases and model demos. Datasets, model weights, and related research outputs may use their own licenses; review the corresponding resource pages before use.