BiliSakura/JL1-CUP-2024-Second-Format

---
license: other
license_details: >
Imagery and labels originate from the Jilin-1 (JL1) cropland change-detection
competition hosted on JL1 Mall. Use is subject to the provider’s competition
rules and repository terms. See **Source** below.
language:
- en
pretty_name: JL1 CUP 2024 (Second Track — SCD folder layout)
tags:
- remote-sensing
- semantic-change-detection
- change-detection
- satellite-imagery
- bi-temporal
task_categories:
- image-segmentation
size_categories:
- 1M<n<10M
# Dataset Viewer: metadata.csv paths must be relative to that split folder (same dir as the CSV);
# HF joins dirname(metadata.csv) + path — repo-root paths like train/T1/… break and show as strings.
# Raw layout uses train/T1, train/T2, … which ImageFolder would otherwise treat as class labels.
configs:
- config_name: default
default: true
drop_labels: true
data_files:
- split: train
path: train/metadata.csv
- split: validation
path: val/metadata.csv
- split: test
path: test/metadata.csv
---

# JL1 CUP 2024 — Second-track format for semantic change detection

Bi-temporal 256×256 RGB patches with **per-pixel semantic maps** at times T1/T2 and a **binary change map**, aligned with the data split described in the literature for the JL1 cropland change-detection benchmark (*Second Track* / JL1-Second style layout).

## Source

| Resource | URL |
| -------- | --- |
| JL1 Mall contest information | [contest page](https://www.jl1mall.com/contest/match/info?id=1645664411716952066) |
| JL1 data / resources portal | [resrepo](https://www.jl1mall.com/resrepo/) |

Data are provided by the JL1 / Jilin-1 ecosystem and the **“耕地变化检测” (cropland change detection)** competition. This Hub snapshot organizes released splits into a single **semantic change detection (SCD)** directory layout (T1/T2 + semantic labels + change mask).

## Credit & citation

The **train / validation** labeling and split follow the convention used in remote-sensing SCD work on this benchmark. If you use this dataset in research, please cite:

```bibtex
@article{wangCrossDifferenceSemanticConsistency2024,
title = {Cross-Difference Semantic Consistency Network for Semantic Change Detection},
author = {Wang, Qi and Jing, Wei and Chi, Kaichen and Yuan, Yuan},
journal = {IEEE Transactions on Geoscience and Remote Sensing},
volume = {62},
pages = {1--12},
year = {2024},
doi = {10.1109/TGRS.2024.3386334}
}
```

Please also **acknowledge the JL1 competition and data provider** in-line (e.g. “JL1 CUP / JL1 Mall”) whenever you report results.

## Dataset summary

| Item | Value |
| ---- | ----- |
| Task | Semantic change detection (semantic maps at T1 & T2 + change mask) |
| Patch size | 256 × 256 × 3 (uint8 PNG) |
| Train samples | 4 050 |
| Validation samples | 1 950 (with labels) |
| Test samples | 2 000 (**bi-temporal images only**, no public ground truth) |

Splits are identified by **full paths** (`train/…`, `val/…`, `test/…`). The same numeric filename stem (e.g. `00001`) **does not** denote the same geographic patch across splits.

## Folder layout

```text
.
├── train/
│ ├── metadata.csv # Hub viewer: one row per patch → T1, T2, GT_T1, GT_T2, GT_CD columns
│ ├── T1/ # pre-change RGB
│ ├── T2/ # post-change RGB
│ ├── GT_T1/ # single-channel semantic map, T1
│ ├── GT_T2/ # single-channel semantic map, T2
│ └── GT_CD/ # binary change: 0 = no change, 255 = change
├── val/
│ ├── metadata.csv # same column layout as train/
│ └── (same modality folders as train/)
├── test/
│ ├── metadata.csv # Hub viewer: T1 + T2 only (no public GT)
│ ├── T1/
│ └── T2/ # hold-out evaluation; labels not distributed
├── train.txt # one stem per line, **without** `.png`
├── val.txt # one filename per line, **with** `.png`
└── test.txt # same naming convention as val.txt
```

**Resolving paths:** for `train`, append `.png` to each line of `train.txt` under `T1/` and `T2/`. For `val` and `test`, use each line as the filename under `T1/` and `T2/`.

## Hugging Face Dataset Viewer

Patches are **multi-image samples** (bi-temporal RGB + up to three label maps). If the Hub scanned the modality folders directly, `T1` / `T2` / `GT_*` would be misread as **image-class subfolders** and the table would not group one patch per row.

This revision fixes that by:

1. **`train/metadata.csv` and `val/metadata.csv`** — CSV rows with path columns `t1_file_name`, `t2_file_name`, `gt_t1_file_name`, `gt_t2_file_name`, `gt_cd_file_name`. Each value is **relative to that split’s directory** (the folder containing `metadata.csv`), e.g. `T1/00001.png`, not `train/T1/00001.png`.
2. **`test/metadata.csv`** — same idea but only `t1_file_name` and `t2_file_name` (no public test labels).
3. **YAML `configs.data_files`** in this card (header above) — points each split at the right `metadata.csv`; `drop_labels: true` avoids treating `T1` / `T2` folder names as classification labels if the Hub scans the tree. Column names use the `*_file_name` pattern so features resolve to **Image** and the viewer can render thumbnails.

Regenerate the CSVs after you change `train.txt` / `val.txt` / `test.txt`:

```bash
# from the SCD-CropLand-HZ repo root
python scripts/generate_jl1_second_hub_metadata.py --root datasets/JL1_second
```

## Semantic classes (`GT_T1` / `GT_T2`)

| Index | Class |
| ----- | ----- |
| 0 | background |
| 1 | cropland |
| 2 | road |
| 3 | forest-grass |
| 4 | building |
| 5 | other |

`GT_CD`: `0` = no change, `255` = change.

**Change-type encoding (competition labels 0–8)** maps to the above land-cover pairs (cropland ↔ road, forest, building, other, etc.); index `0` indicates no cropland-related change.

## Usage

### Install

```bash
pip install huggingface_hub datasets # datasets optional, for integration
```

### Download with the Hub

```python
from pathlib import Path
from huggingface_hub import snapshot_download

root = Path(
snapshot_download(
repo_id="BiliSakura/JL1-CUP-2024-Second-Format",
repo_type="dataset",
)
)
# Example paths:
# root / "train" / "T1" / "00001.png"
# root / "val.txt" # read line-by-line for val split
```

You can also clone with Git LFS after installing [git-lfs](https://git-lfs.com):

```bash
git lfs install
git clone https://huggingface.co/datasets/BiliSakura/JL1-CUP-2024-Second-Format
```

## Limitations

- **Test split:** only `T1` and `T2` are released; there is **no** public `GT_*` for `test/`.
- **Basenames** are **not** comparable across `train`, `val`, and `test`.
- Distribution and commercial use may be restricted by **JL1 Mall / competition** policies—check the official pages above.

## Metadata file

Machine-readable config for this revision is mirrored in the YAML block at the top of this file (`dataset card` header).