{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f0a1b2c3d4e5",
   "metadata": {},
   "source": [
    "# Exporting to HTML\n",
    "\n",
    "Scenes can be exported to standalone HTML files that render interactively using a built-in\n",
    "JavaScript WebGPU engine — no Python needed in the browser."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1b2c3d4e5f6",
   "metadata": {},
   "source": [
    "## Export methods\n",
    "\n",
    "There are three ways to export:\n",
    "\n",
    "- **`Scene.export(path)`** — export a single scene programmatically\n",
    "- **`python -m webgpu.notebook_to_html notebook.ipynb -o output.html`** — convert an entire notebook\n",
    "- **Sphinx builds with `WEBGPU_EXPORTING=1`** — automatic export for documentation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2c3d4e5f6a7",
   "metadata": {},
   "source": [
    "## Programmatic export\n",
    "\n",
    "Create a scene and call `export()` to write a self-contained HTML file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c3d4e5f6a7b8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from webgpu.shapes import generate_cylinder, generate_cone, ShapeRenderer\n",
    "from webgpu.colormap import Colormap, Colorbar\n",
    "from webgpu.scene import Scene\n",
    "from webgpu.jupyter import Draw\n",
    "\n",
    "shaft = generate_cylinder(n=12, radius=0.02, height=0.7, bottom_face=True)\n",
    "tip = generate_cone(n=12, radius=0.06, height=0.3, bottom_face=True).move((0, 0, 0.7))\n",
    "arrow = shaft + tip\n",
    "\n",
    "cmap = Colormap(colormap=\"viridis\")\n",
    "renderer = ShapeRenderer(\n",
    "    arrow,\n",
    "    positions=[[0, 0, 0], [0.5, 0, 0], [1, 0, 0]],\n",
    "    directions=[[0, 0, 1], [1, 0, 0], [0, 1, 0]],\n",
    "    values=[0, 0, 0.5, 0.5, 1, 1],\n",
    "    colormap=cmap,\n",
    ")\n",
    "scene = Draw([renderer, Colorbar(cmap)])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d4e5f6a7b8c9",
   "metadata": {},
   "source": [
    "To export this scene to a standalone HTML file:\n",
    "\n",
    "```\n",
    "scene.export(\"my_scene.html\")\n",
    "```\n",
    "\n",
    "To convert an entire notebook:\n",
    "\n",
    "```\n",
    "python -m webgpu.notebook_to_html notebook.ipynb -o output.html\n",
    "```\n",
    "\n",
    "The exported HTML contains the full JavaScript WebGPU engine inline. It supports\n",
    "camera interaction (rotate, pan, zoom) and, for scenes with clipping or colormap\n",
    "uniforms, interactive GUI controls."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5f6a7b8c9d0",
   "metadata": {},
   "source": [
    "## Sphinx integration\n",
    "\n",
    "The documentation build in `docs/conf.py` sets `WEBGPU_EXPORTING=1` and uses `nbsphinx`\n",
    "to automatically produce interactive 3D canvases from notebook cells. During the build,\n",
    "Playwright drives a headless browser with Vulkan/lavapipe to capture the GPU state that\n",
    "the JavaScript engine needs to reconstruct the scene."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6a7b8c9d0e1",
   "metadata": {},
   "source": [
    "## What gets exported\n",
    "\n",
    "The JavaScript engine reconstructs GPU state from a binary blob embedded in the HTML.\n",
    "It supports all built-in renderers, compute passes, and custom renderers — as long as\n",
    "the custom renderer implements `get_export_descriptor`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}