Figure & Decorators

The figure system for collecting and rendering geometry diagrams.

API Reference

geolet.figure.figure

figure(func: Callable[[], list[Drawable] | list]) -> Figure

Collect Drawable objects from a function's return value into a Figure.

Simple decorator that requires explicit return of drawables.

Usage

@figure def my_diagram(): A = Point("A", 0, 0) B = Point("B", 1, 1) seg = Segment(A, B) return [A, B, seg]

my_diagram.save_asy(Path("output.asy")) my_diagram.save_pdf(Path("output.pdf"))

Returns:

Type	Description
Figure	A Figure object with save_asy(), save_pdf(), save_svg() methods.

---

geolet.figure.autofigure

autofigure(func: Callable[[], list[Drawable] | list | None]) -> Figure

Collect Drawable objects from a function into a Figure.

Uses frame introspection to auto-collect all Drawable locals if no return. Variables with underscore prefix are excluded from auto-collection.

Usage

@autofigure def my_diagram(): A = Point("A", 0, 0) B = Point("B", 1, 1) _helper = Point("H", 0.5, 0.5) # Not drawn (underscore prefix) Segment(A, B) # No return needed - all Drawable locals are collected

my_diagram.save_asy(Path("output.asy")) my_diagram.save_pdf(Path("output.pdf"))

Returns:

Type	Description
Figure	A Figure object with save_asy(), save_pdf(), save_svg() methods.

---

geolet.figure.Figure dataclass

A collection of drawable objects that can be rendered to Asymptote.

Attributes:

Name	Type	Description
drawables	tuple[Drawable, ...]	Immutable tuple of all drawable objects in this figure.

drawables instance-attribute

drawables: tuple[Drawable, ...]

to_asy

to_asy() -> str

Generate complete Asymptote code.

render

render(fmt: Literal['svg']) -> str

render(fmt: Literal['pdf']) -> bytes

render(fmt: Literal['svg', 'pdf']) -> str | bytes

Render to format in-memory.

Parameters:

Name	Type	Description	Default
fmt	Literal['svg', 'pdf']	Output format ('svg' or 'pdf')	required

Returns:

Type	Description
str | bytes	str for svg, bytes for pdf

save_asy

save_asy(path: Path) -> None

Write Asymptote code to file.

save_pdf

save_pdf(path: Path) -> None

Render and save as PDF.

save_svg

save_svg(path: Path) -> None

Render and save as SVG.

---

geolet.figure.FigureContext

Context for collecting drawable objects during figure construction.

drawables property

drawables: tuple[Drawable, ...]

Return collected drawables as immutable tuple.

__init__

__init__() -> None

Initialize empty context.

register

register(obj: Drawable) -> None

Register a drawable object with this context.

Decorators Comparison

Feature	@figure	@autofigure
Return statement	Required	Optional
Auto-collection	No	Yes
Underscore exclusion	N/A	Yes (_var excluded)
Use case	Explicit control	Quick prototyping

Examples

Using @figure (Explicit Return)

from geolet import Point, Segment, figure


@figure
def my_diagram():
    A = Point("A", 0, 0, label_dir="SW")
    B = Point("B", 4, 0, label_dir="SE")
    C = Point("C", 2, 3, label_dir="N")

    return [
        A, B, C,
        Segment(A, B),
        Segment(B, C),
        Segment(C, A),
    ]

Using @autofigure (Automatic Collection)

from geolet import Point, Segment, autofigure


@autofigure
def my_diagram():
    A = Point("A", 0, 0, label_dir="SW")
    B = Point("B", 4, 0, label_dir="SE")
    C = Point("C", 2, 3, label_dir="N")

    Segment(A, B)
    Segment(B, C)
    Segment(C, A)
    # No return needed - all Drawable locals collected

Excluding Variables with Underscore

from geolet import Point, Segment, autofigure


@autofigure
def my_diagram():
    A = Point("A", 0, 0)
    B = Point("B", 4, 0)

    # This helper point won't be drawn
    _midpoint = Point("", 2, 0)

    Segment(A, B)

Saving Output

from pathlib import Path
from geolet import Point, Segment, autofigure


@autofigure
def my_diagram():
    A = Point("A", 0, 0)
    B = Point("B", 1, 1)
    Segment(A, B)


# Save as Asymptote source
my_diagram.save_asy(Path("output.asy"))

# Save as PDF (requires Asymptote installed)
my_diagram.save_pdf(Path("output.pdf"))

# Save as SVG
my_diagram.save_svg(Path("output.svg"))

In-Memory Rendering

from geolet import Point, Segment, autofigure


@autofigure
def my_diagram():
    A = Point("A", 0, 0)
    B = Point("B", 1, 1)
    Segment(A, B)


# Get Asymptote code as string
asy_code = my_diagram.to_asy()
print(asy_code)

# Render to SVG in memory
svg_content = my_diagram.render("svg")

# Render to PDF in memory (returns bytes)
pdf_bytes = my_diagram.render("pdf")