webknossos.dataset.remote_dataset ¶

RemoteDataset ¶

RemoteDataset(
    zarr_streaming_path: UPath | None,
    dataset_properties: DatasetProperties | None,
    dataset_id: str,
    context: webknossos_context,
    read_only: bool,
)

Bases: AbstractDataset[RemoteLayer, RemoteSegmentationLayer]

A representation of a dataset managed by a WEBKNOSSOS server.

This class is returned from RemoteDataset.open() and provides read-only access to image data streamed from the webknossos server. It uses the same interface as Dataset but additionally allows metadata manipulation through properties.

Properties

metadata: Dataset metadata as key-value pairs name: Human readable name description: Dataset description tags: Dataset tags is_public: Whether dataset is public sharing_token: Dataset sharing token allowed_teams: Teams with dataset access folder: Dataset folder location

Examples:

Opening a remote dataset with organization ID:

ds = RemoteDataset.open("my_dataset", "org_id")

Opening with dataset URL:

ds = RemoteDataset.open("https://webknossos.org/datasets/org/dataset/view")

Setting metadata:

ds.metadata = {"key": "value", "tags": ["tag1", "tag2"]}
ds.name = "My_Dataset"
ds.allowed_teams = [Team.get_by_name("Lab_A")]

Note

Do not instantiate directly, use RemoteDataset.open() or RemoteDataset.open_remote instead.

Initialize a remote dataset instance.

Parameters:

zarr_streaming_path (UPath | None) –

Path to the zarr streaming directory
dataset_properties (DatasetProperties | None) –

Properties of the remote dataset
dataset_id (str) –

dataset id of the remote dataset
context (webknossos_context) –

Context manager for WEBKNOSSOS connection

Raises:

FileNotFoundError –

If dataset cannot be opened as zarr format and no metadata exists

Note

Do not call this constructor directly, use RemoteDataset.open() instead. This class provides access to remote WEBKNOSSOS datasets with additional metadata manipulation.

allowed_teams `property` `writable` ¶

allowed_teams: tuple[Team, ...]

Teams that are allowed to access this dataset.

Controls which teams have read access to view and use this dataset. Changes are immediately synchronized with WEBKNOSSOS.

Returns:

tuple[Team, ...] –

tuple[Team, ...]: Teams currently having access

Examples:

from webknossos import Team
team = Team.get_by_name("Lab_A")
ds.allowed_teams = [team]
print([t.name for t in ds.allowed_teams])

# Give access to multiple teams:
ds.allowed_teams = [
    Team.get_by_name("Lab_A"),
    Team.get_by_name("Lab_B")
]

Note

Teams must be from the same organization as the dataset
Can be set using Team objects or team ID strings
An empty list makes the dataset private

created `property` ¶

created: str

Creation date of the dataset.

Returns:

str ( str ) –

Date and time when dataset was created

dataset_id `property` ¶

dataset_id: str

default_view_configuration `property` `writable` ¶

default_view_configuration: DatasetViewConfiguration | None

Default view configuration for this dataset in webknossos.

Controls how the dataset is displayed in webknossos when first opened by a user, including position, zoom level, rotation etc.

Returns:

DatasetViewConfiguration | None –

DatasetViewConfiguration | None: Current view configuration if set

Examples:

ds.default_view_configuration = DatasetViewConfiguration(
    zoom=1.5,
    position=(100, 100, 100)
)

description `deletable` `property` `writable` ¶

description: str | None

Free-text description of the dataset.

Can be edited with markdown formatting. Changes are immediately synchronized with WEBKNOSSOS.

Returns:

str | None –

str | None: Current description if set, None otherwise

Examples:

ds.description = "Dataset acquired on *June 1st*"
ds.description = None  # Remove description

display_name `property` `writable` ¶

display_name: str

Deprecated, please use name. The human-readable name for the dataset in the webknossos interface.

Changes are immediately synchronized with WEBKNOSSOS.

Returns:

str –

str | None: Current display name if set, None otherwise

Examples:

remote_ds.name = "Mouse Brain Sample A"

folder `property` `writable` ¶

folder: RemoteFolder

The (virtual) folder containing this dataset in WEBKNOSSOS.

Represents the folder location in the WEBKNOSSOS UI folder structure. Can be changed to move the dataset to a different folder. Changes are immediately synchronized with WEBKNOSSOS.

Returns:

RemoteFolder ( RemoteFolder ) –

Current folder containing the dataset

Examples:

folder = RemoteFolder.get_by_path("Datasets/Published")
ds.folder = folder
print(ds.folder.path) # 'Datasets/Published'

is_public `property` `writable` ¶

is_public: bool

Control whether the dataset is publicly accessible.

