Interactive Viewer (UI)

A FastAPI-powered web UI that auto-generates parameter controls from function signatures or Pydantic models and renders matplotlib figures in real-time. Install the optional ui extra to use this module:

uv add "dartwork-mpl[ui]"

run(figure_fn, param_model=None, *, title, copy_to, host, port)

Launch the interactive figure viewer in the browser.

• Parameters: - figure_fn: callable accepting a single ParamModel instance, returns a Figure. - param_model: optional explicit ParamModel subclass (auto-detected from type hints if omitted). - title: browser tab title. Default "Dartwork Viewer". - copy_to: path(s) to auto-copy saved images to. - host: server host. Default "127.0.0.1". - port: server port. Default 8501.

• Returns: - None — runs the server until interrupted.

ParamModel

Base Pydantic model for declaring plot parameters. Subclass it and add typed fields with pydantic.Field for validation, ranges, and default values. The UI auto-generates sliders, dropdowns, and text fields from the field metadata.

Features

• Auto-generated controls: sliders, dropdowns, and text inputs created from type annotations.

• Real-time preview: figure re-renders on every parameter change.

• Export: download PNG/SVG/PDF or generate a standalone Python script.

• Presets: save and restore parameter combinations.

• Server-side save: save images and scripts to the project directory.

• Hot reload: restart the server to pick up code changes.

Example

from dartwork_mpl.ui import ParamModel, run
from pydantic import Field
import matplotlib.pyplot as plt
import numpy as np

class Params(ParamModel):
    n: int = Field(default=100, ge=10, le=1000, description="Number of points")
    alpha: float = Field(default=0.5, ge=0, le=1, description="Opacity")

def scatter_plot(params: Params):
    fig, ax = plt.subplots()
    ax.scatter(range(params.n), np.random.randn(params.n), alpha=params.alpha)
    return fig

run(scatter_plot)  # opens http://127.0.0.1:8501

dartwork_mpl.ui — Interactive figure viewer.

Provides a FastAPI-powered web UI that auto-generates parameter controls from function signatures or Pydantic models and renders matplotlib figures in real-time.

Quick start:

from dartwork_mpl.ui import ParamModel, run

def my_plot(n: int = 100, alpha: float = 0.5):
    ...
    return fig

run(my_plot)

class dartwork_mpl.ui.ParamModel(*args: Any, **kwargs: Any)

Bases: BaseModel

Base class for declarative parameter UI specification.

Subclass this and use pydantic.Field to declare parameters with constraints that map to Streamlit widgets:

• ge / le → slider min/max

• gt / lt → number_input bounds (exclusive)

• Literal[...] type → selectbox

• json_schema_extra={"widget": "color"} → color_picker

• description → widget label

Examples

>>> from pydantic import Field
>>> from typing import Literal
>>>
>>> class PlotParams(ParamModel):
...     n_points: int = Field(
...         default=100, ge=10, le=1000,
...         description="Number of data points",
...     )
...     alpha: float = Field(
...         default=0.5, ge=0.0, le=1.0,
...         description="Transparency",
...     )
...     style: Literal["solid", "dashed", "dotted"] = Field(
...         default="solid",
...     )
...     color: str = Field(
...         default="#1f77b4",
...         json_schema_extra={"widget": "color"},
...     )

model_config = {'arbitrary_types_allowed': True}