Skip to content

Commit

Permalink
Updated documentation (#7439)
Browse files Browse the repository at this point in the history 
* updated docs

* docs update #2

* applied some gpt4 feedback

* moar docs

* more docs on the data source formats

* more docs

* Update docs/dashboard.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/datasets.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/datasets.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/datasets.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/datasets.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/zarr.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/zarr.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/zarr.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/zarr.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/getting_started.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/image_stacks.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/image_stacks.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/zarr.md

Co-authored-by: Norman Rzepka <[email protected]>

* Update docs/zarr.md

Co-authored-by: Norman Rzepka <[email protected]>

* added PR feedback

* added example video for animations

---------

Co-authored-by: Norman Rzepka <[email protected]>
  • Loading branch information
@hotzenklotz @normanrz
hotzenklotz and normanrz authored Nov 23, 2023
1 parent aa6b0c0 commit de3b349
Show file tree
Hide file tree
Showing 24 changed files with 655 additions and 331 deletions.
21 changes: 21 additions & 0 deletions docs/animations.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Animations

A picture is worth a thousand words. In this spirit, you can use WEBKNOSSOS to create eye-catching animations of your datasets as a video clip. You can use these short movies as part of a presentation, website, for social media or to promote a publication.

![type:video](https://static.webknossos.org/assets/docs/webknossos_animation_example.mp4){: autoplay loop muted}

## Creating an Animation

Creating an animation is easy:

1. Open any dataset or annotation that you want to use for your animation.
2. Optionally, load any [pre-computed 3D meshes](./mesh_visualization.md#pre-computed-mesh-generation) for any segments that you wish to highlight.
3. For larger datasets, use the bounding box tool to create a bounding box around your area of interest. Smaller datasets can be used in their entirety.
4. From the `Menu` dropdown in navbar at the top of the screen, select "Create Animation".
5. Configure the animation options as desired, i.e. camera movement or resolution.
6. Click the `Start animation` button to launch the animation creation.


Either periodically check the [background jobs page](./jobs.md) or wait for a an email confirmation to download the animation video file. Creating an animation may take a while, depending on the selected bounding box size and the number of included 3D meshes.

WEBKNOSSOS Team plans and above have access to high definition (HD) resolution videos and more options.
14 changes: 7 additions & 7 deletions docs/automated_analysis.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Automated Analysis

While WEBKNOSSOS is great for manual annotation, some datasets are either too big to do by hand or you need results quicker. WEBKNOSSOS contains early access to automated analysis using machine learning classifiers for dataset segmentations. The WEBKNOSSOS developer team has many years of experience with training ML models for large-scale data analysis outside of WEBKNOSSOS. We aim to bring some of this know-how directly into WEBKNOSSOS itself.
While WEBKNOSSOS is great for manual annotation, some datasets are either too big to do by hand or you need results quicker. WEBKNOSSOS contains early access to automated analysis using machine learning classifiers for dataset segmentations. The WEBKNOSSOS developer team has many years of experience with training AI models for large-scale data analysis outside of WEBKNOSSOS. We aim to bring some of this know-how directly into WEBKNOSSOS itself.

The automated analysis features are designed to provide a general solution to a wide range of (EM) datasets. Since datasets differ in staining protocols, imaging modalities, imaging resolution & fidelity, your results may vary. [Please contact us](mailto:[email protected]) for customized, fine-tuned solutions for your dataset.

Expand All @@ -9,23 +9,23 @@ We would love to integrate analysis solutions for more modalities and use cases.

!!!info
Automated analysis is only available on [webknossos.org](https://webknossos.org) at the moment.
If you want to set up on-premise automated analysis at your institute/workplace, then [please contact us](mailto:hello@webknossos.org).
If you want to set up on-premise automated analysis at your institute/workplace, then [please contact sales](mailto:sales@webknossos.org).

## Neuron Segmentation
As a first trial, WEBKNOSSOS includes neuron segmentation. This analysis is designed to work with serial block-face electron microscopy (SBEM) data of neural tissue (brain/cortex) and will segment all neurons within the dataset.

You can launch the AI analysis modal using the button in the action bar at the top. Use the `Start AI neuron segmentation` button in the modal to start the analysis.
You can launch the AI analysis modal using the `AI Analysis` button in the tool bar at the top. Use the `Start AI neuron segmentation` button in the modal to start the analysis.

![Neuron segmentations can be launched from the action bar.](images/process_dataset.jpg)
![Neuron segmentations can be launched from the tool bar.](images/process_dataset.jpg)

Computation time for this analysis depends directly on the size of your dataset.
Expect a few hours for medium-sized volumetric EM datasets.
The finished analysis will be available as a new dataset from your dashboard. You can monitor the status and progress of the [analysis job from the `Processing Jobs` section of the `Administration` menu at the top of the screen](./jobs.md).
The finished analysis will be available as a new dataset from your dashboard. You can monitor the status and progress of the analysis job from the [`Processing Jobs` page](./jobs.md) or wait for the email notification.

![Starting a new neuron segmentation.](images/neuron_segmentation_start.jpeg)
![Monitor the segmentation progress from the Jobs page.](images/nuclei_segmentation_job.jpeg)

## Custom Analysis
At the moment, WEBKNOSSOS can not be used to train a custom classifier itself. This might be something that we add in the future if there is enough interest in this.
At the moment, WEBKNOSSOS can not be used to train custom classifiers. This might be something that we add in the future if there is enough interest in this.

If you are interested in specialized, automated analysis, image segmentation, object detection etc. than feel free to [contact us](mailto:[email protected]). The WEBKNOSSOS development teams offers [commercial analysis services for](https://webknossos.org/services/automated-segmentation) that.
If you are interested in specialized, automated analysis, image segmentation, object detection etc. than feel free to [contact us](mailto:[email protected]). The WEBKNOSSOS development teams offers [commercial analysis services](https://webknossos.org/services/automated-segmentation) for that.
14 changes: 7 additions & 7 deletions docs/dashboard.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Dashboard

The Dashboard is your entry point to WEBKNOSSOS.
You can manage your datasets, create annotations, resume existing annotations and retrieve tasks distributed to you.
Welcome to WEBKNOSSOS!
The Dashboard lets you do the following things: manage your datasets, create new annotations, continue working on existing annotations, and get tasks assigned to you.

## Datasets

This screen shows all the available and accessible datasets for a user.
You can _view_ a dataset (read-only) or start new annotations from this screen.
On this screen, you can see all the datasets that you can access.
You can either _view_ a dataset without making any changes, or start a new annotation on it.
Search for your dataset by using the search bar or sorting any of the table columns.
Learn more about managing datasets in the [Datasets guide](./datasets.md).

The presentation differs depending on your user role.
Regular users can only start or continue annotations and work on tasks.
[Admins and Team Managers](./users.md#access-rights-roles) also have access to additional administration actions, access-rights management, and advanced dataset properties for each dataset.
What you can do on this screen depends on your user role.
If you are a regular user, you can only create or resume annotations and work on tasks.
If you are [an Admin, a Dataset Manager or a Team Manager](./users.md#access-rights-roles), you can also perform administrative actions, manage access rights, and change dataset settings.

Read more about the organization of datasets [here](./datasets.md#dataset-organization).

Expand Down
178 changes: 13 additions & 165 deletions docs/data_formats.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,81 +2,21 @@

WEBKNOSSOS uses several file formats for reading large-scale volumetric image data and storing skeleton and volume annotations. The section will provide technical backgrounds on these file formats, list examples, and explain concepts and details.

The webKnosso-wrap (WKW) container format is used for all internal voxel data representations - both for the raw (microscopy) image datasets and segmentations. Skeleton annotations are saved as NML files.

Any dataset uploaded to webknossos.org will automatically be converted to WKW on upload - given its source file format is supported by WEBKNOSSOS. Alternatively, you can manually convert your datasets using the [WEBKNOSSOS Cuber CLI tools](https://docs.webknossos.org/wkcuber/index.html) or use a custom script based on the [WEBKNOSSOS Python library](https://docs.webknossos.org/webknossos-py/index.html).

WEBKNOSSOS natively supports loading and streaming data in the following formats:

- webKnossos-wrap (WKW)
- Zarr ([OME NGFF v0.4+ spec](https://ngff.openmicroscopy.org/latest/))
- Neuroglancer `precomputed`
- N5

See the page on [datasets](./datasets.md) for uploading and configuring datasets.
See the page on [software tooling](./tooling.md) for working with these file formats in Python and MatLab.

### Conversion with webknossos.org
When uploading data to [WEBKNOSSOS](https://webknossos.org), various data formats are automatically detected and converted.

In particular, the following file formats are supported:

- [WKW dataset](#WKW-Datasets)
- [Image file sequence](#Single-Layer-Image-File-Sequence) in one folder (tif, jpg, png, dm3, dm4)
- as an extension, multiple folders with image sequences are interpreted as [separate layers](#Multi-Layer-Image-File-Sequence)
- Single-file images (tif, czi, nifti, raw)
- KNOSSOS file hierarchy

!!!info
Note, for datasets in the Zarr, N5 and Neuroglancer Precomputed formats uploading and automatic conversion are not supported.
Instead, they can be directly streamed from an HTTP server or the cloud.
See the page on [datasets](./datasets.md) for uploading and configuring these formats.

#### Single-Layer Image File Sequence
When uploading multiple image files, these files are sorted numerically, and each one is interpreted as one section within a 3D dataset.
Alternatively, the same files can also be uploaded bundled in a single folder (or zip archive).

As an example, the following file structure would create a dataset with one layer which has a z-depth of 3:

```
dataset_name/
├── image_1.tif
├── image_2.tif
├── image_3.tif
└── ...
```

#### Multi-Layer Image File Sequence
The image file sequences explained above can be composed to build multiple [layers](#Layers).
For example, the following file structure (note the additional hierarchy level) would create a dataset with two layers (named `color` and `segmentation`):

```
dataset_name/
├── color
│ ├── image_1.tif
│ ├── image_2.tif
│ └── ...
├── segmentation
│ └── ...
```

#### Single-file images
The following file formats can be dragged individually into WEBKNOSSOS to convert them to a 3D dataset:
- [WEBKNOSSOS-wrap (WKW)](./wkw.md)
- [OME-Zarr / NGFF](./zarr.md)
- [Neuroglancer precomputed](./neuroglancer_precomputed.md)
- [N5](./n5.md)
- [Image Stacks (through Conversion)](./image_stacks.md)

- tif
- czi
- nifti
- raw
- dm3
- dm4
- png
The WEBKNOSSOS-wrap (WKW) container format is used for all internal voxel data representations - both for the raw (microscopy) image datasets and segmentations. Skeleton annotations are saved as NML files.

#### KNOSSOS file hierarchy
Datasets saved as KNOSSOS cubes can also be converted on [WEBKNOSSOS](https://webknossos.org).
Please ensure that you import the correct folder (so that all layers of the dataset are contained).
Any dataset uploaded to webknossos.org will automatically be converted to WKW on upload - given its source file format is supported by WEBKNOSSOS. Alternatively, you can manually convert your datasets using the [WEBKNOSSOS CLI tool](https://docs.webknossos.org/cli) or use a custom script based on the [WEBKNOSSOS Python library](https://docs.webknossos.org/webknossos-py/index.html).

Read more about uploading and configuring datasets on the [datasets page](./datasets.md).

## Concepts
## High-Level Concepts

### Datasets, Cubes, and Buckets

Expand Down Expand Up @@ -126,45 +66,9 @@ The underlying data type limits the maximum number of IDs:
| `uint32` | 4,294,967,295 |
| `uint64` | 18,446,744,073,709,551,615 |

## Data Formats

To bring the above concepts together, WEBKNOSSOS uses [webknossos-wrap (WKW)](https://github.com/scalableminds/webknossos-wrap) as a container format for volumetric voxel data.
For sparse skeleton-like structures, WEBKNOSSOS uses [NML](#NML).

### WKW Datasets
[webknossos-wrap (WKW)](https://github.com/scalableminds/webknossos-wrap) is a format optimized for large datasets of 3D voxel imagery and supports compression, efficient cutouts, multi-channel, and several base datatypes.
It works well for large datasets and is built with modern file systems in mind.
Compared to KNOSSOS datasets, it is more efficient because it orders the data within the container for optimal read performance (Morton order).
WKW is versatile in the image formats it can hold: Grayscale, Multi-Channel, Segmentation, RGB, as well as a range of data types (e.g., `uint8`, `uint16`, `float32`).
Additionally, WKW supports compression for disk space efficiency.

Each layer of a WKW dataset may contain one of the following:

* Grayscale data (8 Bit, 16 Bit, Float), also referred to as `color` data
* RGB data (24 Bit)
* Segmentation data (8 Bit, 16 Bit, 32 Bit)

#### WKW Folder Structure
A WKW dataset is represented with the following file system structure:

```
great_dataset # One folder per dataset
├─ color # Dataset layer (e.g., color, segmentation)
│  ├─ 1 # Magnification step (1, 2, 4, 8, 16 etc.)
│  │  ├─ header.wkw # Header wkw file
│  │  ├─ z0
│  │  │  ├─ y0
│  │  │  │  ├─ x0.wkw # Actual data wkw file
│  │  │ │ └─ x1.wkw # Actual data wkw file
│  │  │  └─ y1/...
│  │  └─ z1/...
│  └─ 2/...
├─ segmentation/...
└─ datasource-properties.json # Dataset metadata (will be created upon import, if non-existent)
```

#### WKW Metadata by Example
Metadata is stored in the `datasource-properties.json`.
### Dataset Metadata
For each datasets, we stored metadata in a `datasource-properties.json` file.
See below for the [full specification](#dataset-metadata-specification).
This is an example:

Expand Down Expand Up @@ -215,6 +119,7 @@ This is an example:
"scale" : [ 11.24, 11.24, 28 ]
}
```

Note that the `resolutions` property within the elements of `wkwResolutions` can be an array of length 3.
The three components within such a resolution denote the scaling factor for x, y, and z.
The term "magnifications" is used synonymously for resolutions throughout the UI.
Expand All @@ -223,7 +128,7 @@ At the moment, WebKnossos guarantees correct rendering of data with non-uniform
Most users do not create these metadata files manually.
WEBKNOSSOS can infer most of these properties automatically, except for `scale` and `largestSegmentId`.
During the data import process, WEBKNOSSOS will ask for the necessary properties.
When using the [WEBKNOSSOS Cuber](https://github.com/scalableminds/webknossos-libs/tree/master/wkcuber), a metadata file is automatically generated. Alternatively, you can create and edit WEBKNOSSOS datasets using the [WEBKNOSSOS Python library](https://github.com/scalableminds/webknossos-libs/).
When using the [WEBKNOSSOS CLI](http://docs.webknossos.org/cli), a metadata file is automatically generated. Alternatively, you can create and edit WEBKNOSSOS datasets using the [WEBKNOSSOS Python library](https://github.com/scalableminds/webknossos-libs/).

[See below for the full specification](#dataset-metadata-specification).

Expand All @@ -247,63 +152,6 @@ WEBKNOSSOS requires several metadata properties for each dataset to properly dis
+ `dataLayers.largestSegmentId`: The highest ID that is currently used in the respective segmentation layer. This is required for volume annotations where new objects with incrementing IDs are created. Only applies to segmentation layers.
+ `dataLayers.dataFormat`: Should be `wkw`.

#### Download "Volume Annotation" File Format

Volume annotations can be downloaded and imported using ZIP files that contain [WKW](./data_formats.md#wkw-datasets) datasets.
The ZIP archive contains one NML file that holds meta information including the dataset name and the user's position.
Additionally, there is another embedded ZIP file that contains the volume annotations in WKW file format.

!!!info
In contrast to on-disk WKW datasets, the WKW files in downloaded volume annotations only contain a single 32^3 bucket in each file.
Therefore, also the addressing of the WKW files (e.g. `z48/y5444/x5748.wkw`) is in steps of 32 instead of 1024.

```
volumetracing.zip # A ZIP file containing the volume annotation
├─ data.zip # Container for WKW dataset
│ └─ 1 # Magnification step folder
│ ├─ z48
│ │ ├─ y5444
│ │ │ └─ x5748.wkw # Actual WKW bucket file (32^3 voxel)
│ │ └─ y5445/...
│ ├─ z49/...
│ └─ header.wkw # Information about the WKW files
└─ volumetracing.nml # Annotation metadata NML file
```

After unzipping the archives, the WKW files can be read or modified with the WKW libraries that are available for [Python and MATLAB](./tooling.md).


### Converting with WEBKNOSSOS Cuber

#### Image Stacks
If you have image stacks, e.g., tiff stacks, you can easily convert them with [WEBKNOSSOS cuber](https://github.com/scalableminds/webknossos-libs/tree/master/wkcuber).
The tool expects all image files in a single folder with numbered file names.
After installing, you can create simple WKW datasets with the following command:

```
python -m wkcuber \
--layer_name color \
--scale 11.24,11.24,25 \
--name great_dataset \
data/source/color data/target
```

This snippet converts an image stack that is located at `data/source/color` into a WKW dataset which will be located at `data/target`.
It will create the `color` layer.
You need to supply the `scale` parameter, i.e., the size of one voxel in nanometers.

Read the full documentation at [WEBKNOSSOS cuber](https://github.com/scalableminds/webknossos-libs/tree/master/wkcuber).
[Please contact us](mailto:[email protected]) or [write a post](https://forum.image.sc/tag/webknossos), if you have any issues with converting your dataset.

#### KNOSSOS Cubes

Datasets saved as KNOSSOS cubes can be easily converted with the [WEBKNOSSOS cuber](https://github.com/scalableminds/webknossos-libs/tree/master/wkcuber) tool.

#### Importing Datasets

After the manual conversion, proceed with the remaining import step.
See the [Datasets guide](./datasets.md#Importing) for further instructions.

#### NML Files
When working with skeleton annotation data, WEBKNOSSOS uses the NML format.
It can be [downloaded](./export.md#data-export-and-interoperability) from and uploaded to WEBKNOSSOS, and used for processing in your scripts.
Expand Down
Loading

0 comments on commit de3b349

Please sign in to comment.