webknossos.dataset ¶

RemoteSegmentationLayer ¶

RemoteSegmentationLayer(
    dataset: RemoteDataset,
    properties: SegmentationLayerProperties,
    read_only: bool,
)

Bases: AbstractSegmentationLayer[RemoteAttachments], RemoteLayer

attachments `property` ¶

attachments: AttachmentsTypeT

Access, add and remove the attachments of this layer.

Attachments are additional files that can be attached to a segmentation layer. They can be used to store additional information, such as meshes, agglomerations, segment indices, cumsums and connectomes.

Examples:

# Add a mesh attachment to the segmentation layer
layer.attachments.add_attachment_as_ref(
    MeshAttachment.from_path_and_name(
        mesh_path, "meshfile", data_format=AttachmentDataFormat.Zarr3
    )
)

# Access the mesh attachment path
layer.attachments.meshes[0].path

# Remove the mesh attachment
layer.attachments.delete_attachment(layer.attachments.meshes[0])

bounding_box `property` `writable` ¶

bounding_box: NDBoundingBox

Gets the bounding box encompassing this layer's data.

Returns:

NDBoundingBox ( NDBoundingBox ) –

Bounding box with layer dimensions

category `property` ¶

category: LayerCategoryType

coordinate_transformations `property` `writable` ¶

coordinate_transformations: tuple[
    CoordinateTransformation, ...
]

Gets the coordinate transformations that place this layer into the coordinate space of its dataset.

The transformations are applied in order. They only affect how WEBKNOSSOS renders the layer, the voxel data itself is not modified.

Returns:

tuple[CoordinateTransformation, ...] –

tuple[CoordinateTransformation, ...]: The transformations, empty if there are none.

data_format `property` ¶

data_format: DataFormat

Gets the data storage format used by this layer.

Returns:

DataFormat ( DataFormat ) –

Format used to store data

Raises:

AssertionError –

If data_format is not set in properties

dataset `property` ¶

dataset: RemoteDataset

default_view_configuration `property` `writable` ¶

default_view_configuration: LayerViewConfiguration | None

Gets the default view configuration for this layer.

Returns:

LayerViewConfiguration | None –

LayerViewConfiguration | None: View configuration if set, otherwise None

dtype `property` ¶

dtype: dtype

Gets the data type used per channel.

Returns:

dtype –

np.dtype: NumPy data type for individual channels

dtype_per_channel `property` ¶

dtype_per_channel: dtype

Deprecated. Use dtype instead. Gets the data type used per channel.

Returns:

dtype –

np.dtype: NumPy data type for individual channels

largest_segment_id `property` `writable` ¶

largest_segment_id: int | None

Gets the largest segment ID present in the data.

The largest segment ID is the highest numerical identifier assigned to any segment in this layer. This is useful for: - Allocating new segment IDs - Validating segment ID ranges - Optimizing data structures

Returns:

int | None –

int | None: The highest segment ID present, or None if no segments exist

mags `property` ¶

mags: Mapping[Mag, MagView]

Getter for dictionary containing all mags.

name `property` `writable` ¶

name: str

Returns the name of the layer.

normalized_bounding_box `property` ¶

normalized_bounding_box: NormalizedBoundingBox

Gets the bounding box with axes normalized to include the channel dimension.

Returns:

NormalizedBoundingBox ( NormalizedBoundingBox ) –

Bounding box with channel axis included

num_channels `property` ¶

num_channels: int

Gets the number of channels in this layer.

Returns:

int ( int ) –

Number of channels

Raises:

AssertionError –

If num_channels is not set in properties

read_only `property` ¶

read_only: bool

Whether this layer is read-only.

Returns:

bool ( bool ) –

True if layer is read-only, False if writable

view_configuration `property` `writable` ¶

view_configuration: LayerViewConfiguration | None

The current view configuration for this layer as stored on the WEBKNOSSOS server.

This reflects the user-saved view settings (color, opacity, intensity range, etc.) and is distinct from default_view_configuration, which is default for all users accessing the dataset properties. The value is fetched from the server on every access.

Returns:

LayerViewConfiguration | None –

LayerViewConfiguration | None: The saved view configuration, or None if none is set.

Examples:

cfg = layer.view_configuration
if cfg is not None:
    print(cfg.color, cfg.alpha)

