Skip to content

posgen

package license python runtime status docs

posgen provides shared utilities for poster-generation and content-aware placement packages. Its current public surface is intentionally small: DatasetName identifies supported poster/content datasets, PositionContent carries position tensors plus masks, and label helpers normalize dataset-specific class names.

Use posgen for poster or content-aware placement concerns such as Crello-style element categories and position-content summaries. Use laygen for general layout-generation schemas, bbox conversion, scheduler adapters, and model-card helpers. The package is still a skeleton until more poster models need shared behavior, so model-specific saliency, retrieval, ranking, and rendering logic should stay in model packages.

Install

Install directly from this repository.

pip install "posgen @ git+https://github.com/creative-graphic-design/design-generators.git#subdirectory=lib/posgen"

For local development in a checkout, use uv workspace commands.

uv sync --package posgen

Install from outside the workspace with pip's direct-reference subdirectory form:

pip install "posgen @ git+https://github.com/creative-graphic-design/design-generators.git#subdirectory=lib/posgen"

Current API

uv run --package posgen python

import torch
from posgen.common import (
    PositionContent,
    assert_position_content_schema,
    labels_for_dataset,
    normalize_label,
    render_position_summary,
)

content = PositionContent(
    positions=torch.zeros(1, 2, 2),
    mask=torch.tensor([[True, False]]),
)
assert_position_content_schema(content)
print(normalize_label("Anchor-Point"))
print(render_position_summary(content))
print(labels_for_dataset("crello"))

Example output:

anchor_point
1 active positions
('coloredBackground', 'imageElement', 'maskElement', 'svgElement', 'textElement')

Scope

  • Keep generic position content containers, label normalization, schema tests, and lightweight summaries here.
  • Use posgen for poster/content-aware placement concerns.
  • Keep saliency, retrieval, ranking, and dataset-specific placement logic in model packages until there is proven reuse.
  • posgen is a root project dependency with eight declaring consumers.

Dependency Direction

posgen may depend on laygen when poster/content-aware placement packages need shared layout primitives. laygen must not depend on posgen.

graph LR
    laygen["laygen"] --> model_packages["model packages"]
    laygen -. "optional; currently unused" .-> posgen["posgen"]
    posgen --> poster_models["poster or content-aware model packages"]

The arrows point from a library to the packages that import it.

Growth Rule

Add to posgen only when a second package needs the same behavior, or when a first consumer needs a stable public contract before other poster/content-aware placement packages arrive.

Pointers

API Reference

Shared position-generation utilities.

common

Common building blocks for future position-generation packages.

PositionContent dataclass

Minimal tensor content schema shared by position generators.

Source code in lib/posgen/src/posgen/common/content.py 
11
12
13
14
15
16
@dataclass
class PositionContent:
    """Minimal tensor content schema shared by position generators."""

    positions: Shaped[torch.Tensor, "..."]
    mask: Shaped[torch.Tensor, "..."]

DatasetName

Bases: StrEnum

Canonical poster/content dataset names supported by posgen.

Source code in lib/posgen/src/posgen/common/labels.py 
 9
10
11
12
13
14
15
16
17
18
class DatasetName(StrEnum):
    """Canonical poster/content dataset names supported by posgen."""

    cgl = "cgl"
    cgl_v2 = "cgl_v2"
    pku_posterlayout = "pku_posterlayout"
    posterlayout = "posterlayout"
    smarttext_demo = "smarttext-demo"
    crello = "crello"
    ad_banner = "ad_banner"

id2label_for_dataset 

id2label_for_dataset(
    dataset_name: DatasetName | str,
) -> dict[int, str]

Return an integer-id to label-name mapping for a posgen dataset.

Source code in lib/posgen/src/posgen/common/labels.py 
129
130
131
def id2label_for_dataset(dataset_name: DatasetName | str) -> dict[int, str]:
    """Return an integer-id to label-name mapping for a posgen dataset."""
    return dict(enumerate(labels_for_dataset(dataset_name)))

label2id_for_dataset 

label2id_for_dataset(
    dataset_name: DatasetName | str,
) -> dict[str, int]

Return a label-name to integer-id mapping for a posgen dataset.

Source code in lib/posgen/src/posgen/common/labels.py 
134
135
136
def label2id_for_dataset(dataset_name: DatasetName | str) -> dict[str, int]:
    """Return a label-name to integer-id mapping for a posgen dataset."""
    return {label: i for i, label in id2label_for_dataset(dataset_name).items()}

labels_for_dataset 

labels_for_dataset(
    dataset_name: DatasetName | str,
) -> tuple[str, ...]

Return the ordered label vocabulary for a posgen dataset.

