Skip to content

webknossos.dataset.layer

Layer 

Layer(dataset: Dataset, properties: LayerProperties)

A Layer represents a portion of hierarchical data at multiple magnifications.

A Layer consists of multiple MagViews, which store the same data in different magnifications. Layers are components of a Dataset and provide access to the underlying data arrays.

Attributes:

  • name (str) –

    Name identifier for this layer

  • dataset (Dataset) –

    Parent dataset containing this layer

  • path (Path) –

    Filesystem path to this layer's data

  • category (LayerCategoryType) –

    Category of data (e.g. color, segmentation)

  • dtype_per_layer (str) –

    Data type used for the entire layer

  • dtype_per_channel (dtype) –

    Data type used per channel

  • num_channels (int) –

    Number of channels in the layer

  • data_format (DataFormat) –

    Format used to store the data

  • default_view_configuration (Optional[LayerViewConfiguration]) –

    View configuration

  • read_only (bool) –

    Whether layer is read-only

  • mags (Dict[Mag, MagView]) –

    Dictionary of magnification levels

Parameters:

  • dataset (Dataset) –

    The parent dataset that contains this layer

  • properties (LayerProperties) –

    Properties defining this layer's attributes. Must contain num_channels.

Raises:

  • AssertionError –

    If properties.num_channels is None

Note

Do not use this constructor manually. Instead use Dataset.add_layer() to create a Layer.

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

Gets the category type of this layer.

Returns:

  • LayerCategoryType ( LayerCategoryType ) –

    Layer category (e.g. COLOR_CATEGORY)

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: Dataset

Gets the dataset containing this layer.

Returns:

  • Dataset ( Dataset ) –

    Parent dataset object

default_view_configuration property writable 

default_view_configuration: Optional[LayerViewConfiguration]

Gets the default view configuration for this layer.

Returns:

  • Optional[LayerViewConfiguration] –

    Optional[LayerViewConfiguration]: View configuration if set, otherwise None

dtype_per_channel property 

dtype_per_channel: dtype

Gets the data type used per channel.

Returns:

  • dtype –

    np.dtype: NumPy data type for individual channels

dtype_per_layer property 

dtype_per_layer: str

Gets the data type used for the entire layer.

Returns:

  • str ( str ) –

    Data type string (e.g. "uint8")

is_remote_to_dataset property 

is_remote_to_dataset: bool

Whether this layer's data is stored remotely relative to its dataset.

Returns:

  • bool ( bool ) –

    True if layer path parent differs from dataset path

mags property 

mags: Dict[Mag, MagView]

Getter for dictionary containing all mags.

name property writable 

name: str

Gets the name identifier of this layer.

Returns:

  • str ( str ) –

    Layer name

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

path property 

path: Path

Gets the filesystem path to this layer's data.

The path is determined from the first mag's path parent directory if mags have paths, otherwise uses the dataset path combined with layer name. Remote paths are handled specially.

Returns:

  • Path ( Path ) –

    Filesystem path to this layer's data directory

Raises:

  • AssertionError –

    If mags in layer point to different layers

read_only property 

read_only: bool

Whether this layer is read-only.

Returns:

  • bool ( bool ) –

    True if layer is read-only, False if writable

add_copy_mag 

add_copy_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], extend_layer_bounding_box: bool = True, chunk_shape: Optional[Union[Vec3IntLike, int]] = None, chunks_per_shard: Optional[Union[Vec3IntLike, int]] = None, compress: Optional[bool] = None, executor: Optional[Executor] = None) -> MagView

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

add_existing_remote_mag_view 

add_existing_remote_mag_view(mag_view_maybe: Union[int, str, list, tuple, ndarray, Mag, MagView]) -> MagView

Adds a remote magnification view to this layer.

Links a magnification from a remote dataset into this layer. The remote mag must already exist.

Parameters:

  • mag_view_maybe (Union[int, str, list, tuple, ndarray, Mag, MagView]) –

    Remote magnification to add, as view or identifier

Returns:

  • MagView ( MagView ) –

    View of the added remote magnification

Raises:

  • AssertionError –

    If magnification exists or remote mag invalid

  • ArrayException –

    If remote data cannot be accessed

add_fs_copy_mag 

add_fs_copy_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], extend_layer_bounding_box: bool = True) -> MagView

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

add_mag 

add_mag(mag: Union[int, str, list, tuple, ndarray, Mag], chunk_shape: Optional[Union[Vec3IntLike, int]] = None, chunks_per_shard: Optional[Union[int, Vec3IntLike]] = None, compress: bool = False, *, chunk_size: Optional[Union[Vec3IntLike, int]] = None, block_len: Optional[int] = None, file_len: Optional[int] = None) -> MagView

Creates and adds a new magnification level to the layer.

The new magnification can be configured with various storage parameters to optimize performance, notably chunk_shape, chunks_per_shard and compress. Note that writing compressed data which is not aligned with the blocks on disk may result in diminished performance, as full blocks will automatically be read to pad the write actions. Alternatively, you can call mag.compress() after all the data was written

Parameters:

  • mag (Union[int, str, list, tuple, ndarray, Mag]) –

    Identifier for new magnification level

  • chunk_shape (Optional[Union[Vec3IntLike, int]], default: None ) –

    Shape of chunks for storage. Recommended (32,32,32) or (64,64,64)

  • chunks_per_shard (Optional[Union[int, Vec3IntLike]], default: None ) –

    Number of chunks per shard file

  • compress (bool, default: False ) –

    Whether to enable compression

  • chunk_size (Optional[Union[Vec3IntLike, int]], default: None ) –

    Deprecated, use chunk_shape

  • block_len (Optional[int], default: None ) –

    Deprecated, use chunk_shape

  • file_len (Optional[int], default: None ) –

    Deprecated, use chunks_per_shard

Returns:

  • MagView ( MagView ) –

    View of newly created magnification level

Raises:

  • IndexError –

    If magnification already exists

  • Warning –

    If chunk_shape is not optimal for WEBKNOSSOS performance

add_mag_for_existing_files 

add_mag_for_existing_files(mag: Union[int, str, list, tuple, ndarray, Mag]) -> MagView

Creates a MagView for existing data files.

Adds a magnification level by linking to data files that already exist on the filesystem.

Parameters:

  • mag (Union[int, str, list, tuple, ndarray, Mag]) –

    Identifier for magnification level

Returns:

  • MagView ( MagView ) –

    View of existing magnification data

Raises:

  • AssertionError –

    If magnification already exists in layer

  • ArrayException –

    If files cannot be opened as valid arrays

add_mag_from_zarrarray 

add_mag_from_zarrarray(mag: Union[int, str, list, tuple, ndarray, Mag], path: PathLike, move: bool = False, extend_layer_bounding_box: bool = True) -> MagView

Copies the data at path to the current layer of the dataset via the filesystem and adds it as mag. When move flag is set the array is moved, otherwise a copy of the zarrarray is created.

add_remote_mag 

add_remote_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], extend_layer_bounding_box: bool = True) -> MagView

Adds the mag at foreign_mag_view_or_path which belongs to foreign dataset. The relevant information from the datasource-properties.json of the other dataset is copied to this dataset. Note: If the other dataset modifies its bounding box afterwards, the change does not affect this properties (or vice versa).

add_symlink_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], make_relative: bool = False, extend_layer_bounding_box: bool = True) -> MagView

Creates a symlink to the data at foreign_mag_view_or_path which belongs to another dataset. The relevant information from the datasource-properties.json of the other dataset is copied to this dataset. Note: If the other dataset modifies its bounding box afterwards, the change does not affect this properties (or vice versa). If make_relative is True, the symlink is made relative to the current dataset path. Symlinked mags can only be added to layers on local file systems.

delete_mag 

delete_mag(mag: Union[int, str, list, tuple, ndarray, Mag]) -> None

Deletes the MagView from the datasource-properties.json and the data from disk.

This function raises an IndexError if the specified mag does not exist.

downsample 

