oineus.plot_chain

oineus.plot_chain(source, filtration, chain, *, ax=None, source_kind=None, dualize=False, chain_color=None, point_cloud_color=None, edge_style=None, triangle_style=None, tetrahedron_style=None, vertex_style=None, point_style=None, title=None, plot_source=True, field_cmap='viridis')[source]

Render a chain of cells over its underlying source.

source is one of:

  • a 2D point cloud as (N, 2) ndarray (simplicial filtration),

  • a 3D point cloud as (N, 3) ndarray (simplicial filtration),

  • a 2D scalar field as (H, W) ndarray (cubical or Freudenthal),

  • a 3D scalar field as (D, H, W) ndarray (cubical or Freudenthal).

The dispatch is driven by source_kind ("points" or "field") and, for kind "points", by source.shape[1] (2 vs 3). When source_kind is None we route CubeFiltration_*D to "field" and everything else to "points".

The chain may be a list, ndarray, range, or scipy.sparse column / row slice (e.g. dcmp.v_as_csc()[:, j]). Each entry is normally a filtration sorted-id; cells of dim 0/1/2/3 render as vertices / edges / triangles-or-squares / tetrahedra-or-voxels respectively.

The matrices v_data, r_data, u_data_t of a Decomposition(fil, dualize=True) are indexed in cohomology matrix space rather than filtration space (matrix index = n - 1 - filtration_id). Pass dualize=True (or dualize=dcmp and we will read dcmp.dualize for you) so plot_chain translates the chain back to filtration ids before looking up cells. The default False matches homology decompositions and indices that have already been translated (e.g. those returned by TopologyOptimizer.increase_birth).

Colors:
chain_color – single color or dict[int, color] (keys are

cell dimensions: 0=vertex, 1=edge, 2=triangle, 3=tetrahedron); applied to whatever the matching style dict didn’t already override. None (default) uses DEFAULT_CHAIN_COLOR uniformly.

point_cloud_color – single color for the underlying

point-cloud / field background. None (default) uses DEFAULT_POINT_CLOUD_COLOR.

Parameters:

  • source_kind (str | None)

  • edge_style (dict | None)

  • triangle_style (dict | None)

  • tetrahedron_style (dict | None)

  • vertex_style (dict | None)

  • point_style (dict | None)

  • title (str | None)

  • plot_source (bool)

  • field_cmap (str)