deploy: 63a85616f5fc427cf1e1e7b425293131f2fce2b8

README.md

@@ -8,4 +8,164 @@ sdk_version: 4.36.1
 app_file: app.py
 pinned: false
 ---
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# Layout Unreadability
+
+## Description
+
+The Layout Unreadability metric evaluates whether text elements are placed on visually complex or non-flat background regions that could impair readability. This metric computes the non-flatness (gradient intensity) of regions where text is positioned, helping assess whether text placement respects readability principles in content-aware layout design.
+
+## What It Measures
+
+This metric computes:
+
+- **Background complexity under text**: Gradient intensity in regions occupied by text elements
+- **Text readability risk**: Whether text is placed on busy or complex backgrounds
+- **Content-awareness**: How well the layout avoids placing text on unsuitable regions
+
+Lower scores indicate better text placement on flat, readable backgrounds.
+
+## Metric Details
+
+- Uses Sobel gradient operators to detect edges and texture in background canvas
+- Computes gradient magnitude (non-flatness) in regions covered by text elements
+- Excludes underlay/decoration elements from background canvas analysis
+- From PosterLayout (Hsu et al., CVPR 2023) and CGL-GAN methodology
+- Lower gradient scores mean text is on flatter, more readable backgrounds
+
+## Usage
+
+### Installation
+
+```bash
+pip install evaluate opencv-python
+```
+
+### Basic Example
+
+```python
+import evaluate
+import numpy as np
+
+# Load the metric with canvas dimensions
+metric = evaluate.load(
+    "creative-graphic-design/layout-unreadability",
+    canvas_width=360,
+    canvas_height=504,
+    text_label_index=1,
+    decoration_label_index=3
+)
+
+# Prepare data
+predictions = np.random.rand(1, 25, 4)  # normalized ltrb coordinates
+gold_labels = np.random.randint(0, 4, size=(1, 25))  # class labels
+# Paths to canvas background images
+image_canvases = ["path/to/canvas_image.jpg"]
+
+score = metric.compute(
+    predictions=predictions,
+    gold_labels=gold_labels,
+    image_canvases=image_canvases
+)
+print(score)
+```
+
+### Batch Processing Example
+
+```python
+import evaluate
+
+# Load the metric
+metric = evaluate.load(
+    "creative-graphic-design/layout-unreadability",
+    canvas_width=360,
+    canvas_height=504,
+    text_label_index=1,
+    decoration_label_index=3
+)
+
+# Batch processing
+batch_size = 128
+predictions = np.random.rand(batch_size, 25, 4)
+gold_labels = np.random.randint(0, 4, size=(batch_size, 25))
+image_canvases = [f"path/to/canvas_{i}.jpg" for i in range(batch_size)]
+
+score = metric.compute(
+    predictions=predictions,
+    gold_labels=gold_labels,
+    image_canvases=image_canvases
+)
+print(score)
+```
+
+## Parameters
+
+### Initialization Parameters
+
+- **canvas_width** (`int`, required): Width of the canvas in pixels
+- **canvas_height** (`int`, required): Height of the canvas in pixels
+- **text_label_index** (`int`, optional, default=1): Class index for text elements
+- **decoration_label_index** (`int`, optional, default=3): Class index for underlay/decoration elements to mask out
+
+### Computation Parameters
+
+- **predictions** (`list` of `lists` of `float`): Normalized bounding boxes in ltrb format (0.0 to 1.0)
+- **gold_labels** (`list` of `lists` of `int`): Class labels for each element (0 = padding)
+- **image_canvases** (`list` of `str`): File paths to canvas background images
+
+**Note**:
+
+- Canvas images should show the background content (photos, graphics) where layout will be placed
+- Underlay/decoration elements are masked out before computing gradients
+- Only text elements (text_label_index) are evaluated for readability
+
+## Returns
+
+Returns a `float` value representing the average gradient intensity under text elements (range: 0.0 to 1.0).
+
+## Interpretation
+
+- **Lower is better** (range: 0.0 to 1.0)
+- **Value ~0.0**: Text placed on flat, uniform backgrounds (ideal for readability)
+- **Value 0.0-0.2**: Good text placement on relatively flat regions
+- **Value 0.2-0.4**: Moderate background complexity, may affect readability
+- **Value 0.4-0.6**: High background complexity, readability concerns
+- **Value > 0.6**: Very complex backgrounds under text (poor placement)
+
+### Use Cases
+
+- **Content-aware poster generation**: Ensure text is readable on background imagery
+- **Advertisement layout**: Place call-to-action text on suitable backgrounds
+- **Presentation slides**: Validate text visibility on photo backgrounds
+- **Magazine/flyer design**: Assess text-background contrast and readability
+
+### Key Insights
+
+- **Readability principle**: Text should be on flat or low-detail backgrounds
+- **Design solutions**: Use underlay/decoration elements to create readable regions
+- **Trade-off**: Sometimes text must go on complex backgrounds (consider semi-transparent overlays)
+- **Context matters**: Title text may tolerate more complexity than body text
+
+## Citations
+
+```bibtex
+@inproceedings{hsu2023posterlayout,
+  title={Posterlayout: A new benchmark and approach for content-aware visual-textual presentation layout},
+  author={Hsu, Hsiao Yuan and He, Xiangteng and Peng, Yuxin and Kong, Hao and Zhang, Qing},
+  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
+  pages={6018--6026},
+  year={2023}
+}
+```
+
+## References
+
+- **Paper**: [PosterLayout (Hsu et al., CVPR 2023)](https://arxiv.org/abs/2303.15937)
+- **Reference Implementation**: [PosterLayout eval.py](https://github.com/PKU-ICST-MIPL/PosterLayout-CVPR2023/blob/main/eval.py#L144-L171)
+- **Related**: CGL-GAN text readability evaluation
+
+## Related Metrics
+
+- [Layout Occlusion](../layout_occlusion/): Evaluates coverage of salient regions
+- [Layout Utility](../layout_utility/): Measures utilization of suitable space
+- [Layout Underlay Effectiveness](../layout_underlay_effectiveness/): Evaluates underlay placement

layout-unreadability.py

@@ -6,6 +6,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
 from PIL import Image
 from PIL.Image import Image as PilImage
 
@@ -30,6 +31,7 @@ _CITATION = """\
 ReqType = Literal["pil2cv", "cv2pil"]
 
 
+@add_start_docstrings(_DESCRIPTION, _KWARGS_DESCRIPTION)
 class LayoutUnreadability(evaluate.Metric):
     def __init__(
         self,
@@ -72,7 +74,7 @@ class LayoutUnreadability(evaluate.Metric):
         if req == "pil2cv":
             assert isinstance(img, PilImage)
             color_code = color_code or cv2.COLOR_RGB2BGR
-            return cv2.cvtColor(np.asarray(img), color_code)
+            return cv2.cvtColor(np.asarray(img), color_code)  # type: ignore
         elif req == "cv2pil":
             assert isinstance(img, np.ndarray)
             color_code = color_code or cv2.COLOR_BGR2RGB
@@ -102,9 +104,9 @@ class LayoutUnreadability(evaluate.Metric):
             filepath = filepath[0]
 
         canvas_pil = Image.open(filepath)  # type: ignore
-        canvas_pil = canvas_pil.convert("RGB")
+        canvas_pil = canvas_pil.convert("RGB")  # type: ignore
         if canvas_pil.size != (self.canvas_width, self.canvas_height):
-            canvas_pil = canvas_pil.resize((self.canvas_width, self.canvas_height))
+            canvas_pil = canvas_pil.resize((self.canvas_width, self.canvas_height))  # type: ignore
 
         canvas_pil = self.img_to_g_xy(canvas_pil)
         assert isinstance(canvas_pil, PilImage)

requirements.txt

@@ -1,90 +1,139 @@
-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"
-opencv-python==4.10.0.84 ; 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_unreadability --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-unreadability
+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
+    #   opencv-python
+    #   pandas
+opencv-python==4.12.0.88
+    # via layout-unreadability
+packaging==25.0
+    # via
+    #   datasets
+    #   evaluate
+    #   huggingface-hub
+pandas==2.3.3
+    # via
+    #   datasets
+    #   evaluate
+pillow==12.0.0
+    # via layout-unreadability
+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