statebuilder.tools

Neuroglancer tools: key bindings and tool palettes.

A tool is an action a user activates with a key (shift plus the bound letter) or from a tool palette: selecting segments, adjusting a shader control or layer setting by dragging, or stepping through a dimension. Tools are bound when a ViewerState is built, so keys can be allocated across the whole viewer: Neuroglancer keeps one key namespace for every layer, and a key bound twice silently loses its earlier tool when the state loads.

Annotation-placing tools are not here: Neuroglancer restores them only as a layer's active tool, never from a key binding or palette -- and an unrestorable binding makes it drop every binding after it on that layer. Use AnnotationLayer(active_tool=...).

Examples:

>>> from nglui.statebuilder import tools
>>> vs.add_tools(
...     tools.SelectSegments(layer="seg", key="S"),
...     tools.ShaderControlTool(layer="img", control="normalized"),  # key auto-assigned
...     tools.MeshSilhouette(layer="seg"),
...     tools.Dimension(dimension="z"),
...     palette=tools.ToolPalette("Proofreading", side="right"),
... )

Classes:

• Alpha3d –

  Opacity of meshes in the 3d view. Hold the key and scroll to adjust.

• BaseSegmentColoring –

  Whether supervoxels are colored individually. Press to toggle.

• Blend –

  How the image combines with the layers beneath it. Hold the key and scroll to cycle through the options.

• ColorSeed –

  The random segment color palette. Press to pick new random colors.

• CrossSectionRenderScale –

  Resolution of the 2d rendering. Hold the key and scroll to adjust.

• Dimension –

  Step through one dimension, e.g. z, while the key is held.

• HideSegmentZero –

  Whether segment 0 is hidden. Press to toggle.

• HoverHighlight –

  Whether the segment under the mouse is highlighted. Press to toggle.

• IgnoreNullVisibleSet –

  Whether an empty selection shows every segment. Press to toggle.

• LayerSetting –

  Base class for tools that adjust one of a layer's display settings.

• MergeSegments –

  Merge two segments (graphene/proofreading-enabled segmentations).

• MeshRenderScale –

  Mesh level of detail. Hold the key and scroll to adjust.

• MeshSilhouette –

  Silhouette shading of meshes in the 3d view. Hold the key and scroll to adjust.

• NotSelectedAlpha –

  2d opacity of unselected segments. Hold the key and scroll to adjust.

• Opacity –

  Image opacity in the 2d views. Hold the key and scroll to adjust.

• Saturation –

  Saturation of segment colors. Hold the key and scroll to adjust.

• SegmentDefaultColor –

  One color for all segments without an explicit color. Press to switch to a fixed color, then scroll to adjust it.

• SelectSegments –

  Select or deselect segments by painting over them.

• SelectedAlpha –

  2d opacity of selected segments. Hold the key and scroll to adjust.

• ShaderControlTool –

  Adjust one of a layer's shader controls, e.g. image contrast.

• SkeletonLineWidth2d –

  Skeleton line width in the 2d views. Hold the key and scroll to adjust.

• SkeletonLineWidth3d –

  Skeleton line width in the 3d view. Hold the key and scroll to adjust.

• SkeletonMode2d –

  Skeletons as lines, or lines and points, in the 2d views. Hold the key and scroll to cycle through the options.

• SkeletonMode3d –

  Skeletons as lines, or lines and points, in the 3d view. Hold the key and scroll to cycle through the options.

• SplitSegments –

  Split a segment (graphene/proofreading-enabled segmentations).

• Tool –

  Base class for tools.

• ToolPalette –

  A named panel of tool buttons, placed like any other side panel.

• VolumeRendering –

  Volume rendering mode in the 3d view. Hold the key and scroll to cycle through the options.

• VolumeRenderingDepthSamples –

  Depth samples for the volume rendering. Hold the key and scroll to adjust.

• VolumeRenderingGain –

  Brightness of the volume rendering. Hold the key and scroll to adjust.

Functions:

• coerce_layer_tools –

  Normalize a layer's tools: a list of tools, or a mapping of key -> tool.

• coerce_tool –

  Make a Tool from a Tool, a Tool class, or a Neuroglancer tool type name.

Alpha3d

Bases: LayerSetting

Opacity of meshes in the 3d view. Hold the key and scroll to adjust.

The "Opacity (3d)" control in Neuroglancer's layer panel.