add_mag_as_copy ¶

add_mag_as_copy(
    foreign_mag_view_or_path: (
        PathLike | UPath | str | MagView
    ),
    *,
    extend_layer_bounding_box: bool = True,
    transfer_mode: TransferMode = COPY,
    common_storage_path_prefix: str | None = None,
    overwrite_pending: bool = True
) -> MagView[RemoteLayer]

Copies the data at foreign_mag_view_or_path which can belong to another dataset to the current remote dataset. Additionally, the relevant information from the datasource-properties.json of the other dataset are copied, too.

add_mag_as_ref ¶

add_mag_as_ref(
    foreign_mag_view_or_path: (
        PathLike | UPath | str | MagView
    ),
    *,
    mag: MagLike | None = None,
    extend_layer_bounding_box: bool = True
) -> MagView[RemoteLayer]

Add a mag from another remote dataset by reference.

Creates a mag that references data from a foreign remote layer without copying it.

Parameters:

foreign_mag_view_or_path (PathLike | UPath | str | MagView) –

Foreign mag to add (path or MagView object)
mag (MagLike | None, default: None ) –

Target mag level; uses the foreign mag level if None
extend_layer_bounding_box (bool, default: True ) –

If True, extends this layer's bounding box to include the foreign layer's bounding box

Returns:

MagView ( MagView[RemoteLayer] ) –

The newly created mag view referencing the foreign data

Raises:

ValueError –

If the foreign mag belongs to a local layer or a different WEBKNOSSOS instance

as_segmentation_layer ¶

as_segmentation_layer() -> RemoteSegmentationLayer

Casts into SegmentationLayer.

delete_mag ¶

delete_mag(mag: MagLike) -> None

download_mesh ¶

download_mesh(
    segment_id: int,
    output_dir: PathLike | UPath | str,
    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: Vec3IntLike | None = None,
    token: str | None = None,
    sharing_token: str | None = None,
) -> UPath

downsample ¶

downsample(
    *,
    from_mag: Mag | None = None,
    coarsest_mag: Mag | None = None,
    interpolation_mode: str = "default",
    compress: bool | Zarr3Config = True,
    sampling_mode: str | SamplingModes = ANISOTROPIC,
    align_with_other_layers: bool = True,
    buffer_shape: Vec3IntLike | int | None = None,
    chunk_shape: Vec3IntLike | int | None = None,
    shard_shape: Vec3IntLike | int | None = None,
    force_sampling_scheme: bool = False,
    transfer_mode: TransferMode = COPY,
    common_storage_path_prefix: str | None = None,
    overwrite_pending: bool = True,
    executor: Executor | None = None
) -> None

Downsample data from a source magnification to coarser magnifications.

Downsamples the data starting from from_mag until a magnification is >= max(coarsest_mag). Different sampling modes control how dimensions are downsampled.

Note that the data is written temporarily on the local disk and uploaded afterwards so some local disk space is required.

Parameters:

from_mag (Mag | None, default: None ) –

Source magnification to downsample from. Defaults to highest existing mag.
coarsest_mag (Mag | None, default: None ) –

Target magnification to stop at. Defaults to calculated value.
interpolation_mode (str, default: 'default' ) –

Interpolation method to use. Defaults to "default". Supported modes: "median", "mode", "nearest", "bilinear", "bicubic"
compress (bool | Zarr3Config, default: True ) –

Whether to compress the generated magnifications. For Zarr3 datasets, codec configuration and chunk key encoding may also be supplied. Defaults to True.
sampling_mode (str | SamplingModes, default: ANISOTROPIC ) –

How dimensions should be downsampled. Defaults to ANISOTROPIC.
align_with_other_layers (bool, default: True ) –

Whether to align the mag selection with the dataset’s other layers. True by default.
buffer_shape (Vec3IntLike | int | None, default: None ) –

Shape of processing buffer. Defaults to None.
chunk_shape (Vec3IntLike | int | None, default: None ) –

Shape of chunks for storage.
shard_shape (Vec3IntLike | int | None, default: None ) –

Shape of shards for storage.
force_sampling_scheme (bool, default: False ) –

Force invalid sampling schemes. Defaults to False.
common_storage_path_prefix (str | None, default: None ) –

