Skip to content

statebuilder.ngl_annotations

Classes:

Functions:

Attributes:

  • DEFAULT_TAG_BINDINGS –

    Keys bound to tag tools, in order. Neuroglancer requires single capital letters.

  • PROPERTY_ID_PATTERN –

    Neuroglancer's parseAnnotationPropertyId, which throws on anything else.

DEFAULT_TAG_BINDINGS = ['Q', 'W', 'E', 'R', 'T', 'A', 'S', 'D', 'F', 'G'] module-attribute

Keys bound to tag tools, in order. Neuroglancer requires single capital letters.

PROPERTY_ID_PATTERN = re.compile('^[a-z][a-zA-Z0-9_]*$') module-attribute

Neuroglancer's parseAnnotationPropertyId, which throws on anything else.

A rejected identifier fails the whole layer, not just the property, so nglui has to enforce this even though the Python library does not.

BoolPropertyStrategy

Bases: TagStrategy

Main Neuroglancer encoding.

Tags are annotation properties of type: "bool", bound to the generic toggleBoolProperty tool. Unlike the legacy encoding this is not backward compatible: a viewer that predates bool properties fails to parse the entire layer, which is why it is only used when the target is known to support it.

LegacyTagStrategy

Bases: TagStrategy

seung-lab / Spelunker encoding.

Tags are uint8 properties named tag0..tagN carrying a non-standard tag key that holds the label, bound to tagTool_tagN tool types. Main Neuroglancer parses these without error but ignores the tag key, so the tags survive a modern viewer as unlabeled columns.

TagStrategy

How a set of tag labels becomes Neuroglancer annotation properties.

The two dialects differ in every part of the encoding -- the property spec, the tool binding, and the per-annotation value -- so they are kept as whole strategies rather than as branches inside the serializer.

Methods:

  • encode –

    Build one annotation's props array.

  • property_specs –

    Build the layer's annotationProperties list.

  • tool_bindings –

    Build the layer's toolBindings map.

encode(annotation, tags)

Build one annotation's props array.

Must return exactly one entry per tag: Neuroglancer reads props positionally against annotationProperties and rejects an array of any other length.

property_specs(tags, **kwargs)

Build the layer's annotationProperties list.

tool_bindings(specs)

Build the layer's toolBindings map.

build_property_ids(tags, tag_ids=None, strict=False)

Map tag labels to unique, valid annotation property identifiers.

Parameters:

  • tags (list of str) –

    Ordered tag labels.

  • tag_ids (dict, default: None ) –

    Explicit {label: property_id} overrides. Identifiers given here are validated but never rewritten.

  • strict (bool, default: False ) –

    If True, raise instead of sanitizing a label that is not already a valid identifier. Default is False.

Returns:

  • dict –

    Mapping of tag label to property identifier, in the order of tags.

Raises:

  • ValueError –

    If strict is set and a label is not a valid identifier, or if an explicitly supplied identifier is invalid.

make_annotation_properties(annotations, tag_base_number=0)

Take a list of annotations and build up the dictionary needed

make_bindings(properties, bindings=None)

Make a dictinary describing key bindings for tags

register_property_tools()

Register main Neuroglancer's annotation property tools with the local library.

viewer_state validates tool bindings against a registry and raises KeyError on an unknown type, so these must exist before they can be bound. Registration is guarded, so it becomes a no-op once a released neuroglancer package ships the real classes and the library's own definitions take precedence.

sanitize_property_id(label, fallback_index=0)

Convert a tag label into a valid Neuroglancer annotation property identifier.

Mirrors the transformation the Neuroglancer annotation schema tab applies to typed input, so an nglui-generated identifier matches what a user would get by entering the same string in the viewer. It then adds the step the viewer omits: requiring a leading letter, without which an id like 1st_pass is accepted on entry but rejected when the state is reloaded.

The identifier is what a user actually sees -- the schema tab labels each property by its id -- so this stays readable rather than producing an opaque slug.

Parameters:

  • label (str) –

    Human-readable tag label.

  • fallback_index (int, default: 0 ) –

    Index used to build a placeholder if the label has no usable characters.

Returns:

  • str –

    An identifier matching PROPERTY_ID_PATTERN.

Examples:

>>> sanitize_property_id("Cell Body")
'cell_body'
>>> sanitize_property_id("post-synaptic")
'post_synaptic'
>>> sanitize_property_id("1st pass")
'tag_1st_pass'
>>> sanitize_property_id("β-cell")
'beta_cell'
>>> sanitize_property_id("café")
'cafe'

strategy_for_capabilities(capabilities)

Choose a tag encoding for a deployment's capabilities.

Parameters:

  • capabilities (Capabilities) –

    Capabilities of the target Neuroglancer deployment.

Returns:

  • TagStrategy –

    BOOL_PROPERTY_TAG_STRATEGY if bool annotation properties are supported, otherwise LEGACY_TAG_STRATEGY.

unique_tags(tags)

Drop repeated tags, keeping first-seen order.

A repeated tag cannot be represented on the wire under either encoding: it would mean two properties with the same identifier, which Neuroglancer rejects outright, and the per-annotation value vector has one slot per distinct tag regardless. Tags discovered from a dataframe are already distinct; this guards the case where a caller supplies tags directly.

Parameters:

  • tags (list) –

    Tag labels, possibly with repeats.

Returns:

  • list –

    The same labels, first occurrence only.

Examples:

>>> unique_tags(["axon", "axon", "soma"])
['axon', 'soma']