downsample(from_mag: Optional[Mag] = None, coarsest_mag: Optional[Mag] = None, interpolation_mode: str = 'default', compress: bool = True, sampling_mode: Union[str, SamplingModes] = ANISOTROPIC, align_with_other_layers: Union[bool, Dataset] = True, buffer_shape: Optional[Vec3Int] = None, force_sampling_scheme: bool = False, args: Optional[Namespace] = None, allow_overwrite: bool = False, only_setup_mags: bool = False, executor: Optional[Executor] = 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.

Parameters:

  • from_mag (Optional[Mag], default: None ) –

    Source magnification to downsample from. Defaults to highest existing mag.

  • coarsest_mag (Optional[Mag], 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, default: True ) –

    Whether to compress the generated magnifications. Defaults to True.

  • sampling_mode (Union[str, SamplingModes], default: ANISOTROPIC ) –

    How dimensions should be downsampled. Defaults to ANISOTROPIC.

  • align_with_other_layers (Union[bool, Dataset], default: True ) –

    Whether to align with other layers. True by default.

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer. Defaults to None.

  • force_sampling_scheme (bool, default: False ) –

    Force invalid sampling schemes. Defaults to False.

  • args (Optional[Namespace], default: None ) –

    Deprecated argument handler.

  • allow_overwrite (bool, default: False ) –

    Whether existing mags can be overwritten. False by default.

  • only_setup_mags (bool, default: False ) –

    Only create mags without data. False by default.

  • executor (Optional[Executor], 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

Examples:

from webknossos import SamplingModes

# let 'layer' be a `Layer` with only `Mag(1)`
assert "1" in self.mags.keys()

layer.downsample(
    coarsest_mag=Mag(4),
    sampling_mode=SamplingModes.ISOTROPIC
)

assert "2" in self.mags.keys()
assert "4" in self.mags.keys()

downsample_mag 

downsample_mag(from_mag: Mag, target_mag: Mag, interpolation_mode: str = 'default', compress: bool = True, buffer_shape: Optional[Vec3Int] = None, args: Optional[Namespace] = None, allow_overwrite: bool = False, only_setup_mag: bool = False, executor: Optional[Executor] = None) -> None

Performs a single downsampling step between magnification levels.

Parameters:

  • from_mag (Mag) –

    Source magnification level

  • target_mag (Mag) –

    Target magnification level

  • interpolation_mode (str, default: 'default' ) –

    Method for interpolation ("median", "mode", "nearest", "bilinear", "bicubic")

  • compress (bool, default: True ) –

    Whether to compress target data

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor

  • allow_overwrite (bool, default: False ) –

    Whether to allow overwriting existing mag

  • only_setup_mag (bool, default: False ) –

    Only create mag without data. This parameter can be used to prepare for parallel downsampling of multiple layers while avoiding parallel writes with outdated updates to the datasource-properties.json file.

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing

Raises:

  • AssertionError –

    If from_mag doesn't exist or target exists without overwrite

downsample_mag_list 

downsample_mag_list(from_mag: Mag, target_mags: List[Mag], interpolation_mode: str = 'default', compress: bool = True, buffer_shape: Optional[Vec3Int] = None, args: Optional[Namespace] = None, allow_overwrite: bool = False, only_setup_mags: bool = False, executor: Optional[Executor] = None) -> None

Downsample data iteratively through multiple magnification levels.

Performs sequential downsampling from from_mag through each magnification in target_mags in order.

Parameters:

  • from_mag (Mag) –

    Source magnification to start from

  • target_mags (List[Mag]) –

    Ordered list of target magnifications

  • interpolation_mode (str, default: 'default' ) –

    Interpolation method to use. Defaults to "default".

  • compress (bool, default: True ) –

    Whether to compress outputs. Defaults to True.

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer.

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor.

  • allow_overwrite (bool, default: False ) –

    Whether to allow overwriting mags. Defaults to False.

  • only_setup_mags (bool, default: False ) –

    Only create mag structures without data. Defaults to False.

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing.

Raises:

  • AssertionError –

    If from_mag doesn't exist or target mags not in ascending order

See downsample_mag() for more details on parameters.

get_best_mag 

get_best_mag() -> MagView

Gets the finest magnification view (deprecated).

Deprecated method name. Please use get_finest_mag() instead.

Returns:

  • MagView ( MagView ) –

    View of finest magnification level.

Deprecated

Use get_finest_mag() instead.

get_finest_mag 

get_finest_mag() -> MagView

Gets the MagView with the finest/smallest magnification.

Returns:

  • MagView ( MagView ) –

    View of data at finest available magnification

get_mag 

get_mag(mag: Union[int, str, list, tuple, ndarray, Mag]) -> MagView

Gets the MagView for the specified magnification level.

Returns a view of the data at the requested magnification level. The mag parameter can be specified in various formats that will be normalized.

Parameters:

  • mag (Union[int, str, list, tuple, ndarray, Mag]) –

    Magnification identifier in multiple formats (int, str, list, etc)

Returns:

  • MagView ( MagView ) –

    View of data at the specified magnification

Raises:

  • IndexError –

    If specified magnification does not exist

get_or_add_mag 

get_or_add_mag(mag: Union[int, str, list, tuple, ndarray, Mag], chunk_shape: Optional[Union[Vec3IntLike, int]] = None, chunks_per_shard: Optional[Union[Vec3IntLike, int]] = None, compress: Optional[bool] = None, *, chunk_size: Optional[Union[Vec3IntLike, int]] = None, block_len: Optional[int] = None, file_len: Optional[int] = None) -> MagView

Creates a new mag and adds it to the dataset, in case it did not exist before. Then, returns the mag.

See add_mag for more information.

redownsample 

redownsample(interpolation_mode: str = 'default', compress: bool = True, buffer_shape: Optional[Vec3Int] = None, args: Optional[Namespace] = None, executor: Optional[Executor] = None) -> None

Recompute all downsampled magnifications from base mag.

Used after modifying data in the base magnification to update all derived magnifications.

Parameters:

  • interpolation_mode (str, default: 'default' ) –

    Method for interpolation

  • compress (bool, default: True ) –

    Whether to compress recomputed data

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing

upsample 

upsample(from_mag: Mag, finest_mag: Mag = Mag(1), compress: bool = False, sampling_mode: Union[str, SamplingModes] = ANISOTROPIC, align_with_other_layers: Union[bool, Dataset] = True, buffer_shape: Optional[Vec3Int] = None, buffer_edge_len: Optional[int] = None, args: Optional[Namespace] = None, executor: Optional[Executor] = None, *, min_mag: Optional[Mag] = None) -> None

Upsample data to finer magnifications.

Upsamples from a coarser magnification to a sequence of finer magnifications, stopping at finest_mag. The sampling mode controls how dimensions are handled.

Parameters:

  • from_mag (Mag) –

    Source coarse magnification

  • finest_mag (Mag, default: Mag(1) ) –

    Target finest magnification (default Mag(1))

  • compress (bool, default: False ) –

    Whether to compress upsampled data. Defaults to False.

  • sampling_mode (Union[str, SamplingModes], default: ANISOTROPIC ) –

    How dimensions should be upsampled: - 'anisotropic': Equalizes voxel dimensions based on voxel_size - 'isotropic': Equal upsampling in all dimensions - 'constant_z': Only upsamples x/y dimensions. z remains unchanged.

  • align_with_other_layers (Union[bool, Dataset], default: True ) –

    Whether to align mags with others. Defaults to True.

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer.

  • buffer_edge_len (Optional[int], default: None ) –

    Deprecated, use buffer_shape.

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor.

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing.

  • min_mag (Optional[Mag], default: None ) –

    Deprecated, use finest_mag.

Raises:

  • AssertionError –

    If from_mag doesn't exist or finest_mag invalid

  • AttributeError –

    If sampling_mode is invalid

SegmentationLayer 

SegmentationLayer(dataset: Dataset, properties: LayerProperties)

Bases: Layer

A specialized Layer subclass for segmentation data.

A SegmentationLayer extends the base Layer class with functionality specific to segmentation data, such as tracking the largest segment ID. The key differences are:

  • Always uses the SEGMENTATION_CATEGORY category type
  • Tracks the largest segment ID present in the data
  • Provides methods for updating the largest segment ID

Attributes:

  • largest_segment_id (Optional[int]) –

    Highest segment ID present in data, or None if empty

  • category (LayerCategoryType) –

    Always SEGMENTATION_CATEGORY for this class

Note

When creating a new SegmentationLayer, use Dataset.add_layer() rather than instantiating directly.

A Layer represents a portion of hierarchical data at multiple magnifications.

A Layer consists of multiple MagViews, which store the same data in different magnifications. Layers are components of a Dataset and provide access to the underlying data arrays.

Attributes:

  • name (str) –

    Name identifier for this layer

  • dataset (Dataset) –

    Parent dataset containing this layer

  • path (Path) –

    Filesystem path to this layer's data

  • category (LayerCategoryType) –

    Category of data (e.g. color, segmentation)

  • dtype_per_layer (str) –

    Data type used for the entire layer

  • dtype_per_channel (dtype) –

    Data type used per channel

  • num_channels (int) –

    Number of channels in the layer

  • data_format (DataFormat) –

    Format used to store the data

  • default_view_configuration (Optional[LayerViewConfiguration]) –

    View configuration

  • read_only (bool) –

    Whether layer is read-only

  • mags (Dict[Mag, MagView]) –

    Dictionary of magnification levels

Parameters:

  • dataset (Dataset) –

    The parent dataset that contains this layer

  • properties (LayerProperties) –

    Properties defining this layer's attributes. Must contain num_channels.

Raises:

  • AssertionError –

    If properties.num_channels is None

Note

Do not use this constructor manually. Instead use Dataset.add_layer() to create a Layer.

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

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: Dataset

Gets the dataset containing this layer.

Returns:

  • Dataset ( Dataset ) –

    Parent dataset object

default_view_configuration property writable 

default_view_configuration: Optional[LayerViewConfiguration]

Gets the default view configuration for this layer.

Returns:

  • Optional[LayerViewConfiguration] –

    Optional[LayerViewConfiguration]: View configuration if set, otherwise None

dtype_per_channel property 

dtype_per_channel: dtype

Gets the data type used per channel.

Returns:

  • dtype –

    np.dtype: NumPy data type for individual channels

dtype_per_layer property 

dtype_per_layer: str

Gets the data type used for the entire layer.

Returns:

  • str ( str ) –

    Data type string (e.g. "uint8")

is_remote_to_dataset property 

is_remote_to_dataset: bool

Whether this layer's data is stored remotely relative to its dataset.

Returns:

  • bool ( bool ) –

    True if layer path parent differs from dataset path

largest_segment_id property writable 

largest_segment_id: Optional[int]

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:

  • Optional[int] –

    Optional[int]: The highest segment ID present, or None if no segments exist

mags property 

mags: Dict[Mag, MagView]

Getter for dictionary containing all mags.

name property writable 

name: str

Gets the name identifier of this layer.

Returns:

  • str ( str ) –

    Layer name

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

path property 

path: Path

Gets the filesystem path to this layer's data.

The path is determined from the first mag's path parent directory if mags have paths, otherwise uses the dataset path combined with layer name. Remote paths are handled specially.

Returns:

  • Path ( Path ) –

    Filesystem path to this layer's data directory

Raises:

  • AssertionError –

    If mags in layer point to different layers

read_only property 

read_only: bool

Whether this layer is read-only.

Returns:

  • bool ( bool ) –

    True if layer is read-only, False if writable

add_copy_mag 

add_copy_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], extend_layer_bounding_box: bool = True, chunk_shape: Optional[Union[Vec3IntLike, int]] = None, chunks_per_shard: Optional[Union[Vec3IntLike, int]] = None, compress: Optional[bool] = None, executor: Optional[Executor] = None) -> MagView

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

