MACRO: Advancing Multi-Reference Image Generation with Structured Long-Context Data

MACRO is a large-scale benchmark and training dataset for multi-reference image generation. It covers four task categories and four image-count brackets, providing both training splits and a curated evaluation benchmark.

Dataset Summary

Total: ~400,000 training samples · 4,000 evaluation samples

Task Categories

Image-Count Brackets

Each task is further split by the number of reference images required:

---

Repository Contents

This dataset is distributed as a collection of .tar.gz archives for efficient download. Each archive can be extracted independently.

Metadata & Index

Raw Source Images (data/raw/customization/)

Original source images used during data construction, split by subcategory:

Image Data (data/final/)

Each data/final/{task}/{split}/{category}/ slice is split into chunks of 5,000 sample subdirectories. Archives follow this naming pattern:

final_{task}_{split}_{category}_{start}_{end}.tar.gz

where {start} and {end} are zero-padded 5-digit indices (e.g. 00000_04999). Each chunk contains both the data/<subdir>/ image directories and the corresponding json/<subdir>.json metadata files for that chunk, so every archive is self-contained.

For the spatial task (which has an extra scene layer — indoor, object, outdoor):

final_spatial_{split}_{scene}_{category}_{start}_{end}.tar.gz

Examples:

Note on >=8 in filenames: the >= is encoded as _ge in archive names, so >=8 becomes _ge8.

---

Directory Structure (after extraction)

data/
├── filter/                          # JSON index files (used for training & eval)
│   ├── customization/
│   │   ├── train/
│   │   │   ├── 1-3/   *.json       # 20,000 training samples
│   │   │   ├── 4-5/   *.json       # 20,000 training samples
│   │   │   ├── 6-7/   *.json       # 30,000 training samples
│   │   │   └── >=8/   *.json       # 30,000 training samples
│   │   └── eval/
│   │       ├── 1-3/   *.json       # 250 eval samples
│   │       ├── 4-5/   *.json       # 250 eval samples
│   │       ├── 6-7/   *.json       # 250 eval samples
│   │       └── >=8/   *.json       # 250 eval samples
│   ├── illustration/  (same layout as customization)
│   ├── spatial/       (same layout as customization)
│   └── temporal/      (same layout as customization)
├── final/                           # Actual image data
│   ├── customization/               # layout: {split}/{cat}/data/ + json/
│   │   ├── train/
│   │   │   ├── 1-3/
│   │   │   │   ├── data/
│   │   │   │   │   ├── 00000000/
│   │   │   │   │   │   ├── image_1.jpg
│   │   │   │   │   │   ├── image_2.jpg   (etc.)
│   │   │   │   │   │   └── image_output.jpg
│   │   │   │   │   └── ...
│   │   │   │   └── json/  *.json   (per-sample generation metadata)
│   │   │   ├── 4-5/ ...
│   │   │   ├── 6-7/ ...
│   │   │   └── >=8/ ...
│   │   └── eval/ ...
│   ├── illustration/ ...            (same layout as customization)
│   ├── spatial/                     # extra scene layer: {split}/{scene}/{cat}/
│   │   ├── train/
│   │   │   ├── indoor/
│   │   │   │   ├── 1-3/  data/ + json/
│   │   │   │   ├── 4-5/ ...
│   │   │   │   ├── 6-7/ ...
│   │   │   │   └── >=8/ ...
│   │   │   ├── object/ ...
│   │   │   └── outdoor/ ...
│   │   └── eval/ ...
│   └── temporal/ ...                (same layout as customization)
└── raw/
    ├── t2i_example/
    │   ├── t2i_example.jsonl        # Placeholder T2I prompts (for training format reference)
    │   └── images/                  # Placeholder images
    └── customization/               # Original source images (customization)
        ├── cloth/  *.jpg
        ├── human/  *.jpg
        ├── object/ *.jpg
        ├── scene/  *.jpg
        ├── style/  *.jpg
        └── *_train.jsonl / *_eval.jsonl

---

JSON Sample Format

Each file in data/filter/ contains a single JSON object:

{
  "task": "customization",
  "idx": 1,
  "prompt": "Create an image of the modern glass and metal interior from <image 2>, applying the classical oil painting style from <image 1> globally across the entire scene.",
  "input_images": [
    "data/final/customization/train/1-3/data/00022018/image_1.jpg",
    "data/final/customization/train/1-3/data/00022018/image_2.jpg"
  ],
  "output_image": "data/final/customization/train/1-3/data/00022018/image_output.jpg"
}

All image paths in the JSON files are relative to the root of the extracted data directory (i.e., relative to the parent of data/).

---

Download & Setup

Download all archives

huggingface-cli download Azily/Macro-Dataset --repo-type dataset --local-dir data_tar/

Extract

extract_data.sh is included in the downloaded data_tar/ folder. Run it from the project root:

bash data_tar/extract_data.sh ./data_tar .
# This restores: ./data/filter/, ./data/final/, ./data/raw/

Or extract manually:

for f in data_tar/*.tar.gz; do tar -xzf "$f" -C .; done

---

Selective Download

If you only need the evaluation benchmark (no images), download just filter.tar.gz:

huggingface-cli download Azily/Macro-Dataset \
    --repo-type dataset \
    --include "filter.tar.gz" \
    --local-dir data_tar/
tar -xzf data_tar/filter.tar.gz -C .

To download a specific task/split/category (e.g., all chunks of customization train 1-3):

huggingface-cli download Azily/Macro-Dataset \
    --repo-type dataset \
    --include "final_customization_train_1-3_*.tar.gz" \
    --local-dir data_tar/
for f in data_tar/final_customization_train_1-3_*.tar.gz; do tar -xzf "$f" -C .; done

---

License

This dataset is released under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.