huggingface / huggingface/datasets
Docs proposal: relabel left/right segmentation classes during horizontal flips
- Dominant language
- Python
- Stars
- 22k
- Forks
- 3.4k
- Avg merge
- 5d 7h
- Merged PRs (30d)
- 17
Description
### Feature request
Would you be open to a self-contained documentation recipe showing how to relabel directional semantic classes during a horizontal flip? It could be a separate section in [`docs/source/semantic_segmentation.mdx`](https://github.com/huggingface/datasets/blob/main/docs/source/semantic_segmentation.mdx) or a short standalone document, whichever fits the documentation structure better.
The existing guide demonstrates synchronized image and mask augmentation with Albumentations. I would preserve that example unchanged. The proposed recipe would use AlbumentationsX in its own installation and code path. Albumentations and AlbumentationsX would not appear in one runnable example.
The recipe would use [`mattmdjaga/human_parsing_dataset`](https://huggingface.co/datasets/mattmdjaga/human_parsing_dataset), whose mask schema contains three directional class pairs:
- `9 ↔ 10`: left/right shoe
- `12 ↔ 13`: left/right leg
- `14 ↔ 15`: left/right arm
The core [AlbumentationsX](https://github.com/albumentations-team/AlbumentationsX) configuration would be:
```python
import albumentations as A
transform = A.Compose(
[A.HorizontalFlip(p=0.5)],
semantic_mask_label_mappings={
"HorizontalFlip": {
9: 10,
10: 9,
12: 13,
13: 12,
14: 15,
15: 14,
}
},
)
```
The full example would apply this transform to the dataset's `image` and `mask` columns through `Dataset.set_transform`.
### Motivation
For human parsing masks, a horizontal flip changes both pixel positions and the semantic meaning of directional class IDs. Flipping the image and mask geometry while retaining `left-arm`, `right-arm`, and the other directional IDs creates inconsistent training labels.
Albumentations keeps the image and segmentation mask geometrically synchronized, but Albumentations 2.0.8 does not provide a built-in transform-aware API for changing semantic class IDs only when a particular random transform runs. Using Albumentations for this case requires custom conditional post-processing or a custom transform that shares the flip decision.
AlbumentationsX addresses this case through `semantic_mask_label_mappings`. The mapping is associated with `HorizontalFlip`, so the same `Compose` call flips the image and mask and performs the simultaneous ID swaps only on samples where `HorizontalFlip` runs.
The current Scene Parsing example uses `Resize` and `RandomBrightnessContrast`, so it does not encounter this failure mode. A focused recipe would document the general Datasets pattern for applying an on-the-fly transform that updates mask geometry and directional label meaning together.
I verified the six-ID mapping above with AlbumentationsX 2.4.3: the horizontal flip and simultaneous label swaps preserve the mask's shape and `uint8` dtype.
Two dependency details would be stated directly in the recipe:
- the current public AlbumentationsX package is AGPL-3.0-only;
- importing `albumentations` from AlbumentationsX requires an installed PyTorch runtime. PyTorch is intentionally not selected by the package metadata because users need the CPU, CUDA, or MPS build appropriate for their environment.
The selected Hub dataset card and its upstream repository do not currently declare a license. I would not assign a license to the dataset in the documentation and would proceed with this dataset only if the maintainers consider linking it acceptable.
### Your contribution
I can submit a focused documentation PR that:
- adds a self-contained recipe as either a separate section or a short standalone document, following the maintainers' preference;
- keeps the existing Albumentations and torchvision examples unchanged;
- verifies the example against dataset revision `db120bb5c18c146a8fbd2160f7575a288269fe7d` and explains the three left/right mappings;
- documents the PyTorch-first installation order and the AGPL-3.0-only package license;
- runs the example against a real dataset row and includes only the output image or documentation asset requested during review.
Would this scope be welcome?
Contributor guide
Research direction
Start in docs/source/semantic_segmentation.mdx by reading the existing synchronized image-and-mask augmentation example, then trace the Dataset.set_transform entry point. Verify the recipe against dataset revision db120bb5c18c146a8fbd2160f7575a288269fe7d and a real row; done means the directional mappings, installation order, package license, and dataset caveat are documented without changing existing examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, pytorch
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 70/100