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.