add_existing_remote_mag_view 

add_existing_remote_mag_view(mag_view_maybe: Union[int, str, list, tuple, ndarray, Mag, MagView]) -> MagView

Adds a remote magnification view to this layer.

Links a magnification from a remote dataset into this layer. The remote mag must already exist.

Parameters:

  • mag_view_maybe (Union[int, str, list, tuple, ndarray, Mag, MagView]) –

    Remote magnification to add, as view or identifier

Returns:

  • MagView ( MagView ) –

    View of the added remote magnification

Raises:

  • AssertionError –

    If magnification exists or remote mag invalid

  • ArrayException –

    If remote data cannot be accessed

add_fs_copy_mag 

add_fs_copy_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], extend_layer_bounding_box: bool = True) -> MagView

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

add_mag 

add_mag(mag: Union[int, str, list, tuple, ndarray, Mag], chunk_shape: Optional[Union[Vec3IntLike, int]] = None, chunks_per_shard: Optional[Union[int, Vec3IntLike]] = None, compress: bool = False, *, chunk_size: Optional[Union[Vec3IntLike, int]] = None, block_len: Optional[int] = None, file_len: Optional[int] = None) -> MagView

Creates and adds a new magnification level to the layer.

The new magnification can be configured with various storage parameters to optimize performance, notably chunk_shape, chunks_per_shard and compress. Note that writing compressed data which is not aligned with the blocks on disk may result in diminished performance, as full blocks will automatically be read to pad the write actions. Alternatively, you can call mag.compress() after all the data was written

