fractal-tree modules#
Testing more verbose documentation.
This module contains the Branch class (one branch of the tree) and the Nodes class name
- class fractal_tree.branch.Branch(mesh: Mesh, initial_node: int, initial_direction: ndarray, initial_triangle: int, length: float, angle: float, repulsitivity: float, nodes: Nodes, brother_nodes: list[int], num_segments: int)[source]#
Class that contains a branch of the fractal tree
- Parameters:
mesh – an object of the mesh class, where the fractal tree will grow
initial_node (int) – initial node to grow the branch. This is an index that refers to a node in the nodes.nodes array.
initial_direction (array) – initial direction to grow the branch. In general, it refers to the direction of the last segment of the mother brach.
initial_triangle (int) – the index of triangle of the mesh where the initial_node sits.
l (float) – total length of the branch
angle (float) – angle (rad) with respect to the initial_direction in the plane of the initial_triangle triangle
repulsitivity (float) – repulsitivity parameter. Controls how much the branches repel each other.
nodes – the object of the class nodes that contains all the nodes of the existing branches.
brother_nodes (list) – the nodes of the brother and mother branches, to be excluded from the collision detection between branches.
num_segments (int) – number of segments to divide the branch.
- child#
contains the indexes of the child branches. It is not assigned when created.
- Type:
list
- dir#
vector direction of the last segment of the branch.
- Type:
array
- nodes#
contains the node indices of the branch. The node coordinates can be retrieved using nodes.nodes[i]
- Type:
list
- triangles#
contains the indices of the triangles from the mesh where every node of the branch lies.
- Type:
list
- tri#
triangle index where last node sits.
- Type:
int
- growing#
False if the branch collide or is out of the surface. True otherwise.
- Type:
bool
- add_node_to_queue(mesh: Mesh, initial_node: ndarray, dir: ndarray) bool [source]#
Functions that projects a node in the mesh surface and it to the queue is it lies in the surface.
- Parameters:
mesh – an object of the mesh class, where the fractal tree will grow
initial_node (array) – vector that contains the coordinates of the last node added in the branch.
dir (array) – vector that contains the direction from the initial_node to the node to project.
- Returns:
true if the new node is in the triangle.
- Return type:
success (bool)
- class fractal_tree.branch.Nodes(initial_node: ndarray)[source]#
A class containing the nodes of the branches plus some functions to compute distance related quantities.
- Parameters:
initial_node (array) – an array with the coordinates of the initial node of the first branch.
- nodes#
list of arrays containing the coordinates of the nodes
- Type:
list
- last_node#
last added node.
- Type:
int
- end_nodes#
a list containing the indices of all end nodes (nodes that are not connected) of the tree.
- Type:
list
- tree#
a k-d tree to compute the distance from any point to the closest node in the tree. It is updated once a branch is finished.
- Type:
scipy.spatial.cKDTree
- collision_tree#
a k-d tree to compute the distance from any point to the closest node in the tree, except from the brother and mother branches. It is used to check collision between branches.
- Type:
scipy.spatial.cKDTree
- add_nodes(queue: list[numpy.ndarray]) list[int] [source]#
This function stores a list of nodes of a branch and returns the node indices. It also updates the tree to compute distances.
- Parameters:
queue (list) –
branch. (a list of arrays containing the coordinates of the nodes of one) –
- Returns:
the indices of the added nodes.
- Return type:
nodes_id (list)
- collision(point: ndarray)[source]#
This function returns the distance between one point and the closest node in the tree and the index of the closest node using the collision_tree.
- Parameters:
point (array) – the coordinates of the point to calculate the distance from.
- Returns:
(distance to the closest node, index of the closest node)
- Return type:
collision (tuple)
- distance_from_node(node: int) float [source]#
This function returns the distance from any node to the closest node in the tree.
- Parameters:
node (int) – the index of the node to calculate the distance from.
- Returns:
the distance between specified node and the closest node in the tree.
- Return type:
d (float)
- distance_from_point(point: ndarray) float [source]#
This function returns the distance from any point to the closest node in the tree.
- Parameters:
point (array) – the coordinates of the point to calculate the distance from.
- Returns:
the distance between point and the closest node in the tree.
- Return type:
d (float)
- gradient(point: ndarray, delta: float = 0.01)[source]#
This function returns the gradient of the distance from the existing points of the tree from any point. It uses a central finite difference approximation.
- Parameters:
point (array) – the coordinates of the point to calculate the gradient of the distance from.
- Returns:
(x,y,z) components of gradient of the distance.
- Return type:
grad (array)
- update_collision_tree(nodes_to_exclude: list[int]) None [source]#
This function updates the collision_tree excluding a list of nodes from all the nodes in the tree. If all the existing nodes are excluded, one distant node is added.
- Args
- nodes_to_exclude (list):
contains the nodes to exclude from the tree. Usually it should be the mother and the brother branch nodes.
- Returns:
none
This module contains the function that creates the fractal tree.
- class fractal_tree.tree.FractalTreeParameters(filename: str = 'results', second_node: Optional[ndarray] = None, initial_direction: Optional[ndarray] = None, init_length: float = 0.1, N_it: int = 10, length: float = 0.1, branch_angle: float = 0.15, repulsitivity: float = 0.1, l_segment: float = 0.01, generate_fascicles: bool = True, fascicles_angles: tuple[float, float] = (- 1.5, 0.2), fascicles_length: tuple[float, float] = (0.5, 0.5), save: bool = True, save_paraview: bool = True)[source]#
Class to specify the parameters of the fractal tree.
- filename#
name of the output files.
- Type:
str
- init_node#
the first node of the tree.
- Type:
numpy array
- second_node#
this point is only used to calculate the initial direction of the tree and is not included in the tree. Please avoid selecting nodes that are connected to the init_node by a single edge in the mesh, because it causes numerical issues. If no node is provided, a random node will be selected
- Type:
numpy array
- init_length#
length of the first branch.
- Type:
float
- N_it#
number of generations of branches.
- Type:
int
- length#
average length of the branches in the tree.
- Type:
float
- branch_angle#
angle with respect to the direction of the previous branch and the new branch.
- Type:
float
- repulsitivity#
repulsitivity parameter.
- Type:
float
- l_segment#
length of the segments that compose one branch (approximately, because the length of the branch is random). It can be interpreted as the element length in a finite element mesh.
- Type:
float
- Fascicles#
include one or more straight branches with different lengths and angles from the initial branch. It is motivated by the fascicles of the left ventricle.
- Type:
bool
- fascicles_angles#
angles with respect to the initial branches of the fascicles. Include one per fascicle to include.
- Type:
list
- fascicles_length#
length of the fascicles. Include one per fascicle to include. The size must match the size of fascicles_angles.
- Type:
list
- save#
save text files containing the nodes, the connectivity and end nodes of the tree.
- Type:
bool
- save_paraview#
save a .vtu paraview file. The tvtk module must be installed.
- Type:
bool
- property min_length: float#
Minimum length of the branches. To avoid randomly generated negative lengths.
- property std_length: float#
Standard deviation of the length. Set to zero to avoid random lengths.
- class fractal_tree.tree.FractalTreeResult(branches, nodes, end_nodes, lines)[source]#
- branches: dict[int, fractal_tree.branch.Branch]#
Alias for field number 0
- end_nodes: list[int]#
Alias for field number 2
- lines: list[tuple[int, int]]#
Alias for field number 3
- nodes: ndarray#
Alias for field number 1
- fractal_tree.tree.generate_fractal_tree(mesh: Mesh, parameters: Optional[FractalTreeParameters] = None) FractalTreeResult [source]#
This function creates the fractal tree.
- Parameters:
parameters (Optional[FractalTreeParameters]) – This object contains all the parameters that define the tree. See the parameters module documentation for details:
- Returns:
branches containes a dictionary that contains all the branches objects, and nodes is the object that contains all the nodes of the tree.
- Return type:
- fractal_tree.tree.node_direction(src: ndarray, target: Optional[ndarray] = None) ndarray [source]#
Return the direction from src to target.
- Parameters:
src (np.ndarray) – Source node
target (Optional[np.ndarray]) – Target node
- Returns:
The unit vector from src to node 2
- Return type:
np.ndarray
This module contains the mesh class. This class is the triangular surface where the fractal tree is grown.
- class fractal_tree.mesh.Mesh(verts: ndarray, connectivity: ndarray, init_node: Optional[ndarray] = None)[source]#
Class that contains the mesh where fractal tree is grown. It must be Wavefront .obj file. Be careful on how the normals are defined. It can change where an specified angle will go.
- Parameters:
filename (str) – the path and filename of the .obj file with the mesh.
- verts#
a numpy array that contains all the nodes of the mesh. verts[i,j], where i is the node index and j=[0,1,2] is the coordinate (x,y,z).
- Type:
array
- connectivity#
a numpy array that contains all the connectivity of the triangles of the mesh. connectivity[i,j], where i is the triangle index and j=[0,1,2] is node index.
- Type:
array
- normals#
a numpy array that contains all the normals of the triangles of the mesh. normals[i,j], where i is the triangle index and j=[0,1,2] is normal coordinate (x,y,z).
- Type:
array
- node_to_tri#
a dictionary that relates a node to the triangles that it is connected. It is the inverse relation of connectivity. The triangles are stored as a list for each node.
- Type:
dict
- tree#
a k-d tree to compute the distance from any point to the closest node in the mesh.
- Type:
scipy.spatial.cKDTree
- project_new_point(point: ndarray) ProjectedPoint [source]#
This function projects any point to the surface defined by the mesh.
- Parameters:
point (array) – coordinates of the point to project.
- Returns:
Contains projected_point which is the coordinates of the projected point that lies in the surface. triangle_index is the index of the triangle where the projected point lies. If the point is outside surface, triangle_index=-1.
- Return type: