Metadata-Version: 2.4
Name: gpui-toolkit
Version: 0.9.25
Summary: Python declarations for GPUI Toolkit apps and retained 3D scene specs
Author-email: "Pierre F. Aubert" <pierre@spinorama.org>
License: ISC
Project-URL: Repository, https://github.com/pierreaubert/gpui-toolkit
Project-URL: Documentation, https://docs.rs/gpui-toolkit
Keywords: gpui,ui,visualization,scene3d
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gpui-python-runtime

Retained scene specifications for the GPUI Python wrapper.

Python declares UI and `scene3d` objects. Rust validates the scene, tracks
stable ids, classifies dirty resources, and adapts supported nodes to
`gpui-d3rs` 3D elements. Raw `wgpu` devices, queues, buffers, pipelines, and
shaders remain private to the renderer.

## V1 Scene3D Scope

- Surfaces: row-major `z` grids with optional `x`/`y` axes, log axes, z range,
  labels, colormaps, wireframe mode, orbit cameras, and interactions.
- Lines: retained orbit camera state and CPU-projected `Lines3DElement`
  segments/line strips.
- Meshes, materials, perspective cameras, and lights: validated spec objects
  for the lower-level scene API. Mesh rendering is intentionally not bound to a
  GPUI element yet.

## JSON Schema Contract

Python-authored payloads are versioned at the JSON boundary:

- app IR uses `schema_version: 1`, exposed as
  `PYTHON_APP_IR_SCHEMA_VERSION`.
- Scene3D specs use `schema_version: 1`, exposed as
  `SCENE3D_SPEC_SCHEMA_VERSION`.

New Python emitters write the current schema version. Rust treats omitted
`schema_version` fields as v1 so early examples and local scripts keep loading,
but validation rejects unsupported future versions before rendering or reusing a
cached spec.

Compatibility policy:

1. Additive optional fields may stay on v1 when Rust gives them safe defaults.
2. Renaming fields, removing fields, changing data-shape semantics, or changing
   renderer meaning requires a schema-version bump.
3. A schema-version bump must include compatibility tests for previous v1
   payloads and a migration path before Python emitters start writing it.
4. Consumers should parse JSON, validate `PythonAppIr`, then parse and validate
   Scene3D specs through `TypedSpecCache` or
   `validate_scene3d_spec_schema_version`.

## Resource Model

`RetainedSceneCache` fingerprints geometry, material, and camera state
separately:

- unchanged scenes do no renderer work,
- camera-only changes update uniforms/state,
- color/material changes update small renderer state,
- data/mesh changes reupload affected geometry.

`Gpui3DCache` is available behind the `gpui` feature and keeps
`Surface3DElement` / line camera state keyed by stable ids.

## Python Examples

The examples build JSON-serializable scene specs that the Rust runtime can
validate and adapt to GPUI elements:

```bash
PYTHONPATH=python python examples/surface_dispersion.py
PYTHONPATH=python python examples/lines_orbit.py
PYTHONPATH=python python examples/mesh_scene.py
```

- `surface_dispersion.py` shows a log-frequency surface with orbit controls.
- `lines_orbit.py` shows line strips, axis references, and a shared orbit camera.
- `mesh_scene.py` shows the future lower-level scene shape with mesh, path, and
  light nodes.

The larger app-authored demos mirror the Rust showcase programs:

```bash
# Dump the native app IR without requiring a GPUI host.
GPUI_TOOLKIT_DUMP_IR=1 PYTHONPATH=python python examples/spinorama_demo.py
GPUI_TOOLKIT_DUMP_IR=1 PYTHONPATH=python python examples/surface3d_demo.py
GPUI_TOOLKIT_DUMP_IR=1 PYTHONPATH=python python examples/chart_gallery.py

# Without a host-related environment variable, each script prints JSON too.
PYTHONPATH=python python examples/spinorama_demo.py > /tmp/spinorama-python.json
```

- `spinorama_demo.py` contains CEA2034, horizontal SPL, vertical SPL,
  contour, and retained 3D surface sections using deterministic local data.
- `surface3d_demo.py` contains the sinc, spinorama-style, and saddle surface
  modes from the Rust `surface3d_demo`.
- `chart_gallery.py` covers scatter, line, area, heatmap, contour, isoline, bar,
  pie, donut, box-plot, and treemap declarations.

Replace the local data-builder functions with measurement or application data
when adapting a demo; the chart and Scene3D declarations remain unchanged.

## Python Package

The Python declarations are packaged as `gpui-toolkit` with the import package
`gpui_toolkit`. The package is pure Python and intentionally has no runtime
dependencies; Rust/GPUI remains the rendering host.

```bash
python -m pip install gpui-toolkit
python -c "import gpui_toolkit; print(gpui_toolkit.__version__)"
```

The package version matches the Rust crate version. Update both
`pyproject.toml` and `Cargo.toml` together when releasing a new Python-facing
runtime.

## Showcase Application

Run the Python-authored native GPUI showcase with retained 3D scenes and
embedded `gpui-px` charts:

```bash
cargo run -p gpui-python-runtime --features showcase --bin gpui-python-showcase -- crates/gpui-toolkit/gpui-python-runtime/python/showcase.py
PYTHONPATH=crates/gpui-toolkit/gpui-python-runtime/python ./venv/bin/python crates/gpui-toolkit/gpui-python-runtime/python/showcase.py
```

The showcase app, sections, UI kit demos, chart data, and `scene3d` specs live
in Python. Rust loads the JSON UI IR, then owns GPUI, retained 3D renderer
state, chart widgets, and theme integration.

## Platform Notes

The renderer path is inherited from `wgpu` via `gpui-d3rs`:

- macOS/iOS: Metal,
- Linux: Vulkan where available,
- Windows: DirectX 12 or Vulkan depending adapter support,
- Android: Vulkan once a GPUI Android backend exists.

The Python API is intended to stay the same across platforms; only GPUI backend
initialization should differ.
