From 6867c7b550574bff350bc674d7823bea2b2531df Mon Sep 17 00:00:00 2001 From: Jeran Date: Wed, 30 Sep 2026 14:56:05 +0200 Subject: [PATCH] browzarr-docs --- docs/content/1.getting-started/3.landing.md | 4 +- docs/content/2.Menus/.navigation.yml | 1 + .../1.dataset-loading.md | 0 .../2.variable-selection.md | 0 .../3.plot-types.md} | 0 .../3.colorbar.md => 2.Menus/4.colorbar.md} | 0 .../5.plot-settings.md} | 0 .../5.analytics.md => 2.Menus/6.analytics.md} | 2 +- docs/content/2.essentials/.navigation.yml | 1 - docs/content/3.guides/5.performance-mode.md | 28 -- docs/content/4.pyBrowzarr/.navigation.yml | 2 + docs/content/4.pyBrowzarr/1.overview.md | 52 +++ docs/content/4.pyBrowzarr/2.quickstart.md | 108 ++++++ docs/content/4.pyBrowzarr/4.export.md | 155 +++++++++ docs/content/4.pyBrowzarr/5.environment.md | 85 +++++ .../4.pyBrowzarr/6.build-and-update.md | 86 +++++ docs/content/4.pyBrowzarr/7.api-reference.md | 315 ++++++++++++++++++ .../.navigation.yml | 0 .../2.supported-formats.md | 0 .../3.browser-support.md | 0 .../4.troubleshooting.md | 0 .../{4.reference => 6.reference}/5.faq.md | 0 docs/nuxt.config.ts | 14 + 23 files changed, 821 insertions(+), 32 deletions(-) create mode 100644 docs/content/2.Menus/.navigation.yml rename docs/content/{2.essentials => 2.Menus}/1.dataset-loading.md (100%) rename docs/content/{2.essentials => 2.Menus}/2.variable-selection.md (100%) rename docs/content/{4.reference/1.plot-types.md => 2.Menus/3.plot-types.md} (100%) rename docs/content/{2.essentials/3.colorbar.md => 2.Menus/4.colorbar.md} (100%) rename docs/content/{2.essentials/4.plot-settings.md => 2.Menus/5.plot-settings.md} (100%) rename docs/content/{2.essentials/5.analytics.md => 2.Menus/6.analytics.md} (97%) delete mode 100644 docs/content/2.essentials/.navigation.yml delete mode 100644 docs/content/3.guides/5.performance-mode.md create mode 100644 docs/content/4.pyBrowzarr/.navigation.yml create mode 100644 docs/content/4.pyBrowzarr/1.overview.md create mode 100644 docs/content/4.pyBrowzarr/2.quickstart.md create mode 100644 docs/content/4.pyBrowzarr/4.export.md create mode 100644 docs/content/4.pyBrowzarr/5.environment.md create mode 100644 docs/content/4.pyBrowzarr/6.build-and-update.md create mode 100644 docs/content/4.pyBrowzarr/7.api-reference.md rename docs/content/{4.reference => 6.reference}/.navigation.yml (100%) rename docs/content/{4.reference => 6.reference}/2.supported-formats.md (100%) rename docs/content/{4.reference => 6.reference}/3.browser-support.md (100%) rename docs/content/{4.reference => 6.reference}/4.troubleshooting.md (100%) rename docs/content/{4.reference => 6.reference}/5.faq.md (100%) diff --git a/docs/content/1.getting-started/3.landing.md b/docs/content/1.getting-started/3.landing.md index bfd651b8..d4a1c9c1 100644 --- a/docs/content/1.getting-started/3.landing.md +++ b/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 diff --git a/docs/content/2.Menus/.navigation.yml b/docs/content/2.Menus/.navigation.yml new file mode 100644 index 00000000..312f0eaf --- /dev/null +++ b/docs/content/2.Menus/.navigation.yml @@ -0,0 +1 @@ +title: Menus diff --git a/docs/content/2.essentials/1.dataset-loading.md b/docs/content/2.Menus/1.dataset-loading.md similarity index 100% rename from docs/content/2.essentials/1.dataset-loading.md rename to docs/content/2.Menus/1.dataset-loading.md diff --git a/docs/content/2.essentials/2.variable-selection.md b/docs/content/2.Menus/2.variable-selection.md similarity index 100% rename from docs/content/2.essentials/2.variable-selection.md rename to docs/content/2.Menus/2.variable-selection.md diff --git a/docs/content/4.reference/1.plot-types.md b/docs/content/2.Menus/3.plot-types.md similarity index 100% rename from docs/content/4.reference/1.plot-types.md rename to docs/content/2.Menus/3.plot-types.md diff --git a/docs/content/2.essentials/3.colorbar.md b/docs/content/2.Menus/4.colorbar.md similarity index 100% rename from docs/content/2.essentials/3.colorbar.md rename to docs/content/2.Menus/4.colorbar.md diff --git a/docs/content/2.essentials/4.plot-settings.md b/docs/content/2.Menus/5.plot-settings.md similarity index 100% rename from docs/content/2.essentials/4.plot-settings.md rename to docs/content/2.Menus/5.plot-settings.md diff --git a/docs/content/2.essentials/5.analytics.md b/docs/content/2.Menus/6.analytics.md similarity index 97% rename from docs/content/2.essentials/5.analytics.md rename to docs/content/2.Menus/6.analytics.md index 7c6da76f..bc06ee91 100644 --- a/docs/content/2.essentials/5.analytics.md +++ b/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 --- diff --git a/docs/content/2.essentials/.navigation.yml b/docs/content/2.essentials/.navigation.yml deleted file mode 100644 index b82ae3f5..00000000 --- a/docs/content/2.essentials/.navigation.yml +++ /dev/null @@ -1 +0,0 @@ -title: Essentials diff --git a/docs/content/3.guides/5.performance-mode.md b/docs/content/3.guides/5.performance-mode.md deleted file mode 100644 index a772ea00..00000000 --- a/docs/content/3.guides/5.performance-mode.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Performance mode -description: Smoother interaction with very large datasets. -navigation: - icon: i-ic-outline-rocket-launch ---- - - - -## What it changes - -Performance mode (rocket icon in the floating menu) trades visual fidelity for responsiveness — e.g. coarser rendering during interaction, fewer on-screen elements, reduced texture resolution — so panning/zooming stays smooth on large cubes. - -## When to use it - -- Exploring variables with millions of cells or many time steps -- On machines with modest GPU/CPU headroom -- While recording animations of big datasets (fewer dropped frames) - -## Memory - -Browzarr caches fetched chunks in an LRU memory cache to avoid re-downloading. If you jump around a huge time axis, the cache evicts the oldest chunks; performance mode reduces the per-frame footprint so more chunks fit. - -## Tips for very large datasets - -- Subset with the [variable sliders](/essentials/variable-selection) before plotting -- Prefer re-chunked stores (chunks aligned to your typical slice pattern) -- Close other GPU-heavy tabs — the browser shares one GPU budget diff --git a/docs/content/4.pyBrowzarr/.navigation.yml b/docs/content/4.pyBrowzarr/.navigation.yml new file mode 100644 index 00000000..8bf9c940 --- /dev/null +++ b/docs/content/4.pyBrowzarr/.navigation.yml @@ -0,0 +1,2 @@ +title: pyBrowzarr +icon: false diff --git a/docs/content/4.pyBrowzarr/1.overview.md b/docs/content/4.pyBrowzarr/1.overview.md new file mode 100644 index 00000000..9bee10b4 --- /dev/null +++ b/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()` | diff --git a/docs/content/4.pyBrowzarr/2.quickstart.md b/docs/content/4.pyBrowzarr/2.quickstart.md new file mode 100644 index 00000000..eac0f8e1 --- /dev/null +++ b/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) diff --git a/docs/content/4.pyBrowzarr/4.export.md b/docs/content/4.pyBrowzarr/4.export.md new file mode 100644 index 00000000..9e427e0a --- /dev/null +++ b/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. +:: diff --git a/docs/content/4.pyBrowzarr/5.environment.md b/docs/content/4.pyBrowzarr/5.environment.md new file mode 100644 index 00000000..b356491f --- /dev/null +++ b/docs/content/4.pyBrowzarr/5.environment.md @@ -0,0 +1,85 @@ +--- +title: Environments +description: How pyBrowzarr opens the Browzarr view in terminal, Jupyter, VS Code, and Colab. +navigation: + icon: i-lucide-monitor +--- + +`plot()` detects where your code is running and opens the Browzarr view in the most +convenient place for that environment. You rarely need to do anything — but here is what +happens in each context, and how to override it. + +## How detection works + +When you call `.plot()`, the library checks, in order: + +1. **`give_url=True`** — skip opening anything; just return the hosted URL string. +2. **`external_browser=True`** — always open in your OS default browser. +3. **Jupyter / JupyterLab** — embed the view as an inline `IFrame` in the notebook output. +4. **VS Code** — open the view in VS Code's built-in **Simple Browser** tab (via the + `code` CLI). Falls back to an external browser if the Simple Browser can't open. +5. **Google Colab** — serve the local port as an inline iframe via + `output.serve_kernel_port_as_iframe`. +6. **Otherwise** — open in the OS default browser (with a note printed that the + environment wasn't recognized). + +## Behavior per environment + +### Jupyter / JupyterLab + +The view is rendered inline in the cell output using an `IFrame`. Size it with +`width`/`height`: + +```python +bz.plot(width=900, height=600) +``` + +### VS Code + +If not using Jupyter within VS Code, plotting opens in the built-in Simple Browser tab, so the view stays inside the editor. This +requires the `code` CLI to be on your `PATH` (it is, by default, in a VS Code +installation). If it can't open, it falls back to the external browser. + +### Google Colab + +Uses the Colab kernel to serve the local port as an inline iframe, so the view appears +inside the notebook without opening a new tab. + +### Plain terminal / script + +Opens your OS default web browser at the local server URL. + +## Controlling where it opens + +### `plot()` arguments + +| Argument | Effect | +|----------|--------| +| `give_url=True` | Return the hosted `https://browzarr.io/latest/?...` URL instead of opening anything. | +| `external_browser=True` | Force the OS browser, bypassing all detection. | +| `width`, `height` | Iframe size in Jupyter/Colab. | +| `wait` | Seconds to wait before opening (default `0.3`), so the server is ready. | + +```python +# Just get a shareable URL +url = bz.plot(give_url=True) +print(url) + +# Always use the OS browser, even in a notebook +bz.plot(external_browser=True) +``` + +## Local server & ports + +- A **single local HTTP server** is shared across all `Browzarr` objects in a process. + Repeated `.plot()` calls reuse it rather than spawning duplicates. +- The server binds to `localhost` and picks the **first free port starting at 8765**. + Browsers treat `localhost` as a secure context, which WebGPU requires — so no HTTPS + or certificate setup is needed. +- To stop the shared server and free its port, call: + +```python +from browzarr.api import BrowzarrSession + +BrowzarrSession.shutdown() +``` diff --git a/docs/content/4.pyBrowzarr/6.build-and-update.md b/docs/content/4.pyBrowzarr/6.build-and-update.md new file mode 100644 index 00000000..1fc12d4a --- /dev/null +++ b/docs/content/4.pyBrowzarr/6.build-and-update.md @@ -0,0 +1,86 @@ +--- +title: Build & Update +description: Update or rebuild the Browzarr frontend bundled with the pyBrowzarr package. +navigation: + icon: i-lucide-refresh-cw +--- + +The `browzarr` package ships with a **pre-built** copy of the Browzarr web frontend in +`web/dist`. That build is static — to pick up new features or fixes from the upstream +[Browzarr](https://github.com/EarthyScience/Browzarr) project, rebuild or update it. + +There are two ways to do this, each suited to a different situation. + +## `update_browzarr()` — quick prebuilt update (preferred) + +Downloads a pre-built distribution from the upstream `python-dist` branch and swaps it +into the package. This is fast (no compile step) and the recommended way to stay current. + +```python +from browzarr import update_browzarr + +update_browzarr() +``` + +What it does: + +1. Downloads the `python-dist` tarball from GitHub. +2. Extracts it to a temporary directory. +3. Replaces the package's `web/dist` folder with the new build. + +Requires an internet connection and write access to the package's data directory. + +## `build_browzarr()` — rebuild from source + +Compiles the frontend from the latest upstream `main` source. Use this when you want the +very newest code or are contributing to the frontend itself. + +```python +from browzarr import build_browzarr + +build_browzarr() +``` + +What it does: + +1. Downloads the latest source from the upstream `main` branch. +2. Runs `pnpm install` and `pnpm run build` in a temporary directory. +3. Copies the built output into the package's `web/dist` folder. + +### Prerequisites + +[pnpm](https://pnpm.io/installation) must be installed and available on your `PATH`. If +it isn't, `build_browzarr()` prints an installation hint and stops: + +``` +pnpm not installed. Install it then run again +https://pnpm.io/installation +``` + +The build is slower than `update_browzarr()` because it compiles the frontend. + +## Troubleshooting + +**`No frontend build found in 'web/dist'`** + +The package was installed without the bundled assets (or they were removed). Run +`update_browzarr()` (fast) or `build_browzarr()` (from source) to populate `web/dist`: + +```python +from browzarr import update_browzarr +update_browzarr() +``` + +**Permission errors when writing `web/dist`** + +Both functions write into the installed package's data directory. Make sure you have +write access to that location, or run in an environment where the package is writable +(e.g. a user site-packages install). + +## Which should I use? + +| Situation | Use | +|-----------|-----| +| Just want the latest stable frontend | `update_browzarr()` | +| Want the newest in-development frontend | `build_browzarr()` | +| Missing `web/dist` after install | `update_browzarr()` | diff --git a/docs/content/4.pyBrowzarr/7.api-reference.md b/docs/content/4.pyBrowzarr/7.api-reference.md new file mode 100644 index 00000000..09afb851 --- /dev/null +++ b/docs/content/4.pyBrowzarr/7.api-reference.md @@ -0,0 +1,315 @@ +--- +title: API Reference +description: Full reference for the pyBrowzarr public API — Browzarr, its methods, module functions, and plot-type options. +navigation: + icon: i-lucide-book-open +--- + +This page documents the public, user-facing API. Everything lives under the `browzarr` +package. + +## Exports + +```python +from browzarr import Browzarr, build_browzarr, update_browzarr, main +``` + +| Name | Kind | Purpose | +|------|------|---------| +| `Browzarr` | class | The user-facing configuration object. | +| `build_browzarr()` | function | Rebuild the bundled frontend from the upstream source. | +| `update_browzarr()` | function | Update the bundled frontend from the prebuilt `python-dist` branch. | +| `main()` | function | Command-line entry point (`browzarr` launcher). | + +## `Browzarr` + +A `Browzarr` object holds the configuration for a single visualization. Set attributes +or pass them as keyword arguments, chain a plot type, then call `.plot()`. + +### Constructor + +```python +Browzarr( + dataset, # str, required + variable, # str, required + x_slice=(0, None), # tuple[int, int | None] + y_slice=(0, None), # tuple[int, int | None] + z_slice=(0, None), # tuple[int, int | None] + extra_params={}, # dict[str, Any] +) +``` + +All fields are also accessible as attributes after construction. + +`extra_params` is a catch-all dictionary that gets merged into the final plot state. +Use it to pass any option not explicitly modeled — keys are camel-cased automatically. + +```python +bz = Browzarr(dataset="gs://store", variable="temp") +bz.extra_params["myCustomOption"] = True +``` + +::callout{icon="i-lucide-shield-alert"} +There is no keyword validation — any unexpected keyword on a plot method is silently +serialized rather than raising. Be careful with typos. +:: + +### Plot methods + +Each of these records the plot configuration and returns `self`, so calls can be chained +or stored. + +```python +def volume(**kwargs) -> Browzarr # 3D volume render +def points(**kwargs) -> Browzarr # point cloud +def flat(**kwargs) -> Browzarr # flat surface (can be displaced) +def sphere(**kwargs) -> Browzarr # globe/sphere +``` + +Only the *last* plot method called takes effect. See the [common options](#common-options) +and the plot-type-specific sections below for the accepted keyword arguments. + +```python +bz = Browzarr(dataset="gs://store", variable="temp") +bz.volume(transparency=0.5).points(point_size=3) # points() wins — last call +``` + +### Export method + +```python +def export(open_browser: bool = True, **kwargs) -> Browzarr +``` + +Configures an export (with optional animation) and immediately launches the plot by +calling `.plot()`. See [Export & Animation](/pyBrowzarr/export) for the accepted keyword +arguments. + +```python +Browzarr(dataset="gs://store", variable="temp").volume().export( + main_title="My Map", + animate=True, + frames=120, + frame_rate=30, +) +``` + +### `plot()` + +```python +def plot( + width=720, + height=720, + give_url: bool = False, + external_browser: bool = False, + wait: float = 0.3, +) -> str | None +``` + +Launches (or reuses) the local Browzarr server and opens the view configured on this +object. + +| Argument | Default | Description | +|----------|---------|-------------| +| `width` | `720` | Iframe width in Jupyter/Colab. | +| `height` | `720` | Iframe height in Jupyter/Colab. | +| `give_url` | `False` | When `True`, returns the hosted URL string instead of opening anything. | +| `external_browser` | `False` | Force opening in an external browser, bypassing environment detection. | +| `wait` | `0.3` | Seconds to wait before opening, so the server is ready. | + +Return value: the URL string when `give_url=True`, otherwise `None`. + +```python +bz.plot() +bz.plot(give_url=True) # -> "https://browzarr.io/latest/?data=..." +bz.plot(width=900, height=600) # larger iframe in notebooks +bz.plot(external_browser=True) # always open in the OS browser +``` + +Where the view opens is auto-detected. See [Environments](/pyBrowzarr/environment). + +## Plot types + +The four plot types below share a common set of options; each also accepts its own +type-specific keyword arguments. Unset options use their default values. + +### Common options + +Every plot method (`volume()`, `points()`, `flat()`, `sphere()`) accepts the keyword +arguments below. + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `colormap` | `str` | `"Spectral"` | Name of the colormap to use (e.g. `"turbo"`, `"inferno"`). | +| `flip_colormap` | `bool` | `false` | Reverse the colormap direction. | +| `bottom_left` | `str` | ![#ffffff](https://img.shields.io/badge/-%23ffffff-ffffff?style=flat-square) | Corner color of the bivariate colormap (bottom left). | +| `top_left` | `str` | ![#2a9d8f](https://img.shields.io/badge/-%232a9d8f-2a9d8f?style=flat-square)| Corner color of the bivariate colormap (top left). | +| `bottom_right` | `str` | ![#e63946](https://img.shields.io/badge/-%23e63946-e63946?style=flat-square) | Corner color of the bivariate colormap (bottom right). | +| `resolution` | `int` | `10` | Resolution of the bivariate colormap texture grid. | +| `mix_mode` | `int` | `2` | Mixing mode of the colormap: `0` = darken, `1` = lighten, `2` = multiply, `3` = difference | +| `bivariate_selection` | `int` | `0` | Which variable to send to the colormap when bivariate and only one value should be shown. | +| `value_range` | `tuple[float, float]` | `(0, 1)` | Fixed `(min, max)` bounds of the color mapping. | +| `show_borders` | `bool` | `false` | Draw country/coastline borders over the plot. | +| `use_border_texture` | `bool` | `false` | Draw the borders into the shaders instead of physical lines | +| `border_width` | `float` | `0.05` | Line width of the borders. (**Requires** *use_border_texture=True*) | +| `border_color` | `str` | `"#000000"` | Border color (CSS color string). | +| `lon_extent` | `tuple[float, float]` | Detects automatically. If fail then --> `(-180, 180)` | Longtude extent of data. | +| `lat_extent` | `tuple[float, float]` | Detects automatically. If fail then --> `(-90, 90)` | Latitude extent of data. | +| `lon_resolution` | `float` | Detects automatically. If fail then --> `1` | Grid resolution (degrees). | +| `lat_resolution` | `float` | Detects automatically. If fail then --> `1` | Grid resolution (degrees)g. | +| `interp_pixels` | `bool` | `false` | Interpolate between pixels for smoother rendering. | +| `use_ortho` | `bool` | `false` | Use an orthographic camera. | +| `fill_value` | `float` | `None` | Value to treat as the data fill/missing value. | +| `mask_feature` | `Literal[0, 1, 2]` | `0` | Mask by geographic feature: `0` = no mask, `1` = mask land, `2` = mask ocean. | +| `mask_value` | `float` | `None` | Value to mask out. | +| `camera_position` | `Vector3` | `[0, 0, 5]` | Camera position `{x, y, z}`. | +| `native_CRS` | `str` | `None` | Native CRS of the data (used for reprojection). | +| `dest_CRS` | `str` | `None` | Target CRS to reproject to. When both CRS options are set, reprojection is enabled. | + +See [`extra_params`](#constructor) above for how pass-through keyword arguments are +merged into the final plot state. + +```python +from browzarr import Browzarr + +Browzarr(dataset="gs://some-zarr-store", variable="temperature").volume( + colormap="inferno", + transparency=0.5, + value_range=(270, 310), +).plot() +``` + +### volume() + +The volume plot renders the variable as a 3D volumetric data cube. It is selected with +the `volume()` method: + +```python +from browzarr import Browzarr + +Browzarr(dataset="gs://some-zarr-store", variable="temperature").volume( + colormap="turbo", + transparency=0.6, + value_range=(270, 310), +).plot() +``` + +In addition to the [common options](#common-options), `volume()` accepts the following +volume-specific keyword arguments. Unset options fall back to the frontend's default +state, listed below. + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `use_ray_march` | `bool` | `false` | Use Ray Marcher renderer. If false, volume uses DDA render | +| `transparency` | `float` | `0` | Global opacity of the rendered volume, from `0` (opaque) to `1` (fully transparent). | +| `nan_transparency` | `float` | `1` | Opacity applied to cells whose value is missing (NaN / `fill_value`). | +| `quality` | `float` | `200` | The quality of the ray marcher renderer. Higher values mean smaller step-sizes and better visuals. (**Requires** *use_ray_march=True*) | + +### points() + +The points plot renders the variable as a high-density interactive 3D point cloud. It is +selected with the `points()` method: + +```python +from browzarr import Browzarr + +Browzarr(dataset="gs://some-zarr-store", variable="temperature").points( + point_size=3, +).plot() +``` + +In addition to the [common options](#common-options), `points()` accepts the following +point-specific keyword arguments. Unset options fall back to the frontend's default +state, listed below. + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `point_size` | `float` | `5` | Base size of the rendered points. | +| `time_scale` | `float` | `1` | Scaling factor applied to points along the z-axis. Higher values spread them out. | +| `scale_points` | `bool` | `false` | Scale point size with the data value (intensity-scaled points). | +| `scale_intensity` | `float` | `1` | How exaggerated point scaling is. | + +### flat() - sphere() + +Both the Flatmap and Sphere renderes present a 2D slice/representation of data that can be displaced in 3D. + +```python +from browzarr import Browzarr + +Browzarr(dataset="gs://some-zarr-store", variable="temperature").flat().plot() +Browzarr(dataset="gs://some-zarr-store", variable="temperature").sphere().plot() +``` + +In addition to the [common options](#common-options), `flat()` and `sphere()` accept the +keyword arguments below. Unset options fall back to the frontend's default state, listed +below. + +#### Shared by `flat()` and `sphere()` + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `displace_faces` | `bool` | `false` | Displace the individual faces according to the data values. | +| `displacement` | `float` | `0` | Magnitude of the vertical displacement of the surface/faces. | +| `offset_negatives` | `bool` | `true` | Offset negative values so the surface is not displaced below the base plane/globe. | + +#### `flat()` only + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `rotate_flat` | `bool` | `false` | Rotate the flat surface to face up along the Y-axis. | + +## Session lifecycle + +### `BrowzarrSession.shutdown()` + +A single local server is shared across all `Browzarr` instances in the same process, so +repeated `.plot()` calls reuse it instead of spawning duplicates. + +To stop the shared server and free its port: + +```python +from browzarr.api import BrowzarrSession + +BrowzarrSession.shutdown() +``` + +## Module functions + +### `build_browzarr()` + +Rebuilds the bundled frontend distribution from the upstream source. + +```python +from browzarr import build_browzarr + +build_browzarr() +``` + +Requires [pnpm](https://pnpm.io/installation) on your `PATH`. + +1. Downloads the latest source from the `main` branch of the upstream repo. +2. Runs `pnpm install` and `pnpm run build`. +3. Replaces `web/dist` with the freshly built output. + +The build output is written in the package data directory, which requires write access. + +### `update_browzarr()` + +Updates the bundled frontend from the upstream prebuilt `python-dist` branch — faster +than a full source rebuild. + +```python +from browzarr import update_browzarr + +update_browzarr() +``` + +Downloads the tarball, extracts it, and replaces `web/dist`. + +### `main()` + +The command-line entry point registered as the `browzarr` console script. Run it from a +terminal: + +```bash +browzarr +``` diff --git a/docs/content/4.reference/.navigation.yml b/docs/content/6.reference/.navigation.yml similarity index 100% rename from docs/content/4.reference/.navigation.yml rename to docs/content/6.reference/.navigation.yml diff --git a/docs/content/4.reference/2.supported-formats.md b/docs/content/6.reference/2.supported-formats.md similarity index 100% rename from docs/content/4.reference/2.supported-formats.md rename to docs/content/6.reference/2.supported-formats.md diff --git a/docs/content/4.reference/3.browser-support.md b/docs/content/6.reference/3.browser-support.md similarity index 100% rename from docs/content/4.reference/3.browser-support.md rename to docs/content/6.reference/3.browser-support.md diff --git a/docs/content/4.reference/4.troubleshooting.md b/docs/content/6.reference/4.troubleshooting.md similarity index 100% rename from docs/content/4.reference/4.troubleshooting.md rename to docs/content/6.reference/4.troubleshooting.md diff --git a/docs/content/4.reference/5.faq.md b/docs/content/6.reference/5.faq.md similarity index 100% rename from docs/content/4.reference/5.faq.md rename to docs/content/6.reference/5.faq.md diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts index fafc09a0..f81f3da2 100644 --- a/docs/nuxt.config.ts +++ b/docs/nuxt.config.ts @@ -14,6 +14,20 @@ export default defineNuxtConfig({ llms: false, + content: { + build: { + markdown: { + highlight: { + langs: [ + 'bash', 'diff', 'json', 'js', 'ts', 'html', 'css', + 'vue', 'shell', 'mdc', 'md', 'yaml', + 'python', + ], + }, + }, + }, + }, + // Nitro static build config nitro: { preset: 'static',