WEBKNOSSOS

https://docs.webknossos.org/
Admin
WEBKNOSSOS is an open-source, web-based tool designed for exploring large 3D electron and...
Tokens:256,549
Snippets:2,763
Trust Score:7.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install All Dependencies

Source: https://docs.webknossos.org/webknossos-py/CONTRIBUTING.html

Installs all dependencies for all sub-projects using make. This is a convenient way to set up the development environment.

```bash
make install
```

--------------------------------

### Retrieve Project by ID Example

Source: https://docs.webknossos.org/api/webknossos/administration/project.html

Example demonstrating how to fetch a project by its ID and print its name.

```python
project = Project.get_by_id("project_12345")
print(project.name)
```

--------------------------------

### Install WEBKNOSSOS with Docker Compose

Source: https://docs.webknossos.org/webknossos/open_source/installation.html

This script sets up the necessary directories, downloads the Docker Compose configuration, and starts WEBKNOSSOS with Nginx for HTTPS and automatic SSL certificate management. Ensure you replace placeholder values for DOCKER_TAG, PUBLIC_HOST, and LETSENCRYPT_EMAIL with your specific details. The binaryData folder must have correct permissions for the Docker user.

```bash
# Create a new folder for webknossos
mkdir -p /opt/webknossos
cd /opt/webknossos

# Download the docker-compose.yml for hosting
wget https://github.com/scalableminds/webknossos/raw/master/tools/hosting/docker-compose.yml

# Create the binaryData folder which will contain all your datasets
mkdir binaryData

# The binaryData folder needs to be readable/writable by user id=1000,gid=1000
chown -R 1000:1000 binaryData

# Start WEBKNOSSOS and supply the DOCKER_TAG, PUBLIC_HOST and LETSENCRYPT_EMAIL variables
# In addition to WEBKNOSSOS, we also start an nginx proxy with automatic 
# SSL certificate management via letsencrypt
# Note that PUBLIC_HOST does not include http:// or https:// prefixes
# Please look up the latest WEBKNOSSOS version number at https://github.com/scalableminds/webknossos/releases
DOCKER_TAG=xx.yy.z PUBLIC_HOST=webknossos.example.com LETSENCRYPT_EMAIL=admin@example.com \
docker compose up webknossos nginx nginx-letsencrypt

# Wait a couple of minutes for WEBKNOSSOS to become available under your domain
# e.g. https://webknossos.example.com
# Set up your organization and admin account using the onboarding pages (see below)

# After the initial run, you can start WEBKNOSSOS in the background
DOCKER_TAG=xx.yy.z PUBLIC_HOST=webknossos.example.com LETSENCRYPT_EMAIL=admin@example.com \
docker compose up -d webknossos nginx nginx-letsencrypt

# Congratulations! Your WEBKNOSSOS is now up and running.

# Stop everything
docker compose down

```

--------------------------------

### Retrieve Project by Name Example

Source: https://docs.webknossos.org/api/webknossos/administration/project.html

Example demonstrating how to fetch a project by its name and print its project ID.

```python
project = Project.get_by_name("my_project")
print(project.project_id)
```

--------------------------------

### Install webknossos Package

Source: https://docs.webknossos.org/webknossos-py/installation.html

Install the core webknossos package using pip. This is the basic installation command.

```bash
pip install webknossos
```

--------------------------------

### Skeleton Example: Create and Populate

Source: https://docs.webknossos.org/api/webknossos/skeleton/skeleton.html

Example demonstrating how to create a new skeleton and populate it with groups, trees, nodes, and edges.

```APIDOC
## Skeleton Example: Create and Populate

```python
# Create skeleton through an annotation
annotation = Annotation(
    name="dendrite_trace",
    dataset_name="cortex_sample",
    voxel_size=(11, 11, 24)
)
skeleton = annotation.skeleton

# Add hierarchical structure
dendrites = skeleton.add_group("dendrites")
basal = dendrites.add_group("basal")
tree = basal.add_tree("dendrite_1")

# Add and connect nodes
soma = tree.add_node(position=(100, 100, 100), comment="soma")
branch = tree.add_node(position=(200, 150, 100), radius=1.5)
tree.add_edge(soma, branch)
```
```

--------------------------------

### Skeleton Example: Load Existing

Source: https://docs.webknossos.org/api/webknossos/skeleton/skeleton.html

Example demonstrating how to load an existing skeleton from an NML file and access its structure.

```APIDOC
## Skeleton Example: Load Existing

```python
# Load from NML file
skeleton = Skeleton.load("annotation.nml")

# Access existing structure
for group in skeleton.groups:
    for tree in group.trees:
        print(f"Tree {tree.name} has {len(tree.nodes)} nodes")
```
```

--------------------------------

### NML File Structure Example

Source: https://docs.webknossos.org/webknossos/data/concepts.html

This is an example of the NML file structure, showcasing parameters, node and edge definitions, metadata, and volume information.

