webknossos.dataset.mag_view ¶

MagView ¶

MagView(layer: Layer, mag: Mag, path: Path, read_only: bool = False)

Bases: View

A view of a specific magnification level within a WEBKNOSSOS layer.

MagView provides access to volumetric data at a specific resolution/magnification level. It supports reading, writing, and processing operations on the underlying data, with coordinates automatically handled in the correct magnification space.

Key Features

Read/write volumetric data at specific magnification levels
Automatic coordinate transformation between Mag(1) and current magnification
Support for compressed and uncompressed data formats
Chunked processing for efficient memory usage
Downsampling and upsampling capabilities

Attributes:

layer (Layer) –

The parent Layer object this magnification belongs to.
mag (Layer) –

The magnification level (e.g., Mag(1), Mag(2), Mag(4), etc.).
info (Layer) –

Information about array storage (chunk shape, compression, etc.).
path (Path) –

Path to the data on disk.
bounding_box (NDBoundingBox) –

The spatial extent of this magnification in Mag(1) coordinates.
read_only (NDBoundingBox) –

Whether this magnification is read-only.

Examples:

# Create a dataset with a segmentation layer
ds = Dataset("path/to/dataset", voxel_size=(1, 1, 1))
layer = ds.add_layer(
    "segmentation",
    SEGMENTATION_CATEGORY,
    bounding_box=BoundingBox((100, 200, 300), (512, 512, 512)),
)

# Add and work with magnification levels
mag1 = layer.add_mag(Mag(1))
mag2 = layer.add_mag(Mag(2))

# Write data at Mag(1)
mag1.write(data, absolute_offset=(100, 200, 300))

# Read data at Mag(2) - coordinates are in Mag(1) space
data = mag2.read(absolute_offset=(100, 200, 300), size=(512, 512, 512))

# Process data in chunks
def process_chunk(view: View) -> None:
    data = view.read()
    # Process data...
    view.write(processed_data)

mag1.for_each_chunk(process_chunk)

Notes

All offset/size parameters in read/write methods expect Mag(1) coordinates
Use get_view() to obtain restricted views of the data
Compressed data operations may have performance implications
When writing to segmentation layers, update largest_segment_id as needed

bounding_box `property` ¶

bounding_box: NDBoundingBox

Get the spatial extent of this magnification level in Mag(1) coordinates.

Returns:

NDBoundingBox ( NDBoundingBox ) –

The bounding box of this magnification level in Mag(1) coordinates.

Notes

The bounding box is automatically aligned with the magnification level
It represents the overall extent of the data, potentially including empty regions

info `property` ¶

info: ArrayInfo

Get information about the array structure and properties.

Returns:

ArrayInfo ( ArrayInfo ) –

Object containing array metadata such as data type, num_channels, and other array-specific information.

Examples:

view = layer.get_mag("1").get_view(size=(100, 100, 10))
array_info = view.info
print(f"Data type: {array_info.data_type}")
print(f"Num channels: {array_info.num_channels}")

is_foreign `property` ¶

is_foreign: bool

Check if this magnification's data is stored not as part of to the dataset. Returns: bool: True if data is stored in a different location than the parent dataset.

is_remote_to_dataset `property` ¶

is_remote_to_dataset: bool

layer `property` ¶

layer: Layer

Get the parent Layer object.

Returns:

Layer ( Layer ) –

The Layer object that contains this magnification level.

Notes

The Layer provides context about data type, category, and overall properties
Used internally for coordinate transformations and data validation

mag `property` ¶

mag: Mag

Gets the magnification level of this view.

The magnification level determines the resolution at which the data is accessed. A higher magnification number means lower resolution (e.g., mag 2 means every second voxel, mag 4 means every fourth voxel, etc.).

Returns:

Mag ( Mag ) –

The magnification level of this view.

Examples:

view = layer.get_mag("1").get_view(size=(100, 100, 10))
print(f"Current magnification: {view.mag}")

name `property` ¶

