Skip to content

webknossos.dataset

CorruptImageError 

CorruptImageError(
    message: str, *, path: UPath | None = None
)

Bases: ImageConversionError

Raised when a file of a supported format cannot be read.

The reader recognized the format but could not make sense of the contents, which in practice almost always means the file is damaged or was uploaded incompletely. The underlying reader error is kept as the __cause__, which belongs in a log rather than in a user-facing message.

Missing files and permission errors are deliberately not reported this way: those keep raising FileNotFoundError/PermissionError.

path instance-attribute 

path = path

ImageConversionError 

ImageConversionError(
    message: str, *, path: UPath | None = None
)

Bases: ValueError

Base class for the ways image conversion can fail because of its input.

Raised by Dataset.from_images and Dataset.add_layer_from_images.

Attributes:

  • path –

    The offending input path, if there is a single one. None when the images were passed as a list, or when the failure is not tied to one file.

path instance-attribute 

path = path

UnsupportedImageDataError 

UnsupportedImageDataError(
    message: str, *, path: UPath | None = None
)

Bases: ImageConversionError

Raised when readable image data cannot be stored as requested.

The file itself is fine — its data does not fit the target, e.g. a segmentation layer with a non-integer dtype, an image with more axes than the chosen data_format supports, or a dimensionality no reader can map to a layer. The message names what to change; unlike a CorruptImageError, these are usually fixable by converting with different arguments.

path instance-attribute 

path = path

UnsupportedImageFormatError 

UnsupportedImageFormatError(
    message: str,
    *,
    path: UPath | None = None,
    file_extension: str | None = None,
    supported_file_extensions: tuple[str, ...] = (),
    found_file_extensions: tuple[str, ...] | None = None,
    missing_extras: tuple[str, ...] = ()
)

Bases: ImageConversionError

Raised when image data cannot be converted because no reader handles its format.

Raised either because the input contains no file with a supported extension, or because every reader failed to recognize the file.

Attributes:

  • path –

    The offending input path, if there is a single one. None when the images were passed as a list.

  • file_extension –

    The offending file's extension — lowercase, without the leading dot (e.g. "dcm"). None when path is a directory or unknown.

  • supported_file_extensions –

    The extensions that can currently be converted, in the same lowercase, dot-less form.

  • found_file_extensions –

    The extensions actually present in the input, in the same lowercase, dot-less form, most common first. For a directory this is what it contains, which is what names the offending format when file_extension is None; for a single file it is just that file's extension. Empty when nothing was found, e.g. for an empty directory.

  • missing_extras –

    The webknossos extras that would add support for the input at hand, e.g. ("ims",) when converting an .ims file without webknossos[ims] installed. Empty when the format is not supported at all — which is the distinction to make when turning this exception into a user-facing message: a non-empty value means the format is supported and the installation is incomplete.

Examples:

try:
    wk.Dataset.from_images(input_path, output_path, voxel_size=(1, 1, 1))
except wk.UnsupportedImageFormatError as e:
    if e.missing_extras:
        print(f"Install webknossos[{','.join(e.missing_extras)}] to convert this file.")
    elif e.found_file_extensions:
        found = ", ".join("." + s for s in e.found_file_extensions)
        print(f"Cannot convert {found} files.")

file_extension instance-attribute 

file_extension = file_extension

found_file_extensions instance-attribute 

found_file_extensions = (
    found_file_extensions
    if found_file_extensions is not None
    else (
        (file_extension,)
        if file_extension is not None
        else ()
    )
)

missing_extras instance-attribute 

missing_extras = missing_extras

path instance-attribute 

path = path

supported_file_extensions instance-attribute 

supported_file_extensions = supported_file_extensions