BaseSegmentColoring

Bases: LayerSetting

Whether supervoxels are colored individually. Press to toggle.

The "Base segment coloring" control in Neuroglancer's layer panel.

Blend

Bases: LayerSetting

How the image combines with the layers beneath it. Hold the key and scroll to cycle through the options.

The "Blending (slice)" control in Neuroglancer's layer panel.

ColorSeed

Bases: LayerSetting

The random segment color palette. Press to pick new random colors.

The "Color seed" control in Neuroglancer's layer panel.

CrossSectionRenderScale

Bases: LayerSetting

Resolution of the 2d rendering. Hold the key and scroll to adjust.

The "Resolution (slice)" control in Neuroglancer's layer panel.

Dimension

Bases: Tool

Step through one dimension, e.g. z, while the key is held.

A viewer-level tool: it acts on the viewer position, not on a layer.

Parameters:

• dimension (str) –

  Name of the dimension, e.g. "z".

HideSegmentZero

Bases: LayerSetting

Whether segment 0 is hidden. Press to toggle.

The "Hide segment ID 0" control in Neuroglancer's layer panel.

HoverHighlight

Bases: LayerSetting

Whether the segment under the mouse is highlighted. Press to toggle.

The "Highlight on hover" control in Neuroglancer's layer panel.

IgnoreNullVisibleSet

Bases: LayerSetting

Whether an empty selection shows every segment. Press to toggle.

The "Show all by default" control in Neuroglancer's layer panel.

LayerSetting

Bases: Tool

Base class for tools that adjust one of a layer's display settings.

Activating one (shift plus its key) shows that setting's control at the bottom of the viewer. Use the named subclasses, e.g. MeshSilhouette or Alpha3d, so a misspelled setting is an attribute error your editor or type checker catches.

MergeSegments

Bases: _SegmentationTool

Merge two segments (graphene/proofreading-enabled segmentations).

MeshRenderScale

Bases: LayerSetting

Mesh level of detail. Hold the key and scroll to adjust.

The "Resolution (mesh)" control in Neuroglancer's layer panel.

MeshSilhouette

Bases: LayerSetting

Silhouette shading of meshes in the 3d view. Hold the key and scroll to adjust.

The "Silhouette (3d)" control in Neuroglancer's layer panel.

NotSelectedAlpha

Bases: LayerSetting

2d opacity of unselected segments. Hold the key and scroll to adjust.

The "Opacity (off)" control in Neuroglancer's layer panel.

Opacity

Bases: LayerSetting

Image opacity in the 2d views. Hold the key and scroll to adjust.

The "Opacity (slice)" control in Neuroglancer's layer panel.

Saturation

Bases: LayerSetting

Saturation of segment colors. Hold the key and scroll to adjust.

The "Saturation" control in Neuroglancer's layer panel.

SegmentDefaultColor

Bases: LayerSetting

One color for all segments without an explicit color. Press to switch to a fixed color, then scroll to adjust it.

The "Fixed color" control in Neuroglancer's layer panel.

SelectSegments

Bases: _SegmentationTool

Select or deselect segments by painting over them.

SelectedAlpha

Bases: LayerSetting

2d opacity of selected segments. Hold the key and scroll to adjust.

The "Opacity (on)" control in Neuroglancer's layer panel.

ShaderControlTool

Bases: Tool

Adjust one of a layer's shader controls, e.g. image contrast.

Parameters:

• control (str) –

  Name of the #uicontrol; "normalized" is the default image shader's contrast control.

SkeletonLineWidth2d

Bases: LayerSetting

Skeleton line width in the 2d views. Hold the key and scroll to adjust.

The "Line width (2d)" control in Neuroglancer's layer panel.

SkeletonLineWidth3d

Bases: LayerSetting

Skeleton line width in the 3d view. Hold the key and scroll to adjust.

The "Line width (3d)" control in Neuroglancer's layer panel.

SkeletonMode2d

Bases: LayerSetting

Skeletons as lines, or lines and points, in the 2d views. Hold the key and scroll to cycle through the options.

The "Skeleton mode (2d)" control in Neuroglancer's layer panel.

SkeletonMode3d

Bases: LayerSetting

Skeletons as lines, or lines and points, in the 3d view. Hold the key and scroll to cycle through the options.

The "Skeleton mode (3d)" control in Neuroglancer's layer panel.