name: str

Get the name of this magnification level.

Returns:

str ( str ) –

String representation of the magnification level (e.g., "1-1-1" for Mag(1)).

path `property` ¶

path: Path

Get the path to this magnification level's data.

Returns:

Path ( Path ) –

Path to the data files on disk.

Notes

Path may be local or remote depending on dataset configuration

read_only `property` ¶

read_only: bool

Indicates whether this view is read-only.

When a view is read-only, write operations are not permitted. This property helps prevent accidental modifications to the dataset.

Returns:

bool ( bool ) –

True if the view is read-only, False if write operations are allowed.

Examples:

view = layer.get_mag("1").get_view(size=(100, 100, 10))
if not view.read_only:
    view.write(data)
else:
    print("Cannot modify read-only view")

chunk ¶

chunk(chunk_shape: VecIntLike, chunk_border_alignments: VecIntLike | None = None, read_only: bool = False) -> Generator[View, None, None]

Generate a sequence of sub-views by chunking the current view.

Divides the view into smaller, regularly-sized chunks that can be processed independently. This is useful for parallel processing or when working with large datasets that don't fit in memory.

Parameters:

chunk_shape (VecIntLike) –

Size of each chunk in Mag(1) coordinates.
chunk_border_alignments (VecIntLike | None, default: None ) –

Alignment of chunk borders in Mag(1) coordinates. If None, aligns to (0, 0, 0). Defaults to None.
read_only (bool, default: False ) –

Whether the generated chunks should be read-only. Defaults to False.

Yields:

View ( View ) –

Sub-views representing each chunk of the original view.

Examples:

# let 'mag1' be a `MagView`
chunks = mag1.chunk(chunk_shape=(100, 100, 100), chunk_border_alignments=(50, 50, 50))

compress ¶

compress(*, target_path: str | Path | None = None, executor: Executor | None = None) -> None

Compresses the files on disk.

Compresses the magnification level's data, either in-place or to a new location. Compression can reduce storage space but may impact read/write performance.

Parameters:

target_path (str | Path | None, default: None ) –

Optional path to write compressed data. If None, compresses in-place.
executor (Executor | None, default: None ) –

Optional executor for parallel compression.

Examples:

# Compress in-place
mag1.compress()

Notes

In-place compression requires local filesystem
Remote compression requires target_path
Compression is parallelized when executor is provided
Progress is displayed during compression
Compressed data may have slower read/write speeds

content_is_equal ¶

content_is_equal(other: View, executor: Executor | None = None) -> bool

Compare the content of this view with another view.

Performs a chunk-by-chunk comparison of the data in both views. This is more memory efficient than reading entire views at once for large datasets.

Parameters:

other (View) –

The view to compare against.
executor (Executor | None, default: None ) –

Executor for parallel comparison. If None, compares sequentially. Defaults to None.
progress_desc (str | None) –

Description for progress bar. If None, no progress bar is shown. Defaults to None.

Returns:

bool ( bool ) –

True if the content of both views is identical, False otherwise.

Examples:

# Compare views sequentially
if view1.content_is_equal(view2):
    print("Views are identical")

Note

Comparison is done chunk by chunk to manage memory usage
Views must have the same shape and data type
Returns False immediately if shapes or types don't match
Progress tracks total volume compared
Parallel execution can speed up comparison of large views

create `classmethod` ¶

create(layer: Layer, mag: Mag, *, path: Path, chunk_shape: Vec3Int, shard_shape: Vec3Int | None = None, chunks_per_shard: Vec3Int | None = None, compression_mode: bool, read_only: bool = False) -> MagView

Do not use this constructor manually. Instead use webknossos.dataset.layer.Layer.add_mag().

for_each_chunk ¶

for_each_chunk(func_per_chunk: Callable[[tuple[View, int]], None], chunk_shape: Vec3IntLike | None = None, executor: Executor | None = None, progress_desc: str | None = None) -> None

Process each chunk of the view with a given function.

