Annotation Layers¶

Annotation layers let you place geometric markers — points, lines, bounding boxes, ellipsoids, and polylines — on top of any other data displayed in the viewer. Local annotations are stored as part of the viewer state and can be linked to segmentation layers so that each annotation records the IDs of the segments it touches. Remote annotations can stream from data locations outside of neuroglancer, but this guide will focus on local annotations.

Creating a local annotation layer¶

To create a new annotation layer:

Click the + button at the right end of the layer bar at the top of the viewer.
In the layer type picker, choose annotation (abbreviated ann). Then type local://annotations as the source to make a local annotation layer.

shortcut: ctrl+click the ‘+’ button to make a new annotation layer immediately.

A new, empty local annotation layer is added to the layer bar and its side panel opens.

The Annotations tab¶

Selecting an annotation layer opens its side panel. Within the side panel, select the Annotations tab. This tab contains:

A row of tool buttons for placing new annotations (see Annotation tools below).
A list of all annotations in the layer. an entry in this list selects that annotation and moves the view to its position.

the Rendering tab for controls related to how annotations are drawn, including: - Controls for the annotation layer’s color. - The annotation shader code, which can control how annotations are rendered.

Annotation tools¶

The Annotations tab provides one button per annotation type. Click a tool button to activate that tool for the layer. With the tool active, you place points by holding Ctrl + left-clicking in either a 2-D cross-section view or the 3-D projection view — both work for every annotation tool. The point is placed at the location under the mouse cursor in whichever view you click.

Each tool interprets your Ctrl left-clicks as follows:

Annotate point

A single Ctrl left-click places a point at the cursor and finishes the annotation. Each subsequent click starts a new point annotation.

Annotate line

First Ctrl + : places the start endpoint of the line.
Second Ctrl + : places the end endpoint of the line and finishes the annotation.

Annotate bounding box

First Ctrl + : places one corner of the axis-aligned bounding box.
Second Ctrl + : places the opposite corner and finishes the annotation. The box is drawn axis-aligned in the annotation coordinate space between the two corner points.

Annotate ellipsoid

First Ctrl + : places the center of the axis-aligned ellipsoid.
Second Ctrl + : sets the ellipsoid’s radii. The radius along each axis is taken from the absolute distance between the center and the second click along that axis, so clicking farther from the center produces a larger ellipsoid. The second click also finishes the annotation.

Annotate polyline

First Ctrl + : places the first vertex of the polyline.
Each subsequent Ctrl + : appends another vertex, extending the polyline by one segment.
Finishing: hit enter to end the polyline. See Working with polylines for details and how to undo the last vertex.

All clicks use the same Ctrl + left-click binding regardless of whether you are clicking in a 2-D or 3-D view. Neuroglancer will use the same picking scheme that the right click tool uses when moving.

Note, you can still right click to move around, or drag/scroll through the dataset to find the place where you want to annotate.

Working with polylines¶

The polyline tool builds up an annotation one point at a time. To finish a polyline, hit Enter or click the last point a second time — that is, place a new point at the exact location of the previous one. Neuroglancer treats two consecutive points at the same position as the end of the polyline.

To remove the most recently added point of an in-progress annotation (useful if you misclicked a vertex of a polyline, line, box, or ellipsoid), press Backspace.

Selecting an annotation¶

To select an existing annotation:

In a data view (2-D or 3-D): hover over the annotation and press Ctrl + right-click. The annotation is selected and its details appear in the selection panel.
In the annotation list: left-click an entry in the list inside the Annotations tab. The annotation is pinned in the selection panel and the view recenters on it.
Jump to an annotation without selecting it: right-click an entry in the annotation list. The view moves directly to that annotation’s location without changing the current pinned selection.

Deleting an annotation¶

There are three ways to delete an annotation:

