Skip to content

Posgen

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"