```xml
<things>
  <parameters>
    <experiment name="great_dataset" organization="my_org" datasetId="abc123" description="My annotation" wkUrl="https://webknossos.org" />
    <scale x="11.24" y="11.24" z="25.0" unit="nanometer" />
    <offset x="0" y="0" z="0" />
    <time ms="1534787309180" />
    <editPosition x="1024" y="1024" z="512" />
    <editRotation xRot="0.0" yRot="0.0" zRot="0.0" />
    <zoomLevel zoom="1.0" />
    <activeNode id="1" />
    <userBoundingBox id="1" name="My Box" isVisible="true" color.r="1.0" color.g="0.0" color.b="0.0" color.a="1.0"
      topLeftX="0" topLeftY="0" topLeftZ="0" width="512" height="512" depth="512" />
    <taskBoundingBox topLeftX="0" topLeftY="0" topLeftZ="0" width="512" height="512" depth="512" />
    <additionalAxes>
      <additionalAxis name="t" index="0" start="0" end="10" />
    </additionalAxes>
  </parameters>
  <thing id="1" groupId="2" color.r="0.0" color.g="0.0" color.b="1.0" color.a="1.0" name="explorative_2018-08-20_Example" isVisible="true">
    <nodes>
      <node id="1" radius="120.0" x="1475" y="987" z="512" rotX="0.0" rotY="0.0" rotZ="0.0" inVp="0" inMag="0" bitDepth="8" interpolation="false" time="1534787309180" />
      <node id="2" radius="120.0" x="1548" y="1008" z="512" rotX="0.0" rotY="0.0" rotZ="0.0" inVp="0" inMag="0" bitDepth="8" interpolation="false" time="1534787309180" />
    </nodes>
    <edges>
      <edge source="1" target="2" />
    </edges>
    <metadata>
      <metadataEntry key="comment" stringValue="interesting tree" />
    </metadata>
  </thing>
  <branchpoints>
    <branchpoint id="1" time="1534787309180" />
  </branchpoints>
  <comments>
    <comment node="2" content="This is a really interesting node" />
  </comments>
  <groups>
    <group id="1" name="Axon 1" isExpanded="true">
        <group id="2" name="Foo" isExpanded="false" />
    </group>
  </groups>
  <volume id="0" name="Volume Layer" location="data.zip" format="zip"
    fallbackLayer="segmentation" largestSegmentId="1000" mappingName="agglomerate_view" mappingIsLocked="false">
    <segments>
      <segment id="1" name="Cell 1" isVisible="true" created="1534787309180"
        anchorPositionX="1475" anchorPositionY="987" anchorPositionZ="512"
        color.r="1.0" color.g="0.0" color.b="0.0" color.a="1.0" groupId="1">
        <metadata>
          <metadataEntry key="score" numberValue="0.95" />
          <metadataEntry key="reviewed" boolValue="true" />
        </metadata>
      </segment>
    </segments>
    <groups>
      <group id="1" name="Group A" />
    </groups>
  </volume>
</things>

```

--------------------------------

### Install webknossos Python Library

Source: https://docs.webknossos.org/webknossos/data/export_python.html

Install the WEBKNOSSOS Python library using pip. It is recommended to use a virtual environment.

```bash
pip install webknossos

```

--------------------------------

### Install WEBKNOSSOS CLI

Source: https://docs.webknossos.org/webknossos/data/zarr.html

Install the WEBKNOSSOS CLI with all extras to enable Zarr conversion. This command ensures all necessary dependencies for handling various image formats and Zarr are included.

```bash
pip install --extra-index-url https://pypi.scm.io/simple "webknossos[all]"
```

--------------------------------

### Install WEBKNOSSOS CLI with pip

Source: https://docs.webknossos.org/cli/install.html

Install the webknossos package with all extras. Ensure you have Python 3.10 or higher.

```bash
pip install "webknossos[all]"
```

--------------------------------

### MagView info Property Example

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/view/mag_view.html

Example demonstrating how to access and print array information, such as data type and bounding box size, from the `info` property.

```python
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"Shape: {array_info.bounding_box.size}")

```

--------------------------------

### MagView mag Property Example

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/view/mag_view.html

Example showing how to retrieve and print the current magnification level of a view.

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

