pyBrowzarr-docs

docs/content/1.getting-started/3.landing.md

@@ -1,5 +1,5 @@
 ---
-title: Landing
+title: Crash Course
 description: User Interface.
 navigation:
   icon: i-lucide-plane-landing
@@ -40,7 +40,7 @@ There some default plotting options depending on your dataset dimensions, howeve
 
 Hover the colormap options to see how your plot will change, then click on the one you like to setup that one!
 
-### :icon{name="i-lucide-settings" class="icon-lg"} Settings
+### :icon{name="i-heroicons-adjustments-horizontal" class="icon-lg"} Settings
 
 ### :icon{name="i-ph-play-pause-fill" class="icon-lg"} Animation controls
 

docs/content/2.Menus/.navigation.yml

@@ -0,0 +1 @@
+title: Menus

docs/content/2.essentials/5.analytics.md → docs/content/2.Menus/6.analytics.md

@@ -2,7 +2,7 @@
 title: Analytics
 description: Powered WebGPU analytics
 navigation:
-  icon: i-lucide-brain
+  icon: i-ph-math-operations-bold
 seo:
   description: Powered WebGPU analytics
 ---

docs/content/4.pyBrowzarr/.navigation.yml

@@ -0,0 +1,2 @@
+title: pyBrowzarr
+icon: false

docs/content/4.pyBrowzarr/1.overview.md

