deploy: 63a85616f5fc427cf1e1e7b425293131f2fce2b8

README.md

@@ -9,4 +9,181 @@ app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Layout Overlap
+
+## Description
+
+The Layout Overlap metric quantifies how much layout elements overlap with each other. This metric implements three different overlap calculation methods from influential layout generation research papers, providing comprehensive evaluation of element spacing and collision issues.
+
+## What It Measures
+
+This metric computes overlap scores that measure:
+
+- **Element collisions**: How much elements physically overlap in the layout
+- **Spatial efficiency**: Whether elements are placed with appropriate spacing
+- **Layout density**: How tightly elements are packed (which may cause overlaps)
+
+Lower overlap scores generally indicate better layouts with minimal element collisions.
+
+## Metric Details
+
+Implements three overlap metrics from different research works:
+
+1. **LayoutGAN** (Li et al., ICLR 2019): Sum of intersection areas for all element pairs
+2. **LayoutGAN++**: Normalized version of LayoutGAN overlap per element
+3. **AC-LayoutGAN** (Li et al., TVCG 2021): Ratio-based overlap calculation
+
+Each variant has slightly different calculation methods and sensitivities to overlap patterns.
+
+## Usage
+
+### Installation
+
+```bash
+pip install evaluate
+```
+
+### Basic Example
+
+```python
+import evaluate
+import numpy as np
+
+# Load the metric
+metric = evaluate.load("creative-graphic-design/layout-overlap")
+
+# Single layout processing
+model_max_length, num_coordinates = 25, 4
+bbox = np.random.rand(model_max_length, num_coordinates)
+mask = np.random.choice(a=[True, False], size=(model_max_length,))
+metric.add(bbox=bbox, mask=mask)
+print(metric.compute())
+```
+
+### Batch Processing Example
+
+```python
+import evaluate
+import numpy as np
+
+# Load the metric
+metric = evaluate.load("creative-graphic-design/layout-overlap")
+
+# Batch processing
+batch_size, model_max_length, num_coordinates = 512, 25, 4
+batch_bbox = np.random.rand(batch_size, model_max_length, num_coordinates)
+batch_mask = np.random.choice(a=[True, False], size=(batch_size, model_max_length))
+metric.add_batch(bbox=batch_bbox, mask=batch_mask)
+print(metric.compute())
+```
+
+## Parameters
+
+### Initialization Parameters
+
+This metric does not require any initialization parameters.
+
+### Computation Parameters
+
+- **bbox** (`list` of `lists` of `float`): Bounding boxes in xywh (center-x, center-y, width, height) format
+- **mask** (`list` of `lists` of `bool`): Boolean mask indicating valid elements (True) vs padding (False)
+
+**Note**: The mask parameter is essential for handling variable-length layouts where some positions are padding.
+
+## Returns
+
+Returns a dictionary containing three overlap scores:
+
+- **overlap-LayoutGAN** (`array`): Total intersection area across all element pairs (per layout)
+- **overlap-LayoutGAN++** (`array`): Normalized overlap per valid element (per layout)
+- **overlap-ACLayoutGAN** (`array`): Ratio-based overlap score (per layout)
+
+Each score is an array with one value per layout in the batch.
+
+## Interpretation
+
+### General Interpretation
+
+- **Lower is better** for all three metrics
+- **Value of 0**: No overlapping elements (ideal for most layout types)
+- **Higher values**: More element overlap, potential layout quality issues
+
+### Metric-Specific Notes
+
+**LayoutGAN**:
+
+- Absolute sum of intersection areas
+- Sensitive to both number of overlaps and overlap sizes
+- Grows with layout density
+
+**LayoutGAN++**:
+
+- Normalized by number of valid elements
+- Better for comparing layouts with different element counts
+- Range depends on element sizes and density
+
+**AC-LayoutGAN**:
+
+- Uses area ratios for overlap calculation
+- Accounts for element sizes in overlap measurement
+- More robust to element size variations
+
+### Use Cases
+
+- **Layout generation evaluation**: Assess whether generated layouts have acceptable spacing
+- **Collision detection**: Identify layouts with problematic element overlaps
+- **Design quality**: Compare overlap patterns between different generation methods
+- **Multi-metric evaluation**: Use alongside alignment and validity metrics
+
+### Key Insights
+
+- **Some overlap may be acceptable** depending on design type (e.g., intentional layering)
+- **Context matters**: Poster designs may tolerate more overlap than UI layouts
+- **Trade-offs**: Denser layouts naturally have higher overlap potential
+- **Compare variants**: Different metrics may highlight different overlap patterns
+
+## Citations
+
+```bibtex
+@inproceedings{li2018layoutgan,
+  title={LayoutGAN: Generating Graphic Layouts with Wireframe Discriminators},
+  author={Li, Jianan and Yang, Jimei and Hertzmann, Aaron and Zhang, Jianming and Xu, Tingfa},
+  booktitle={International Conference on Learning Representations},
+  year={2019}
+}
+
+@article{li2020attribute,
+  title={Attribute-conditioned layout gan for automatic graphic design},
+  author={Li, Jianan and Yang, Jimei and Zhang, Jianming and Liu, Chang and Wang, Christina and Xu, Tingfa},
+  journal={IEEE Transactions on Visualization and Computer Graphics},
+  volume={27},
+  number={10},
+  pages={4039--4048},
+  year={2020},
+  publisher={IEEE}
+}
+
+@inproceedings{kikuchi2021constrained,
+  title={Constrained graphic layout generation via latent optimization},
+  author={Kikuchi, Kotaro and Simo-Serra, Edgar and Otani, Mayu and Yamaguchi, Kota},
+  booktitle={Proceedings of the 29th ACM International Conference on Multimedia},
+  pages={88--96},
+  year={2021}
+}
+```
+
+## References
+
+- **Paper**: [LayoutGAN (Li et al., ICLR 2019)](https://arxiv.org/abs/1901.06767)
+- **Paper**: [Attribute-Conditioned Layout GAN (Li et al., TVCG 2021)](https://arxiv.org/abs/2009.05284)
+- **Paper**: [Constrained Graphic Layout Generation (Kikuchi et al., ACM MM 2021)](https://arxiv.org/abs/2108.00871)
+- **Reference Implementation (CGL)**: [const_layout metric](https://github.com/ktrk115/const_layout/blob/master/metric.py#L138-L164)
+- **Reference Implementation (layout-dm)**: [layout-dm metric](https://github.com/CyberAgentAILab/layout-dm/blob/main/src/trainer/trainer/helpers/metric.py#L150-L203)
+- **Hugging Face Space**: [creative-graphic-design/layout-overlap](https://huggingface.co/spaces/creative-graphic-design/layout-overlap)
+
+## Related Metrics
+
+- [Layout Average IoU](../layout_average_iou/): Measures overlap using IoU metric
+- [Layout Overlay](../layout_overlay/): Specialized overlap metric excluding underlay elements
+- [Layout Alignment](../layout_alignment/): Evaluates element alignment patterns
+- [Layout Validity](../layout_validity/): Checks basic layout validity constraints

layout-overlap.py

@@ -4,6 +4,7 @@ import datasets as ds
 import evaluate
 import numpy as np
 import numpy.typing as npt
+from evaluate.utils.file_utils import add_start_docstrings
 
 _DESCRIPTION = """\
 Some overlap metrics that are different to each other in previous works.
@@ -63,6 +64,7 @@ class A(TypedDict):
     ai: npt.NDArray[np.float64]
 
 
+@add_start_docstrings(_DESCRIPTION, _KWARGS_DESCRIPTION)
 class LayoutOverlap(evaluate.Metric):
     def _info(self) -> evaluate.EvaluationModuleInfo:
         return evaluate.MetricInfo(

requirements.txt

@@ -1,89 +1,134 @@
-aiofiles==23.2.1 ; python_version >= "3.9" and python_version < "4.0"
-aiohttp==3.9.3 ; python_version >= "3.9" and python_version < "4.0"
-aiosignal==1.3.1 ; python_version >= "3.9" and python_version < "4.0"
-altair==5.2.0 ; python_version >= "3.9" and python_version < "4.0"
-annotated-types==0.6.0 ; python_version >= "3.9" and python_version < "4.0"
-anyio==4.2.0 ; python_version >= "3.9" and python_version < "4.0"
-arrow==1.3.0 ; python_version >= "3.9" and python_version < "4.0"
-async-timeout==4.0.3 ; python_version >= "3.9" and python_version < "3.11"
-attrs==23.2.0 ; python_version >= "3.9" and python_version < "4.0"
-binaryornot==0.4.4 ; python_version >= "3.9" and python_version < "4.0"
-certifi==2024.2.2 ; python_version >= "3.9" and python_version < "4.0"
-chardet==5.2.0 ; python_version >= "3.9" and python_version < "4.0"
-charset-normalizer==3.3.2 ; python_version >= "3.9" and python_version < "4.0"
-click==8.1.7 ; python_version >= "3.9" and python_version < "4.0"
-colorama==0.4.6 ; python_version >= "3.9" and python_version < "4.0"
-contourpy==1.2.0 ; python_version >= "3.9" and python_version < "4.0"
-cookiecutter==2.5.0 ; python_version >= "3.9" and python_version < "4.0"
-cycler==0.12.1 ; python_version >= "3.9" and python_version < "4.0"
-datasets==2.17.0 ; python_version >= "3.9" and python_version < "4.0"
-dill==0.3.8 ; python_version >= "3.9" and python_version < "4.0"
-evaluate[template]==0.4.1 ; python_version >= "3.9" and python_version < "4.0"
-exceptiongroup==1.2.0 ; python_version >= "3.9" and python_version < "3.11"
-fastapi==0.109.2 ; python_version >= "3.9" and python_version < "4.0"
-ffmpy==0.3.1 ; python_version >= "3.9" and python_version < "4.0"
-filelock==3.13.1 ; python_version >= "3.9" and python_version < "4.0"
-fonttools==4.48.1 ; python_version >= "3.9" and python_version < "4.0"
-frozenlist==1.4.1 ; python_version >= "3.9" and python_version < "4.0"
-fsspec==2023.10.0 ; python_version >= "3.9" and python_version < "4.0"
-fsspec[http]==2023.10.0 ; python_version >= "3.9" and python_version < "4.0"
-gradio-client==0.10.0 ; python_version >= "3.9" and python_version < "4.0"
-gradio==4.18.0 ; python_version >= "3.9" and python_version < "4.0"
-h11==0.14.0 ; python_version >= "3.9" and python_version < "4.0"
-httpcore==1.0.2 ; python_version >= "3.9" and python_version < "4.0"
-httpx==0.26.0 ; python_version >= "3.9" and python_version < "4.0"
-huggingface-hub==0.20.3 ; python_version >= "3.9" and python_version < "4.0"
-idna==3.6 ; python_version >= "3.9" and python_version < "4.0"
-importlib-resources==6.1.1 ; python_version >= "3.9" and python_version < "4.0"
-jinja2==3.1.3 ; python_version >= "3.9" and python_version < "4.0"
-jsonschema-specifications==2023.12.1 ; python_version >= "3.9" and python_version < "4.0"
-jsonschema==4.21.1 ; python_version >= "3.9" and python_version < "4.0"
-kiwisolver==1.4.5 ; python_version >= "3.9" and python_version < "4.0"
-markdown-it-py==3.0.0 ; python_version >= "3.9" and python_version < "4.0"
-markupsafe==2.1.5 ; python_version >= "3.9" and python_version < "4.0"
-matplotlib==3.8.2 ; python_version >= "3.9" and python_version < "4.0"
-mdurl==0.1.2 ; python_version >= "3.9" and python_version < "4.0"
-multidict==6.0.5 ; python_version >= "3.9" and python_version < "4.0"
-multiprocess==0.70.16 ; python_version >= "3.9" and python_version < "4.0"
-numpy==1.26.4 ; python_version >= "3.9" and python_version < "4.0"
-orjson==3.9.13 ; python_version >= "3.9" and python_version < "4.0"
-packaging==23.2 ; python_version >= "3.9" and python_version < "4.0"
-pandas==2.2.0 ; python_version >= "3.9" and python_version < "4.0"
-pillow==10.2.0 ; python_version >= "3.9" and python_version < "4.0"
-pyarrow-hotfix==0.6 ; python_version >= "3.9" and python_version < "4.0"
-pyarrow==15.0.0 ; python_version >= "3.9" and python_version < "4.0"
-pydantic-core==2.16.2 ; python_version >= "3.9" and python_version < "4.0"
-pydantic==2.6.1 ; python_version >= "3.9" and python_version < "4.0"
-pydub==0.25.1 ; python_version >= "3.9" and python_version < "4.0"
-pygments==2.17.2 ; python_version >= "3.9" and python_version < "4.0"
-pyparsing==3.1.1 ; python_version >= "3.9" and python_version < "4.0"
-python-dateutil==2.8.2 ; python_version >= "3.9" and python_version < "4.0"
-python-multipart==0.0.9 ; python_version >= "3.9" and python_version < "4.0"
-python-slugify==8.0.4 ; python_version >= "3.9" and python_version < "4.0"
-pytz==2024.1 ; python_version >= "3.9" and python_version < "4.0"
-pyyaml==6.0.1 ; python_version >= "3.9" and python_version < "4.0"
-referencing==0.33.0 ; python_version >= "3.9" and python_version < "4.0"
-requests==2.31.0 ; python_version >= "3.9" and python_version < "4.0"
-responses==0.18.0 ; python_version >= "3.9" and python_version < "4.0"
-rich==13.7.0 ; python_version >= "3.9" and python_version < "4.0"
-rpds-py==0.17.1 ; python_version >= "3.9" and python_version < "4.0"
-ruff==0.2.1 ; python_version >= "3.9" and python_version < "4.0"
-semantic-version==2.10.0 ; python_version >= "3.9" and python_version < "4.0"
-shellingham==1.5.4 ; python_version >= "3.9" and python_version < "4.0"
-six==1.16.0 ; python_version >= "3.9" and python_version < "4.0"
-sniffio==1.3.0 ; python_version >= "3.9" and python_version < "4.0"
-starlette==0.36.3 ; python_version >= "3.9" and python_version < "4.0"
-text-unidecode==1.3 ; python_version >= "3.9" and python_version < "4.0"
-tomlkit==0.12.0 ; python_version >= "3.9" and python_version < "4.0"
-toolz==0.12.1 ; python_version >= "3.9" and python_version < "4.0"
-tqdm==4.66.2 ; python_version >= "3.9" and python_version < "4.0"
-typer[all]==0.9.0 ; python_version >= "3.9" and python_version < "4.0"
-types-python-dateutil==2.8.19.20240106 ; python_version >= "3.9" and python_version < "4.0"
-typing-extensions==4.9.0 ; python_version >= "3.9" and python_version < "4.0"
-tzdata==2024.1 ; python_version >= "3.9" and python_version < "4.0"
-urllib3==2.2.0 ; python_version >= "3.9" and python_version < "4.0"
-uvicorn==0.27.1 ; python_version >= "3.9" and python_version < "4.0"
-websockets==11.0.3 ; python_version >= "3.9" and python_version < "4.0"
-xxhash==3.4.1 ; python_version >= "3.9" and python_version < "4.0"
-yarl==1.9.4 ; python_version >= "3.9" and python_version < "4.0"
-zipp==3.17.0 ; python_version >= "3.9" and python_version < "3.10"
+# This file was autogenerated by uv via the following command:
+#    uv export --package layout_overlap --no-dev --no-hashes --format requirements-txt
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.13.2
+    # via fsspec
+aiosignal==1.4.0
+    # via aiohttp
+anyio==4.12.0
+    # via httpx
+attrs==25.4.0
+    # via aiohttp
+certifi==2025.11.12
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+charset-normalizer==3.4.4
+    # via requests
+click==8.3.1
+    # via typer-slim
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   click
+    #   tqdm
+datasets==4.4.2
+    # via evaluate
+dill==0.4.0
+    # via
+    #   datasets
+    #   evaluate
+    #   multiprocess
+evaluate==0.4.6
+    # via layout-overlap
+filelock==3.20.1
+    # via
+    #   datasets
+    #   huggingface-hub
+frozenlist==1.8.0
+    # via
+    #   aiohttp
+    #   aiosignal
+fsspec==2025.10.0
+    # via
+    #   datasets
+    #   evaluate
+    #   huggingface-hub
+h11==0.16.0
+    # via httpcore
+hf-xet==1.2.0 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via
+    #   datasets
+    #   huggingface-hub
+huggingface-hub==1.2.3
+    # via
+    #   datasets
+    #   evaluate
+idna==3.11
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+    #   yarl
+multidict==6.7.0
+    # via
+    #   aiohttp
+    #   yarl
+multiprocess==0.70.18
+    # via
+    #   datasets
+    #   evaluate
+numpy==2.2.6
+    # via
+    #   datasets
+    #   evaluate
+    #   pandas
+packaging==25.0
+    # via
+    #   datasets
+    #   evaluate
+    #   huggingface-hub
+pandas==2.3.3
+    # via
+    #   datasets
+    #   evaluate
+propcache==0.4.1
+    # via
+    #   aiohttp
+    #   yarl
+pyarrow==22.0.0
+    # via datasets
+python-dateutil==2.9.0.post0
+    # via pandas
+pytz==2025.2
+    # via pandas
+pyyaml==6.0.3
+    # via
+    #   datasets
+    #   huggingface-hub
+requests==2.32.5
+    # via
+    #   datasets
+    #   evaluate
+shellingham==1.5.4
+    # via huggingface-hub
+six==1.17.0
+    # via python-dateutil
+tqdm==4.67.1
+    # via
+    #   datasets
+    #   evaluate
+    #   huggingface-hub
+typer-slim==0.21.0
+    # via huggingface-hub
+typing-extensions==4.15.0
+    # via
+    #   aiosignal
+    #   anyio
+    #   huggingface-hub
+    #   typer-slim
+tzdata==2025.3
+    # via pandas
+urllib3==2.6.2
+    # via requests
+xxhash==3.6.0
+    # via
+    #   datasets
+    #   evaluate
+yarl==1.22.0
+    # via aiohttp