```

--------------------------------

### Install webknossos for CZI Data Support

Source: https://docs.webknossos.org/webknossos-py/installation.html

Install webknossos with specific dependencies for working with Zeiss CZI microscopy data, utilizing the pylibczirw package. This command includes an extra index URL for the required package.

```bash
pip install --extra-index-url https://pypi.scm.io/simple/ "webknossos[czi]"
```

--------------------------------

### Enable Shell Auto-Completion

Source: https://docs.webknossos.org/cli/install.html

After installation, enable shell auto-completion for the WEBKNOSSOS CLI.

```bash
webknossos --install-completion
```

--------------------------------

### Example Dataset Transformations

Source: https://docs.webknossos.org/webknossos/datasets/settings.html

Illustrates how to apply affine transformations to 'color' and 'segmentation' layers within a dataset using JSON.

```json
[
  {
    "name": "color",
    "coordinateTransformations": [
      {
        "type": "affine",
        "matrix": [[1, 0, 0, 10], [0, 1, 0, 20], [0, 0, 1, 30], [0, 0, 0, 1]]
      }
    ]
  },
    {
    "name": "segmentation",
    "coordinateTransformations": [
      {
        "type": "affine",
        "matrix": [[1, 0, 0, 10], [0, 1, 0, 20], [0, 0, 1, 30], [0, 0, 0, 1]]
      }
    ]
  }
]
```

--------------------------------

### Minimal WKW Dataset Configuration

Source: https://docs.webknossos.org/webknossos-py/spec/datasource_properties.html

Example of a basic Webknossos dataset configuration for a WKW format layer.

```json
{
  "version": 1,
  "id": { "name": "my_dataset", "team": "" },
  "scale": [11.24, 11.24, 28.0],
  "dataLayers": [
    {
      "name": "color",
      "category": "color",
      "boundingBox": { "topLeft": [0, 0, 0], "width": 1024, "height": 1024, "depth": 512 },
      "elementClass": "uint8",
      "dataFormat": "wkw",
      "mags": [
        { "mag": [1, 1, 1], "path": "./color/1" },
        { "mag": [2, 2, 2], "path": "./color/2" }
      ]
    }
  ]
}
```

--------------------------------

### Get Annotation Infos

Source: https://docs.webknossos.org/api/webknossos/administration/task.html

Retrieves AnnotationInfo objects describing all task instances that have been started by annotators for this task.

```APIDOC
## Task.get_annotation_infos

### Description
Returns AnnotationInfo objects describing all task instances that have been started by annotators for this task

### Method Signature
```python
get_annotation_infos() -> list[AnnotationInfo]
```

### Returns
* `list[AnnotationInfo]` - List of AnnotationInfo objects.
```

--------------------------------

### Get Annotation Infos for Task

Source: https://docs.webknossos.org/api/webknossos/administration/task.html

Retrieves AnnotationInfo objects that describe all task instances started by annotators for this task.

```python
task.get_annotation_infos()
```

--------------------------------

### Get Axis Bounds

Source: https://docs.webknossos.org/api/webknossos/geometry/nd_bounding_box.html

Retrieves the start and end coordinates for a specified axis within the bounding box. Useful for understanding the spatial extent along a particular dimension.

```python
get_bounds(axis: str) -> tuple[int, int]
```

--------------------------------

### Initialize a View instance

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/view/view.html

The recommended way to create a View is through `get_view()`. This method is available on a `MagView` object.

```python
from webknossos.dataset import Dataset, View
dataset = Dataset.open("path/to/dataset")

# Get a view for a specific layer at mag 1
layer = dataset.get_layer("color")
view = layer.get_mag("1").get_view(size=(100, 100, 10))
```

--------------------------------

### Open, Create, Write, and Read Dataset Operations

Source: https://docs.webknossos.org/webknossos-py/examples/dataset_usage.html

Demonstrates the fundamental operations of opening an existing dataset, creating a new one, writing data to layers and magnifications, and reading data back. Ensure the dataset path and layer names match your setup.

```python
import numpy as np

import webknossos as wk

# ruff: noqa: F841 unused-variable


def main() -> None:
    #####################
    # Opening a dataset #
    #####################
    dataset = wk.Dataset.open("testdata/simple_wkw_dataset")
    # Assuming that the dataset has a layer "color"
    # and the layer has the magnification 1
    layer = dataset.get_layer("color")
    mag1 = layer.get_mag("1")

    ######################
    # Creating a dataset #
    ######################

    dataset = wk.Dataset("testoutput/my_new_dataset", voxel_size=(1, 1, 1))
    layer = dataset.add_layer(
        layer_name="color",
        category="color",
        dtype="uint8",
        num_channels=3,
        bounding_box=wk.BoundingBox((10, 20, 30), (512, 512, 32)),
    )
    mag1 = layer.add_mag("1")
    mag2 = layer.add_mag("2")

    ##########################
    # Writing into a dataset #
    ##########################

    # The properties are updated automatically
    # when the written data exceeds the bounding box in the properties
    mag1.write(
        absolute_offset=(10, 20, 30),
        # assuming the layer has 3 channels:
        data=(np.random.rand(3, 512, 512, 32) * 255).astype(np.uint8),
        allow_unaligned=True,
    )

    mag2.write(
        absolute_offset=(10, 20, 30),
        data=(np.random.rand(3, 256, 256, 16) * 255).astype(np.uint8),
        allow_unaligned=True,
    )

    ##########################
    # Reading from a dataset #
    ##########################

    data_in_mag1 = mag1.read()  # the offset and size from the properties are used
    data_in_mag1_subset = mag1.read(absolute_offset=(10, 20, 30), size=(512, 512, 32))

    data_in_mag2 = mag2.read()
    data_in_mag2_subset = mag2.read(absolute_offset=(10, 20, 30), size=(512, 512, 32))
    assert data_in_mag2_subset.shape == (3, 256, 256, 16)

    #####################
    # Copying a dataset #
    #####################

    copy_of_dataset = dataset.copy_dataset(
        "testoutput/copy_of_dataset",
        chunk_shape=(32, 32, 32),
        shard_shape=(64, 64, 64),
        compress=True,
    )
    new_layer = dataset.add_layer(
        layer_name="segmentation",
        category="segmentation",
        dtype="uint8",
        largest_segment_id=0,
    )
    # Link a layer of the initial dataset to the copy:
    sym_layer = copy_of_dataset.add_symlink_layer(new_layer)


