Skip to content
This repository was archived by the owner on Aug 8, 2024. It is now read-only.

wknml.md

Latest commit

 

History

History
343 lines (232 loc) · 10.8 KB

wknml.md

File metadata and controls

343 lines (232 loc) · 10.8 KB

Table of Contents

wknml

NMLParameters Objects

class NMLParameters(NamedTuple)

Contains common metadata for NML files

Notes:

Setting a task bounding boxes will cause wK to 1) render these visually and 2) prevent data loading from outside them.

Attributes:

  • name str - Name of a dataset that the annotation is based on. Will cause wK to open the given skeleton annotation with the referenced dataset.
  • scale Vector3[float] - Voxel scale of the referenced dataset in nanometers.
  • offset Optional[Vector3[float]] - Deprecated. Kept for backward compatibility.
  • time Optional[int] - A UNIX timestamp marking the creation time & date of an annotation.
  • editPosition Optional[Vector3[float]] - The position of the wK camera when creating/downloading an annotation
  • editRotation Optional[Vector3[float]] - The rotation of the wK camera when creating/downloading an annotation
  • zoomLevel Optional[float] - The zoomLevel of the wK camera when creating/downloading an annotation
  • taskBoundingBox Optional[IntVector6[int]] - A custom bounding box specified as part of a wK task. Will be rendered in wK.
  • userBoundingBoxes Optional[List[IntVector6[int]]] - A list of custom user-defined bounding boxes. Will be rendered in wK.

Node Objects

class Node(NamedTuple)

A webKnossos skeleton node annotation object.

Attributes:

  • id int - A unique identifier
  • position Vector3 - 3D position of a node. Format: [x, y, z]
  • radius Optional[float] - Radius of a node when rendered in wK. Unit: nanometers (nm)
  • rotation Optional[Vector3] - 3D rotation of the camera when the node was annotated. Mostly relevant for Flight mode to resume in the same direction when returning to Flight mode.
  • inVp Optional[int] - Enumeration of the wK UI viewport in which the node was annotated. 0: XY plane, 1: YZ plane. 2: XY plane, 3: 3D viewport
  • inMag Optional[int] - wK rendering magnification-level when the node was annotated. Lower magnification levels typically indicate a "zoomed-in" workflow resulting in more accurate annotations.
  • bitDepth Optional[int] - wK rendering bit-depth when the node was annotated. 4bit (lower data quality) or 8bit (regular quality). Lower quality data rendering might lead to less accurate annotations.
  • interpolation Optional[bool] - wK rendering interpolation flag when the node was annotated. Interpolated data rendering might lead to less accurate annotations.
  • time Optional[int] - A Unix timestamp marking the creation time of the node.

Edge Objects

class Edge(NamedTuple)

A webKnossos skeleton edge.

Attributes:

  • source int - node id reference
  • target int - node id reference

Tree Objects

class Tree(NamedTuple)

A webKnossos skeleton (tree) object. A graph structure consisting of nodes and edges.

Attributes:

  • id - int
  • color Vector4 - RGBA
  • name - str
  • nodes - List[Node]
  • edges - List[Edge]
  • groupId Optional[int] - group id reference

Branchpoint Objects

class Branchpoint(NamedTuple)

A webKnossos branchpoint, i.e. a skeleton node with more than one outgoing edge.

Attributes:

  • id int - Reference to a Node ID
  • time int - Unix timestamp

Group Objects

class Group(NamedTuple)

A container to group several skeletons (trees) together. Mostly for cosmetic or organizational purposes.

Attributes:

  • id int - A unique group identifier
  • name str - Name of the group. Will be displayed in wK UI
  • children List[Group] - List of all sub-groups belonging to this parent element for nested structures

Comment Objects

class Comment(NamedTuple)

A single comment belonging to a skeleton node.

Attributes:

  • node int - Reference to a Node ID
  • content str - A free text field. Supports Markdown formatting.

Volume Objects

class Volume(NamedTuple)

A metadata reference to a wK volume annotation. Typically, the volume annotation data is provided in a ZIP file in the same directory as the skeleton annotation.

Attributes:

  • id int - A unique identifier
  • location str - A path to a ZIP file containing a wK volume annotation
  • fallback_layer Optional[str] - Name of an already existing wK volume annotation segmentation layer (aka "fallback layer")

NML Objects

class NML(NamedTuple)