Source code in lib/posgen/src/posgen/common/labels.py 
124
125
126
def labels_for_dataset(dataset_name: DatasetName | str) -> tuple[str, ...]:
    """Return the ordered label vocabulary for a posgen dataset."""
    return tuple(str(label) for label in _LABELS[normalize_dataset_name(dataset_name)])

normalize_dataset_name 

normalize_dataset_name(
    dataset_name: DatasetName | str,
) -> DatasetName

Normalize poster/content dataset aliases to canonical names.

Parameters:

Name Type Description Default
dataset_name DatasetName | str

Dataset enum or public/release alias.

 required

Returns:

Type Description
DatasetName

Canonical posgen dataset enum.

Raises:

Type Description
ValueError

If the dataset name is unknown.
Source code in lib/posgen/src/posgen/common/labels.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def normalize_dataset_name(dataset_name: DatasetName | str) -> DatasetName:
    """Normalize poster/content dataset aliases to canonical names.

    Args:
        dataset_name: Dataset enum or public/release alias.

    Returns:
        Canonical posgen dataset enum.

    Raises:
        ValueError: If the dataset name is unknown.
    """
    if isinstance(dataset_name, DatasetName):
        return dataset_name
    key = normalize_label(dataset_name)
    try:
        return _ALIASES[key]
    except KeyError as exc:
        raise ValueError(f"Unknown posgen dataset_name: {dataset_name}") from exc

normalize_label 

normalize_label(label: str) -> str

Normalize a position-generation label key.

Source code in lib/posgen/src/posgen/common/labels.py 
 98
 99
100
def normalize_label(label: str) -> str:
    """Normalize a position-generation label key."""
    return label.strip().lower().replace("-", "_")

assert_position_content_schema 

assert_position_content_schema(
    content: PositionContent,
) -> None

Check the minimal position-generation content schema.

Source code in lib/posgen/src/posgen/common/testing.py 
 8
 9
10
11
12
13
def assert_position_content_schema(content: PositionContent) -> None:
    """Check the minimal position-generation content schema."""
    assert content.positions.shape[:-1] == content.mask.shape
    assert content.positions.shape[-1] == 2
    assert content.positions.dtype.is_floating_point
    assert content.mask.dtype == torch.bool

render_position_summary 

render_position_summary(content: PositionContent) -> str

Return a compact text summary for a position-generation sample.

Source code in lib/posgen/src/posgen/common/visualization.py 
6
7
8
def render_position_summary(content: PositionContent) -> str:
    """Return a compact text summary for a position-generation sample."""
    return f"{int(content.mask.sum().item())} active positions"

content

Content containers reserved for future position-generation models.

PositionContent dataclass

Minimal tensor content schema shared by position generators.

Source code in lib/posgen/src/posgen/common/content.py 
11
12
13
14
15
16
@dataclass
class PositionContent:
    """Minimal tensor content schema shared by position generators."""

    positions: Shaped[torch.Tensor, "..."]
    mask: Shaped[torch.Tensor, "..."]

labels

Dataset label registries shared by position-generation packages.

DatasetName

Bases: StrEnum

Canonical poster/content dataset names supported by posgen.

Source code in lib/posgen/src/posgen/common/labels.py 
 9
10
11
12
13
14
15
16
17
18
class DatasetName(StrEnum):
    """Canonical poster/content dataset names supported by posgen."""

    cgl = "cgl"
    cgl_v2 = "cgl_v2"
    pku_posterlayout = "pku_posterlayout"
    posterlayout = "posterlayout"
    smarttext_demo = "smarttext-demo"
    crello = "crello"
    ad_banner = "ad_banner"

CGLLabel

Bases: StrEnum

CGL label names in dataset id order.

Source code in lib/posgen/src/posgen/common/labels.py 
21
22
23
24
25
26
27
28
class CGLLabel(StrEnum):
    """CGL label names in dataset id order."""

    logo = "logo"
    text = "text"
    underlay = "underlay"
    embellishment = "embellishment"
    highlighted_text = "highlighted text"

PKUPosterLayoutLabel

Bases: StrEnum

PKU-PosterLayout label names in dataset id order.

Source code in lib/posgen/src/posgen/common/labels.py 
31
32
33
34
35
36
37
class PKUPosterLayoutLabel(StrEnum):
    """PKU-PosterLayout label names in dataset id order."""

    text = "text"
    logo = "logo"
    underlay = "underlay"
    invalid = "INVALID"

CrelloLabel

Bases: StrEnum

Crello label names in dataset id order.