Parameters:

  • mag (Union[int, str, list, tuple, ndarray, Mag]) –

    Identifier for new magnification level

  • chunk_shape (Optional[Union[Vec3IntLike, int]], default: None ) –

    Shape of chunks for storage. Recommended (32,32,32) or (64,64,64)

  • chunks_per_shard (Optional[Union[int, Vec3IntLike]], default: None ) –

    Number of chunks per shard file

  • compress (bool, default: False ) –

    Whether to enable compression

  • chunk_size (Optional[Union[Vec3IntLike, int]], default: None ) –

    Deprecated, use chunk_shape

  • block_len (Optional[int], default: None ) –

    Deprecated, use chunk_shape

  • file_len (Optional[int], default: None ) –

    Deprecated, use chunks_per_shard

Returns:

  • MagView ( MagView ) –

    View of newly created magnification level

Raises:

  • IndexError –

    If magnification already exists

  • Warning –

    If chunk_shape is not optimal for WEBKNOSSOS performance

add_mag_for_existing_files 

add_mag_for_existing_files(mag: Union[int, str, list, tuple, ndarray, Mag]) -> MagView

Creates a MagView for existing data files.

Adds a magnification level by linking to data files that already exist on the filesystem.

Parameters:

  • mag (Union[int, str, list, tuple, ndarray, Mag]) –

    Identifier for magnification level