if __name__ == "__main__":
    main()

```

--------------------------------

### Webknossos CLI Help Overview

Source: https://docs.webknossos.org/webknossos-py/changelog.html

To view all available webknossos subcommands, use the `--help` flag. For specific subcommand usage, append `--help` after the subcommand name.

```bash
webknossos --help
```

```bash
webknossos <subcommand> --help
```

--------------------------------

### Run Scripts with uv

Source: https://docs.webknossos.org/webknossos-py/CONTRIBUTING.html

Demonstrates how to run scripts within a package's virtual environment using `uv run`. This ensures that the correct dependencies are used for script execution.

```bash
uv run python myscript.py
```

--------------------------------

### MagView Example: Creating and Accessing Magnification Levels

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/view/mag_view.html

Demonstrates creating a dataset, adding a segmentation layer, adding magnification levels, and writing/reading data at different magnifications. Coordinates are handled in Mag(1) space.

```python
# 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)

```

--------------------------------

### Zarr Group Metadata Example

Source: https://docs.webknossos.org/webknossos-py/spec/agglomerate_attachment.html

Provides an example of the zarr.json file content for an AgglomerateViewArtifact, including schema version and artifact class.

```json
{
  "zarr_format": 3,
  "node_type": "group",
  "attributes": {
    "voxelytics": {
      "artifact_schema_version": 4,
      "artifact_class": "AgglomerateViewArtifact"
    }
  }
}

```

--------------------------------

### Recommend Legacy Bindings for New Tasks

Source: https://docs.webknossos.org/webknossos/MIGRATIONS.released.html

Use this SQL query to recommend legacy mouse bindings for users when they start a new task. Adapt 'true' to 'false' to recommend the opposite.

```sql
-- Recommend legacy bindings for users when starting a new task
UPDATE webknossos.tasktypes
SET recommendedconfiguration = jsonb_set(
        recommendedconfiguration,
        array['useLegacyBindings'],
        to_jsonb('true'::boolean))

```

--------------------------------

### VecInt Initialization

Source: https://docs.webknossos.org/api/webknossos/geometry/vec_int.html

Demonstrates various ways to initialize a VecInt object, including positional arguments, lists, named arguments, and using the `full` or `ones` class methods.

```APIDOC
## VecInt Initialization

### Description
Initialize a VecInt with positional arguments, a list of integers, or named arguments. You can also use class methods like `full` to create a vector with a repeated value or `ones` to create a vector of ones.

### Examples

Create a vector with 4 named dimensions:
```python
vector_1 = VecInt(1, 2, 3, 4, axes=("x", "y", "z", "t"))
vector_1 = VecInt([1, 2, 3, 4], axes=("x", "y", "z", "t"))
vector_1 = VecInt(x=1, y=2, z=3, t=4)
```

Create a vector filled with ones:
```python
vector_2 = VecInt.full(1, axes=("x", "y", "z", "t"))
assert vector_2[0] == vector_2[1] == vector_2[2] == vector_2[3]

vector_3 = VecInt.ones(axes=("x", "y", "z"))
```
```

--------------------------------

### Create and Populate a Tree

Source: https://docs.webknossos.org/api/webknossos/skeleton/tree.html

Demonstrates how to create a skeleton, add a tree to it, add nodes with positions and comments, and connect them with edges. Accessing node positions is also shown.

```python
# First create a skeleton (parent object)
skeleton = Skeleton("example_skeleton")

# Add a new tree to the skeleton
tree = skeleton.add_tree("dendrite_1")

# Add nodes with 3D positions
soma = tree.add_node(position=(0, 0, 0), comment="soma")
branch1 = tree.add_node(position=(100, 0, 0), comment="branch1")
branch2 = tree.add_node(position=(0, 100, 0), comment="branch2")

# Connect nodes with edges
tree.add_edge(soma, branch1)
tree.add_edge(soma, branch2)

# Access node positions
positions = tree.get_node_positions()  # Returns numpy array of all positions

```

--------------------------------

### name

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the name of the layer.

```APIDOC
## name property writable

### Description
Returns the name of the layer.

### Returns
* **`str`**(`str` ) – 
Layer name
```

--------------------------------

### View Initialization (Recommended: get_view)

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/view/view.html

Initializes a View instance for accessing and manipulating dataset regions. It is recommended to use `View.get_view()` or `MagView.get_view()` instead of direct constructor usage.

```APIDOC
## View Initialization (Recommended: get_view)

### Description
Initializes a View instance for accessing and manipulating dataset regions. It is recommended to use `View.get_view()` or `MagView.get_view()` instead of direct constructor usage.

### Parameters
* **`path_to_mag_view`**(`Path`) – Path to the magnification view directory.
* **`array_info`**(`ArrayInfo`) – Information about the array structure and properties.
* **`bounding_box`**(`NDBoundingBox | None`) – The bounding box in mag 1 absolute coordinates. Optional only for mag_view since it overwrites the bounding_box property.
* **`mag`**(`Mag`) – Magnification level of the view.
* **`read_only`**(`bool` , default: `False` ) – Whether the view is read-only. Defaults to False.

### Examples
```python
# The recommended way to create a View is through get_view():
layer = dataset.get_layer("color")
mag_view = layer.get_mag("1")
view = mag_view.get_view(size=(100, 100, 10))
```
```

--------------------------------

### category

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the category of the layer.

```APIDOC
## category property

### Description
Gets the category of the layer.

### Returns
* **`LayerCategoryType`**(`LayerCategoryType` ) – 
Layer category
```

--------------------------------

### NDBoundingBox Initialization

Source: https://docs.webknossos.org/api/webknossos/geometry/nd_bounding_box.html

Demonstrates how to create NDBoundingBox instances for different dimensions.

```APIDOC
## NDBoundingBox Initialization

### Description
Creates a generalized N-dimensional bounding box.

### Parameters
* **`topleft`** (`VecInt`) - The coordinates of the upper-left corner (inclusive).
* **`size`** (`VecInt`) - The size/extent in each dimension.
* **`axes`** (`tuple[str, ...]`) - The names of the axes/dimensions (e.g. "x", "y", "z", "t").
* **`index`** (`VecInt | None`, optional) - The order/position of each axis, starting from 0. Deprecated, index is inferred from axes.
* **`name`** (`str | None`, optional) - Optional name for this bounding box.
* **`is_visible`** (`bool`, optional, default: `True`) - Whether this bounding box should be visible.
* **`color`** (`tuple[float, float, float, float] | None`, optional) - Optional RGBA color tuple (4 floats) for display.

### Examples

Create a 2D bounding box:
```python
bbox_1 = NDBoundingBox(
    topleft=(0, 0),
    size=(100, 100),
    axes=("x", "y"),
)
```

Create a 4D bounding box:
```python
bbox_2 = NDBoundingBox(
    topleft=(75, 75, 75, 0),
    size=(100, 100, 100, 20),
    axes=("x", "y", "z", "t"),
)
```
```

--------------------------------

### N5 Folder Structure Example

Source: https://docs.webknossos.org/webknossos/data/n5.html

This illustrates the expected file structure for N5 datasets when used with Webknossos. It shows the root dataset folder, attribute files, and the hierarchical chunk organization.

```text
my_dataset.n5             # One root folder per dataset
├─ attributes.json        # Dataset metadata
└─ my_EM                  # One N5 group per data layer. In WK directly link to a N5 group.
  ├─ attributes.json                
  ├─ s0                  # Chunks in a directory hierarchy that enumerates their positive integer position in the chunk grid. (e.g. 0/4/1/7 for chunk grid position p=(0, 4, 1, 7)).
   │  ├─ 0
   │  │  ├─ <chunks>
   │  ├─ ...
   │  └─ n
 ...                
 └─ sn                

```

--------------------------------

### Node.id

Source: https://docs.webknossos.org/api/webknossos/skeleton/node.html

Gets the unique identifier for the node.

```APIDOC
## Node.id

### Description
Gets the unique identifier for the node.

### Property
- **`id`**(`int`)
```

--------------------------------

### num_channels

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the number of channels in this layer.

```APIDOC
## num_channels property

### Description
Gets the number of channels in this layer.

### Returns
* **`int`**(`int` ) – 
Number of channels

### Raises
* `AssertionError` – 
If num_channels is not set in properties
```

--------------------------------

### Create Remote Datasets with Cloud Storage Support

Source: https://docs.webknossos.org/webknossos-py/changelog.html

Demonstrates how to create datasets using cloud storage with UPath and fsspec. This is applicable for Zarr-based layers.

```python
Dataset(UPath("s3://bucket/path/to/dataset", key="...", secret="..."), scale=(11, 11, 24))
```

--------------------------------

### Upload a dataset with custom configuration

Source: https://docs.webknossos.org/cli/upload.html

Uploads the dataset with a new name and uses 4 parallel processes. Ensure your token is valid and the target URL is correct.

```bash
webknossos upload --webknossos-url https://webknosos.example.com --token YOUR_TOKEN --dataset-name new_name --jobs 4 /path/to/local/dataset
```

--------------------------------

### num_channels property

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/view/view.html

Gets the number of channels in this view.

```APIDOC
## num_channels property

### Description
Gets the number of channels in this view.

### Returns
* **`int`**(`int` ) – Number of channels
```

--------------------------------

### dataset

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the remote dataset associated with this layer.

```APIDOC
## dataset property

### Description
Gets the remote dataset associated with this layer.

### Returns
* **`RemoteDataset`**(`RemoteDataset` ) – 
Remote dataset
```

--------------------------------

### Generate Documentation Locally

Source: https://docs.webknossos.org/webknossos-py/CONTRIBUTING.html

Generates the documentation locally using the `generate.sh` script. This command should be run after cloning the WEBKNOSSOS repository.

```bash
docs/generate.sh
```

--------------------------------

### Get Project

Source: https://docs.webknossos.org/api/webknossos/administration/task.html

Returns the project this task belongs to.

```APIDOC
## Task.get_project

