# msoechting/lexcube architecture

> Architecture diagram of the GitHub repository msoechting/lexcube, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/msoechting/lexcube
- Repository: https://github.com/msoechting/lexcube

## Overview

Lexcube turns a three-dimensional NumPy or xarray dataset into an interactive Jupyter cube. The workflow starts with a notebook user creating a widget, which starts a tile server; the browser client requests and renders tiles, while interaction and controls support exploration. Documented capabilities include voxel rendering, time series, GeoJSON overlays, colormaps, range boundaries, and figure export. The graph reflects the sampled code and README; several feature modules are indexed but not excerpted, so their internal call relationships are not asserted.

Main entry points: [`src/lexcube-client/src/client/interaction.ts`](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/interaction.ts) (Cube interaction), [`src/lexcube-client/src/client/client.ts`](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/client.ts) (Client context), [`src/lexcube-client/src/client/tiledata.ts`](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/tiledata.ts) (Tile data), [`src/lexcube-client/src/client/rendering.ts`](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering.ts) (Cube rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python widget and data"]
  node_widget["Cube widget<br/>[cube3d.py]"]
  node_server["Tile server<br/>[tile_server.py]"]
  node_widget_backend["Widget backend<br/>[lexcube_widget.py]"]
end

subgraph group_client["Browser client"]
  node_frontend_widget["Jupyter widget view<br/>[widget.ts]"]
  node_client_context["Client context<br/>[client.ts]"]
  node_network["Tile networking<br/>[networking.ts]"]
  node_interaction["Cube interaction<br/>[interaction.ts]"]
  node_camera["Camera controls<br/>[camera-controls.ts]"]
  node_slider_ui["Dimension sliders<br/>[slider-ui.ts]"]
  node_colormap_ui["Colormap controls<br/>[colormap-ui.ts]"]
  node_animation_ui["Animation controls<br/>[animation-ui.ts]"]
end

subgraph group_state["Cube state and tiles"]
  node_dimensions["Dimensions<br/>[dimensions.ts]"]
  node_parameters["Parameters<br/>[parameters.ts]"]
  node_selection["Selection ranges<br/>[selection.ts]"]
  node_animation["Time animation<br/>[animation.ts]"]
  node_tiledata["Tile data<br/>[tiledata.ts]"]
  node_tiles["Tile definitions<br/>[tiles.ts]"]
  node_tile_storage["Tile storage<br/>[tile-storage.ts]"]
  node_decompression["Tile decompression"]
end

subgraph group_render["Rendering and features"]
  node_rendering["Cube rendering<br/>[rendering.ts]"]
  node_volume["Voxel rendering"]
  node_texture_views["Tile texture views"]
  node_geojson["GeoJSON overlays<br/>[region-borders.ts]"]
  node_geo_worker["GeoJSON processing"]
  node_export["Figure export<br/>[export-recorder.ts]"]
end

node_user(("Notebook user"))
node_dataset[("3D dataset")]

node_user -->|"creates widget"| node_widget
node_dataset -->|"provides data"| node_widget
node_widget -->|"starts serving"| node_server
node_widget -->|"configures view"| node_widget_backend
node_widget_backend -->|"uses tile server"| node_server
node_frontend_widget -->|"creates context"| node_client_context
node_client_context -->|"creates networking"| node_network
node_client_context -->|"creates tile data"| node_tiledata
node_client_context -->|"creates renderer"| node_rendering
node_client_context -->|"creates interaction"| node_interaction
node_network -.->|"requests tiles"| node_server
node_interaction -->|"uses controls"| node_camera
node_interaction -->|"reads dimensions"| node_dimensions
node_interaction -->|"uses parameters"| node_parameters
node_interaction -->|"uses selection"| node_selection
node_interaction -->|"uses animation"| node_animation
node_interaction -->|"creates controls"| node_slider_ui
node_interaction -->|"creates controls"| node_colormap_ui
node_interaction -->|"creates controls"| node_animation_ui
node_tiledata -->|"creates decompressor"| node_decompression
node_tiledata -->|"creates storage"| node_tile_storage
node_tiledata -->|"requests time tiles"| node_network
node_tiledata -->|"uses tile types"| node_tiles
node_rendering -->|"uses renderer"| node_volume
node_rendering -->|"uses texture views"| node_texture_views
node_rendering -->|"uses borders"| node_geojson
node_rendering -->|"uses recorder"| node_export
node_geojson -->|"parses GeoJSON"| node_geo_worker

click node_widget "https://github.com/msoechting/lexcube/blob/main/lexcube/cube3d.py"
click node_server "https://github.com/msoechting/lexcube/blob/main/lexcube/lexcube_server/src/tile_server.py"
click node_widget_backend "https://github.com/msoechting/lexcube/blob/main/lexcube/lexcube_server/src/lexcube_widget.py"
click node_frontend_widget "https://github.com/msoechting/lexcube/blob/main/src/widget.ts"
click node_client_context "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/client.ts"
click node_network "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/networking.ts"
click node_interaction "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/interaction.ts"
click node_camera "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/interaction/camera-controls.ts"
click node_dimensions "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/dimensions.ts"
click node_parameters "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/parameters.ts"
click node_selection "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/selection.ts"
click node_animation "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/animation.ts"
click node_tiledata "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/tiledata.ts"
click node_tiles "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/tiles.ts"
click node_tile_storage "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/services/tile-storage.ts"
click node_decompression "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/services/tile-decompression.ts"
click node_rendering "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering.ts"
click node_volume "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/volume-rendering.ts"
click node_texture_views "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/tile-texture-views.ts"
click node_geojson "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/region-borders.ts"
click node_geo_worker "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/geojson-loader.worker.ts"
click node_export "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/export-recorder.ts"
click node_slider_ui "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/ui/slider-ui.ts"
click node_colormap_ui "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/ui/colormap-ui.ts"
click node_animation_ui "https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/ui/animation-ui.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_widget,node_server,node_widget_backend,node_user toneBlue
class node_frontend_widget,node_client_context,node_network,node_interaction,node_camera,node_slider_ui,node_colormap_ui,node_animation_ui,node_dataset toneAmber
class node_dimensions,node_parameters,node_selection,node_animation,node_tiledata,node_tiles,node_tile_storage,node_decompression toneMint
class node_rendering,node_volume,node_texture_views,node_geojson,node_geo_worker,node_export toneRose
```

## Components

### Python widget and data

- [Cube widget](https://github.com/msoechting/lexcube/blob/main/lexcube/cube3d.py): `lexcube/cube3d.py`
- [Tile server](https://github.com/msoechting/lexcube/blob/main/lexcube/lexcube_server/src/tile_server.py): `lexcube/lexcube_server/src/tile_server.py`
- [Widget backend](https://github.com/msoechting/lexcube/blob/main/lexcube/lexcube_server/src/lexcube_widget.py): `lexcube/lexcube_server/src/lexcube_widget.py`

### Browser client

- [Jupyter widget view](https://github.com/msoechting/lexcube/blob/main/src/widget.ts): `src/widget.ts`
- [Client context](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/client.ts): `src/lexcube-client/src/client/client.ts`
- [Tile networking](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/networking.ts): `src/lexcube-client/src/client/networking.ts`
- [Cube interaction](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/interaction.ts): `src/lexcube-client/src/client/interaction.ts`
- [Camera controls](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/interaction/camera-controls.ts): `src/lexcube-client/src/client/interaction/camera-controls.ts`
- [Dimension sliders](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/ui/slider-ui.ts): `src/lexcube-client/src/client/ui/slider-ui.ts`
- [Colormap controls](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/ui/colormap-ui.ts): `src/lexcube-client/src/client/ui/colormap-ui.ts`
- [Animation controls](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/ui/animation-ui.ts): `src/lexcube-client/src/client/ui/animation-ui.ts`

### Cube state and tiles

- [Dimensions](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/dimensions.ts): `src/lexcube-client/src/client/core/dimensions.ts`
- [Parameters](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/parameters.ts): `src/lexcube-client/src/client/core/parameters.ts`
- [Selection ranges](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/selection.ts): `src/lexcube-client/src/client/core/selection.ts`
- [Time animation](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/animation.ts): `src/lexcube-client/src/client/core/animation.ts`
- [Tile data](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/tiledata.ts): `src/lexcube-client/src/client/tiledata.ts`
- [Tile definitions](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/core/tiles.ts): `src/lexcube-client/src/client/core/tiles.ts`
- [Tile storage](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/services/tile-storage.ts): `src/lexcube-client/src/client/services/tile-storage.ts`
- [Tile decompression](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/services/tile-decompression.ts): `src/lexcube-client/src/client/services/tile-decompression.ts`

### Rendering and features

- [Cube rendering](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering.ts): `src/lexcube-client/src/client/rendering.ts`
- [Voxel rendering](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/volume-rendering.ts): `src/lexcube-client/src/client/rendering/volume-rendering.ts`
- [Tile texture views](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/tile-texture-views.ts): `src/lexcube-client/src/client/rendering/tile-texture-views.ts`
- [GeoJSON overlays](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/region-borders.ts): `src/lexcube-client/src/client/rendering/region-borders.ts`
- [GeoJSON processing](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/geojson-loader.worker.ts): `src/lexcube-client/src/client/rendering/geojson-loader.worker.ts`
- [Figure export](https://github.com/msoechting/lexcube/blob/main/src/lexcube-client/src/client/rendering/export-recorder.ts): `src/lexcube-client/src/client/rendering/export-recorder.ts`

### Other components

- **Notebook user**
- **3D dataset**

## Connections

- Notebook user → Cube widget: creates widget
- 3D dataset → Cube widget: provides data
- Cube widget → Tile server: starts serving (evidence: `lexcube/cube3d.py`)
- Cube widget → Widget backend: configures view (evidence: `lexcube/cube3d.py`)
- Widget backend → Tile server: uses tile server (evidence: `lexcube/lexcube_server/src/lexcube_widget.py`)
- Jupyter widget view → Client context: creates context (evidence: `src/widget.ts`)
- Client context → Tile networking: creates networking (evidence: `src/lexcube-client/src/client/client.ts`)
- Client context → Tile data: creates tile data (evidence: `src/lexcube-client/src/client/client.ts`)
- Client context → Cube rendering: creates renderer (evidence: `src/lexcube-client/src/client/client.ts`)
- Client context → Cube interaction: creates interaction (evidence: `src/lexcube-client/src/client/client.ts`)
- Tile networking → Tile server: requests tiles
- Cube interaction → Camera controls: uses controls (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Cube interaction → Dimensions: reads dimensions (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Cube interaction → Parameters: uses parameters (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Cube interaction → Selection ranges: uses selection (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Cube interaction → Time animation: uses animation (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Cube interaction → Dimension sliders: creates controls (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Cube interaction → Colormap controls: creates controls (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Cube interaction → Animation controls: creates controls (evidence: `src/lexcube-client/src/client/interaction.ts`)
- Tile data → Tile decompression: creates decompressor (evidence: `src/lexcube-client/src/client/tiledata.ts`)
- Tile data → Tile storage: creates storage (evidence: `src/lexcube-client/src/client/tiledata.ts`)
- Tile data → Tile networking: requests time tiles (evidence: `src/lexcube-client/src/client/tiledata.ts`)
- Tile data → Tile definitions: uses tile types (evidence: `src/lexcube-client/src/client/tiledata.ts`)
- Cube rendering → Voxel rendering: uses renderer (evidence: `src/lexcube-client/src/client/rendering.ts`)
- Cube rendering → Tile texture views: uses texture views (evidence: `src/lexcube-client/src/client/rendering.ts`)
- Cube rendering → GeoJSON overlays: uses borders (evidence: `src/lexcube-client/src/client/rendering.ts`)
- Cube rendering → Figure export: uses recorder (evidence: `src/lexcube-client/src/client/rendering.ts`)
- GeoJSON overlays → GeoJSON processing: parses GeoJSON (evidence: `src/lexcube-client/src/client/rendering/region-borders.ts`)