SplitSegments

Bases: _SegmentationTool

Split a segment (graphene/proofreading-enabled segmentations).

Tool

Base class for tools.

Parameters:

• layer (str or Layer) –

  The layer the tool acts on. Required for layer tools added with ViewerState.add_tools; omitted when the tool is given to a layer's own tools list.

• key (str or False) –

  A single capital letter to bind the tool to. None assigns a free key; False binds no key, for a tool that should only appear in a palette.

Methods:

• to_json –

  The tool's JSON, with a layer field when given one (as palettes need).

to_json(layer_name=None)

The tool's JSON, with a layer field when given one (as palettes need).

ToolPalette

Bases: SidePanel

A named panel of tool buttons, placed like any other side panel.

Parameters:

• name (str) –

  The palette's title.

• tools (sequence of Tool) –

  Tools shown in the palette. Tools can also be added with vs.add_tools(..., palette=...). Layer tools need their layer set.

• query (str) –

  A query that fills the palette with matching tools, in Neuroglancer's palette query syntax.

• visible (bool) –

  Whether the palette is open. Default is True: unlike the built-in panels, a palette exists only because you added it.

• side (optional) –

  Placement, as for SidePanel.

• size (optional) –

  Placement, as for SidePanel.

• flex (optional) –

  Placement, as for SidePanel.

• row (optional) –

  Placement, as for SidePanel.

• col (optional) –

  Placement, as for SidePanel.

Examples:

>>> ToolPalette("Proofreading", side="right")

Methods:

• to_json –

  The palette's JSON, checking each tool's layer against state.

• with_tools –

  Return a copy of this palette with tools appended.

to_json(state)

The palette's JSON, checking each tool's layer against state.

with_tools(*tools)

Return a copy of this palette with tools appended.

VolumeRendering

Bases: LayerSetting

Volume rendering mode in the 3d view. Hold the key and scroll to cycle through the options.

The "Volume rendering (experimental)" control in Neuroglancer's layer panel.

VolumeRenderingDepthSamples

Bases: LayerSetting

Depth samples for the volume rendering. Hold the key and scroll to adjust.

The "Resolution (3D)" control in Neuroglancer's layer panel.

VolumeRenderingGain

Bases: LayerSetting

Brightness of the volume rendering. Hold the key and scroll to adjust.

The "Gain (3D)" control in Neuroglancer's layer panel.

add_palettes(state, palettes)

Write tool palettes onto a built neuroglancer state.

bind_tools(state, requests, tag_layers=(), reserved=())

Bind tools onto a built neuroglancer state, allocating keys viewer-wide.

Keys are claimed in order of how deliberately they were chosen:

1. Bindings the state already has from a raw layer or base state, which are kept as they are. Duplicates among them are warned about, since the viewer will drop one.
2. Tools with an explicit key, which must be free, or this raises.
3. Tag tools that nglui generated on tag_layers. Each keeps its usual key when that is free; the rest then move to the next free letters, with a warning, and any left without a key are dropped, with a warning -- the tag stays usable from the layer's annotation panel.
4. Tools with key=None, which take the next free letter, or this raises.

Parameters:

• state (ViewerState) –

  The state, with every layer already added.

• requests (list of (Tool, str or None)) –

  Each tool with the name of the layer it belongs to, if it came from a layer's own tools list.

• tag_layers (tuple of str, default: () ) –

  Names of nglui annotation layers whose tag tool bindings may be moved.

• reserved (iterable of str, default: () ) –

  Keys bound elsewhere, e.g. by the viewer's extra JSON, which is merged in after binding and would otherwise silently replace what lands there.

check_layer_type(tool, layer_type, layer_name)

Raise if tool cannot act on a layer of layer_type.

coerce_layer_tools(value)

Normalize a layer's tools: a list of tools, or a mapping of key -> tool.

Values may be Tool instances, Tool classes, or Neuroglancer tool type names.

Examples:

>>> coerce_layer_tools({"H": "meshSilhouetteRendering", "S": tools.SelectSegments})
[MeshSilhouette(layer=None, key='H'), SelectSegments(layer=None, key='S')]

coerce_tool(value)

Make a Tool from a Tool, a Tool class, or a Neuroglancer tool type name.

Raises:

• ValueError –

  If a name is not a bindable tool type, or names a tool that needs options.