-
Notifications
You must be signed in to change notification settings - Fork 24
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Updated documentation #7439
Merged
Merged
Updated documentation #7439
Changes from 14 commits
Commits
Show all changes
24 commits
Select commit
Hold shift + click to select a range
45537cb
updated docs
hotzenklotz b21c4ea
docs update #2
hotzenklotz 89b7381
applied some gpt4 feedback
hotzenklotz da2bed9
moar docs
hotzenklotz 719f446
more docs on the data source formats
hotzenklotz e68b34f
more docs
hotzenklotz f6d2c4a
Update docs/dashboard.md
hotzenklotz c30f801
Update docs/datasets.md
hotzenklotz 2386498
Update docs/datasets.md
hotzenklotz db43482
Update docs/datasets.md
hotzenklotz d4fabf6
Update docs/datasets.md
hotzenklotz ad05183
Update docs/zarr.md
hotzenklotz ec5381c
Update docs/zarr.md
hotzenklotz 4222c86
Update docs/zarr.md
hotzenklotz ce2be79
Update docs/zarr.md
hotzenklotz 988caa0
Update docs/getting_started.md
hotzenklotz d9228bd
Update docs/image_stacks.md
hotzenklotz 59dc800
Update docs/image_stacks.md
hotzenklotz 59a4b03
Update docs/zarr.md
hotzenklotz fd661ad
Update docs/zarr.md
hotzenklotz b6162fc
Merge branch 'master' of github.com:scalableminds/webknossos into doc…
hotzenklotz 7972fe3
added PR feedback
hotzenklotz fe0e471
Merge branch 'master' of github.com:scalableminds/webknossos into doc…
hotzenklotz 53ab384
added example video for animations
hotzenklotz File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# Animations | ||
|
||
A picture is worth a thousand words. In this spirit, you can use WEBKNOSSOS to create eye-catching animation 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. | ||
|
||
// animation video | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. TODO |
||
|
||
## 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. | ||
hotzenklotz marked this conversation as resolved.
Show resolved
Hide resolved
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. | ||
|
||
|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
||
|
@@ -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: | ||
|
||
|
@@ -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. | ||
|
@@ -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). | ||
|
||
|
@@ -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. | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"more than" is Genglish: https://en.wikipedia.org/wiki/A_picture_is_worth_a_thousand_words