Source code in lib/posgen/src/posgen/common/labels.py 
40
41
42
43
44
45
46
47
class CrelloLabel(StrEnum):
    """Crello label names in dataset id order."""

    colored_background = "coloredBackground"
    image_element = "imageElement"
    mask_element = "maskElement"
    svg_element = "svgElement"
    text_element = "textElement"

AdBannerLabel

Bases: StrEnum

Ad Banner label names in LayoutDETR dataset id order.

Source code in lib/posgen/src/posgen/common/labels.py 
50
51
52
53
54
55
56
57
58
59
60
class AdBannerLabel(StrEnum):
    """Ad Banner label names in LayoutDETR dataset id order."""

    header = "header"
    pre_header = "pre-header"
    post_header = "post-header"
    body_text = "body text"
    disclaimer_footnote = "disclaimer / footnote"
    button = "button"
    callout = "callout"
    logo = "logo"

normalize_label 

normalize_label(label: str) -> str

Normalize a position-generation label key.

Source code in lib/posgen/src/posgen/common/labels.py 
 98
 99
100
def normalize_label(label: str) -> str:
    """Normalize a position-generation label key."""
    return label.strip().lower().replace("-", "_")

normalize_dataset_name 

normalize_dataset_name(
    dataset_name: DatasetName | str,
) -> DatasetName

Normalize poster/content dataset aliases to canonical names.

Parameters:

Name Type Description Default
dataset_name DatasetName | str

Dataset enum or public/release alias.

 required

Returns:

Type Description
DatasetName

Canonical posgen dataset enum.

Raises:

Type Description
ValueError

If the dataset name is unknown.
Source code in lib/posgen/src/posgen/common/labels.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def normalize_dataset_name(dataset_name: DatasetName | str) -> DatasetName:
    """Normalize poster/content dataset aliases to canonical names.

    Args:
        dataset_name: Dataset enum or public/release alias.

    Returns:
        Canonical posgen dataset enum.

    Raises:
        ValueError: If the dataset name is unknown.
    """
    if isinstance(dataset_name, DatasetName):
        return dataset_name
    key = normalize_label(dataset_name)
    try:
        return _ALIASES[key]
    except KeyError as exc:
        raise ValueError(f"Unknown posgen dataset_name: {dataset_name}") from exc

labels_for_dataset 

labels_for_dataset(
    dataset_name: DatasetName | str,
) -> tuple[str, ...]

Return the ordered label vocabulary for a posgen dataset.

Source code in lib/posgen/src/posgen/common/labels.py 
124
125
126
def labels_for_dataset(dataset_name: DatasetName | str) -> tuple[str, ...]:
    """Return the ordered label vocabulary for a posgen dataset."""
    return tuple(str(label) for label in _LABELS[normalize_dataset_name(dataset_name)])

id2label_for_dataset 

id2label_for_dataset(
    dataset_name: DatasetName | str,
) -> dict[int, str]

Return an integer-id to label-name mapping for a posgen dataset.

Source code in lib/posgen/src/posgen/common/labels.py 
129
130
131
def id2label_for_dataset(dataset_name: DatasetName | str) -> dict[int, str]:
    """Return an integer-id to label-name mapping for a posgen dataset."""
    return dict(enumerate(labels_for_dataset(dataset_name)))

label2id_for_dataset 

label2id_for_dataset(
    dataset_name: DatasetName | str,
) -> dict[str, int]

Return a label-name to integer-id mapping for a posgen dataset.

Source code in lib/posgen/src/posgen/common/labels.py 
134
135
136
def label2id_for_dataset(dataset_name: DatasetName | str) -> dict[str, int]:
    """Return a label-name to integer-id mapping for a posgen dataset."""
    return {label: i for i, label in id2label_for_dataset(dataset_name).items()}

testing

Testing helpers reserved for future position-generation packages.

assert_position_content_schema 

assert_position_content_schema(
    content: PositionContent,
) -> None

Check the minimal position-generation content schema.

Source code in lib/posgen/src/posgen/common/testing.py 
 8
 9
10
11
12
13
def assert_position_content_schema(content: PositionContent) -> None:
    """Check the minimal position-generation content schema."""
    assert content.positions.shape[:-1] == content.mask.shape
    assert content.positions.shape[-1] == 2
    assert content.positions.dtype.is_floating_point
    assert content.mask.dtype == torch.bool

visualization

Visualization placeholders for future position-generation outputs.

render_position_summary 

render_position_summary(content: PositionContent) -> str

Return a compact text summary for a position-generation sample.

Source code in lib/posgen/src/posgen/common/visualization.py 
6
7
8
def render_position_summary(content: PositionContent) -> str:
    """Return a compact text summary for a position-generation sample."""
    return f"{int(content.mask.sum().item())} active positions"