Azily/Macro-Dataset

--- license: cc-by-4.0 task_categories: - image-to-image - text-to-image language: - en tags: - multi-reference - image-generation - customization - illustration - spatial - temporal - benchmark pretty_name: "MACRO: Advancing Multi-Reference Image Generation with Structured Long-Context Data" size_categories: - 100K<n<1M --- # 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 | Task | Train samples (per category) | Eval samples (per category) | |------|------------------------------|-----------------------------| | **Customization** | 1-3: 20,000 / 4-5: 20,000 / 6-7: 30,000 / ≥8: 30,000 | 250 each | | **Illustration** | 25,000 each | 250 each | | **Spatial** | 25,000 each | 250 each | | **Temporal** | 25,000 each | 250 each | **Total:** ~400,000 training samples · 4,000 evaluation samples ### Task Categories | Category | Description | |----------|-------------| | **Customization** | Generate images preserving specific subjects (objects, persons, styles) from reference images | | **Illustration** | Generate illustrations conditioned on multiple reference images | | **Spatial** | Generate images respecting spatial relationships between objects in references | | **Temporal** | Generate images reflecting temporal or sequential changes across references | ### Image-Count Brackets Each task is further split by the number of reference images required: | Bracket | Reference images | |---------|-----------------| | `1-3` | 1 to 3 | | `4-5` | 4 to 5 | | `6-7` | 6 to 7 | | `>=8` | 8 or more | --- ## Repository Contents This dataset is distributed as a collection of `.tar.gz` archives for efficient download. Each archive can be extracted independently. ### Metadata & Index | Archive | Contents | |---------|----------| | `filter.tar.gz` | `data/filter/` — all JSON index files for train/eval samples (~510 MB uncompressed) | | `raw_t2i_example.tar.gz` | `data/raw/t2i_example/` — placeholder T2I JSONL + sample images | | `extract_data.sh` | Shell script to extract all archives back to the original `data/` layout | ### Raw Source Images (`data/raw/customization/`) Original source images used during data construction, split by subcategory: | Archive | Contents | |---------|----------| | `raw_customization_cloth.tar.gz` | `data/raw/customization/cloth/` + `cloth_train.jsonl` + `cloth_eval.jsonl` | | `raw_customization_human.tar.gz` | `data/raw/customization/human/` + `human_train.jsonl` + `human_eval.jsonl` | | `raw_customization_object.tar.gz` | `data/raw/customization/object/` + `object_train.jsonl` + `object_eval.jsonl` | | `raw_customization_scene.tar.gz` | `data/raw/customization/scene/` + `scene_train.jsonl` + `scene_eval.jsonl` | | `raw_customization_style.tar.gz` | `data/raw/customization/style/` + `style_train.jsonl` + `style_eval.jsonl` | ### 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: | Archive | Contents | |---------|----------| | `final_customization_train_1-3_00000_04999.tar.gz` | First 5,000 samples of `data/final/customization/train/1-3/data/` + `json/` | | `final_customization_train_1-3_05000_09999.tar.gz` | Next 5,000 samples | | `final_customization_train__ge8_00000_04999.tar.gz` | First 5,000 samples of `data/final/customization/train/>=8/data/` + `json/` | | `final_spatial_train_indoor_1-3_00000_04999.tar.gz` | First 5,000 samples of `data/final/spatial/train/indoor/1-3/` | | `final_temporal_eval_1-3_00000_00499.tar.gz` | All 500 eval samples of `data/final/temporal/eval/1-3/` | > **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: ```json { "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 ```bash 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 bash data_tar/extract_data.sh ./data_tar . # This restores: ./data/filter/, ./data/final/, ./data/raw/ ``` Or extract manually: ```bash 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`: ```bash 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): ```bash 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)](https://creativecommons.org/licenses/by/4.0/) license.--- 许可证: CC BY 4.0 任务类别: - 图像到图像生成（image-to-image） - 文本到图像生成（text-to-image） 语言: - 英语 标签: - 多参考（multi-reference） - 图像生成（image-generation） - 定制化（customization） - 插画（illustration） - 空间（spatial） - 时序（temporal） - 基准测试（benchmark） 展示名称: "MACRO：基于结构化长上下文数据推进多参考图像生成技术" 样本规模: 100K < n < 1M --- # MACRO：基于结构化长上下文数据推进多参考图像生成技术 **MACRO** 是一款面向多参考图像生成任务的大规模基准测试与训练数据集，涵盖四大任务类别与四类图像数量区间，同时提供训练子集与精心整理的评估基准集。 ## 数据集概览 | 任务类型 | 单类别训练样本数 | 单类别评估样本数 | | ------ | ---------------- | ---------------- | | **定制化（Customization）** | 1-3张参考图：20,000 / 4-5张参考图：20,000 / 6-7张参考图：30,000 / ≥8张参考图：30,000 | 每类250个 | | **插画（Illustration）** | 每类25,000个 | 每类250个 | | **空间（Spatial）** | 每类25,000个 | 每类250个 | | **时序（Temporal）** | 每类25,000个 | 每类250个 | **总计**：约400,000个训练样本 · 4,000个评估样本 ### 任务类别说明 | 类别 | 描述 | | ---- | ---- | | **定制化（Customization）** | 基于参考图像生成保留特定主体（物体、人物、风格）的图像 | | **插画（Illustration）** | 基于多幅参考图像生成插画作品 | | **空间（Spatial）** | 生成符合参考图像中物体间空间关系的图像 | | **时序（Temporal）** | 生成反映参考图像间时序或序列变化的图像 | ### 图像数量区间划分 所有任务均按照所需参考图像的数量进一步划分为以下区间： | 区间标识 | 参考图像数量 | | ------- | ----------- | | `1-3` | 1至3幅 | | `4-5` | 4至5幅 | | `6-7` | 6至7幅 | | `>=8` | 8幅及以上 | --- ## 仓库内容说明 本数据集以`.tar.gz`压缩包集合形式分发，便于高效下载，每个压缩包均可独立解压。 ### 元数据与索引文件 | 压缩包名称 | 包含内容 | | --------- | ------- | | `filter.tar.gz` | `data/filter/` — 训练/评估样本的全部JSON索引文件（未压缩大小约510 MB） | | `raw_t2i_example.tar.gz` | `data/raw/t2i_example/` — 文本到图像生成的占位符JSONL文件与示例图像 | | `extract_data.sh` | 用于将所有压缩包还原为原始`data/`目录结构的Shell脚本 | ### 原始源图像（`data/raw/customization/`） 数据集构建过程中使用的原始源图像，按子类别划分： | 压缩包名称 | 包含内容 | | --------- | ------- | | `raw_customization_cloth.tar.gz` | `data/raw/customization/cloth/` + `cloth_train.jsonl` + `cloth_eval.jsonl` | | `raw_customization_human.tar.gz` | `data/raw/customization/human/` + `human_train.jsonl` + `human_eval.jsonl` | | `raw_customization_object.tar.gz` | `data/raw/customization/object/` + `object_train.jsonl` + `object_eval.jsonl` | | `raw_customization_scene.tar.gz` | `data/raw/customization/scene/` + `scene_train.jsonl` + `scene_eval.jsonl` | | `raw_customization_style.tar.gz` | `data/raw/customization/style/` + `style_train.jsonl` + `style_eval.jsonl` | ### 最终图像数据（`data/final/`） 每个`data/final/{task}/{split}/{category}/`路径下的数据集均被划分为每5000个样本为一组的子目录块。压缩包命名遵循以下格式： final_{task}_{split}_{category}_{start}_{end}.tar.gz 其中`{start}`与`{end}`为补零至5位的数字索引（例如`00000_04999`）。每个压缩包均包含对应块的`data/<subdir>/`图像目录与`json/<subdir>.json`元数据文件，因此每个压缩包均可独立使用。 针对**空间（Spatial）**任务（其额外包含场景层级：`indoor`（室内）、`object`（物体）、`outdoor`（室外）），压缩包命名格式调整为： final_spatial_{split}_{scene}_{category}_{start}_{end}.tar.gz 示例如下： | 压缩包名称 | 包含内容 | | --------- | ------- | | `final_customization_train_1-3_00000_04999.tar.gz` | `data/final/customization/train/1-3/data/`与`json/`目录下的前5000个样本 | | `final_customization_train_1-3_05000_09999.tar.gz` | `data/final/customization/train/1-3/data/`与`json/`目录下的后续5000个样本 | | `final_customization_train__ge8_00000_04999.tar.gz` | `data/final/customization/train/>=8/data/`与`json/`目录下的前5000个样本 | | `final_spatial_train_indoor_1-3_00000_04999.tar.gz` | `data/final/spatial/train/indoor/1-3/`目录下的前5000个样本 | | `final_temporal_eval_1-3_00000_00499.tar.gz` | `data/final/temporal/eval/1-3/`目录下的全部500个评估样本 | > **关于文件名中`>=8`的说明**：`>=`符号在压缩包名称中被编码为`_ge`，因此`>=8`会被转换为`_ge8`。 --- ## 解压后的目录结构 data/ ├── filter/ # 训练与评估所用的JSON索引文件 │ ├── customization/ │ │ ├── train/ │ │ │ ├── 1-3/ *.json # 20,000个训练样本 │ │ │ ├── 4-5/ *.json # 20,000个训练样本 │ │ │ ├── 6-7/ *.json # 30,000个训练样本 │ │ │ └── >=8/ *.json # 30,000个训练样本 │ │ └── eval/ │ │ ├── 1-3/ *.json # 250个评估样本 │ │ ├── 4-5/ *.json # 250个评估样本 │ │ ├── 6-7/ *.json # 250个评估样本 │ │ └── >=8/ *.json # 250个评估样本 │ ├── illustration/ # 目录结构与customization一致 │ ├── spatial/ # 目录结构与customization一致 │ └── temporal/ # 目录结构与customization一致 ├── final/ # 实际图像数据 │ ├── customization/ # 目录布局：{split}/{cat}/data/ + json/ │ │ ├── train/ │ │ │ ├── 1-3/ │ │ │ │ ├── data/ │ │ │ │ │ ├── 00000000/ │ │ │ │ │ │ ├── image_1.jpg │ │ │ │ │ │ ├── image_2.jpg # 依此类推 │ │ │ │ │ │ └── image_output.jpg │ │ │ │ │ └── ... │ │ │ │ └── json/ *.json # 单样本生成元数据 │ │ │ ├── 4-5/ ... │ │ │ ├── 6-7/ ... │ │ │ └── >=8/ ... │ │ └── eval/ ... │ ├── illustration/ ... # 目录结构与customization一致 │ ├── spatial/ # 额外包含场景层级：{split}/{scene}/{cat}/ │ │ ├── train/ │ │ │ ├── indoor/ │ │ │ │ ├── 1-3/ data/ + json/ │ │ │ │ ├── 4-5/ ... │ │ │ │ ├── 6-7/ ... │ │ │ │ └── >=8/ ... │ │ │ ├── object/ ... │ │ │ └── outdoor/ ... │ │ └── eval/ ... │ └── temporal/ ... # 目录结构与customization一致 └── raw/ ├── t2i_example/ │ ├── t2i_example.jsonl # 占位符文本到图像生成提示词（用于训练格式参考） │ └── images/ # 占位符图像 └── customization/ # 定制化任务的原始源图像 ├── cloth/ *.jpg ├── human/ *.jpg ├── object/ *.jpg ├── scene/ *.jpg ├── style/ *.jpg └── *_train.jsonl / *_eval.jsonl --- ## JSON样本格式 `data/filter/`目录下的每个文件均包含单个JSON对象，格式示例如下： json { "task": "customization", "idx": 1, "prompt": "以<image 2>中的现代玻璃金属内饰为主体，将<image 1>中的古典油画风格全局应用于整个场景，生成对应图像。", "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" } JSON文件中的所有图像路径均**相对于解压后的数据目录根目录**（即`data/`的上级目录）。 --- ## 下载与配置 ### 全量下载所有压缩包 bash huggingface-cli download Azily/Macro-Dataset --repo-type dataset --local-dir data_tar/ ### 解压操作 解压脚本`extract_data.sh`已包含在下载的`data_tar/`文件夹中，请在项目根目录执行以下命令： bash bash data_tar/extract_data.sh ./data_tar . # 该命令将还原：./data/filter/, ./data/final/, ./data/raw/ 目录结构 或手动解压： bash for f in data_tar/*.tar.gz; do tar -xzf "$f" -C .; done ### 选择性下载 若仅需评估基准集（无需图像文件），仅下载`filter.tar.gz`即可： bash 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 . 若需下载特定任务/子集/类别的数据（例如定制化训练任务1-3区间的所有数据块）： bash 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 --- ## 许可证 本数据集采用[知识共享署名4.0国际许可协议（CC BY 4.0）](https://creativecommons.org/licenses/by/4.0/)进行分发。