When True, anyone can view the dataset without logging in to WEBKNOSSOS. Changes are immediately synchronized with WEBKNOSSOS.

Returns:

bool ( bool ) –

True if dataset is public, False if private

Examples:

ds.is_public = True
ds.is_public = False
print("Public" if ds.is_public else "Private")  # Private

layers `property` ¶

layers: Mapping[str, LayerType]

Dictionary containing all layers of this dataset.

Returns:

Mapping[str, LayerType] –

dict[str, Layer]: Dictionary mapping layer names to Layer objects

Examples:

for layer_name, layer in ds.layers.items():
   print(layer_name)

metadata `property` `writable` ¶

metadata: DatasetMetadata

Get or set metadata key-value pairs for the dataset.

The metadata can contain strings, numbers, and lists of strings as values. Changes are immediately synchronized with WEBKNOSSOS.

Returns:

DatasetMetadata ( DatasetMetadata ) –

Current metadata key-value pairs

Examples:

ds.metadata = {
    "species": "mouse",
    "age_days": 42,
    "tags": ["verified", "published"]
}
print(ds.metadata["species"])

name `property` `writable` ¶

name: str

The human-readable name for the dataset in the webknossos interface.

Changes are immediately synchronized with WEBKNOSSOS.

Returns:

str –

str | None: Current display name if set, None otherwise

Examples:

remote_ds.name = "Mouse Brain Sample A"

read_only `property` ¶

read_only: bool

Whether this dataset is opened in read-only mode.

When True, operations that would modify the dataset (adding layers, changing properties, etc.) are not allowed and will raise RuntimeError.

Returns:

bool ( bool ) –

True if dataset is read-only, False otherwise

sharing_token `property` ¶

sharing_token: str

Get a new token for sharing access to this dataset.

Each call generates a fresh token that allows viewing the dataset without logging in. The token can be appended to dataset URLs as a query parameter.

Returns:

str ( str ) –

Fresh sharing token for dataset access

Examples:

token = ds.sharing_token
url = f"{ds.url}?token={token}"
print("Share this link:", url)

Note

A new token is generated on each access
The token provides read-only access
Anyone with the token can view the dataset

tags `property` `writable` ¶

tags: tuple[str, ...]

User-assigned tags for organizing and filtering datasets.

Tags allow categorizing and filtering datasets in the webknossos dashboard interface. Changes are immediately synchronized with WEBKNOSSOS.

Returns:

tuple[str, ...] –

tuple[str, ...]: Currently assigned tags, in string tuple form

Examples:

ds.tags = ["verified", "published"]
print(ds.tags)  # ('verified', 'published')
ds.tags = []  # Remove all tags

url `property` ¶

url: str

URL to access this dataset in webknossos.

Constructs the full URL to the dataset in the webknossos web interface.

Returns:

str ( str ) –

Full dataset URL including organization and dataset name

Examples:

print(ds.url) # 'https://webknossos.org/datasets/my_org/my_dataset'

voxel_size `property` ¶

voxel_size: tuple[float, float, float]

Size of each voxel in nanometers along each dimension (x, y, z).

Returns:

tuple[float, float, float] –

tuple[float, float, float]: Size of each voxel in nanometers for x,y,z dimensions

Examples:

vx, vy, vz = ds.voxel_size
print(f"X resolution is {vx}nm")

voxel_size_with_unit `property` ¶

voxel_size_with_unit: VoxelSize

Size of voxels including unit information.

Size of each voxel along each dimension (x, y, z), including unit specification. The default unit is nanometers.

Returns:

VoxelSize ( VoxelSize ) –

Object containing voxel sizes and their units

zarr_streaming_path `instance-attribute` ¶

zarr_streaming_path = zarr_streaming_path

calculate_bounding_box ¶

calculate_bounding_box() -> NDBoundingBox

Calculate the enclosing bounding box of all layers.

Finds the smallest box that contains all data from all layers in the dataset.

Returns:

NDBoundingBox ( NDBoundingBox ) –

Bounding box containing all layer data

Examples:

bbox = ds.calculate_bounding_box()
print(f"Dataset spans {bbox.size} voxels")
print(f"Dataset starts at {bbox.topleft}")

download ¶

download(
    sharing_token: str | None = None,
    bbox: BoundingBox | None = None,
    layers: list[str] | str | None = None,
    mags: list[Mag] | None = None,
    path: PathLike | UPath | str | None = None,
    exist_ok: bool = False,
) -> Dataset

Downloads a dataset and returns the Dataset instance. * sharing_token may be supplied if a dataset name was used and can specify a sharing token. * bbox, layers, and mags specify which parts of the dataset to download. If nothing is specified the whole image, all layers, and all mags are downloaded respectively. * path and exist_ok specify where to save the downloaded dataset and whether to overwrite if the path exists.