Returns:

  • MagView ( MagView ) –

    View of existing magnification data

Raises:

  • AssertionError –

    If magnification already exists in layer

  • ArrayException –

    If files cannot be opened as valid arrays

add_mag_from_zarrarray 

add_mag_from_zarrarray(mag: Union[int, str, list, tuple, ndarray, Mag], path: PathLike, move: bool = False, extend_layer_bounding_box: bool = True) -> MagView

Copies the data at path to the current layer of the dataset via the filesystem and adds it as mag. When move flag is set the array is moved, otherwise a copy of the zarrarray is created.

add_remote_mag 

add_remote_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], extend_layer_bounding_box: bool = True) -> MagView

Adds the mag at foreign_mag_view_or_path which belongs to foreign dataset. The relevant information from the datasource-properties.json of the other dataset is copied to this dataset. Note: If the other dataset modifies its bounding box afterwards, the change does not affect this properties (or vice versa).

add_symlink_mag(foreign_mag_view_or_path: Union[PathLike, str, MagView], make_relative: bool = False, extend_layer_bounding_box: bool = True) -> MagView

Creates a symlink to the data at foreign_mag_view_or_path which belongs to another dataset. The relevant information from the datasource-properties.json of the other dataset is copied to this dataset. Note: If the other dataset modifies its bounding box afterwards, the change does not affect this properties (or vice versa). If make_relative is True, the symlink is made relative to the current dataset path. Symlinked mags can only be added to layers on local file systems.

delete_mag 

delete_mag(mag: Union[int, str, list, tuple, ndarray, Mag]) -> None

Deletes the MagView from the datasource-properties.json and the data from disk.

This function raises an IndexError if the specified mag does not exist.

downsample 

downsample(from_mag: Optional[Mag] = None, coarsest_mag: Optional[Mag] = None, interpolation_mode: str = 'default', compress: bool = True, sampling_mode: Union[str, SamplingModes] = ANISOTROPIC, align_with_other_layers: Union[bool, Dataset] = True, buffer_shape: Optional[Vec3Int] = None, force_sampling_scheme: bool = False, args: Optional[Namespace] = None, allow_overwrite: bool = False, only_setup_mags: bool = False, executor: Optional[Executor] = 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.

Parameters:

  • from_mag (Optional[Mag], default: None ) –

    Source magnification to downsample from. Defaults to highest existing mag.

  • coarsest_mag (Optional[Mag], 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, default: True ) –

    Whether to compress the generated magnifications. Defaults to True.

  • sampling_mode (Union[str, SamplingModes], default: ANISOTROPIC ) –

    How dimensions should be downsampled. Defaults to ANISOTROPIC.

  • align_with_other_layers (Union[bool, Dataset], default: True ) –

    Whether to align with other layers. True by default.

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer. Defaults to None.

  • force_sampling_scheme (bool, default: False ) –

    Force invalid sampling schemes. Defaults to False.

  • args (Optional[Namespace], default: None ) –

    Deprecated argument handler.

  • allow_overwrite (bool, default: False ) –

    Whether existing mags can be overwritten. False by default.

  • only_setup_mags (bool, default: False ) –

    Only create mags without data. False by default.

  • executor (Optional[Executor], 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

Examples:

from webknossos import SamplingModes

# let 'layer' be a `Layer` with only `Mag(1)`
assert "1" in self.mags.keys()

layer.downsample(
    coarsest_mag=Mag(4),
    sampling_mode=SamplingModes.ISOTROPIC
)

assert "2" in self.mags.keys()
assert "4" in self.mags.keys()

downsample_mag 

downsample_mag(from_mag: Mag, target_mag: Mag, interpolation_mode: str = 'default', compress: bool = True, buffer_shape: Optional[Vec3Int] = None, args: Optional[Namespace] = None, allow_overwrite: bool = False, only_setup_mag: bool = False, executor: Optional[Executor] = None) -> None

Performs a single downsampling step between magnification levels.

Parameters:

  • from_mag (Mag) –

    Source magnification level

  • target_mag (Mag) –

    Target magnification level

  • interpolation_mode (str, default: 'default' ) –

    Method for interpolation ("median", "mode", "nearest", "bilinear", "bicubic")

  • compress (bool, default: True ) –

    Whether to compress target data

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor

  • allow_overwrite (bool, default: False ) –

    Whether to allow overwriting existing mag

  • only_setup_mag (bool, default: False ) –

    Only create mag without data. This parameter can be used to prepare for parallel downsampling of multiple layers while avoiding parallel writes with outdated updates to the datasource-properties.json file.

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing

Raises:

  • AssertionError –

    If from_mag doesn't exist or target exists without overwrite

downsample_mag_list 

downsample_mag_list(from_mag: Mag, target_mags: List[Mag], interpolation_mode: str = 'default', compress: bool = True, buffer_shape: Optional[Vec3Int] = None, args: Optional[Namespace] = None, allow_overwrite: bool = False, only_setup_mags: bool = False, executor: Optional[Executor] = None) -> None

Downsample data iteratively through multiple magnification levels.

Performs sequential downsampling from from_mag through each magnification in target_mags in order.

Parameters:

  • from_mag (Mag) –

    Source magnification to start from

  • target_mags (List[Mag]) –

    Ordered list of target magnifications

  • interpolation_mode (str, default: 'default' ) –

    Interpolation method to use. Defaults to "default".

  • compress (bool, default: True ) –

    Whether to compress outputs. Defaults to True.

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer.

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor.

  • allow_overwrite (bool, default: False ) –

    Whether to allow overwriting mags. Defaults to False.

  • only_setup_mags (bool, default: False ) –

    Only create mag structures without data. Defaults to False.

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing.

Raises:

  • AssertionError –

    If from_mag doesn't exist or target mags not in ascending order

See downsample_mag() for more details on parameters.

get_best_mag 

get_best_mag() -> MagView

Gets the finest magnification view (deprecated).

Deprecated method name. Please use get_finest_mag() instead.

Returns:

  • MagView ( MagView ) –

    View of finest magnification level.

Deprecated

Use get_finest_mag() instead.

get_finest_mag 

get_finest_mag() -> MagView

Gets the MagView with the finest/smallest magnification.

Returns:

  • MagView ( MagView ) –

    View of data at finest available magnification

get_mag 

get_mag(mag: Union[int, str, list, tuple, ndarray, Mag]) -> MagView

Gets the MagView for the specified magnification level.

Returns a view of the data at the requested magnification level. The mag parameter can be specified in various formats that will be normalized.

Parameters:

  • mag (Union[int, str, list, tuple, ndarray, Mag]) –

    Magnification identifier in multiple formats (int, str, list, etc)

Returns:

  • MagView ( MagView ) –

    View of data at the specified magnification

Raises:

  • IndexError –

    If specified magnification does not exist

get_or_add_mag 

get_or_add_mag(mag: Union[int, str, list, tuple, ndarray, Mag], chunk_shape: Optional[Union[Vec3IntLike, int]] = None, chunks_per_shard: Optional[Union[Vec3IntLike, int]] = None, compress: Optional[bool] = None, *, chunk_size: Optional[Union[Vec3IntLike, int]] = None, block_len: Optional[int] = None, file_len: Optional[int] = None) -> MagView

Creates a new mag and adds it to the dataset, in case it did not exist before. Then, returns the mag.

See add_mag for more information.

redownsample 

redownsample(interpolation_mode: str = 'default', compress: bool = True, buffer_shape: Optional[Vec3Int] = None, args: Optional[Namespace] = None, executor: Optional[Executor] = None) -> None

Recompute all downsampled magnifications from base mag.

Used after modifying data in the base magnification to update all derived magnifications.

Parameters:

  • interpolation_mode (str, default: 'default' ) –

    Method for interpolation

  • compress (bool, default: True ) –

    Whether to compress recomputed data

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing

refresh_largest_segment_id 

refresh_largest_segment_id(chunk_shape: Optional[Vec3Int] = None, executor: Optional[Executor] = 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 (Optional[Vec3Int], default: None ) –

    Shape of chunks for processing

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing

upsample 

upsample(from_mag: Mag, finest_mag: Mag = Mag(1), compress: bool = False, sampling_mode: Union[str, SamplingModes] = ANISOTROPIC, align_with_other_layers: Union[bool, Dataset] = True, buffer_shape: Optional[Vec3Int] = None, buffer_edge_len: Optional[int] = None, args: Optional[Namespace] = None, executor: Optional[Executor] = None, *, min_mag: Optional[Mag] = None) -> None

Upsample data to finer magnifications.

Upsamples from a coarser magnification to a sequence of finer magnifications, stopping at finest_mag. The sampling mode controls how dimensions are handled.

Parameters:

  • from_mag (Mag) –

    Source coarse magnification

  • finest_mag (Mag, default: Mag(1) ) –

    Target finest magnification (default Mag(1))

  • compress (bool, default: False ) –

    Whether to compress upsampled data. Defaults to False.

  • sampling_mode (Union[str, SamplingModes], default: ANISOTROPIC ) –

    How dimensions should be upsampled: - 'anisotropic': Equalizes voxel dimensions based on voxel_size - 'isotropic': Equal upsampling in all dimensions - 'constant_z': Only upsamples x/y dimensions. z remains unchanged.

  • align_with_other_layers (Union[bool, Dataset], default: True ) –

    Whether to align mags with others. Defaults to True.

  • buffer_shape (Optional[Vec3Int], default: None ) –

    Shape of processing buffer.

  • buffer_edge_len (Optional[int], default: None ) –

    Deprecated, use buffer_shape.

  • args (Optional[Namespace], default: None ) –

    Deprecated, use executor.

  • executor (Optional[Executor], default: None ) –

    Executor for parallel processing.

  • min_mag (Optional[Mag], default: None ) –

    Deprecated, use finest_mag.

Raises:

  • AssertionError –

    If from_mag doesn't exist or finest_mag invalid

  • AttributeError –

    If sampling_mode is invalid