Divides the view into chunks and applies a function to each chunk, optionally in parallel. This is useful for processing large datasets in manageable pieces, with optional progress tracking and parallel execution.

Parameters:

func_per_chunk (Callable[[tuple[View, int]], None]) –

Function to apply to each chunk. Takes a tuple of (chunk_view, chunk_index) as argument. The chunk_index can be used for progress tracking or logging.
chunk_shape (Vec3IntLike | None, default: None ) –

Size of each chunk in Mag(1) coordinates. If None, uses one chunk per file based on the dataset's file dimensions. Defaults to None.
executor (Executor | None, default: None ) –

Executor for parallel processing. If None, processes chunks sequentially. Defaults to None.
progress_desc (str | None, default: None ) –

Description for progress bar. If None, no progress bar is shown. Defaults to None.

Examples:

from webknossos.utils import named_partial

# Define processing function
def process_chunk(args: tuple[View, int], threshold: float) -> None:
    chunk_view, chunk_idx = args
    data = chunk_view.read()
    # Process data...
    chunk_view.write(processed_data)
    print(f"Processed chunk {chunk_idx}")

# Sequential processing with progress bar
view.for_each_chunk(
    named_partial(process_chunk, threshold=0.5),
    chunk_shape=(64, 64, 64),
    progress_desc="Processing chunks"
)

Note

Each chunk is processed independently, making this suitable for parallel execution
For non-read-only views, chunks must align with file boundaries
Progress tracking shows total volume processed
Memory usage depends on chunk_shape and parallel execution settings
When using an executor, ensure thread/process safety in func_per_chunk
The view's magnification affects the actual data resolution

for_zipped_chunks ¶

for_zipped_chunks(func_per_chunk: Callable[[tuple[View, View, int]], None], target_view: View, source_chunk_shape: Vec3IntLike | None = None, target_chunk_shape: Vec3IntLike | None = None, executor: Executor | None = None, progress_desc: str | None = None) -> None

Process paired chunks from source and target views simultaneously.

Chunks both the source (self) and target views, then applies a function to each corresponding pair of chunks. This is particularly useful for operations that transform data between views of different magnifications, like downsampling.

Parameters:

func_per_chunk (Callable[[tuple[View, View, int]], None]) –

Function to apply to each chunk pair. Takes (source_chunk, target_chunk, index) as arguments.
target_view (View) –

The target view to write transformed data to.
source_chunk_shape (Vec3IntLike | None, default: None ) –

Size of source chunks in Mag(1). If None, uses maximum of source and target file dimensions. Defaults to None.
target_chunk_shape (Vec3IntLike | None, default: None ) –

Size of target chunks in Mag(1). If None, uses maximum of source and target file dimensions. Defaults to None.
executor (Executor | None, default: None ) –

Executor for parallel processing. If None, processes chunks sequentially. Defaults to None.
progress_desc (str | None, default: None ) –

Description for progress bar. If None, no progress bar is shown. Defaults to None.

Examples:

# Downsample data from Mag(1) to Mag(2)
def downsample_chunk(args: tuple[View, View, int]) -> None:
    source_chunk, target_chunk, idx = args
    data = source_chunk.read()
    downsampled = downsample_data(data)  # Your downsampling function
    target_chunk.write(downsampled)
    print(f"Processed chunk pair {idx}")

# Process with default chunk sizes
mag1_view.for_zipped_chunks(
    downsample_chunk,
    mag2_view,
    progress_desc="Downsampling data"
)

Note

Source/target view size ratios must match chunk size ratios
Target chunks must align with file boundaries to avoid concurrent writes
Both views are chunked with matching strides
Progress tracks total volume processed
Memory usage depends on chunk sizes and parallel execution

get_bounding_boxes_on_disk ¶

get_bounding_boxes_on_disk() -> Iterator[NDBoundingBox]

Returns a Mag(1) bounding box for each file on disk.

