Understanding the User Interface
The main webKnossos user interface for viewing and annotating datasets is divided into five sections:
- A toolbar for general purposes features such as Saving your work and displaying the current position within the dataset. Further, it provides access to all the tools for annotating and manipulating your data. It spans along the full width of the top of your screen.
- The left-hand side panel provides a list of all available data, segmentation, and annotation layers as well as a settings menu for viewport options and keyboard controls.
- The center of the screen is occupied by the annotation interface. Your dataset is displayed here, and you navigate and annotate it as desired. Most interactions will take place here.
- The right-hand side panel is occupied by several tabs providing more information on your current dataset, skeleton/volume annotations, and other lists. Depending on your editing mode these tabs might adapt.
- The bottom of the screen is covered by a status bar showing context-sensitive hints for mouse controls as well as additional information on mouse hover.
The toolbar contains frequently used commands, such as saving and sharing, your current position within the dataset, and the ability to switch between various modes for viewing. Further, it provides access to all the tools for annotation, navigation, and more.
The most common buttons are:
Settings: Toggles the visibility of the left-hand side panel with all data and segmentation layers and their respective settings.
Redo: Undoes the last operation or redoes it if no new changes have been made in the meantime. Undo can only revert changes made in this session (since the moment the annotation view was opened). To revert to older versions use the "Restore Older Version" functionality described later in this list.
Save: Saves your annotation work. webKnossos automatically saves every 30 seconds.
Archive: Closes the annotation and archives it, removing it from a user's dashboard. Archived annotations can be found on a user's dashboard under "My Annotations" and by clicking on "Show Archived Annotations". Use this to declutter your dashboard. (Not available for tasks)
Download: Starts a download of the current annotation including any skeleton and volume data. Skeleton annotations are downloaded as NML files. Volume annotation downloads contain the raw segmentation data as WKW files.
Share: Create a shareable link to your dataset containing the current position, rotation, zoom level etc. Use this to collaboratively work with colleagues. Read more about this feature in the Sharing guide.
Restore Older Version: Opens a window that shows all previous versions of an annotation. webKnossos keeps a complete version history of all your changes to an annotation (separate for skeleton/volume). From this window, any older version can be selected, previewed, and restored.
A user can directly jump to any position within their datasets by entering them in the position input field. The same is true for the camera rotation in flight/oblique modes. Clicking on the position or rotation labels copies the values to the clipboard.
The toolbar further features all available navigation and annotation tools for quick access:
Move: Navigate around the dataset.
Skeleton: Create skeleton annotations and place nodes. Read more about skeleton annotations.
Trace: Creates volume annotations by drawing outlines around the voxels you would like to label. Read more about volume annotations.
Brush: Creates volume annotations by drawing over the voxels you would like to label.
Erase (Trace/Brush): Removes voxels from a volume annotation by drawing over the voxels you would like to erase.
Fill Tool: Flood-fills the clicked region with a volume annotation until it hits the next segment boundary (or the outer edge of your viewport). Used to fill holes in a volume annotation or to relabel a segment with a different id.
Segment Picker: Select the volume annotation ID of a segment to make it the active cell id to continue labeling with that ID/color.
Bounding Box: Creates and resizes any bounding box. See also the BoundingBox panel below.
Layers and Settings
The left-hand side panel features both a list of all available data and annotation layers as well as settings menu to fine-tune some parameters of webKnossos. All settings are automatically saved as part of a user's profile.
Each dataset consists of one or more data and annotation layers. A dataset typically has at least one
color layer containing the raw microscopy/etc image. Additional layers can include segmentations, skeleton and volume annotations. Each layer has several settings to adjust the viewing experience:
Histogram & General Layer Properties
Histogram: The Histogram displays sampled color values of the dataset on a logarithmic scale. The slider below the Histogram can be used to adjust the dynamic range of the displayed values. In order to increase the contrast of data, reduce the dynamic range. To decrease the contrast, widen the range. In order to increase the brightness, move the range to the left. To decrease the brightness, move the range to the right. Above the the histogram, there are icon buttons to further adjust the histogram or otherwise interact with the layer:
pencil: Manipulate the min/max value of the histogram range. Clips values above/below these limits.
vertical line: Automatically adjust the histogram for best contrast. Contrast estimation is based on the data currently available in your viewport.
circle arrow: Reload the data from server. Useful if the raw data has been changed on disk and you want to refresh your current session.
scanner: Navigates the webKnossos camera to a position within the dataset where there is data available for the respective layer. This is especially useful for working with smaller layers - likely segmentations - that might not cover the whole dataset and are hard to find manually.
Opacity: Increase / Decrease the opacity of the data layer. 0% opacity makes a layer invisible. 100% opacity makes it totally opaque. Useful for overlaying several layers above one another.
Visibility: Use the eye icon on the left side of layer name to enable/disable it. Toggeling the visibility of a layer, is often the quickest way to make information available in the dataset or hide to get an overview. Disabling the visibility, unloads/frees these resources from your GPU hardware and can make viewing larger datasets more performant. Also, depending on your GPU hardware, there is a physical upper limit for how many layers - typically 16 or more - can be displayed at any time (WebGL limitation). Toggle layers as needed to mitigate this.
Color and Segmentation Layers
In addition to the general layer properties mentioned above,
segmentation layers come with a number of other settings:
colorlayer can be re-colored to make it easily identifiable. By default, all layers have a white overlay, showing the true, raw black & white data. Clicking on the square color indicator brings up your system's color palette to choose from. Note, there is an icon button for inverting all color values in this layer.
Pattern Opacity: Adjust the visibility of the texture/pattern on each segment. To make segments easier to distinguish and more unique, a pattern is applied to each in addition to its base color. 0% hides the pattern. 100% makes the pattern very prominent. Great for increasing the visual contrast between segments.
ID Mapping: webKnossos supports applying pre-computed agglomerations/groupings of segmentation IDs for a given segmentation layer. This is a very powerful feature to explore and compare different segmentation strategies for a given segmentation layer. Mappings need to be pre-computed and stored together with a dataset for webKnossos to download and apply. Read more about this here.
Skeleton Annotation Layer
The skeleton annotation layer contains any skeletons/trees that you add to your dataset. You can quickly toggle the visibility of all skeletons by enabling/disabling this layer.
Node Radius: Controls the size property of each node. Large values will render big nodes, small values create tiny nodes. Each node can have a different size. This is useful for annotations where node sizes encode a meaning.
Particle Size: Controls the minimum node size for all nodes. This will globally override nodes falling below this node radius threshold. Used together with the
Override Node Radiusbelow.
Clipping Distance: The distance between 3D structures and the camera used for hiding ("clipping") structures. Use it to reduce the number of visible nodes in the viewports and declutter your screen.
Override Node Radius: When toggled, globally overrides all individual node sizes. This allows to uniformly adjust the size of all nodes simultaneously. Used together with the
Auto-center Nodes: Per default, each time you place a node in a skeleton annotation, the webKnossos viewport will center on this node. Disable, if you do not want the viewport to move/reposition while clicking nodes.
Highlight Commented Nodes: When active, nodes that have a comment associated with them will be rendered with a slight board around them. This is useful for quickly identifying (important) nodes.
Note, not all control/viewport settings are available in every annotation mode.
Keyboard delay (ms): The initial delay before an operation will be executed when pressing a keyboard shortcut. A low value will immediately execute a keyboard's associated operation, whereas a high value will delay the execution of an operation. This is useful for preventing an operation being called multiple times when rapidly pressing a key in short succession, e.g., for movement.
Move Value (nm/s): A high value will speed up movement through the dataset, e.g., when holding down the spacebar. Vice-versa, a low value will slow down the movement allowing for more precision. This setting is especially useful in
d/f-Switching: If d/f switching is disabled, moving through the dataset with
fwill always go forward by increasing the coordinate orthogonal to the current slice. Correspondingly,
dwill move backwards by decreasing that coordinate. However, if d/f is enabled, the meaning of "forward" and "backward" will change depending on how you create nodes. For example, when a node is placed at z == 100 and afterwards another node is created at z == 90, z will be decreased when going forward.
Classic Controls: Disabled by default to provide the best webKnossos user experience. When enabled, several keyboard shortcuts and mouse interactions change to maintain backward compatibility for long-time users. See also the section on Classic Keyboard Controls.
Viewport Options / Flight Options
Zoom: The zoom factor for viewing the dataset. A low value moves the camera really close to the data, showing many details. A high value, will you show more of the dataset but with fewer details and is great for getting an overview or moving around quickly.
Show Crosshairs: Shows / Hides the crosshair overlay over the viewports.
Show Scalebars: Shows / Hides the scale bars overlay over the viewports.
Mouse Rotation: Increases / Decreases the movement speed when using the mouse to rotate within the datasets. A low value rotates the camera slower for more precise movements. A high value rotates the camera quicker for greater agility.
Keyboard Rotation: Increases / Decreases the movement speed when using the arrow keys on the keyboard to rotate within the datasets. A low value rotates the camera slower for more precise movements. A high value rotates the camera quicker for greater agility.
Crosshair Size: Controls the size of the crosshair in flight mode.
Sphere Radius: In flight mode, the data is projected on the inside of a sphere with the camera located at the center of the sphere. This option influences the radius of said sphere flattening / rounding the projected viewport. A high value will cause less curvature showing the detail with more detail and less distortion. A low value will show more data along the edges of the viewport.
Hardware Utilization: Adjusts the quality level used for rendering data. Changing this setting influences how many data is downloaded from the server as well as how much pressure is put on the user's graphics card. Tune this value to your network connection and hardware power. After changing the setting, the page has to be refreshed.
Loading Strategy: You can choose between two different loading strategies. When using "best quality first" it will take a bit longer until you see data, because the highest quality is loaded. Alternatively, "Progressive quality" can be chosen which will improve the quality progressively while loading. As a result, initial data will be visible faster, but it will take more time until the best quality is shown.
4 Bit: Toggles data download from the server using only 4 bit instead of 8 bit for each voxel. Use this to reduce the amount of necessary internet bandwidth for webKnossos. Useful for showcasing data on the go over cellular networks, e.g 4G.
Interpolation: When interpolation is enabled, bilinear filtering is applied while rendering pixels between two voxels. As a result, data may look "smoother" (or blurry when being zoomed in very far). Without interpolation, data may look more "crisp" (or pixelated when being zoomed in very far).
Render Missing Data Black: If a dataset does not contain data at a specific position, webKnossos can either render these voxels in "black" or it can try to render data from another magnification.
Right-Hand Side Panel
The right-hand side panel includes a number of tabs with specific information, additional interactions, listings about your current skeleton and/or volume annotation. When working with any of the webKnossos annotation tools (see above), any interactions with the dataset will lead to entries in the listing provided here.
Info: Contains mostly metainformation about the dataset and annotation. Can be used to name an annotation and provide an additional description, e.g., when sharing with collaborators. Includes a button to start automated analysis on your dataset (beta feature).
Skeleton: Lists all available skeleton annotations and offers further interactions with them. Read more about skeleton annotations.
Comments: Lists all comments assigned to individual nodes of a skeleton. Read more about comments and skeleton annotations.
Segments: List all segments created during a volume annotation. It also provides access to mesh generation for indivual segments or the whole dataset, mesh visualization, mesh downloads, and more. Read more about 3D meshes.
BBoxes: List all bounding boxes present in the dataset. Create new bounding boxes or adjust existing ones. This provides an alternativ interface for the
AbsTree: Renders and abstract 2D tree representation of a skeleton annotation when enabled. Might be quite resource intense when working with large skeletons.
The status bar at the bottom of the screen serves three functions:
- It shows context-sensitive mouse and keyboard control hints. Depending on your selected annotation tool amd any pressed modifier keys (Shift, CMD, CTRL, ALT, etc) it provides useful interaction hints and shortcuts.
- It provides useful information based on your mouse positioning and which objects it hovers over. This includes the current mouse position in the dataset coordinate space, any segment ID that you hover over, and the currently rendered magnification level (MipMap image pyramid) used for displaying any data.
- When working with skeletons, the active node and tree IDs are listed. Use the little pencil icon to select/mark a specific ID as active if required. For more on the active node ID, see the section on skeleton annotations.