spine.vis.ellipsoid

Module to convert a point cloud into an ellipsoidal envelope.

Functions

ellipsoid_trace([points, centroid, covmat, ...])

Converts a cloud of points or a covariance matrix into a 3D ellipsoid.

ellipsoid_traces(centroids, covmat[, color, ...])

Function which produces a list of plotly traces of ellipsoids given a list of centroids and one covariance matrix in x, y and z.
spine.vis.ellipsoid.ellipsoid_trace(points: ndarray | None = None, centroid: ndarray | None = None, covmat: ndarray | None = None, contour: float = 0.5, num_samples: int = 10, color: bool | int | float | generic | str | Sequence[bool | int | float | generic | str] | ndarray | None = None, intensity: bool | int | float | generic | Sequence[bool | int | float | generic] | ndarray | None = None, hovertext: bool | int | float | generic | str | Sequence[bool | int | float | generic | str] | ndarray | None = None, showscale: bool = False, **kwargs: Any) → plotly.graph_objs.Mesh3d[source]

Converts a cloud of points or a covariance matrix into a 3D ellipsoid.

This function uses the centroid and the covariance matrix of a cloud of points to define an ellipsoid which would encompass a user-defined fraction contour of all the points, were the points distributed following a 3D Gaussian.

Parameters:

  • points (np.ndarray, optional) – (N, 3) Array of point coordinates

  • centroid (np.ndarray, optional) –

    1. Centroid

  • covmat (np.ndarray, optional) – (3, 3) Covariance matrix which defines the ellipsoid shape

  • contour (float, default 0.5) – Fraction of the points contained in the ellipsoid, under the Gaussian distribution assumption

  • num_samples (int, default 10) – Number of points sampled along theta and phi in the spherical coordinate system of the ellipsoid. A larger number increases the resolution.

  • color (Union[str, int, float, Sequence], optional) – Color of the ellipsoid. Can be a single Plotly color or numeric value.

  • intensity (Union[int, float, Sequence], optional) – Color intensity of the ellipsoid along the colorscale axis. Can be a single numeric value or a per-vertex sequence.

  • hovertext (Union[int, float, str, Sequence], optional) – Text associated with the ellipsoid. Can be a scalar label or a per-vertex sequence of labels.

  • showscale (bool, default False) – If True, show the colorscale of the plotly.graph_objs.Mesh3d

  • **kwargs (dict, optional) – Additional parameters to pass to the underlying plotly.graph_objs.Mesh3d object

spine.vis.ellipsoid.ellipsoid_traces(centroids: ndarray, covmat: ndarray, color: bool | int | float | generic | str | Sequence[bool | int | float | generic | str] | ndarray | None = None, hovertext: bool | int | float | generic | str | Sequence[bool | int | float | generic | str] | ndarray | None = None, cmin: float | None = None, cmax: float | None = None, shared_legend: bool = True, legendgroup: str | None = None, showlegend: bool = True, name: str | None = None, **kwargs: Any) → list[plotly.graph_objs.Mesh3d][source]

Function which produces a list of plotly traces of ellipsoids given a list of centroids and one covariance matrix in x, y and z.

Parameters:

  • centroids (np.ndarray) – (N, 3) Positions of each of the ellipsoid centroids

  • covmat (np.ndarray) – (3, 3) Covariance matrix which defines any of the base ellipsoid shape

  • color (Union[str, int, float, Sequence], optional) – Color of the ellipsoids, either as one shared value or one value per ellipsoid.

  • hovertext (Union[int, float, str, Sequence], optional) – Text associated with the ellipsoids, either as one shared label or one label per ellipsoid.

  • cmin (float, optional) – Minimum value along the color scale

  • cmax (float, optional) – Maximum value along the color scale

  • shared_legend (bool, default True) – If True, the plotly legend of all ellipsoids is shared as one

  • legendgroup (str, optional) – Legend group to be shared between all ellipsoids

  • showlegend (bool, default True) – Whether to show legends on not

  • name (str, optional) – Name of the trace(s)

  • **kwargs (dict, optional) – List of additional arguments to pass to the underlying list of plotly.graph_objs.Mesh3D

Returns:

Ellipsoid traces

Return type:

Union[List[plotly.graph_objs.Mesh3D]]