local_3d.py

High-level description

The cassiopeia/plotting/local_3d.py file provides functionality for creating and displaying 3D visualizations of CassiopeiaTree objects. It leverages the PyVista library for 3D rendering and offers features like node and branch placement, subclone shading, image integration, and interactive widgets for exploring the tree structure.

Code Structure

The code defines several helper functions for color manipulation, branch interpolation, and PyVista object creation. The core functionality is encapsulated in the Tree3D class, which manages the tree data, labels, images, and PyVista plotter. The class provides methods for adding images, setting visualization parameters (e.g., root, time, blur strength), updating displayed elements, and adding interactive widgets.

References

The code references the CassiopeiaTree class from cassiopeia/data for tree data and the palettes module from cassiopeia/plotting for colormaps.

Symbols

interpolate_branch

Description

Interpolates the branch between a parent and child node in 3D space, ensuring a 90-degree angle.

Inputs

Name	Type	Description
parent	Tuple[float, float, float]	Coordinates of the parent node (x, y, z).
child	Tuple[float, float, float]	Coordinates of the child node (x, y, z).

Outputs

Name	Type	Description
branch_coords	np.ndarray	Numpy array containing the interpolated x, y, z coordinates of the branch.

Internal Logic

The function calculates the intermediate point on the branch by taking the x and y coordinates of the child and the z coordinate of the parent. It then returns an array containing the parent, intermediate point, and child coordinates.

polyline_from_points

Description

Creates a PyVista PolyData object representing a polyline connecting a set of points.

Inputs

Name	Type	Description
points	np.ndarray	Numpy array containing the x, y, z coordinates of the points.

Outputs

Name	Type	Description
poly	pv.PolyData	PyVista PolyData object representing the polyline.

Internal Logic

The function creates a PolyData object, sets its points to the input points, and defines a cell connecting all points in sequence.

average_mixing

Description

Mixes a set of colors by averaging the RGB values of each color.

Inputs

Name	Type	Description
*c	Tuple[float, float, float]	Variable number of color tuples in RGB format.

Outputs

Name	Type	Description
mixed_color	Tuple[float, float, float]	The mixed color in RGB format.

Internal Logic

The function converts the input colors to RGBA arrays using to_rgba_array, extracts the RGB channels, calculates the mean across all colors for each channel, and returns the resulting RGB tuple.

highlight

Description

Highlights a color by increasing its value (V) component in the HSV color space.

Inputs

Name	Type	Description
c	Tuple[float, float, float]	Color tuple in RGB format.

Outputs

Name	Type	Description
highlighted_color	Tuple[float, float, float]	The highlighted color in RGB format.

Internal Logic

The function converts the input color to HSV using rgb_to_hsv, increases the V component by 0.5 (capped at 1), and converts back to RGB using hsv_to_rgb.

lowlight

Description

Dims out a color by decreasing its value (V) component in the HSV color space.

Inputs

Name	Type	Description
c	Tuple[float, float, float]	Color tuple in RGB format.

Outputs

Name	Type	Description
dimmed_color	Tuple[float, float, float]	The dimmed color in RGB format.

Internal Logic

The function converts the input color to HSV using rgb_to_hsv, decreases the V component by 0.5 (capped at 0), and converts back to RGB using hsv_to_rgb.

labels_from_coordinates

Description

Creates a synthetic labels array for 3D plotting based on the spatial coordinates of cells in a CassiopeiaTree.

Inputs

Name	Type	Description
tree	CassiopeiaTree	The CassiopeiaTree object containing cell spatial coordinates.
attribute_key	str	Attribute name in the cell_meta of the tree containing coordinates.
shape	tuple	Shape of the output labels array (height, width).

Outputs

Name	Type	Description
labels	np.ndarray	A synthetic labels array where each cell is represented by a circle centered at its spatial coordinates.

Internal Logic

The function extracts spatial coordinates from the tree’s cell_meta, normalizes them to the range [0.05, 0.95], and scales the circle radius based on the number of cells. It then iterates through the cells, drawing circles on the labels array using OpenCV’s ellipse function.

Tree3D

Description

A class for creating and displaying 3D visualizations of CassiopeiaTree objects.

Inputs

Name	Type	Description
tree	CassiopeiaTree	The CassiopeiaTree object to visualize.
labels	np.ndarray	Optional labels array for cell positions. If None, labels are generated using labels_from_coordinates.
offset	float	Offset for tree and subclone shading to prevent clipping.
downscale	float	Downscaling factor for images and labels.
cmap	Optional[List[str]]	Colormap to use for nodes and branches.
attribute_key	str	Attribute key for leaf labels in the cell_meta.

Internal Logic

The class initializes PyVista objects, caches for tree data, and visualization parameters. It provides methods for adding images, setting visualization parameters, updating displayed elements (nodes, branches, subclones, images), and adding interactive widgets (sliders, checkboxes). The plot method renders the 3D visualization using PyVista.

Dependencies

Dependency	Purpose
cv2 (OpenCV)	Image processing and circle drawing.
pyvista	3D rendering and visualization.
skimage.measure	Region properties analysis for cell positions.
vtk	Visualization Toolkit for PyVista.

Error Handling

The code raises PlottingError exceptions for invalid input dimensions, image shapes, and missing dependencies. It also issues PlottingWarning warnings for missing cell meta data.

Configuration

The Tree3D class allows configuration of visualization parameters through its methods, such as set_subclone_sigma, set_height, set_time, set_root, and select_node.

Logging

The code does not implement explicit logging mechanisms.