### Description
Returns the project this task belongs to

### Method Signature
```python
get_project() -> Project
```

### Returns
* `Project` - The Project object associated with the task.
```

--------------------------------

### largest_segment_id

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the largest segment ID present in the data.

```APIDOC
## largest_segment_id property writable

### Description
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
```

--------------------------------

### dtype

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the data type used per channel.

```APIDOC
## dtype property

### Description
Gets the data type used per channel.

### Returns
* `dtype` – 
np.dtype: NumPy data type for individual channels
```

--------------------------------

### Create and Populate a New Skeleton

Source: https://docs.webknossos.org/api/webknossos/skeleton/skeleton.html

Demonstrates how to create a new skeleton, add hierarchical groups and trees, and then populate it with nodes and edges.

```python
annotation = Annotation(
    name="dendrite_trace",
    dataset_name="cortex_sample",
    voxel_size=(11, 11, 24)
)
skeleton = annotation.skeleton

# Add hierarchical structure
dendrites = skeleton.add_group("dendrites")
basal = dendrites.add_group("basal")
tree = basal.add_tree("dendrite_1")

# Add and connect nodes
soma = tree.add_node(position=(100, 100, 100), comment="soma")
branch = tree.add_node(position=(200, 150, 100), radius=1.5)
tree.add_edge(soma, branch)
```

--------------------------------

### default_view_configuration

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets or sets the default view configuration for this layer.

```APIDOC
## default_view_configuration property writable

### Description
Gets the default view configuration for this layer.

### Returns
* `LayerViewConfiguration | None` – 
LayerViewConfiguration | None: View configuration if set, otherwise None
```

--------------------------------

### Create and Connect Skeleton Nodes

Source: https://docs.webknossos.org/api/webknossos/skeleton/node.html

Demonstrates how to create a skeleton, add a tree, and then add nodes with optional metadata. It also shows how to connect nodes with edges and mark a node as a branchpoint. Nodes should be created using Tree.add_node() for proper integration.

```python
skeleton = Skeleton(name="example")
tree = skeleton.add_tree("dendrite")

# Add nodes and connect them
node1 = tree.add_node(position=(0, 0, 0), comment="soma")
node2 = tree.add_node(position=(100, 0, 0), radius=1.5)
tree.add_edge(node1, node2)

# Mark as branchpoint if needed
node1.is_branchpoint = True

```

--------------------------------

### data_format

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the data storage format used by this layer.

```APIDOC
## data_format property

### Description
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
```

--------------------------------

### Create a New Project

Source: https://docs.webknossos.org/api/webknossos/administration/project.html

Use this class method to create a new project. The current user is automatically assigned as the owner. Optional parameters allow setting priority, paused status, expected time, and blacklist status.

```python
create(
    name: str,
    team: str | Team,
    expected_time: int | None,
    priority: int = 100,
    paused: bool = False,
    is_blacklisted_from_report: bool = False,
    owner: str | User | None = None,
) -> Project
```

--------------------------------

### Get Project Owner

Source: https://docs.webknossos.org/api/webknossos/administration/project.html

Returns the user that is the owner of this project.

```APIDOC
## `get_owner`

### Description
Returns the user that is the owner of this project.

### Method
`get_owner() -> User`

### Parameters
None

### Returns
- **`User`** (`User`) - The user object representing the owner of the project.
```

--------------------------------

### Run WEBKNOSSOS CLI with uv

Source: https://docs.webknossos.org/cli/install.html

Use uv to run the WEBKNOSSOS CLI, ensuring the latest version is utilized. Replace [COMMAND], [OPTIONS], and [ARGUMENTS] with your desired CLI command.

```bash
uv --with 'webknossos[all]' webknossos [COMMAND] [OPTIONS] [ARGUMENTS]
```

--------------------------------

### path Property

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/view/mag_view.html

Get the path to this magnification level's data.

```APIDOC
## path Property

### Description
Get the path to this magnification level's data.

### Returns
- **`UPath`** - Path to the data files on disk.

### Notes
- Path may be local or remote depending on dataset configuration
```

--------------------------------

### Upload a dataset with default settings

Source: https://docs.webknossos.org/cli/upload.html

Uploads a dataset to the WEBKNOSSOS server specified by `WK_URL` or to the default url https://webknossos.org.

```bash
webknossos upload /path/to/local/dataset
```

--------------------------------

### Create Project

Source: https://docs.webknossos.org/api/webknossos/administration/project.html

Creates a new project and returns it. The project will be created with the current user as owner.

```APIDOC
## `create`

### Description
Creates a new project and returns it. Note: The project will be created with the current user as owner.

### Method
`create(
    name: str,
    team: str | Team,
    expected_time: int | None,
    priority: int = 100,
    paused: bool = False,
    is_blacklisted_from_report: bool = False,
    owner: str | User | None = None,
) -> Project`

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters

- **`name`** (`str`) - Required - The name of the project.
- **`team`** (`str | Team`) - Required - The team to which the project belongs.
- **`expected_time`** (`int | None`) - Required - The expected time for the project in minutes.
- **`priority`** (`int`) - Optional - The priority of the project. Defaults to `100`.
- **`paused`** (`bool`) - Optional - Whether the project is paused or not. Defaults to `False`.
- **`is_blacklisted_from_report`** (`bool`) - Optional - Whether the project is blacklisted from reports. Defaults to `False`.
- **`owner`** (`str | User | None`) - Optional - The owner of the project. If None, the current user will be used.

### Returns
- **`Project`** (`Project`) - The created project.
```

--------------------------------

### bounding_box

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets the bounding box encompassing this layer's data.

```APIDOC
## bounding_box property writable

### Description
Gets the bounding box encompassing this layer's data.

### Returns
* **`NDBoundingBox`**(`NDBoundingBox` ) – 
Bounding box with layer dimensions
```

--------------------------------

### Create VecInt instances

Source: https://docs.webknossos.org/api/webknossos/geometry/vec_int.html

Initialize VecInt with positional arguments, a list, or named arguments. Ensure axes are provided for clarity.

```python
vector_1 = VecInt(1, 2, 3, 4, axes=("x", "y", "z", "t"))
```

```python
vector_1 = VecInt([1, 2, 3, 4], axes=("x", "y", "z", "t"))
```

```python
vector_1 = VecInt(x=1, y=2, z=3, t=4)
```

--------------------------------

### Get Project for Task

Source: https://docs.webknossos.org/api/webknossos/administration/task.html

Returns the Project object to which this task belongs.

```python
task.get_project()
```

--------------------------------

### Zarr Folder Structure Example

Source: https://docs.webknossos.org/webknossos/data/zarr.html

Illustrates the expected file and directory layout for OME-Zarr v0.4 datasets, including image data and labels.

```tree
.                             # Root folder,
│                             # with a flat list of images by image ID.
│
└── 456.zarr                  # Another image (id=456) converted to Zarr.
    │
    ├── .zgroup               # Each image is a Zarr group, or a folder, of other groups and arrays.
    ├── .zattrs               # Group level attributes are stored in the .zattrs file and include
    │                         # "multiscales" and "omero" (see below). In addition, the group level attributes
    │                         # may also contain "_ARRAY_DIMENSIONS" for compatibility with xarray if this group directly contains multi-scale arrays.
    │
    ├── 0                     # Each multiscale level is stored as a separate Zarr array,
    │   ...                   # which is a folder containing chunk files which compose the array.
    ├── n                     # The name of the array is arbitrary with the ordering defined by
    │   │                     # by the "multiscales" metadata, but is often a sequence starting at 0.
    │   │
    │   ├── .zarray           # All image arrays must be up to 5-dimensional
    │   │                     # with the axis of type time before type channel, before spatial axes.
    │   │
    │   └─ t                  # Chunks are stored with the nested directory layout.
    │      └─ c               # All but the last chunk element are stored as directories.
    │         └─ z            # The terminal chunk is a file. Together the directory and file names
    │            └─ y         # provide the "chunk coordinate" (t, c, z, y, x), where the maximum coordinate
    │               └─ x      # will be dimension_size / chunk_size.
    │
    └── labels
        │
        ├── .zgroup           # The labels group is a container which holds a list of labels to make the objects easily discoverable
        │
        ├── .zattrs           # All labels will be listed in .zattrs e.g. { "labels": [ "original/0" ] }
        │                     # Each dimension of the label (t, c, z, y, x) should be either the same as the
        │                     # corresponding dimension of the image, or 1 if that dimension of the label
        │                     # is irrelevant.
        │
        └── original          # Intermediate folders are permitted but not necessary and currently contain no extra metadata.
            │
            └── 0             # Multiscale, labeled image. The name is unimportant but is registered in the "labels" group above.
                ├── .zgroup   # Zarr Group which is both a multiscaled image as well as a labeled image.
                ├── .zattrs   # Metadata of the related image and as well as display information under the "image-label" key.
                │
                ├── 0         # Each multiscale level is stored as a separate Zarr array, as above, but only integer values
                │   ...       # are supported.
                └── n

```

--------------------------------

### url Property

Source: https://docs.webknossos.org/api/webknossos/dataset/remote_dataset.html

Get the URL to access this dataset in the webknossos web interface.

```APIDOC
## url Property