From a data view: hover over the annotation and press Ctrl + Alt + right-click.
From the annotation list: hover over the annotation’s entry in the list and click the trash-can icon that appears.
From the selection panel: select the annotation (Ctrl + left-click) so its details open in the selection panel, then click the trash-can icon in the selection widget.

Moving annotation points¶

Individual points and vertices of existing annotations can be moved by holding Alt + left-click-dragging on the point. This works for the endpoints of a line, the corners of a bounding box, the center and radius handles of an ellipsoid, and any vertex of a polyline.

If you do the same Alt + left-click-dragging on the lines of an annotation you will move the entire annotation instead of just a single point. This is useful for repositioning an annotation without changing its shape. Also, this works in 3d, but moves points in the plane parallel to the screen, witout changing the points depth relative to the camera. You may need to move a point rotate 90 degrees, and then move the point again to get it close to what where you watn to be.

Note, shift + left-click-dragging on an annotation point in the 2D view will rotate the plane of that 2D view to make for an “off-axis” cut of the data. This can be disorienting, if you don’t know what is happening. In anisotropic data, this can lead to ‘striping’ patterns in the rendering, where different slices of lower resolution, data occupy different regions of the screen. To ‘snap’ the plane back to the nearest axis-aligned orientation, hit the Z shortcut.

If you use the same Alt + left-click-dragging in the annotation list, you can reorder the annotations in the list.

Reordering annotations in the list¶

For local annotation layers, you can change the order of annotations in the Annotations tab by Alt + left-click-dragging an entry in the list to a new position. While dragging, a colored bar indicates whether the dragged annotation will be placed before (top edge) or after (bottom edge) the row under the cursor. Release the mouse to commit the move, or press Escape to cancel.

Reordering is restricted to annotations within the same local annotation source and is persisted in the viewer JSON state.

Adding a description to an annotation¶

Each annotation can carry a free-form text description.

Select the annotation (see Selecting an annotation). Its details open in the selection panel on the right.
In the selection panel, locate the Description text area underneath the annotation’s properties.
Type your description. The text is saved to the annotation when the text area loses focus (for example, when you click elsewhere or Tab away).

The description is stored on the annotation itself and is persisted as part of the viewer state.

Depth Range and Annotations¶

Neuroglancer has a concept of a “depth range” that controls which objects are visible in the 2D and 3D views based on their depth relative to the cursor. Annotations are visible if they are within that depth range. This applies to all objects in the 3d view, and or other vector based objects (i.e. skeletons) which are not voxel based in the 2d view. Voxel based objects (images/segmentation) are always “sliced” through at a single pixel depth in the 2D views.

The depth range can be found by hovering over the xyz position readout in the upper left of each rendering panel. The depth range is expressed in physical units if the dimensions rendered has them. (for example, nm = nanometers, um=microns, mm=millimeters, etc).

You may need to adjust the depth range to get rendering behavior that you desire. For example, consider annotating cell body locations in an Electron Microscopy dataset that has 40nm thick sections in Z.

With a depth range of 10nm, annotations are visible only in the precise section where they were placed. If you relax the depth range to 120nm and move through sections, annotations fade out after a few sections. Setting it back to 40nm makes annotations visible only in the annotated section.

If the “zoom-relative” button is checked, neuroglancer adjusts the depth range to scale up as you zoom out and scale down as you zoom in. When zoomed out and flipping through sections, annotations appear ‘farther’ away in Z than when zoomed in. For some applications this is natural, as images downsample as you zoom out — annotations then render at a similar relative depth to the voxels used for the current view.

However for some applications this is unintuitive. For example, if you want to easily see whether a cell has already been annotated regardless of zoom level, disable the “zoom-relative” option and set the depth range to the approximate radius of the object you are annotating (say 5 microns for a cell). Annotations will then fade in and out on that length scale, no matter the zoom.

Annotation Properties and Schema¶

Annotations are geometries in space that can represent many things, but often you also want to write something else down about those annotations. The description field is nice, but any scientist who has tried to turn free form text fields into data knows that unstructured fields are not the best way to capture information. Plus, if we write down our data in structured way we can easily use that data to drive the visual appearence of our annotations, which you can read about in Annotation Shaders.

