Metadata-Version: 2.4
Name: hakowan
Version: 0.6.1
Summary: Hakowan: A 3D data visualization grammar
Author-email: Qingnan Zhou <qnzhou@gmail.com>, Zhicheng Liu <leozcliu@umd.edu>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: Apache Software License
License-File: LICENSE
Requires-Dist: adobe-lagrange>=6.49.0
Requires-Dist: numpy>=2.0
Requires-Dist: Pillow>=11.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: tqdm>=4.66
Requires-Dist: colorcet>=3.2.1,<4
Requires-Dist: pygltflib>=1.16.5,<2
Requires-Dist: pydantic>=2.10,<3
Requires-Dist: bpy>=5.1,<6 ; extra == "blender" and ( python_version == '3.13')
Requires-Dist: pandas>=2.0 ; extra == "data"
Requires-Dist: xarray>=2024.1 ; extra == "data"
Requires-Dist: pyvista>=0.44 ; extra == "data"
Requires-Dist: trimesh>=4.0 ; extra == "data"
Requires-Dist: mkdocs-materialx>=10.2,<11 ; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24 ; extra == "docs"
Requires-Dist: dulwich>=0.25,<1 ; extra == "docs"
Requires-Dist: mitsuba~=3.9 ; extra == "mitsuba"
Requires-Dist: playwright>=1.49,<2 ; extra == "observe"
Provides-Extra: blender
Provides-Extra: data
Provides-Extra: docs
Provides-Extra: mitsuba
Provides-Extra: observe

# Hakowan

![Hakowan teaser](docs/images/teaser.webp)

Hakowan is a 3D data visualization grammar. It is inspired by the grammar of graphics, and it is
designed for easily creating beautiful 3D visualizations.

## Install

Hakowan relies on [Lagrange](https://opensource.adobe.com/lagrange-docs/) for geometry processing
and supports three rendering backends:

| Backend | Description | Extra |
|---------|-------------|-------|
| **WebGL** (default) | Interactive browser viewer — ships with base install | *(none)* |
| **Mitsuba** | Photorealistic offline renderer | `hakowan[mitsuba]` |
| **Blender** | Cycles/EEVEE renderer (requires Python 3.13) | `hakowan[blender]` |

```sh
# WebGL only (default)
pip install hakowan

# Mitsuba backend
pip install "hakowan[mitsuba]"

# Blender backend (Python 3.13 required)
pip install "hakowan[blender]"

# All backends
pip install "hakowan[mitsuba,blender]"

# Add deterministic headless snapshots and multi-view observations
pip install "hakowan[observe]"
playwright install chromium

# Optional dataframe and geometry adapters
pip install "hakowan[data]"

# Agent integration is distributed separately
pip install "hakowan-mcp"
```

Note that Hakowan requires Python 3.11 and above (Python 3.13 for the Blender backend).

## Command line

`hkw` requires an action. `render` writes a still image using Mitsuba or Blender,
preferring Mitsuba when both are available. One of those optional backends must
be installed; otherwise, `render` reports an error. `view` creates an
interactive WebGL HTML viewer. `inspect` lists a mesh's attributes, domains,
and each channel's min/max without selecting a render backend. Run `hkw --help`
or an action's help for details. `--facet-id` selects Blender for `render` and
reports an error if Blender is unavailable.

`view` works with the base WebGL install. `render` requires the Mitsuba or
Blender extra.

```sh
hkw render mesh.obj
hkw view mesh.obj
hkw inspect mesh.obj
```

To check which backends are available in your environment:

```py
import hakowan as hkw
print(hkw.list_backends())
```

## Quick start

The following example renders an interactive HTML viewer using the WebGL backend:

```py
import hakowan as hkw

layer = (
    hkw.layer("mesh.obj")
    .mark(hkw.mark.Surface)
    .channel(material=hkw.material.Diffuse(reflectance="orange"))
)

result = hkw.render(layer, filename="viewer.html", backend="webgl")
# Open viewer.html in any modern browser
```

`render()` produces the requested output (an interactive viewer or a
Mitsuba/Blender image). For AI or programmatic inspection, use `observe()` for
one or more WebGL views, render passes, and visibility queries. Observation
captures independently; it does not require a preceding render. See the
[rendering and viewers guide](https://hakowan.github.io/hakowan/guide/rendering/).

## Agent integration

Hakowan's provider-neutral agent integration is maintained separately in
[`Hakowan/hakowan-mcp`](https://github.com/Hakowan/hakowan-mcp). It exposes
Hakowan's deterministic inspection, schema, validation, compilation, rendering,
observation, camera-fitting, and patch APIs to Copilot, Oh My Pi, and other MCP
hosts without adding model-provider dependencies to this package.

## Documentation

[HTML](https://hakowan.github.io/hakowan/)

```bibtex
@software{hakowan,
    title = {Hakowan: A 3D Data Visualization Grammar},
    version = {0.6.1},
    year = 2026,
}
```