This method iterates through the actual files stored on disk and returns their bounding boxes. This is different from the layer's bounding box property, which represents the overall extent of the data, potentially including regions without actual data files.

Returns:

Iterator[NDBoundingBox] –

Iterator[NDBoundingBox]: Iterator yielding bounding boxes in Mag(1) coordinates.

Examples:

# Print all data file bounding boxes
for bbox in mag1.get_bounding_boxes_on_disk():
    print(f"Found data file at {bbox}")

# Calculate total data volume
total_volume = sum(bbox.volume() for bbox in mag1.get_bounding_boxes_on_disk())

Notes

Bounding boxes are in Mag(1) coordinates
Some storage formats may not support efficient listing
For unsupported formats, falls back to chunk-based iteration
Useful for understanding actual data distribution on disk

get_buffered_slice_reader ¶

get_buffered_slice_reader(buffer_size: int | None = None, dimension: int = 2, *, relative_bounding_box: NDBoundingBox | None = None, absolute_bounding_box: NDBoundingBox | None = None, use_logging: bool = False) -> BufferedSliceReader

Get a buffered reader for efficiently reading data slices.

Creates a BufferedSliceReader that allows efficient reading of data slices by buffering multiple slices in memory. This is particularly useful when reading large datasets slice by slice.

Parameters:

buffer_size (int, default: None ) –

Number of slices to buffer in memory at once. Defaults to the size of the shard in the dimension.
dimension (int, default: 2 ) –

Axis along which to read slices (0=x, 1=y, 2=z). Defaults to 2 (z-axis).
relative_bounding_box (NDBoundingBox | None, default: None ) –

Bounding box in mag1 coordinates, relative to the current view's offset. Mutually exclusive with absolute_bounding_box. Defaults to None.
absolute_bounding_box (NDBoundingBox | None, default: None ) –

Bounding box in mag1 coordinates in absolute dataset coordinates. Mutually exclusive with relative_bounding_box. Defaults to None.
use_logging (bool, default: False ) –

Whether to enable logging of read operations.

Returns:

BufferedSliceReader ( BufferedSliceReader ) –

A reader object that yields data slices.

Examples:

view = layer.get_mag("1").get_view(size=(100, 100, 10))

# Create a reader with default settings (z-slices)
with view.get_buffered_slice_reader() as reader:
    for slice_data in reader:
        process_slice(slice_data)

# Read y-slices with custom buffer size
with view.get_buffered_slice_reader(
    buffer_size=10,
    dimension=1,  # y-axis
    relative_offset=(10, 0, 0)
) as reader:

Note

Larger buffer sizes improve performance but use more memory
Choose dimension based on your data access pattern
Only one positioning parameter should be specified
The reader can be used as an iterator

get_buffered_slice_writer ¶

get_buffered_slice_writer(buffer_size: int | None = None, dimension: int = 2, *, relative_offset: Vec3IntLike | None = None, absolute_offset: Vec3IntLike | None = None, relative_bounding_box: NDBoundingBox | None = None, absolute_bounding_box: NDBoundingBox | None = None, use_logging: bool = False, allow_unaligned: bool = False) -> BufferedSliceWriter

Get a buffered writer for efficiently writing data slices.

Creates a BufferedSliceWriter that allows efficient writing of data slices by buffering multiple slices before performing the actual write operation.

Parameters:

buffer_size (int, default: None ) –

Number of slices to buffer before performing a write. Defaults to the size of the shard in the dimension.
dimension (int, default: 2 ) –

Axis along which to write slices (0=x, 1=y, 2=z). Defaults to 2 (z-axis).
relative_offset (Vec3IntLike | None, default: None ) –

Offset in mag1 coordinates, relative to the current view's position. Mutually exclusive with absolute_offset. Defaults to None.
absolute_offset (Vec3IntLike | None, default: None ) –

Offset in mag1 coordinates in absolute dataset coordinates. Mutually exclusive with relative_offset. Defaults to None.
relative_bounding_box (NDBoundingBox | None, default: None ) –

