Lines3D

class core.Lines3D

Bases: matlab.mixin.Copyable

LINES3D - Container for 3D lines and skeletons represented as a MATLAB graph object.

The Lines3D class manages spatial networks of nodes and edges using MATLAB’s built-in graph object, supporting visualization, editing, and file I/O of 3D skeletal structures (trees, filaments, networks).

Constructor Summary
Lines3D(Gin, activeNodeId, options)

LINES3D - Constructor for the Lines3D class.

Syntax:
obj = Lines3D()
obj = Lines3D(Gin)
obj = Lines3D(Gin, activeNodeId, options)

Initializes a Lines3D container with a graph of 3D nodes and edges.

Input Arguments:

  • Gin - (optional) [graph] a MATLAB graph object with nodes and edges; must have the following structure:

    • .Nodes - table containing node information:

      • .PointsXYZ - coordinates of nodes [NodeId][x, y, z] IN PHYSICAL UNITS; use mibImage.convertPixelsToUnits to convert from pixels

      • .TreeName - cell array with tree name for each node

      • .NodeName - (optional) cell array with individual node names

      • .Radius - (optional) vector with node radii

    • .Edges - table containing edge information:

      • .EndNodes - connectivity table [edgeId][Node1 Node2] defining connected node pairs

      • .Weight - (optional) weights of edges

      • .Length - (optional) length of edges, IN PHYSICAL UNITS

    • .Nodes.Properties.VariableUnits - cell array indicating units for each variable; specify 'pixel' when coordinates are in pixels

    • .Nodes.Properties.UserData.pixSize - struct with pixel size fields .x, .y, .z, .units

    • .Nodes.Properties.UserData.BoundingBox - vector [xmin, width, ymin, height, zmin, depth]

  • activeNodeId - (optional) [numeric] index of the node to set as active; can be []

  • options - (optional) [struct] display and rendering settings:

    • .edgeColor - [1×3 numeric] color of edges [R, G, B], range 0-1 (default: [1.000, 0.800, 0.502])

    • .edgeThickness - [numeric] thickness of edges (default: 2)

    • .nodeColor - [1×3 numeric] color of nodes [R, G, B], range 0-1 (default: [1.0000, 1.0000, 0])

    • .nodeActiveColor - [1×3 numeric] color of the active node [R, G, B], range 0-1 (default: [1.0000, 0.0000, 0])

    • .nodeRadius - [numeric] radius of nodes (default: 5)

Example 1 - create a simple graph with points in pixels:

points = [303 81 72; 294 90 67; 294 172 56; 290 207 20; ...
          252 268 1; 294 172 40; 387 198 42; 400 252 25; 314 270 19];
s = [1 2 3 4 4 6 7];
t = [2 3 4 5 6 7 8];
Weight = ones([numel(s), 1]);
NodeTable = table(points, 'VariableNames', {'PointsXYZ'});
EdgeTable = table([s', t'], Weight, 'VariableNames', {'EndNodes', 'Weight'});
G = graph(EdgeTable, NodeTable);
G.Nodes.Properties.VariableUnits = {'pixel'};
G.Nodes.Properties.UserData.pixSize = struct('x', 0.013, 'y', 0.013, 'z', 0.03, 'units', 'um');
G.Nodes.Properties.UserData.BoundingBox = obj.mibModel.I{obj.mibModel.id}.getBoundingBox();
obj = core.Lines3D(G);

Example 2 - create a graph with two trees:

points = [303 81 72; 294 90 67; 294 172 56; 290 207 20; ...
          252 268 1; 294 172 40; 387 198 42; 400 252 25; 314 270 19];
s = [1 2 3 5 6 7];
t = [2 3 4 6 7 8];
TreeName = [repmat({'TreeName1'}, 4, 1); repmat({'TreeName2'}, 4, 1); {'TreeName2'}];
NodeTable = table(points, TreeName, 'VariableNames', {'PointsXYZ', 'TreeName'});
EdgeTable = table([s', t'], 'VariableNames', {'EndNodes'});
G = graph(EdgeTable, NodeTable);
G.Nodes.Properties.VariableUnits = {'pixel', 'string'};
G.Nodes.Properties.UserData.pixSize = obj.mibModel.I{obj.mibModel.id}.pixSize;
G.Nodes.Properties.UserData.BoundingBox = obj.mibModel.I{obj.mibModel.id}.getBoundingBox();
obj = core.Lines3D(G);
Property Summary
G
activeNodeId

