Skip to content

guidellm.data.deserializers.synthetic_image

Synthetic image dataset deserializer.

SyntheticImageDataArgs

Bases: SyntheticVisionDataArgs

Model for synthetic image dataset deserializer arguments.

Source code in src/guidellm/data/deserializers/synthetic_image.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
@DataArgs.register(_DESERIALIZER_TYPE)
class SyntheticImageDataArgs(SyntheticVisionDataArgs):
    """Model for synthetic image dataset deserializer arguments."""

    kind: Literal["synthetic_image"] = Field(  # type: ignore[assignment]
        default="synthetic_image",
        description="Type identifier for the synthetic image dataset configuration.",
    )
    width: int | None = Field(
        description="Image width in pixels.",
        gt=0,
        default=None,
    )
    height: int | None = Field(
        description="Image height in pixels.",
        gt=0,
        default=None,
    )
    resolution: str | None = Field(
        description="Resolution shortcut such as '720p' or '1080p'.",
        default=None,
    )
    aspect_ratio: str | None = Field(
        description="Aspect ratio override, e.g. '16:9' or '4:3'.",
        default=None,
    )
    format: Literal["jpeg", "png"] = Field(
        description="Encoded image format.",
        default="jpeg",
    )
    jpeg_quality: int = Field(
        description="JPEG quality 1..100. Ignored when format='png'.",
        ge=1,
        le=100,
        default=85,
    )
    content: Literal["gradient", "noise", "solid", "checkerboard"] = Field(
        description="Pixel content to synthesize.",
        default="gradient",
    )
    images_per_request: int = Field(
        description="Number of images per emitted row.",
        ge=1,
        default=1,
    )

    @model_validator(mode="after")
    def _resolve_dimensions(self) -> SyntheticImageDataArgs:
        w = self.width
        h = self.height
        if self.resolution is not None:
            preset = RESOLUTION_PRESETS.get(self.resolution.lower())
            if preset is None:
                raise ValueError(
                    f"Unknown resolution '{self.resolution}'. Known: "
                    f"{sorted(RESOLUTION_PRESETS)}"
                )
            preset_w, preset_h = preset
            if h is None:
                h = preset_h
            if w is None:
                w = (
                    int(round(h * parse_aspect_ratio(self.aspect_ratio)))
                    if self.aspect_ratio is not None
                    else preset_w
                )
        elif self.aspect_ratio is not None:
            if h is not None and w is None:
                w = int(round(h * parse_aspect_ratio(self.aspect_ratio)))
            elif w is not None and h is None:
                h = int(round(w / parse_aspect_ratio(self.aspect_ratio)))

        if w is None or h is None:
            raise ValueError(
                "synthetic_image config requires width and height, either "
                "explicitly or via resolution/aspect_ratio."
            )
        self.width = int(w) - (int(w) % 2)
        self.height = int(h) - (int(h) % 2)
        if self.width <= 0 or self.height <= 0:
            raise ValueError(
                f"Resolved image dims must be positive, got {self.width}x{self.height}"
            )
        return self

parse_aspect_ratio(aspect)

Parse 'W:H' or 'W/H' into a float ratio.

Source code in src/guidellm/data/deserializers/synthetic_image.py 
43
44
45
46
47
48
49
50
51
52
def parse_aspect_ratio(aspect: str) -> float:
    """Parse 'W:H' or 'W/H' into a float ratio."""
    sep = ":" if ":" in aspect else "/"
    try:
        w, h = aspect.split(sep)
        return float(w) / float(h)
    except Exception as exc:  # noqa: BLE001
        raise ValueError(
            f"Invalid aspect_ratio '{aspect}', expected 'W:H' or 'W/H'"
        ) from exc