The schema tab of the local annotation layer lets you define custom properties for your annotations, with default properties. To add a new property click the + button. You first select a data type from the list of available types. This will add a new row to the schema. Once added, you can name the property and give it a default value. New annotations will hae the default value. Note however, if you change the default value, existing annotations will not be updated to have the new default value. Press the pencil icon to the right to edit the description of the property.

Once you have added properties, the selection widget will show the properties of that annotation in the selection widget, and you can set the properties for that annotation there. and the rendering tab will show the properties as options to drive the shader code (see Annotation Shaders). The descriptions will be available as tooltips hover text in both locations.

Enums¶

If you scroll down in this list of available types, below “Numeric” you will find a list of “Enum” types. These are useful for when you want to mark annotations with a controlled vocabulary of strings. If you want free form text, the annotation description field is already available for that.

When you pick an enum type, below the “Default value” for that enum will be a interface to add and rename enum values. You can add new values with the + button found there. Once you have added some enum values, you can select one as the default value for that property. When you edit the property of an annotation, you will get a dropdown to select which enum value you want to set that property to.

Keyboard and mouse shortcuts¶

The following default bindings apply when an annotation tool is active on the selected layer:

Action	Binding
Create annotation / place next point	`Ctrl` + left-click
Select annotation under cursor	`Ctrl` + right-click
Move an annotation point	`Alt` + left-click-drag
Reorder an annotation in the list (local annotations)	`Alt` + left-click-drag on a list entry
Delete an annotation	`Ctrl` + `Alt` + right-click
Undo last annotation point (during multi-point placement)	`Backspace`
Finish polyline annotation	`Enter` or place a new point at the same position as the previous one

Custom hotkeys¶

Mainline neuroglancer does not include built-in hotkeys for cycling through annotations (for example, “next annotation” / “previous annotation”).

Forks or downstream deployments of neuroglancer may bundle additional default bindings for annotation navigation.

Linked segmentation layers¶

An annotation layer can be linked to one or more segmentation layers through named relationships. The default relationship is named segments. When an annotation is created on or near a segment in a linked segmentation layer, the segment’s ID is captured on the annotation as a related ID for that relationship.

To link an annotation to a segmentation, select the segmentation layer from the dropdown next to the segments relationship control. Once selected, any annotations you make will capture the segment ID underneath the annotation, in either 2d or 3d.

Once annotations have related IDs, then checking the box next to the relationship control will trigger selective loading of the annotations that are related to visible segmentIDs selected from the segmentation layer.

Note, this same control works for non-local annotation layers that have registered relationships as well.

Linking a segmentation layer¶

In the annotation layer’s side panel, the linked-segmentations widget shows one row per relationship. Each row provides:

A checkbox that controls whether annotations are filtered by this relationship’s related IDs (see Filtering annotations by segmentation).
The relationship name (for example, segments).
A layer selector for picking the segmentation layer this relationship is linked to.

Selecting a segmentation layer in this widget establishes the link. After that, newly created annotations automatically pick up the IDs of the segments under their points.

When a single annotation is selected, the selection panel includes a Related Segments section for each relationship. The section lists the related IDs for that annotation and lets you:

Toggle the visibility of each related segment in the linked segmentation layer.
Copy segment IDs.
Add or remove related IDs.

Filtering annotations by segmentation¶

When the filter checkbox for a relationship is enabled, the annotation layer displays only annotations whose related IDs for that relationship are currently visible in the linked segmentation layer. This is useful for showing only the annotations that belong to the segments you have selected.

An additional Ignore null related segment filter checkbox controls how annotations with no related IDs are treated while filtering is active:

When enabled, annotations with no related IDs are shown regardless of which segments are visible.
When disabled, annotations with no related IDs are hidden whenever filtering by segmentation is on.