README.md

---
license: cc-by-4.0
task_categories:
- image-to-text
- visual-question-answering
language:
- en
tags:
- map
- navigation
size_categories:
- 1M<n<10M
---

# MapTrace: A 2M-Sample Synthetic Dataset for Path Tracing on Maps


<div>
<p align="center">
<img src="assets/teaser.png" width="800px">
</p>
</div>

Welcome to the **MapTrace** dataset! If you use this dataset in your work, please **[cite our paper below](#citation)**.
For more details about our methodology and findings, please visit our [project page](https://artemisp.github.io/maptrace/) or read the official [white paper](https://arxiv.org/abs/2512.19609).
This work was also recently featured on the [Google Research Blog](https://research.google/blog/teaching-ai-to-read-a-map/).

## Code & Scripts

Official training and data loading scripts are available in our GitHub repository: 
**[google-research/MapTrace](https://github.com/google-research/MapTrace)**


## Quick Start: Downloading the Dataset

To easily download and work with MapTrace locally, we recommend using the Hugging Face `datasets` library for browsing. But you can also download the raw files directly to train on the entire set.

### Method 1: Using huggingface_hub library to download all raw files.

#### 1. Install library

First, install the `datasets` and `matplotlib` package in your environment:
```bash
pip install huggingface_hub
```

#### 2. Download with python

Now download with python

```python
from huggingface_hub import snapshot_download

local_dir = "./MapTrace_Data"
snapshot_download(
    repo_id="google/MapTrace",
    repo_type="dataset",
    local_dir=local_dir
)
print(f"All raw parquet files downloaded to: {local_dir}")
```

Note: You can also specify `allow_patterns="maptrace_20k/*"` to download a specific split.

### Method 2: Using datasets library to browse through the data.

#### 1. Install the library
First, install the `datasets` and `matplotlib` package in your environment:
```bash
pip install datasets
pip install matplotlib
```

#### 2. Load specific splits

Because the dataset is organized into separate folders of `.parquet` files, you can use the `data_dir` argument to load the specific subset you want:

```python
from datasets import load_dataset

# Load the 20k subset used in the paper
ds_20k = load_dataset("google/MapTrace", data_dir="maptrace_20k")

# Load the floor maps
ds_floormaps = load_dataset("google/MapTrace", data_dir="floormaps")

# Load the large complex maps dataset
ds_maptrace = load_dataset("google/MapTrace", data_dir="maptrace")
```

#### 3. Browsing the data

```python
import io
import ast
import matplotlib.pyplot as plt
from PIL import Image
from datasets import load_dataset

# 1. Load the dataset folder
print("Loading dataset...")
# maptrace split
ds = load_dataset("google/MapTrace", data_dir="maptrace_20k")

# Print the automatically generated splits (e.g., dict_keys(['train', 'validation']))
print(f"Available splits: {ds.keys()}")

# Access the first sample from your preferred split (e.g., 'validation' or 'train')
split_name = "train" # Change this to "validation" if you prefer
sample = ds[split_name][0]

# 2. Decode the raw image bytes into a PIL Image
img_bytes = sample["image"]
img = Image.open(io.BytesIO(img_bytes)).convert("RGB")
width, height = img.size

# 3. Parse the label text into a list of coordinates
normalized_coords = ast.literal_eval(sample["label_"])

# 4. Scale the normalized [0, 1] coordinates to the actual image pixel dimensions
pixel_coords = [(x * width, y * height) for x, y in normalized_coords]

# 5. Print the text fields
print("\n--- Map Information ---")
print(f"Input Prompt: {sample['input']}")

# 6. Plot the image and the path
plt.figure(figsize=(10, 10))
plt.imshow(img)

# Unzip the coordinates into separate x and y lists for plotting
x_coords, y_coords = zip(*pixel_coords)

# Plot the path line and overlay points
plt.plot(x_coords, y_coords, color='red', linewidth=3, label='Path')
plt.scatter(x_coords, y_coords, color='blue', s=40, zorder=5, label='Waypoints')

# Mark the Start and End points clearly
plt.scatter(x_coords[0], y_coords[0], color='green', s=100, marker='*', zorder=6, label='Start')
plt.scatter(x_coords[-1], y_coords[-1], color='orange', s=100, marker='X', zorder=6, label='End')

plt.title(f"MapTrace Path Visualization ({split_name.capitalize()} Split)")
plt.axis('off') # Hide axes for a cleaner look
plt.legend()

# 7. Save the plot instead of showing it to avoid the FigureCanvasAgg warning
output_filename = f"visualized_path_{split_name}.png"
plt.savefig(output_filename, bbox_inches='tight', dpi=300)
print(f"Success! Map visualization saved locally to: {output_filename}")

```

## Dataset Format

This dataset contains 2 million annotated paths designed to train models on route-tracing tasks. 

### Data Splits

The dataset contains 2M annotated paths designed to train models on route-tracing tasks. 
Splits:
- `maptrace_parquet`: Contains paths on more complex, stylized maps such as those found in brochures, park directories or shopping malls. 
- `floormap_parquet`: Contains paths on simpler, structured floor maps, typical of office buildings appartment complexes, or campus maps.
- `maptrace_20k`: Contains paths on more complex, stylized maps such as those found in brochures, park directories or shopping malls and this subset was used for our paper `MapTrace: Scalable Data Generation for Route Tracing on Maps`. 

### Schemas

Splits `maptrace_parquet` and `floormap_parquet` has the following fields:
- `image_bytes`: The raw bytes of the generated map image (without post processing.)
- `label_text`: A string representation of a list of coordinates defining the target path. All coordinates are normalized between 0 and 1. 
- `input_text`: A natural language question (prompt) asking the model to find the path specified in `label_text`. 
- `map_description`: A natural language description of the map image, used by a text-to-image generation model to create the synthetic image. 

We also release the splits used in our paper in `maptrace_20k`. The schema in these files is as follows: 
- `image`: The image bytes of the map, *annotated* with start and end positions
- `label`: A string representation of a list of coordinates defining the target path. All coordinates are normalized between 0 and 1.
- `input`: A natural language question (prompt) asking the model to find the path specified in `label`.


## Citation

If you use our work, please cite:

```bibtex
@misc{panagopoulou2025maptracescalabledatageneration,
      title={MapTrace: Scalable Data Generation for Route Tracing on Maps}, 
      author={Artemis Panagopoulou and Aveek Purohit and Achin Kulshrestha and Soroosh Yazdani and Mohit Goyal},
      year={2025},
      eprint={2512.19609},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2512.19609}, 
}
```