tenderness 0.3.0

tenderness is a fast library for synthetic, deterministic document rendering from text and images, powered by Cairo and Pango.

Why tenderness?

Most document datasets don’t come from real structure — they come from reconstruction. Text is rendered, then reverse-engineered back into layout using OCR, heuristics, or fragile parsing pipelines. The result is noisy, incomplete, and not reproducible.

tenderness flips this entirely.

It renders text directly into documents producing images, SVGs, and PDFs with fully known layout from the start. Every character placement, line break, and block position is defined at render time — not inferred afterward.

What this gives you

• Generate large-scale synthetic document datasets
• Provide precise structural supervision for vision-language models
• Build benchmarks for layout understanding systems
• Ground-truth layout across characters, clusters, runs, and lines

No OCR. No heuristics. No reconstruction. No manual annotation.

Just text in → fully structured document out.

Main Features

• Multi-format output: Render text and images into Image, SVG, PDF, or NumPy arrays.

• Composable content blocks: Build documents from simple primitives: TextBlock, ImageBlock, and TableBlock.

• Minimal flexbox layout engine: A lightweight system that automatically resolves positioning and flow.

• Exact bounding boxes (OBB + AABB, logical + ink): Extract multi-level data for text (character, cluster, run, line, layout) and blocks.

• Rich typography & text flow: Custom fonts, hierarchical styling, Pango markup, automatic font fallback, and overflow-aware text continuation across blocks.

• Composable pipelines: Use the built-in pipeline with pre-defined layouts, or build your own from scratch.

Quick Start

pip install tenderness

import pathlib

from tenderness.cairo_backend.color_patterns import SolidColorSpec
from tenderness.cairo_backend.surface_config_manager import SurfaceConfigManager
from tenderness.colors.color_selector import ColorSelector
from tenderness.pango_backend.font_description_interface import FontDescriptionInterfaceParameters
from tenderness.pipelines.document import (
    DocumentBlocksConfig,
    DocumentConfig,
    DocumentRenderPipeline,
    TextBlock,
    TextStyle,
)

# select colors
color_selector = ColorSelector()
white = SolidColorSpec(color=color_selector.by_names(["white"])[0])
black = SolidColorSpec(color=color_selector.by_names(["black"])[0])

# select surface (image, pdf, svg, etc.)
img_surface_config = SurfaceConfigManager().create_image_surface_config(
    width=400,
    height=100,
)

# create document config and blocks config
doc_config = DocumentConfig(surface_config=img_surface_config, background_spec=white)
doc_blocks_config = DocumentBlocksConfig(
    surface_config=img_surface_config,
    blocks=[
        TextBlock(
            text="Hello, world!",
            text_style=TextStyle(
                font_description_params=FontDescriptionInterfaceParameters(size=32),
                text_color_spec=black,
            ),
        ),
    ],
)

# create pipeline and render document
pipeline = DocumentRenderPipeline()
setup_result = pipeline.setup(config=doc_config)
render_result = pipeline.render(
    blocks_config=doc_blocks_config,
    setup_result=setup_result,
)

# save the rendered document to a file
pipeline.save_as_file(
    surface=setup_result.surface,
    surface_config=img_surface_config,
    output_file_path=pathlib.Path("hello_world"),
)

# The output file will be saved as `hello_world.png` in the current working directory.

You can find the runnable version at scripts/mini_example.py, and more examples over at tenderness-examples. If you run into missing system libraries (Cairo, Pango, PyGObject), check the install guide.