Getting Started

Welcome to the webKnossos documentation. webKnossos is a tool for exploring large-scale 3D image datasets, creating versatile skeleton annotations and generating 3D training data for automated segmentations. Since it is a web-based tool, collaboration, crowdsourcing and publication is very easy.

Feel free to drop us a line or create a Pull Request if you have any suggestions for improving the documentation.

Create a webknossos.org Account

Signing up to webknossos.org is the easiest way to get started with webKnossos. Go to webknossos.org and create an account in the "Demo_Lab" organization. Please make sure to enter a correct email address. After you have entered your details, the account will be automatically activated.

You can also choose to create a new organization which will allow you to upload private datasets at a later point in time and manage other users. For testing purposes, the "Demo_Lab" organization is preferred.

Accounts on webknossos.org are free to use with published datasets. If you wish to use private datasets, there is a fee that covers storage costs and also provides support services such as dataset conversions. Check out the pricing page for more details. You can also rent a fully-managed dedicated webKnossos server from scalable minds or install webKnossos on your own server.

Explore Published Datasets

On webknossos.org there are already a bunch of published community datasets available for you to explore. To get started, navigate to the Datasets tab on your dashboard. There, you find a list of all available datasets. Click on the dataset name to open the dataset.

The list of available datasets

Once you are in the view mode, you are presented with three orthongonal views and one 3D viewport. You can use the following shortcuts to navigate the data. See the full list of gestures and keyboard shortcuts for advanced use.

Shortcut

Operation

Left Mouse Drag or Arrow Keys

Move In-Plane

SPACE or Mousewheel

Move Forward

SHIFT + SPACE or Mousewheel

Move Backward

I or ALT + Mousewheel

Zoom In

O or ALT + Mousewheel

Zoom Out

Scroll Mousewheel (3D View)

Zoom In And Out

Right Click Drag (3D View)

Rotate 3D View

. (Dot)

Toggle Viewport Maximization

You can also change the size of the viewports to see more details in your data and customize your layout.

Explore datasets with customized viewport layouts

Your First Annotation

Click the Create Tracing button from the view mode of a dataset to create your first annotation. Alternatively, navigate to the Datasets tab on your dashboard, identify a dataset that your interested in and click on Start Skeleton Tracing to create a new skeleton annotation. webKnossos will launch the main annotation screen allowing you to navigate your dataset and place markers to reconstruct skeletons.

Drag the mouse while pressing the left mouse button to navigate the dataset. Right-click in the data to place markers, called nodes. Basic movement in the dataset is done with the mouse wheel or by pressing the spacebar keyboard shortcut.

Learn more about the skeleton, volume, and hybrid annotations as well as the interface in the Tracing UI guide.

Editing skeleton and volume annotations in the Tracing UI

Learn More

Now you know the basics of webKnossos. Feel free to explore more features of webKnossos in this documentation.

If you need help with webKnossos, there is a Community Support forum where members of the community and scalable minds are happy to answer your questions. scalable minds also offers commercial support, managed hosting and feature development services. Please contact us if you want to learn more.

webKnossos on Your Own Server

webKnossos is open-source, so you can install it on your own server. We recommend a server with at least 4 CPU cores, 16 GB RAM, and as much disk space as you require for your datasets. As prerequisites, you need to install Git, Docker and Docker Compose on your server.

Installation

To get started, simply clone the Git repository and start the docker containers:

git clone https://github.com/scalableminds/webknossos.git
cd webknossos
docker-compose pull webknossos
./start-docker.sh

This will start an instance of webKnossos on http://localhost:9000/. Open the URL in your browser and configure your organization (see below). This will create a folder for your data at webknossos/binaryData/<organization name>.

For production setups, we recommend more elaborate configurations with a public domain name and HTTPS support. Please contact us if you require any assistance with your production setup.

You may also install webKnossos without Docker. This may be useful if you intend to develop features for webKnossos. Please refer to the Code Readme for details.

Onboarding

When starting with webKnossos you first need to create an organization. An organization represents your lab in webKnossos and handles permissions for users and datasets. Choose a descriptive name for your organization, e.g. "The University of Springfield", "Simpsons Lab" or "Neuroscience Department".

Create your organization

In the onboarding flow, you are asked to create a user account for yourself. This will be the first user of your organization which will automatically be activated and granted admin rights. Make sure to enter a correct email address.

Create your first user

Your First Dataset

Now that you've completed the onboarding, you need to import a dataset. Without any data, webKnossos is not fun.

For small datasets (max. 1GB), you can use the upload functionality provide in the web interface. For larger datasets, we recommend the file system upload. Read more about the import functionality in the Datasets guide.

If you do not have a compatible dataset available, you can use one of the sample datasets for testing purposes.

By default, datasets are visible to all users in your organization. However, webKnossos includes fine-grained permissions to assign datasets to groups of users.

Upload your first dataset Confirm the dataset properties