fiftyone.core.annotation.nodes#

Taxonomy node primitive.

Copyright 2017-2026, Voxel51, Inc.
voxel51.com

Classes:

Node(name[, description, can_select, ...])

A node in a fiftyone.core.ontology.Taxonomy tree.

Functions:

`find_in_dict`(root, name)	Returns the first descendant (or `root` itself) whose `name` matches, or `None`.
`truncate_dict`(node, depth)	Returns a copy of `node` truncated to `depth` levels below.

class fiftyone.core.annotation.nodes.Node(name: str, description: str | None = None, can_select: bool = True, deprecated: bool = False, values: list[Node] | None = None)#

Bases: object

A node in a fiftyone.core.ontology.Taxonomy tree.

There is a single node type: every node has the same shape regardless of whether it represents a leaf class, a sub-class, or a group header. The role of a node is determined by its position in the tree and by the can_select flag.

Parameters:

name – required label for this node — a class name, sub-class name, or group header. Must be unique within the taxonomy (uniqueness is enforced by validate_taxonomy, not at construction time).
description – optional context for the user (tooltip / guidance text in the UI)
can_select – if False, the node is a group header — it expands to show child nodes but is not itself selectable as a class. Defaults to True.
deprecated – if True, the node is hidden from the UI for new selections but remains valid on existing labels. Defaults to False.
values – optional list of child Node instances. A leaf node has no values; a node with children has values.

Example:

Node(
    name="vehicles",
    can_select=False,
    values=[
        Node(name="car"),
        Node(name="truck"),
    ],
)

Attributes:

`name`
`description`
`can_select`
`deprecated`
`values`

Methods:

`to_dict`()	Serializes this node to a dict.
`from_dict`(d)	Creates a `Node` from a dict.

name: str#

description: str | None = None#

can_select: bool = True#

deprecated: bool = False#

values: list[Node] | None = None#

to_dict() → dict#

Serializes this node to a dict.

Returns:: a dict

classmethod from_dict(d: dict) → Node#

Creates a Node from a dict.

Parameters:: d – a node dict
Returns:: a Node

fiftyone.core.annotation.nodes.find_in_dict(root: dict, name: str) → dict | None#

Returns the first descendant (or root itself) whose name matches, or None.

Node names are unique within a taxonomy (enforced by fiftyone.core.ontology_validation.validate_taxonomy()), so the first match is the only match.

Parameters:

root – a node-shaped dict
name – the node name to search for

Returns:

the matching dict (a reference into root) or None

fiftyone.core.annotation.nodes.truncate_dict(node: dict, depth: int) → dict#

Returns a copy of node truncated to depth levels below.

At the truncation boundary, nodes that had children in the source are returned with values=[] so the wire format distinguishes them from real leaves (which have no values key).

Parameters:

node – a node-shaped dict
depth – non-negative recursion depth. 0 returns just node with no descendants.

Returns:

a new dict; the input is not mutated