Bounding box in mag1 coordinates, relative to the current view's offset. Mutually exclusive with absolute_bounding_box. Defaults to None.
absolute_bounding_box (NDBoundingBox | None, default: None ) –

Bounding box in mag1 coordinates in absolute dataset coordinates. Mutually exclusive with relative_bounding_box. Defaults to None.
use_logging (bool, default: False ) –

Whether to enable logging of write operations. Defaults to False.
allow_unaligned (bool, default: False ) –

Whether to allow unaligned writes. Defaults to False.

Returns:

BufferedSliceWriter ( BufferedSliceWriter ) –

A writer object for buffered slice writing.

Examples:

view = layer.get_mag("1").get_view(size=(100, 100, 10))

# Create a buffered writer with default settings
with view.get_buffered_slice_writer() as writer:
    # Write slices efficiently
    for z in range(10):
        slice_data = np.zeros((100, 100))  # Your slice data
        writer.send(slice_data)

# Create a writer with custom buffer size and offset
with view.get_buffered_slice_writer(
    buffer_size=5,
    relative_offset=(10, 10, 0)
)

Note

Larger buffer sizes can improve performance but use more memory
Remember to use the writer in a context manager
Only one positioning parameter should be specified

get_dtype ¶

get_dtype() -> dtype

Returns the dtype per channel of the data. For example uint8.

get_view ¶

get_view(size: Vec3IntLike | None = None, *, relative_offset: Vec3IntLike | None = None, absolute_offset: Vec3IntLike | None = None, relative_bounding_box: NDBoundingBox | None = None, absolute_bounding_box: NDBoundingBox | None = None, read_only: bool | None = None) -> View

Create a new view restricted to a specified region.

This method returns a new View instance that represents a subset of the current view's data. The new view can be specified using various coordinate systems and can optionally be made read-only.

Parameters:

size (Vec3IntLike | None, default: None ) –

Size of the new view. Must be specified when using any offset parameter. Defaults to None.

relative_offset (Vec3IntLike | None, optional): Offset relative to current
    view's position in Mag(1) coordinates. Must be used with size. Defaults to None.
absolute_offset (Vec3IntLike | None, optional): Absolute offset in Mag(1)
    coordinates. Must be used with size. Defaults to None.
relative_bounding_box (NDBoundingBox | None, optional): Bounding box relative
    to current view's position in Mag(1) coordinates. Defaults to None.
absolute_bounding_box (NDBoundingBox | None, optional): Absolute bounding box
    in Mag(1) coordinates. Defaults to None.
read_only (bool | None, optional): Whether the new view should be read-only.
    If None, inherits from parent view. Defaults to None.

Returns:

View ( View ) –

A new View instance representing the specified region.

Raises:

AssertionError –

If: - Multiple positioning parameters are provided - Size is missing when using offset parameters - Non-read-only subview requested from read-only parent - Non-read-only subview extends beyond parent's bounds

Examples:

# Create view from MagView
mag1 = layer.get_mag("1")
view = mag1.get_view(absolute_offset=(10, 20, 30), size=(100, 200, 300))

# Create subview within bounds
sub_view = view.get_view(
    relative_offset=(50, 60, 70),
    size=(10, 120, 230)
)

# Create read-only subview (can extend beyond bounds)
large_view = view.get_view(
    relative_offset=(50, 60, 70),
    size=(999, 120, 230),
    read_only=True
)

# Use bounding box instead of offset+size
bbox = BoundingBox((10, 10, 0), (50, 50, 10))
bbox_view = view.get_view(relative_bounding_box=bbox)

Note

Use only one method to specify the region (offset+size or bounding_box)
All coordinates are in Mag(1)
Non-read-only views must stay within parent view's bounds
Read-only views can extend beyond parent view's bounds
The view's magnification affects the actual data resolution

get_views_on_disk ¶

get_views_on_disk(read_only: bool | None = None) -> Iterator[View]

Yields a view for each file on disk for efficient parallelization.

Creates View objects that correspond to actual data files on disk. This is particularly useful for parallel processing as each view represents a natural unit of data storage.

Parameters:

read_only (bool | None, default: None ) –

If True, returned views will be read-only. If None, determined by context.

Returns:

Iterator[View] –

Iterator[View]: Iterator yielding View objects for each data file.

Examples:

# Process each data file in parallel
def process_chunk(view: View) -> None:
    data = view.read()
    # Process data...
    if not view.read_only:
        view.write(processed_data)

with get_executor_for_args(None) as executor:
    executor.map(process_chunk, mag1.get_views_on_disk())

Notes

Views correspond to actual files/chunks on disk
Ideal for parallel processing of large datasets
Each view's bounding box aligns with storage boundaries
Memory efficient as only one chunk is loaded at a time

get_zarr_array ¶

get_zarr_array() -> TensorStore

Get direct access to the underlying Zarr array.

Provides direct access to the underlying Zarr array for advanced operations. Only available for Zarr-based datasets.

Returns:

NDArrayLike ( TensorStore ) –

The underlying Zarr array object.

Raises:

ValueError –

If called on a non-Zarr dataset.

Notes

Only works with Zarr-based datasets
Provides low-level access to data storage
Use with caution as it bypasses normal access patterns

map_chunk ¶

map_chunk(func_per_chunk: Callable[[View], Any], chunk_shape: Vec3IntLike | None = None, executor: Executor | None = None, progress_desc: str | None = None) -> list[Any]

Process each chunk of the view and collect results.

Similar to for_each_chunk(), but collects and returns the results from each chunk. Useful for parallel data analysis or feature extraction where results need to be aggregated.

Parameters:

func_per_chunk (Callable[[View], Any]) –

Function to apply to each chunk. Takes a chunk view as argument and returns a result of any type.
chunk_shape (Vec3IntLike | None, default: None ) –

Size of each chunk in Mag(1) coordinates. If None, uses one chunk per file based on the dataset's file dimensions. Defaults to None.
executor (Executor | None, default: None ) –

Executor for parallel processing. If None, processes chunks sequentially. Defaults to None.
progress_desc (str | None, default: None ) –

Description for progress bar. If None, no progress bar is shown. Defaults to None.

Returns:

list[Any] –

list[Any]: List of results from processing each chunk, in chunk order.

Examples:

from webknossos.utils import named_partial

# Calculate statistics per chunk
def chunk_statistics(view: View, min_value: float) -> dict[str, float]:
    data = view.read()
    return {
        "mean": data[data > min_value].mean(),
        "std": data[data > min_value].std(),
        "volume": view.bounding_box.volume()
    }

# Sequential processing
stats = view.map_chunk(
    named_partial(chunk_statistics, min_value=0.1),
    chunk_shape=(128, 128, 128)
)

# Aggregate results
total_volume = sum(s["volume"] for s in stats)
mean_values = [s["mean"] for s in stats]

Note

Results are collected in memory, consider memory usage for large datasets
Each chunk is processed independently, suitable for parallel execution
For non-read-only views, chunks must align with file boundaries
When using an executor, ensure thread/process safety in func_per_chunk
Results maintain chunk order regardless of execution order

merge_chunk ¶

merge_chunk(args: tuple[MagView, NDBoundingBox, list[NDBoundingBox]]) -> None

Merge a single chunk during parallel merge operations.

Internal method used by merge_with_view() for parallel processing. Merges data from another view into this one for a specific chunk region.

Parameters:

args (tuple[MagView, NDBoundingBox, list[NDBoundingBox]]) –

Tuple containing: - other (MagView): Source view to merge from - shard (NDBoundingBox): Target shard region - bboxes (list[NDBoundingBox]): List of source bounding boxes

merge_with_view ¶

merge_with_view(other: MagView, executor: Executor) -> None

Merges data from another view into this one.