a graph with lines.

  • .Edges - a table containing information about edges of the graph:

    • .EndNodes - connectivity table [edgeId][Node1 Node2], each row defines an edge with indices of nodes that form the edge

    • .Edges - matrix with coordinates of the edges, [edgeId][x1 y1 z1 x2 y2 z2], IN PHYSICAL UNITS

    • .Weight - weights of edges

    • .Length - length of nodes, IN PHYSICAL UNITS

  • .Nodes - a table containing information about nodes of the graph:

    • .PointsXYZ - coordinates of nodes [NodeId][x, y, z] IN PHYSICAL UNITS; to recalculate from pixels to imaging units use mibImage.convertPixelsToUnits

    • .TreeName - a cell array where each node has the name of the tree to which the node belongs, [NodeId]{'TreeName'}

    • .NodeName - a cell array with names for the nodes, [NodeId]{'NodeName'}

    • .Radius - a vector with radii of nodes

    • .Properties.VariableUnits - a cell array with units for each variable; when coordinates are ‘pixels’, MIB suggests recomputing them to image units

    • .Properties.UserData.pixSize - a structure with pixSize of the underlying dataset (.x, .y, .z - resolution in um/px)

    • .Properties.UserData.BoundingBox - a vector with the bounding box information [xmin, width, ymin, height, zmin, depth]

clipExtraThickness

index of the active node

defaultNodeName

a number, extend clipping of the edges with additional thickness +/- this number sections

defaultTreeName

default name for nodes

edgeActiveColor

default name for trees

edgeColor

color of edges for the active tree [R, G, B], from 0 to 1

edgeThickness

color of edges [R, G, B], from 0 to 1

extraEdgeFields

thickness of edges

extraEdgeFieldsNumeric

a cell array with names of additional fields in the Edges table of the graph object

extraNodeFields

a vector with indicator whether the field in extraEdgeFields is numeric (1) or not (0)

extraNodeFieldsNumeric

a cell array with names of additional fields in the Nodes table of the graph object

filename

a vector with indicator whether the field in extraNodeFields is numeric (1) or not (0)

noTrees

strel element for making nodes

nodeActiveColor

filename of the Lines3D file

nodeColor

color of the active node [R, G, B], from 0 to 1

nodeRadius

color of nodes [R, G, B], from 0 to 1

nodeStrel

radius of nodes

treeLengths

number of trees of the graph

Method Summary
addLinesToImage(img, Box, options)

ADDLINESTOIMAGE - Render 3D lines onto a 2D image.

Syntax:
img = obj.addLinesToImage(img, Box, options)

Overlays the 3D graph lines and nodes onto a 2D image slice, applying the configured colors and rendering parameters.

Input Arguments:

  • img - [numeric array] 2D or 3D image array where lines should be rendered

  • Box - [1×6 numeric] clipping box [xmin, xmax, ymin, ymax, zmin, zmax] defining the region to render

  • options - (optional) [struct] rendering settings:

    • .orientation - [numeric] image plane orientation (default: 3):

      • 3 - YX plane (default)

      • 1 - XZ plane

      • 2 - YZ plane

Output Arguments:

  • img - [numeric array] image with rendered lines and nodes

addNode(x, y, z, newTreeSwitch, options)

ADDNODE - Add one or more nodes to the graph.

Syntax:
obj.addNode(x, y, z, newTreeSwitch, options)

Adds a sequence of nodes connected by edges to the graph. When x, y, z are column vectors, the nodes are connected sequentially in the order given. New nodes can extend an existing tree or start a new tree.

Input Arguments:

  • x - [numeric vector] x coordinates of nodes IN PHYSICAL UNITS

  • y - [numeric vector] y coordinates of nodes IN PHYSICAL UNITS

  • z - [numeric vector] z coordinates of nodes IN PHYSICAL UNITS

  • newTreeSwitch - (optional) [numeric] start a new tree (default: 0 = extend active tree):

    • 0 - add nodes to the active tree

    • 1 - start a new tree

  • options - (optional) [struct] metadata and dataset information:

    • .pixSize - [struct] pixel size with fields .x, .y, .z, .units

    • .BoundingBox - [1×6 numeric] bounding box [xmin, width, ymin, height, zmin, depth]

calculateLengthOfNodes(Graph, options)

CALCULATELENGTHOFNODES - Calculate edge lengths from coordinate endpoints.

Syntax:
Graph = obj.calculateLengthOfNodes(Graph, options)

Computes the Euclidean distance for edges in the graph, updating or populating the .Length field based on node coordinates and optional filters.

Input Arguments:

  • Graph - [graph] a MATLAB graph object with node and edge information

  • options - (optional) [struct] specifies which edges to recalculate:

    • .nodeId - [numeric vector] node IDs; edges incident to these nodes are recalculated

    • .edgeId - [numeric vector] edge IDs to recalculate (alternative to nodeId)

    • If neither option is provided, all edges are recalculated