### Description
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
```python
print(ds.url) # 'https://webknossos.org/datasets/my_org/my_dataset'
```
```

--------------------------------

### Example: Create Skeleton Tracing Task Type

Source: https://docs.webknossos.org/api/webknossos/administration/task.html

Demonstrates how to create a new skeleton tracing task type for a specified team. The created task type's ID is then printed.

```python
task_type = TaskType.create(
    name="Neuron Skeleton Tracing",
    description="Trace neuron skeletons for connectomics project.",
    team="NeuroLab",
    tracing_type="skeleton"
print(task_type.id)
```

--------------------------------

### Get Group by ID

Source: https://docs.webknossos.org/api/webknossos/skeleton/group.html

Retrieves a specific group using its unique identifier.

```python
group.get_group_by_id(group_id)
```

--------------------------------

### WEBKNOSSOS Context Manager

Source: https://docs.webknossos.org/api/webknossos/client/context.html

Use this as a context manager to establish a WEBKNOSSOS server connection. The token must be explicitly provided. URL and timeout will default to previous context values if not specified.

```python
with webknossos_context(token="my_webknossos_token"):
    # code that interacts with webknossos
    ds.download(...)
```

--------------------------------

### normalized_bounding_box

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

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

```APIDOC
## normalized_bounding_box property

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

### Returns
* **`NormalizedBoundingBox`**(`NormalizedBoundingBox` ) – 
Bounding box with channel axis included
```

--------------------------------

### Get Parent Dataset

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/layer.html

Retrieves the parent Dataset object that contains this layer.

```python
dataset: Dataset

```

--------------------------------

### Edge Source Attribute

Source: https://docs.webknossos.org/api/webknossos/_nml/edge.html

Represents the starting point of an edge. This is an integer attribute.

```python
source: int
```

--------------------------------

### Project Creation

Source: https://docs.webknossos.org/api/webknossos/client/api_client/wk_api_client.html

Creates a new project with the specified parameters.

```APIDOC
## project_create

### Description
Creates a new project.

### Method
`project_create`

### Parameters
- **project** (ApiProjectCreate) - Required - Project creation parameters.

### Returns
- **ApiProject** - The created project object.
```

--------------------------------

### name property

Source: https://docs.webknossos.org/api/webknossos/dataset/dataset.html

Gets or sets the name of the dataset. Changes are persisted to the properties file.

```APIDOC
## name property

### Description
Name of this dataset as specified in `datasource-properties.json`. Can be modified to rename the dataset. Changes are persisted to the properties file.

### Returns
* **`str`**(`str` ) – Current dataset name

### Example
```python
ds.name = "my_renamed_dataset"  # Updates the name in properties file
```
```

--------------------------------

### voxel_size Property

Source: https://docs.webknossos.org/api/webknossos/dataset/remote_dataset.html

Get the size of each voxel in nanometers along the x, y, and z dimensions.

```APIDOC
## voxel_size Property

### Description
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
```python
vx, vy, vz = ds.voxel_size
print(f"X resolution is {vx}nm")
```
```

--------------------------------

### Convert Image Stack to Zarr3 Dataset (CLI)

Source: https://docs.webknossos.org/webknossos/data/image_stacks.html

Use the WEBKNOSSOS CLI to convert an image stack from a source directory to a Zarr3 dataset in a target directory. Specify voxel size in nanometers. Creates a 'color' layer by default.

```bash
pip install webknossos

webknossos convert \
  --voxel-size 11.24,11.24,25 \
  --name my_dataset \
  data/source data/target

```

--------------------------------

### Get Specific Magnification

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Retrieves the MagView for a specific magnification level of the remote layer.

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

```

--------------------------------

### Basic `convert` Command Usage

Source: https://docs.webknossos.org/cli/convert.html

Use this command to convert a source image stack to a WEBKNOSSOS dataset. The target path is required unless the `--upload` flag is used.

```bash
webknossos convert [OPTIONS] SOURCE [TARGET]
```

--------------------------------

### view_configuration

Source: https://docs.webknossos.org/api/webknossos/dataset/layer/segmentation_layer/remote_segmentation_layer.html

Gets or sets the current view configuration for this layer as stored on the WEBKNOSSOS server.

```APIDOC
## view_configuration property writable

### Description
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.

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

--------------------------------

### WkApiClient Initialization

Source: https://docs.webknossos.org/api/webknossos/client/api_client/wk_api_client.html

Initializes the WkApiClient with the base URL, timeout, and optional headers for the Webknossos service.

```APIDOC
## WkApiClient

### Description
Initializes the Webknossos client.

### Parameters
- **base_wk_url** (str) - The base URL of the Webknossos instance.
- **timeout_seconds** (float) - The timeout in seconds for API requests.
- **headers** (dict[str, str] | None) - Optional dictionary of headers to include in requests.
```

--------------------------------

### Initialize WkImportError

Source: https://docs.webknossos.org/api/webknossos/utils.html

Exception raised when a required package is missing. Allows specifying missing package, extras, and a custom message.

```python
WkImportError(
    missing_package: str,
    extras: str = "all",
    custom_message: str | None = None,
)
```

--------------------------------

### Get Project By Name

Source: https://docs.webknossos.org/api/webknossos/administration/project.html

Retrieves a project by its unique name. Requires valid authentication.

```APIDOC
## `get_by_name`

### Description
Retrieve a project by its unique name. Fetches the project with the specified `name` from the backend, provided the current user can access the project. This method requires valid authentication.

### Method
`get_by_name(name: str) -> Project`

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters

- **`name`** (`str`) - Required - The unique name of the project to retrieve.

### Returns
- **`Project`** (`Project`) - An instance of the Project class corresponding to the specified name.

### Raises
- `UnexpectedStatusError` - If the project does not exist or the user is not authorized to access it.

### Examples
```python
project = Project.get_by_name("my_project")
print(project.project_id)
```
```
Tokens:
Raw