Combines data from another MagView into this one, using this view's data as the base and overlaying the other view's data where present. This is particularly useful for merging annotations or overlays.

Parameters:

other (MagView) –

The MagView to merge into this one.
executor (Executor) –

Executor for parallel merging operations.

Notes

Both views must have same magnification
Other view must have file_len = 1
Both views must have same voxel type
Merging is parallelized using the provided executor
Updates layer bounding box if necessary

read ¶

read(size: Vec3IntLike | None = None, *, relative_offset: Vec3IntLike | None = None, absolute_offset: Vec3IntLike | None = None, relative_bounding_box: NDBoundingBox | None = None, absolute_bounding_box: NDBoundingBox | None = None) -> ndarray

Read data from the view at a specified location.

This method provides flexible ways to read data from the view's region. If no parameters are provided, it reads the entire view's bounding box. The region to read can be specified using either offset+size combinations or bounding boxes.

Parameters:

size (Vec3IntLike | None, default: None ) –

Size of region to read. Specified in Mag(1) coordinates. Defaults to None.
relative_offset (Vec3IntLike | None, default: None ) –

Offset relative to the view's position in Mag(1) coordinates. Must be used with size. Defaults to None.
absolute_offset (Vec3IntLike | None, default: None ) –

Absolute offset in Mag(1) coordinates. Must be used with size. Defaults to None.
relative_bounding_box (NDBoundingBox | None, default: None ) –

Bounding box relative to the view's position in Mag(1) coordinates. Defaults to None.
absolute_bounding_box (NDBoundingBox | None, default: None ) –

Absolute bounding box in Mag(1) coordinates. Defaults to None.

Returns:

ndarray –

np.ndarray: The requested data as a numpy array. The shape will be either (channels, x, y, z) for multi-channel data or (x, y, z) for single-channel data. Areas outside the dataset are zero-padded.

Raises:

AssertionError –

If incompatible parameters are provided (e.g., both offset+size and bounding_box) or if the requested region is empty.

Examples:

# Read entire view's data
view = layer.get_mag("1").get_view(size=(100, 100, 10))
data = view.read()  # Returns (x, y, z) array for single-channel data

# Read with relative offset and size
data = view.read(
    relative_offset=(10, 10, 0),  # Offset from view's position
    size=(50, 50, 10)            # Size in Mag(1) coordinates
)

# Read with absolute bounding box
bbox = BoundingBox((0, 0, 0), (100, 100, 10))
data = view.read(absolute_bounding_box=bbox)

# Read from multi-channel data
view = color_layer.get_mag("1").get_view(size=(100, 100, 10))
data = view.read()  # Returns (channels, x, y, z) array

Note

Use only one method to specify the region (offset+size or bounding_box)
All coordinates are in Mag(1)
For multi-channel data, the returned array has shape (C, X, Y, Z)
For single-channel data, the returned array has shape (X, Y, Z)
Regions outside the dataset are automatically zero-padded
The view's magnification affects the actual data resolution
Data shape must match the target region size

read_xyz ¶

read_xyz(relative_bounding_box: NDBoundingBox | None = None, absolute_bounding_box: NDBoundingBox | None = None) -> ndarray

Read n-dimensional data and convert it to 3D XYZ format.

This method is designed for handling n-dimensional data (n > 3) and converting it to strictly 3D data ordered as (X, Y, Z). It is primarily used internally by operations that require 3D data like downsampling, upsampling, and compression.

When provided with a BoundingBox where additional dimensions (beyond X, Y, Z) have a shape of 1, it returns an array containing only the 3D spatial data. This ensures compatibility with operations that expect purely 3-dimensional input.

Parameters:

relative_bounding_box (NDBoundingBox | None, default: None ) –

Bounding box relative to view's position in Mag(1) coordinates. Defaults to None.
absolute_bounding_box (NDBoundingBox | None, default: None ) –

Absolute bounding box in Mag(1) coordinates. Defaults to None.

Returns:

ndarray –

np.ndarray: The requested data as a numpy array with dimensions ordered as (channels, X, Y, Z) for multi-channel data or (X, Y, Z) for single-channel data. Areas outside the dataset are zero-padded.

Examples:

# Read entire view's data in XYZ order
view = layer.get_mag("1").get_view(size=(100, 100, 10))
xyz_data = view.read_xyz()  # Returns (X, Y, Z) array

# Read with relative bounding box
bbox = NDBoundingBox((10, 10, 0), (50, 50, 10), axis=("x", "y", "z"), index=(1, 2, 3))
xyz_data = view.read_xyz(relative_bounding_box=bbox)

Note

If no bounding box is provided, reads the entire view's region
Only one bounding box parameter should be specified
The returned array's axes are ordered differently from read()
All coordinates are in Mag(1)

write ¶

write(data: ndarray, *, allow_resize: bool = False, allow_unaligned: bool = False, relative_offset: Vec3IntLike | None = None, absolute_offset: Vec3IntLike | None = None, relative_bounding_box: NDBoundingBox | None = None, absolute_bounding_box: NDBoundingBox | None = None) -> None

Write volumetric data to the magnification level.

This method writes numpy array data to the dataset at the specified location. All offset and bounding box coordinates are expected to be in Mag(1) space, regardless of the current magnification level.

Parameters:

data (ndarray) –

The data to write. For 3D data, shape should be (x, y, z). For multi-channel 3D data, shape should be (channels, x, y, z). For n-dimensional data, the axes must match the bounding box axes of the layer. Shape must match the target region size.
allow_resize (bool, default: False ) –

If True, allows updating the layer's bounding box if the write extends beyond it. Must not be set to True, when writing to the same magnification level in parallel. For one-off writes, consider using Dataset.write_layer. Defaults to False.
allow_unaligned (bool, default: False ) –

If True, allows writing data to without being aligned to the shard shape. Defaults to False.
relative_offset (Vec3IntLike | None, default: None ) –

Offset relative to view's position in Mag(1) coordinates. Defaults to None.
absolute_offset (Vec3IntLike | None, default: None ) –

Absolute offset in Mag(1) coordinates. Defaults to None.
relative_bounding_box (NDBoundingBox | None, default: None ) –

Bounding box relative to view's position in Mag(1) coordinates. Defaults to None.
absolute_bounding_box (NDBoundingBox | None, default: None ) –

Absolute bounding box in Mag(1) coordinates. Defaults to None.

Examples:

# Write data at absolute position
mag1.write(data, absolute_offset=(100, 200, 300))

# Write using bounding box
bbox = BoundingBox((0, 0, 0), (100, 100, 100))
mag2.write(data, absolute_bounding_box=bbox)

Notes

At least one of offset/bounding_box parameters must be provided
Data shape must match the target region size
Coordinates are automatically scaled based on magnification
For compressed data, writing may be slower due to compression
Large writes may temporarily increase memory usage

webknossos.dataset.mag_view ¶

MagView ¶

bounding_box property ¶

info property ¶

is_foreign property ¶

is_remote_to_dataset property ¶

layer property ¶

mag property ¶

name property ¶

path property ¶

read_only property ¶

chunk ¶

compress ¶

content_is_equal ¶

create classmethod ¶

for_each_chunk ¶

for_zipped_chunks ¶

get_bounding_boxes_on_disk ¶

get_buffered_slice_reader ¶

get_buffered_slice_writer ¶

get_dtype ¶

get_view ¶

get_views_on_disk ¶

get_zarr_array ¶

map_chunk ¶

merge_chunk ¶

merge_with_view ¶

read ¶

read_xyz ¶

write ¶

bounding_box `property` ¶

info `property` ¶

is_foreign `property` ¶

is_remote_to_dataset `property` ¶

layer `property` ¶

mag `property` ¶

name `property` ¶

path `property` ¶

read_only `property` ¶

create `classmethod` ¶