Optional path prefix used when transfer_mode is either COPY or MOVE_AND_SYMLINK to select one of the available WEBKNOSSOS storages.
executor (Executor | None, default: None ) –

Executor for parallel processing. None by default.

Raises:

AssertionError –

If from_mag does not exist
RuntimeError –

If sampling scheme produces invalid magnifications
AttributeError –

If sampling_mode is invalid

get_finest_mag ¶

get_finest_mag() -> MagView[RemoteLayer]

get_mag ¶

get_mag(mag: MagLike) -> MagView[RemoteLayer]

refresh_largest_segment_id ¶

refresh_largest_segment_id(
    *,
    chunk_shape: Vec3Int | None = None,
    executor: Executor | None = None
) -> None

Updates largest_segment_id based on actual data content.

Scans through the data to find the highest segment ID value. Sets to None if data is empty.

Parameters:

chunk_shape (Vec3Int | None, default: None ) –

Shape of chunks for processing
executor (Executor | None, default: None ) –

Executor for parallel processing

upsample ¶

upsample(
    from_mag: Mag,
    *,
    finest_mag: Mag = Mag(1),
    compress: bool | Zarr3Config = True,
    sampling_mode: str | SamplingModes = ANISOTROPIC,
    align_with_other_layers: bool = True,
    buffer_shape: Vec3IntLike | None = None,
    transfer_mode: TransferMode = COPY,
    common_storage_path_prefix: str | None = None,
    overwrite_pending: bool = True,
    executor: Executor | None = None
) -> None

Upsample data to finer magnifications.

Upsamples from a coarser magnification to a sequence of finer magnifications, stopping at finest_mag. The data is written temporarily on the local disk and uploaded afterwards, so some local disk space is required.

Parameters:

from_mag (Mag) –

Source coarse magnification.
finest_mag (Mag, default: Mag(1) ) –

Target finest magnification. Defaults to Mag(1).
compress (bool | Zarr3Config, default: True ) –

Whether to compress upsampled data. For Zarr3 datasets, codec configuration and chunk key encoding may also be supplied. Defaults to True.
sampling_mode (str | SamplingModes, default: ANISOTROPIC ) –

How dimensions should be upsampled. Defaults to ANISOTROPIC.
align_with_other_layers (bool, default: True ) –

Whether to align mags with the dataset's other layers. Defaults to True.
buffer_shape (Vec3IntLike | None, default: None ) –

Shape of processing buffer. Defaults to None.
transfer_mode (TransferMode, default: COPY ) –

How new mags are transferred to the remote storage. Defaults to COPY.
common_storage_path_prefix (str | None, default: None ) –

Optional path prefix used when transfer_mode is COPY or MOVE_AND_SYMLINK.
overwrite_pending (bool, default: True ) –

If there are already pending/unfinished committed mags on the server, overwrite them. Defaults to True.
executor (Executor | None, default: None ) –

Executor for parallel processing. Defaults to None.

Raises:

KeyError –

If from_mag doesn't exist is invalid.
AssertionError –

If finest_mag is invalid.
AttributeError –

If sampling_mode is invalid.

webknossos.dataset ¶

RemoteSegmentationLayer ¶

attachments property ¶

bounding_box property writable ¶

category property ¶

coordinate_transformations property writable ¶

data_format property ¶

dataset property ¶

default_view_configuration property writable ¶

dtype property ¶

dtype_per_channel property ¶

largest_segment_id property writable ¶

mags property ¶

name property writable ¶

normalized_bounding_box property ¶

num_channels property ¶

read_only property ¶

view_configuration property writable ¶

add_mag_as_copy ¶

add_mag_as_ref ¶

as_segmentation_layer ¶

delete_mag ¶

download_mesh ¶

downsample ¶

get_finest_mag ¶

get_mag ¶

refresh_largest_segment_id ¶

upsample ¶

attachments `property` ¶

bounding_box `property` `writable` ¶

category `property` ¶

coordinate_transformations `property` `writable` ¶

data_format `property` ¶

dataset `property` ¶

default_view_configuration `property` `writable` ¶

dtype `property` ¶

dtype_per_channel `property` ¶

largest_segment_id `property` `writable` ¶

mags `property` ¶

name `property` `writable` ¶

normalized_bounding_box `property` ¶

num_channels `property` ¶

read_only `property` ¶

view_configuration `property` `writable` ¶