download_mesh ¶

download_mesh(
    segment_id: int,
    output_dir: PathLike | UPath | str,
    layer_name: str | None = None,
    mesh_file_name: str | None = None,
    datastore_url: str | None = None,
    lod: int = 0,
    mapping_name: str | None = None,
    mapping_type: (
        Literal["agglomerate", "json"] | None
    ) = None,
    mag: MagLike | None = None,
    seed_position: Vec3Int | None = None,
    token: str | None = None,
) -> UPath

explore_and_add_remote `classmethod` ¶

explore_and_add_remote(
    dataset_uri: str | PathLike | UPath,
    dataset_name: str,
    folder_path: str,
) -> RemoteDataset

Explore and add an external dataset as a remote dataset.

Adds a dataset from an external location (e.g. S3, Google Cloud Storage, or HTTPs) to WEBKNOSSOS by inspecting its layout and metadata without copying the data.

Parameters:

dataset_uri (str | PathLike | UPath) –

URI pointing to the remote dataset location
dataset_name (str) –

Name to register dataset under in WEBKNOSSOS
folder_path (str) –

Path in WEBKNOSSOS folder structure where dataset should appear

Returns:

RemoteDataset ( RemoteDataset ) –

The newly added dataset accessible via WEBKNOSSOS

Examples:

remote = Dataset.explore_and_add_remote(
    "s3://bucket/dataset",
    "my_dataset",
    "Datasets/Research"
)

Note

The dataset files must be accessible from the WEBKNOSSOS server for this to work. The data will be streamed through webknossos from the source.

get_color_layers ¶

get_color_layers() -> list[LayerType]

Get all color layers in the dataset.

Provides access to all layers with category 'color'. Useful when a dataset contains multiple color layers.

Returns:

list[LayerType] –

list[Layer]: List of all color layers in order

Examples:

Print all color layer names:

for layer in ds.get_color_layers():
    print(layer.name)

Note

If you need only a single color layer, consider using get_layer() with the specific layer name instead.

get_layer ¶

get_layer(layer_name: str) -> LayerType

Get a specific layer from this dataset.

Parameters:

layer_name (str) –

Name of the layer to retrieve

Returns:

Layer ( LayerType ) –

The requested layer object

Raises:

IndexError –

If no layer with the given name exists

Examples:

color_layer = ds.get_layer("color")
seg_layer = ds.get_layer("segmentation")

Note

Use layers property to access all layers at once.

get_segmentation_layer ¶

get_segmentation_layer(
    layer_name: str,
) -> SegmentationLayerType

Get a segmentation layer by name.

Parameters:

layer_name (str) –

Name of the layer to get

Returns:

SegmentationLayer ( SegmentationLayerType ) –

The segmentation layer

get_segmentation_layers ¶

get_segmentation_layers() -> list[SegmentationLayerType]

Get all segmentation layers in the dataset.

Provides access to all layers with category 'segmentation'. Useful when a dataset contains multiple segmentation layers.

Returns:

list[SegmentationLayerType] –

list[SegmentationLayer]: List of all segmentation layers in order

Examples:

Print all segmentation layer names:

for layer in ds.get_segmentation_layers():
    print(layer.name)

Note

If you need only a single segmentation layer, consider using get_layer() with the specific layer name instead.

list `classmethod` ¶

list(
    organization_id: str | None = None,
    tags: str | Sequence[str] | None = None,
    name: str | None = None,
    folder_id: RemoteFolder | str | None = None,
) -> Mapping[str, RemoteDataset]

Get all available datasets from the WEBKNOSSOS server.

Returns a mapping of dataset ids to lazy-initialized RemoteDataset objects for all datasets visible to the specified organization or current user. Datasets can be further filtered by tags, name or folder.

Parameters:

organization_id (str | None, default: None ) –

Optional organization to get datasets from. Defaults to organization of logged in user.
tags (str | Sequence[str] | None, default: None ) –

Optional tag(s) to filter datasets by. Can be a single tag string or sequence of tags. Only returns datasets with all specified tags.
name (str | None, default: None ) –

Optional name to filter datasets by. Only returns datasets with matching name.
folder –

Optional folder to filter datasets by. Only returns datasets in the specified folder.

Returns:

Mapping[str, RemoteDataset] –

Mapping[str, RemoteDataset]: Dict mapping dataset ids to RemoteDataset objects

Examples:

List all available datasets:

datasets = RemoteDataset.list()
print(sorted(datasets.keys()))

Get datasets for specific organization:

org_datasets = RemoteDataset.list()("my_organization")
ds = org_datasets["dataset_name"]

Filter datasets by tag:

