API Reference

This page documents the public, user-facing API. Everything lives under the browzarr package.

Exports

from browzarr import Browzarr, build_browzarr, update_browzarr, main

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

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.

bz = Browzarr(dataset="gs://store", variable="temp")
bz.extra_params["myCustomOption"] = True

Plot methods

Each of these records the plot configuration and returns self, so calls can be chained or stored.

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 and the plot-type-specific sections below for the accepted keyword arguments.

bz = Browzarr(dataset="gs://store", variable="temp")
bz.volume(transparency=0.5).points(point_size=3)   # points() wins — last call

Export method

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 for the accepted keyword arguments.

Browzarr(dataset="gs://store", variable="temp").volume().export(
    main_title="My Map",
    animate=True,
    frames=120,
    frame_rate=30,
)

plot()

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.

Return value: the URL string when give_url=True, otherwise None.

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.

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		Corner color of the bivariate colormap (bottom left).
top_left	str		Corner color of the bivariate colormap (top left).
bottom_right	str		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 above for how pass-through keyword arguments are merged into the final plot state.

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:

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, volume() accepts the following volume-specific keyword arguments. Unset options fall back to the frontend's default state, listed below.

points()

The points plot renders the variable as a high-density interactive 3D point cloud. It is selected with the points() method:

from browzarr import Browzarr

Browzarr(dataset="gs://some-zarr-store", variable="temperature").points(
    point_size=3,
).plot()

In addition to the common options, points() accepts the following point-specific keyword arguments. Unset options fall back to the frontend's default state, listed below.

flat() - sphere()

Both the Flatmap and Sphere renderes present a 2D slice/representation of data that can be displaced in 3D.

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, 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()

flat() only

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:

from browzarr.api import BrowzarrSession

BrowzarrSession.shutdown()

Module functions

build_browzarr()

Rebuilds the bundled frontend distribution from the upstream source.

from browzarr import build_browzarr

build_browzarr()

Requires pnpm 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.

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:

browzarr