@@ -0,0 +1,52 @@
+---
+title: Overview
+description: pyBrowzarr — the Python API for configuring and launching Browzarr plots from your code.
+navigation:
+  icon: i-lucide-terminal
+---
+
+**pyBrowzarr** is a Python package that serves a pre-built [Browzarr](https://browzarr.io)
+frontend from a local HTTP server and opens it
+in your browser (or notebook). It gives you a Pythonic, chainable API to configure a
+plot and launch it with a single call.
+
+## What you can do
+
+- Tune shared and plot-type-specific options (colormaps, extents, transparency, and more).
+- Export the result or script an animation with walkthrough keyframes.
+- Run from a terminal, Jupyter/JupyterLab, VS Code, or Google Colab automatically.
+
+## Installation
+
+```bash
+pip install browzarr
+```
+
+The `browzarr` command-line launcher is also installed:
+
+```bash
+browzarr
+```
+
+A pre-built frontend comes bundled with the package. See
+[Build & Update](/pybrowzarr/build-and-update) to rebuild it from source or update it.
+
+## First plot
+
+```python
+from browzarr import Browzarr
+
+Browzarr(dataset="path://some-zarr-store", variable="some_variable").volume().plot()
+```
+
+That's it — a configured Browzarr view opens in your default browser.
+
+## Documentation map
+
+| Guide | Covers |
+|-------|--------|
+| [Quickstart](/pybrowzarr/quickstart) | Install, `Browzarr` basics, slicing, launching a plot |
+| [API Reference](/pybrowzarr/api-reference) | Full reference for `Browzarr`, its methods, module functions, and plot-type options |
+| [Export & Animation](/pybrowzarr/export) | The `export()` method, export options, keyframes, and animation |
+| [Environments](/pybrowzarr/environment) | Behavior in terminal, Jupyter, VS Code, and Colab |
+| [Build & Update](/pybrowzarr/build-and-update) | `build_browzarr()` and `update_browzarr()` |

docs/content/4.pyBrowzarr/2.quickstart.md

@@ -0,0 +1,108 @@
+---
+title: Quickstart
+description: Install pyBrowzarr and go from zero to your first Browzarr plot.
+navigation:
+  icon: i-lucide-rocket
+---
+
+This guide gets you from install to your first plot.
+
+## 1. Install
+
+```bash
+pip install browzarr
+```
+
+## 2. Create a Browzarr session
+
+A `Browzarr` object describes *what* to visualize. You give it a dataset and a variable,
+then optionally adjust what visual characteristics to highlgiht.
+
+```python
+from browzarr import Browzarr
+
+bz = Browzarr(dataset="path://some-zarr-store", variable="temperature")
+```
+
+### Constructor fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `dataset` | `str` | *(required)* | Zarr store path or NetCDF `.nc` / `.nc4` / `.netcdf` file. |
+| `variable` | `str` | *(required)* | The variable name to visualize. |
+| `variable2` | `str` | None | The name of a second variable for bivariate plotting. |
+| `share_scale` | `str` | `false` | Whether both variables use the same scale/units. |
+| `x_slice` | `tuple[int, int \| None]` | `(0, None)` | X-axis slice (start, stop). `None` means "to the end". |
+| `y_slice` | `tuple[int, int \| None]` | `(0, None)` | Y-axis slice. |
+| `z_slice` | `tuple[int, int \| None]` | `(0, None)` | Z-axis slice. |
+| `extra_params` | `dict` | `{}` | Additional parameters merged into the plot state (advanced, see [API Reference](/pybrowzarr/api-reference)). |
+
+```python
+# Load only a subset of a large dataset
+bz = Browzarr(
+    dataset="gs://some-zarr-store",
+    variable="temperature",
+    z_slice=(0, 50),
+    y_slice=(10, 200),
+    x_slice=(10, 200),
+)
+```
+
+## 3. Choose a plot type
+
+Pick one plot method to configure the visualization. Each returns the same `Browzarr`
+object so you can keep chaining or store it.
+
+```python
+bz.volume()      # 3D volume render
+# bz.points()    # point cloud
+# bz.flat()      # flat (3D-displaceable) surface
+# bz.sphere()    # globe/sphere
+```
+
+You can pass options directly:
+
+```python
+bz.volume(colormap="inferno", transparency=0.5)
+```
+Options for each plot are found in the [API Reference](/pybrowzarr/api-reference):
+[Common](/pybrowzarr/api-reference#common-options), [Volume](/pybrowzarr/api-reference#volume), [Points](/pybrowzarr/api-reference#points), [Flat & Sphere](/pybrowzarr/api-reference#flat-sphere).
+
+## 4. Launch the plot
+
+```python
+bz.plot()
+```
+
+`plot()` starts (or reuses) a local server and opens the view. Where it appears depends
+on your environment — see [Environments](/pybrowzarr/environment).
+
+### Getting the URL instead of opening a browser
+
+```python
+url = bz.plot(give_url=True)
+print(url)  # https://browzarr.io/latest/?data=...
+```
+Provides a url to the plot that you can open in a browser or share with others. 
+
+## Full example
+
+```python
+from browzarr import Browzarr
+
+Browzarr(
+    dataset="gs://some-zarr-store",
+    variable="temperature",
+    z_slice=(0, 40),
+).volume(
+    colormap="turbo",
+    transparency=0.6,
+    value_range=(270, 310),
+).plot()
+```
+
+## Next steps
+
+- Explore plot-specific options: [Plot Types](/pybrowzarr/api-reference#plot-types)
+- Full API details: [API Reference](/pybrowzarr/api-reference)
+- Export and animate: [Export & Animation](/pybrowzarr/export)

docs/content/4.pyBrowzarr/4.export.md

@@ -0,0 +1,155 @@
+---
+title: Export & Animation
+description: Static image export, video export, and scripted walkthrough keyframes with pyBrowzarr.
+navigation:
+  icon: i-lucide-clapperboard
+---
+
+The `export()` method configures a **static image or animated export** of the current
+plot. Unlike the other plot methods, `export()` immediately calls `.plot()` for you, so
+a single chained call both configures the export and launches the view.
+
+```python
+Browzarr(dataset="gs://store", variable="temp").volume().export(main_title="My Map")
+```
+
+## `export()` signature
+
+```python
+def export(open_browser: bool = True, **kwargs) -> Browzarr
+```
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `open_browser` | `True` | Open the browser/iframe after configuring the export. Pass `False` to configure only. |
+| `**kwargs` | — | Any option listed below. |
+
+::callout{icon="i-lucide-info"}
+All options are optional — only the keys you pass are included in the export config.
+Keys are snake_case in Python and delivered camel-cased to the frontend.
+::
+
+## Image options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `include_background` | `bool` | Include the background. If false then transparent |
+| `main_title` | `str` | Main title drawn on the export. |
+| `custom_res` | `tuple[float, float]` | Custom export resolution `(width, height)` in pixels. |
+| `include_axis` | `bool` | Draw the axes in the export. |
+| `include_colorbar` | `bool` | Draw a colorbar in the export. |
+| **Colorbar Options** |||
+| `cbar_loc` | `str` | Colorbar position (`"left"`, `"right"`, `"top"`, `"bottom"`). |
+| `cbar_num` | `int` | Number of tick marks on the colorbar. |
+| `cbar_label` | `str` | Text label shown on the colorbar. |
+| `cbar_units` | `str` | Units shown alongside the colorbar label. |
+
+```python
+.export(
+    include_background=True,
+    include_colorbar=True,
+    include_axis=False,
+    cbar_loc="right",
+    cbar_num=8,
+    cbar_label="Temperature",
+    cbar_units="K",
+    main_title="July Mean Temperature",
+    custom_res=(1920, 1080),
+)
+```
+
+## Animation options
+
+Enable `animate=True` to produce a video/animation. The following options control how
+the animation is driven.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `animate` | `bool` | Export as animation |
+| `frames` | `int` | Total number of frames to render. |
+| `frame_rate` | `int` | Frames per second (FPS) of the output. |
+| `orbit` | `bool` | Animate a camera orbit around the globe. |
+| `orbit_deg` | `float` | Total degrees of orbit to sweep during the animation duration. |
+| `use_time` | `bool` | Animate the time/Z-axis along with the animation. |
+| `time_rate` | `int` | Time playback rate (FPS) to play slower or faster than camera FPS. |
+| `loop_time` | `bool` | Loop the time axis back to the start when it reaches the end. |
+
+```python
+.export(
+    animate=True,
+    frames=120,
+    frame_rate=30,
+    use_time=True,
+    time_rate=1.0,
+    loop_time=True,
+)
+```
+
+### Camera orbit example
+
+```python
+.export(
+    animate=True,
+    frames=180,
+    frame_rate=30,
+    orbit=True,
+    orbit_deg=360.0,
+)
+```
+
+## Keyframes
+
+For a fully scripted camera/visual walkthrough, pass `keyframes` as a dict (or point to
+a file with `keyframes_path`). Each keyframe maps a frame number to a `visual` and
+`camera` state, and an optional `time`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `keyframes` | `object` | A dict of keyframes. When provided, it is written to a `keyframes.json` file and that path is passed to the frontend. |
+| `keyframes_path` | `str` | Path to an existing keyframes JSON file to use instead of passing `keyframes` inline. |
+
+```python
+from browzarr import Browzarr
+
+keyframes = {
+    "0": {
+        "visual": {"transparency": 0.0, "valueRange": [0, 1], "nanTransparency": 1},
+        "camera": {
+            "position": {"x": -4.5, "y": 2.4, "z": 4.8},
+            "rotation": {"isEuler": True, "_x": -0.46, "_y": -0.70, "_z": -0.31, "_order": "XYZ"},
+        },
+        "time": 0,
+    },
+    "31": {
+        "visual": {"transparency": 0.0, "valueRange": [0, 1], "nanTransparency": 1},
+        "camera": {
+            "position": {"x": 2.2, "y": 2.9, "z": 6.0},
+            "rotation": {"isEuler": True, "_x": -0.44, "_y": 0.32, "_z": 0.15, "_order": "XYZ"},
+        },
+        "time": 0,
+    },
+}
+
+Browzarr(dataset="gs://store", variable="temperature").volume().export(
+    animate=True,
+    frames=60,
+    frame_rate=30,
+    keyframes=keyframes,
+)
+```
+
+Or reference a file on disk:
+
+```python
+Browzarr(dataset="gs://store", variable="temperature").volume().export(
+    animate=True,
+    frames=60,
+    frame_rate=30,
+    keyframes_path=r"C:\path\to\keyframes.json",
+)
+```
+
+::callout{icon="i-lucide-shield-alert"}
+The `keyframes`/`keyframes_path` options are mutually exclusive — provide one or the
+other, not both.
+::