A complete webKnossos skeleton annotation object contain one or more skeletons (trees).

Attributes:

  • parameters NMLParameters - All the metadata attributes associated with a wK annotation.
  • trees List[Tree] - A list of all skeleton/tree objects. Usually contains the majority of the annotated skeleton information.
  • branchpoints List[Branchpoint] - A list of all branchpoint objects.
  • comments List[Comment] - A list of all comment objects.
  • groups List[Group] - A list of all group objects.
  • volume Optional[Volume] - A reference to any volume data that is part of this annotation.

parse_nml

parse_nml(file: BinaryIO) -> NML

Reads a webKnossos NML skeleton file from disk, parses it and returns an NML Python object

Arguments:

  • file BinaryIO - A Python file handle

Returns:

  • NML - A webKnossos skeleton annotation as Python NML object

Example:

with open("input.nml", "rb") as f:
nml = wknml.parse_nml(f, nml)

write_nml

write_nml(file: BinaryIO, nml: NML)

Writes an NML object to a file on disk.

Arguments:

  • file BinaryIO - A Python file handle
  • nml NML - A NML object that should be persisted to disk

Example:

with open("out.nml", "wb") as f:
wknml.write_nml(f, nml)

wknml.nml_generation

random_color_rgba

random_color_rgba() -> Tuple[float, float, float, float]

A utility to generate a new random RGBA color.

discard_children_hierarchy

discard_children_hierarchy(groups: List[Group]) -> List[Group]

A utility to flatten the group structure. All sub-groups will become top-level items.

globalize_tree_ids

globalize_tree_ids(group_dict: Dict[str, List[nx.Graph]])

A utility to in-place re-assign new and globally unqiue IDs to all Tree objects. Starts with ID 1

Arguments:

  • group_dict Dict[str, List[nx.Graph]] - A mapping of group names to a list of trees as NetworkX graph objects

globalize_node_ids

globalize_node_ids(group_dict: Dict[str, List[nx.Graph]])

A utility to in-place re-assign new and globally unqiue IDs to all Node objects. Edges are updated accordingly. Starts with ID 1.

Arguments:

  • group_dict Dict[str, List[nx.Graph]] - A mapping of group names to a list of trees as NetworkX graph objects

generate_nml

generate_nml(tree_dict: Union[List[nx.Graph], Dict[str, List[nx.Graph]]], parameters: Dict[str, Any] = {}, globalize_ids: bool = True, volume: Optional[Dict[str, Any]] = None) -> NML

A utility to convert a NetworkX graph object into wK NML skeleton annotation object. Accepts both a simple list of multiple skeletons/trees or a dictionary grouping skeleton inputs.

Arguments:

  • tree_dict Union[List[nx.Graph], Dict[str, List[nx.Graph]]] - A list of wK tree-like structures as NetworkX graphs or a dictionary of group names and same lists of NetworkX tree objects.
  • parameters Dict[str, Any] - A dictionary representation of the skeleton annotation metadata. See NMLParameters for accepted attributes.
  • globalize_ids bool = True - An option to re-assign new, globally unique IDs to all skeletons. Default: True
  • volume Optional[Dict[str, Any]] = None - A dictionary representation of a reference to a wK volume annotation. See Volume object for attributes.

Returns:

  • nml NML - A wK NML skeleton annotation object

generate_graph

generate_graph(nml: NML) -> Tuple[Dict[str, List[nx.Graph]], Dict[Text, any]]

A utility to convert a wK NML object into a NetworkX graph object. Skeletons/Trees are grouped by the provided groups in the NML file.

Arguments:

  • nml NML - A wK NML skeleton annotation object

Returns:

A tuple consisting of:

  1. A dictionary with group names as keys and lists of all respective NML trees as values
  2. A dictionary representation of the NML metadata parameters. See NMLParameters for attributes.

nml_tree_to_graph

nml_tree_to_graph(tree: Tree) -> nx.Graph

A utility to convert a single wK Tree object into a NetworkX graph object.

extract_nodes_and_edges_from_graph

extract_nodes_and_edges_from_graph(graph: nx.Graph) -> Tuple[List[Node], List[Edge]]

A utility to convert a single NetworkX graph object into a list of Node objects and Edge objects.

Return Tuple[List[Node], List[Edge]]: A tuple containing both all nodes and all edges

wknml.nml_utils