Output Arguments:

  • Graph - [graph] the input graph with .Length field populated or updated

clearContents()

CLEARCONTENTS - Set all elements of the class to default values.

Syntax:
obj.clearContents()

Input Arguments:

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.Lines3D.clearContents();
clipEdge(Box)

CLIPEDGE - clip the edge using the Box matrix.

Syntax:
[edge, edgeIds] = obj.clipEdge(Box)
Input Arguments:

  • Box - a vector used for cliping the edges [xMin, xMax, yMin, yMax, zMin, zMax]

Output Arguments:

  • edge - a matrix of edges shown inside the clipping box, [x1 y1 z1 x2 y2 z2]

  • edgeIds - indices of the returned edges

connectNodes(s, t)

CONNECTNODES - make an edge between two nodes.

Syntax:
obj.connectNodes(s, t)
Input Arguments:

  • s - index of the first node

  • t - index of the second node

deleteNode(x, y, z, orientation)

DELETENODE - delete node that is closest to the point with coordinates x, y, z.

Syntax:
result = obj.deleteNode(x, y, z, orientation)

the previous and following nodes get connected after remove of the node

Input Arguments:

  • x - x coordinate of a point next to the node, or index of the node (in this case, y and z should be empty)

  • y - y coordinate of a point next to the node

  • z - z coordinate of a point next to the node

  • orientation - (optional) a number with orientation of the dataset, 3-yx, 1-xz, 2-yz, default 3

Output Arguments:

  • result - type of the node that was deleted ‘removed tree’ - the last node of a tree was removed, so the tree was deleted ‘middle node’ - the removed node was in a middle of a tree ‘multiple split’ - the node had more than 2 connections and as result multiple new trees were formed

deleteTree(treeId)

DELETETREE - delete tree from the graph.

Syntax:
obj.deleteTree(treeId)
Input Arguments:

  • treeId - index of the tree to delete, or string with name of the tree

findClosestNode(x, y, z, orientation)

FINDCLOSESTNODE - find the closest node to a point with coordinates x, y, z.

Syntax:
nodeId = obj.findClosestNode(x, y, z, orientation)
Input Arguments:

  • x - x coordinate of a point next to the node

  • y - y coordinate of a point next to the node

  • z - z coordinate of a point next to the node

  • orientation - (optional) a number with orientation of the dataset, 3-yx, 1-xz, 2-yz, default 3

findSliceNodes(z, orientation)

FINDSLICENODES - find nodes that are shown on the current slice.

Syntax:
[nodes, indices] = obj.findSliceNodes(z, orientation)
Input Arguments:

  • z - Z-value to obtain the nodes

  • orientation - [optional, default 3 for XY] a number that specifies desired orientation, 3-yx, 1-xz, 2-yz

Output Arguments:

  • nodes - a matrix with coordinates of nodes [node; x, y, z]

  • indices - a vector with indices of returned nodes

getOptions()

GETOPTIONS - get options of the class.

Syntax:
options = obj.getOptions()
Output Arguments:

  • options - a structure with options

getTree(treeId)

GETTREE - return graph with the tree specified in treeId.

Syntax:
[Graph, nodeIds, EdgesTable, NodesTable] = obj.getTree(treeId)
Input Arguments:

  • treeId - index of tree to get

Output Arguments:

  • Graph - graph object containing tree specified in treeId

  • nodeIds - indices of nodes belonging to this tree

  • EdgesTable - a table with edges that belong to treeId

  • NodesTable - a table with nodes that belong to treeId

getTreeNames(index)

GETTREENAMES - return name of trees.

Syntax:
treeNames = obj.getTreeNames(index)

One name is returned per tree, i.e. per connected component of the graph, so that the indices match those used by getTree, deleteTree and the nodeByTree vector of updateNumberOfTrees. The name is taken from the first node of each component; the same name may be returned more than once when a tree got disconnected without being renamed (for example a Delaunay triangulation that left isolated points).

Input Arguments:

  • index - (optional) indices of the trees

Output Arguments:

  • treeNames - a cell array with names of trees

insertNode(nodeId, x, y, z)

INSERTNODE - insert node to a tree after nodeId, the inserted node becomes an active node.

Syntax:
obj.insertNode(nodeId, x, y, z)
Input Arguments:

  • nodeId - index of the node after which a new node should be inserted

  • x - new x coordinate

  • y - new y coordinate

  • z - new z coordinate

makeDummyGraph()

MAKEDUMMYGRAPH - generate a dummy graph for developmental purposes.

Syntax:
obj.makeDummyGraph()
replaceGraph(Graph)

REPLACEGRAPH - Replace the graph object with a new graph.