published = RemoteDataset.list(tags="published")
tagged = RemoteDataset.list(tags=["tag1", "tag2"])

Filter datasets by name:

fun_datasets = RemoteDataset.list(name="MyFunDataset")

Note

RemoteDataset objects are initialized lazily when accessed for the first time. The mapping object provides a fast way to list and look up available datasets.

open `classmethod` ¶

open(
    dataset_name_or_url: str | None = None,
    organization_id: str | None = None,
    sharing_token: str | None = None,
    webknossos_url: str | None = None,
    dataset_id: str | None = None,
    annotation_id: str | None = None,
    use_zarr_streaming: bool = True,
    read_only: bool = False,
) -> RemoteDataset

Opens a remote webknossos dataset. Image data is accessed via network requests. Dataset metadata such as allowed teams or the sharing token can be read and set via the respective RemoteDataset properties.

Parameters:

dataset_name_or_url (str | None, default: None ) –

Either dataset name or full URL to dataset view, e.g. https://webknossos.org/datasets/scalable_minds/l4_sample_dev/view
organization_id (str | None, default: None ) –

Optional organization ID if using dataset name. Can be found here
sharing_token (str | None, default: None ) –

Optional sharing token for dataset access
webknossos_url (str | None, default: None ) –

Optional custom webknossos URL, defaults to context URL, usually https://webknossos.org
dataset_id (str | None, default: None ) –

Optional unique ID of the dataset
annotation_id (str | None, default: None ) –

Optional unique ID of the annotation to stream the data from the annotation.
use_zarr_streaming (bool, default: True ) –

Whether to use zarr streaming

Returns:

RemoteDataset ( RemoteDataset ) –

Dataset instance for remote access

Examples:

ds = RemoteDataset.open("`https://webknossos.org/datasets/scalable_minds/l4_sample_dev/view`")

Note

If supplying an URL, organization_id, webknossos_url and sharing_token must not be set.

trigger_reload_in_datastore `classmethod` ¶

trigger_reload_in_datastore(
    dataset_name_or_url: str | None = None,
    organization_id: str | None = None,
    webknossos_url: str | None = None,
    dataset_id: str | None = None,
    organization: str | None = None,
    token: str | None = None,
    datastore_url: str | None = None,
) -> None

Trigger a manual reload of the dataset's properties.

For manually uploaded datasets, properties are normally updated automatically after a few minutes. This method forces an immediate reload.

This is typically only needed after manual changes to the dataset's files. Cannot be used for local datasets.

Parameters:

dataset_name_or_url (str | None, default: None ) –

Name or URL of dataset to reload
dataset_id (str | None, default: None ) –

ID of dataset to reload
organization_id (str | None, default: None ) –

Organization ID where dataset is located
datastore_url (str | None, default: None ) –

Optional URL to the datastore
webknossos_url (str | None, default: None ) –

Optional URL to the webknossos server
token (str | None, default: None ) –

Optional authentication token

Examples:

# Force reload after manual file changes
Dataset.trigger_reload_in_datastore(
    "my_dataset",
    "organization_id"
)

webknossos.dataset.remote_dataset ¶

RemoteDataset ¶

allowed_teams property writable ¶

created property ¶

dataset_id property ¶

default_view_configuration property writable ¶

description deletable property writable ¶

display_name property writable ¶

folder property writable ¶

is_public property writable ¶

layers property ¶

metadata property writable ¶

name property writable ¶

read_only property ¶

sharing_token property ¶

tags property writable ¶

url property ¶

voxel_size property ¶

voxel_size_with_unit property ¶

zarr_streaming_path instance-attribute ¶

calculate_bounding_box ¶

download ¶

download_mesh ¶

explore_and_add_remote classmethod ¶

get_color_layers ¶

get_layer ¶

get_segmentation_layer ¶

get_segmentation_layers ¶

list classmethod ¶

open classmethod ¶

trigger_reload_in_datastore classmethod ¶

allowed_teams `property` `writable` ¶

created `property` ¶

dataset_id `property` ¶

default_view_configuration `property` `writable` ¶

description `deletable` `property` `writable` ¶

display_name `property` `writable` ¶

folder `property` `writable` ¶

is_public `property` `writable` ¶

layers `property` ¶

metadata `property` `writable` ¶

name `property` `writable` ¶

read_only `property` ¶

sharing_token `property` ¶

tags `property` `writable` ¶

url `property` ¶

voxel_size `property` ¶

voxel_size_with_unit `property` ¶

zarr_streaming_path `instance-attribute` ¶

explore_and_add_remote `classmethod` ¶

list `classmethod` ¶

open `classmethod` ¶

trigger_reload_in_datastore `classmethod` ¶