Speckle Docs

# WorldTree

#

Constructors

constructor

#

Accessors

nodeCount root

#

Methods

addNode addSubtree findAll findId
getAncestors getInstances getRenderTree isRoot
parse purge removeNode walk
walkAsync

#

Typedefs

NodeData SearchPredicate TreeNode SelectionEvent
SpeckleView SunLightConfiguration UpdateFlags Utils
ViewerEvent ViewerParams World

#

Constructors

# constructor

new WorldTree();
1

Returns: WorldTree

#

Accessors

# nodeCount

get nodeCount(): number
1

Gets the total node count for the tree.

Returns: number

# root

get root(): TreeNode
1

Gets the root TreeNode.

Returns: TreeNode

#

Methods

# addNode

addNode(node: TreeNode, parent: TreeNode): void
1

Adds a TreeNode as a child of the provided parent node.

Parameters

Returns: void

# addSubtree

addSubtree(node: TreeNode): void
1

Adds a TreeNode as the root of a subtree. The world tree can be split into subtrees, each of which will have it's dedicated NodeMap for optimal searching speed. A subtree does not differ structurally from a regula node, and it does not alter the overall hierarchy of the world tree in any way.

Parameters

Returns: void

# findAll

findAll(predicate: SearchPredicate, node?: TreeNode): TreeNode[]
1

Goes throught the tree starting at node if provided, otherwise at the tree root and runs the provided predicate for each node. All nodes which satisfy the predicate are returned.

WARNING

Be mindful about the predicate's contents. If the tree is very large this operation can lock the main thread for too long. If you need to execute complex predicates on large trees, walkAsync is a better candidate.

Parameters

  • predicate: The SearchPredicate to run for each node
  • (optional) node: The TreeNode to start at. If not provided, the tree root will be used

Returns: TreeNode[]

# findId

findId(id: string, subtreeId?: number): TreeNode[]
1

Find a node by id. The optional subtreeId argument can narrow down the search to a specific subtree, otherwise it will search the entire tree. It returns an array of nodes because multiple nodes can have the same id, like in the case of instances.

TIP

Using this method for tree searches is encouraged because it's accelerated by a backing NodeMap which brings down searches to just one or more lookups

Parameters

  • id: The id of the node to search for
  • (optional) subtreeId: The id of the subtree to search in. If undefined the search will include the entire tree

Returns: TreeNode[]

# getAncestors

getAncestors(node: TreeNode): TreeNode[]
1

Gets the full list of node ancestors in hierarchical order.

Parameters

  • node: The node to search ancestors for

Returns: TreeNode[]

# getInstances

getInstances(subtree: string): { [id: string]: Record<string, TreeNode> }
1

Gets all the instances in the provided subtree id.

Parameters

  • subtree: The root subtree id

Returns: A dictionary where each instance id holds a record of TreeNode grouped by their instance unique id.

# getRenderTree

getRenderTree(): RenderTree
getRenderTree(subtreeId: string): RenderTree | null
1
2

Gets the RenderTree instance of the provided subtree id. If the subtree id is not found, null is returned. The overloaded version with no argument gets the RenderTree instance for the entire tree, which can never be null.

Parameters

  • subtreeId: The root subtree id

Returns: RenderTree

# isRoot

isRoot(node: TreeNode): boolean
1

Checks is a TreeNode is root.

Parameters

Returns: boolean

# parse

parse(model): TreeNode
1

Default way of creating TreeNodes. The input model needs to follow the form.

{
    id: string,
    raw?: object,
    atomic?: boolean,
    children?: []
}
1
2
3
4
5
6

The input model can contain virtually anything, but it should have at least the properties defined above.

Parameters

  • node: { id: string, raw?: object, atomic?: boolean, children: []}

Returns: TreeNode

# purge

purge(subtreeId?: string): void
1

Destroys part of the tree, or in the absence of a subtreeId argument, the entire tree.

WARNING

Purged trees are no longer usable!

Parameters

  • optional subtreeId: The subtree root id. If undefined the whole tree will get purged

Returns: void

# removeNode

removeNode(node: TreeNode): void
1

Removed the provided TreeNode from the tree.

Parameters

Returns: void

# walk

walk(predicate: SearchPredicate, node?: TreeNode): void
1

Walks the tree starting at node and executes the SearchPredicate for each node. If node argument is undefined, walking starts at root. Walking is stopped when the predicate returns false.

WARNING

This function is synchronous and depending on the complexity of your SearchPredicate and the total number of nodes, it might block the main thread. For a heavy SearchPredicate use walkAsync.

Parameters

Returns: void

# walkAsync

async walkAsync(predicate: SearchPredicate, node?: TreeNode): Promise<boolean>
1

The asynchronous version of walk. The function will yield for 16ms (one frame) after a cummulated 100ms spent executing. The return promise will resolve to a boolean which determines if the tree was completely walked (true) or not (false).

Parameters

Returns: Promise< boolean >

#

Typedefs

# NodeData

interface NodeData {
  id: string;
  raw: { [prop: string]: any };
  children: TreeNode[];
  atomic: boolean;
  subtreeId?: number;
  renderView?: NodeRenderView;
  instanced?: boolean;
}
1
2
3
4
5
6
7
8
9

This is the data payload for each TreeNode.

  • raw: Raw from node creation with parse
  • children: Children TreeNodes
  • atomic: Whether this node is a complete object (true) or just part of another object (false)
  • optional subtreeId: Assigned at runtime used for search acceleration
  • optional renderView: Data required for everything rendering related
  • optional instanced: Whether this node is an instance

# SearchPredicate

type SearchPredicate = (node: TreeNode) => boolean;
1

Delegate type used in tree's findAll, walk and walkAsync methods.

WARNING

When using the predicate in findAll the return value detemines if the current node matche the search(true) or not(false). When using the predicate in walk and walkAsync, return false will stop the tree walking early.

# TreeNode

type TreeNode = TreeModel.Node<NodeData>;
1

Abstraction of a tree node. The tree is implemented on top of an existing tree library (opens new window) which defines the tree nodes it'w own way. At runtime the nodes will consist of:

{
  children: Node[]
  config: {childrenPropertyName: 'children', modelComparatorFn: undefined}
  model: NodeData
  parent: TreeNode
}
1
2
3
4
5
6

← Extension →