Syntax:
obj.replaceGraph(Graph)

Replaces the current graph with a new one, normalizing node and edge structure, converting pixel coordinates to physical units if needed, and calculating missing metadata fields.

Input Arguments:

  • Graph - (optional) [graph] a MATLAB graph object containing the new data; if [] or missing, clears the graph. The graph should have the following structure:

    • .Nodes - table containing node information:

      • .PointsXYZ - [required] matrix [NodeId × 3] with (x, y, z) coordinates IN PHYSICAL UNITS; use mibImage.convertPixelsToUnits to convert from pixels

      • .TreeName - (optional) cell array assigning each node to a tree

      • .NodeName - (optional) cell array with individual node names

      • .Radius - (optional) vector with radius parameter for each node

      • .Properties.UserData.pixSize - struct with pixel size fields .x, .y, .z, .units

      • .Properties.UserData.BoundingBox - vector [xmin, width, ymin, height, zmin, depth]

      • .Properties.VariableUnits - cell array indicating units; specify 'pixel' when coordinates are in pixels

    • .Edges - table containing edge information:

      • .EndNodes - [required] connectivity table [EdgeId × 2] with (Node1, Node2) indices

      • .Edges - (optional) matrix [EdgeId × 6] with coordinates [x1, y1, z1, x2, y2, z2] IN PHYSICAL UNITS

      • .Weight - (optional) vector of edge weights

      • .Length - (optional) vector of edge lengths IN PHYSICAL UNITS

saveToFile(filename, options)

SAVETOFILE - Save the Lines3D graph to a file.

Syntax:
obj.saveToFile(filename, options)

Saves the graph to a file in one of several supported formats. If filename is omitted, a dialog prompts the user to select the filename and format.

Input Arguments:

  • filename - (optional) [char] full output path; if [] or missing, a file dialog opens

  • options - (optional) [struct] export settings:

    • .format - [char] output format; if missing, inferred from file extension:

      • 'lines3d' - MIB native format (MATLAB .lines3d binary)

      • 'amira-ascii' - Amira Spatial Graph ASCII format

      • 'amira-binary' - Amira Spatial Graph binary format

      • 'excel' - Microsoft Excel .xls spreadsheet

    • .treeId - (optional) [numeric or []] tree index to export (default: [] = all trees)

    • .NodeFieldName - (optional) [char] field name to export for nodes (Amira only)

    • .EdgeFieldName - (optional) [char] field name to export for edges (Amira only)

    • .showWaitbar - (optional) [logical] display progress bar (default: 1)

setActiveNode(x, y, z, orientation)

SETACTIVENODE - Set the active node closest to a given coordinate.

Syntax:
obj.setActiveNode(x, y, z, orientation)

Activates the node that is closest to the specified point coordinates.

Input Arguments:

  • x - [numeric] x coordinate of the reference point

  • y - [numeric] y coordinate of the reference point

  • z - [numeric] z coordinate of the reference point

  • orientation - (optional) [numeric] image orientation; allowed values:

    • 3 - YX plane (default)

    • 1 - XZ plane

    • 2 - YZ plane

setOptions(options)

SETOPTIONS - update options of the class.

Syntax:
obj.setOptions(options)
Input Arguments:

  • options - a structure with options to set

splitAtNode(x, y, z, orientation)

SPLITATNODE - split tree at the node that is closest to the point with coordinates x, y, z.

Syntax:
obj.splitAtNode(x, y, z, orientation)

the node and its edges will be removed

Input Arguments:

  • x - x coordinate of a point next to the node

  • y - y coordinate of a point next to the node

  • z - z coordinate of a point next to the node

  • orientation - (optional) a number with orientation of the dataset, 3-yx, 1-xz, 2-yz, default 3

updateNodeCoordinate(nodeId, x, y, z)

UPDATENODECOORDINATE - update coordinate of the node.

Syntax:
obj.updateNodeCoordinate(nodeId, x, y, z)
Input Arguments:

  • nodeId - index of the node to update

  • x - new x coordinate

  • y - new y coordinate

  • z - new z coordinate

updateNodeStrel(nodeStrelSize)

UPDATENODESTREL - update strel element for showing nodes as circles.

Syntax:
obj.updateNodeStrel(nodeStrelSize)
Input Arguments:

  • nodeStrelSize - radius of the strel element

updateNumberOfTrees()

UPDATENUMBEROFTREES - update number of trees in the graph and get array of nodes by tree index.

Syntax:
[noTrees, nodeByTree] = obj.updateNumberOfTrees()

Input Arguments:

Output Arguments:

  • noTrees - total number of isolated trees of the graph

  • nodeByTree - vector of nodes, where values indicate corresponding tree of the node