Visualization

knowledgecomplex.viz — NetworkX export and visualization helpers.

Two complementary views of a knowledge complex are provided:

Hasse diagram (plot_hasse, plot_hasse_star, plot_hasse_skeleton) Every element (vertex, edge, face) becomes a graph node. Directed edges represent the boundary operator, pointing from each element to its boundary elements (higher dimension → lower dimension). Faces have out-degree 3 and in-degree 0; edges have out-degree 2; vertices have out-degree 0. Nodes are colored by type and sized by dimension.

Geometric realization (plot_geometric, plot_geometric_interactive) Only KC vertices become points in 3D space. KC edges become line segments connecting their two boundary vertices. KC faces become filled, semi-transparent triangular patches spanning their three boundary vertices. This is the classical geometric realization of the abstract simplicial complex — the view a topologist would draw.

to_networkx exports a DiGraph that backs the Hasse plots. verify_networkx validates that a DiGraph satisfies simplicial complex cardinality and closure invariants at runtime.

Requires optional dependencies::

pip install knowledgecomplex[viz]                # matplotlib + networkx
pip install knowledgecomplex[viz-interactive]     # + plotly for interactive 3D

to_networkx(kc)

Convert a KnowledgeComplex to a directed networkx DiGraph.

Every element (vertex, edge, face) becomes a node. Directed edges represent the boundary operator kc:boundedBy, pointing from each element to its boundary elements (higher dimension → lower dimension).

In the resulting DiGraph:

• Face nodes have out-degree 3 (→ 3 boundary edges) and in-degree 0.
• Edge nodes have out-degree 2 (→ 2 boundary vertices).
• Vertex nodes have out-degree 0 (empty boundary).

Each node carries attributes:

• type: element type name (e.g. "Node", "Link")
• kind: "vertex", "edge", or "face"
• dim: 0, 1, or 2
• uri: file URI if present, else None
• All model-namespace attributes from the element

Parameters:

Name	Type	Description	Default
kc	KnowledgeComplex		required

Returns:

Type	Description
DiGraph

Source code in knowledgecomplex/viz.py

def to_networkx(kc: "KnowledgeComplex") -> Any:
    """Convert a KnowledgeComplex to a directed networkx DiGraph.

    Every element (vertex, edge, face) becomes a node.  Directed edges
    represent the boundary operator ``kc:boundedBy``, pointing **from each
    element to its boundary elements** (higher dimension → lower dimension).

    In the resulting DiGraph:

    - **Face** nodes have out-degree 3 (→ 3 boundary edges) and in-degree 0.
    - **Edge** nodes have out-degree 2 (→ 2 boundary vertices).
    - **Vertex** nodes have out-degree 0 (empty boundary).

    Each node carries attributes:

    - ``type``: element type name (e.g. ``"Node"``, ``"Link"``)
    - ``kind``: ``"vertex"``, ``"edge"``, or ``"face"``
    - ``dim``: 0, 1, or 2
    - ``uri``: file URI if present, else ``None``
    - All model-namespace attributes from the element

    Parameters
    ----------
    kc : KnowledgeComplex

    Returns
    -------
    networkx.DiGraph
    """
    nx = _require_nx()
    G = nx.DiGraph(name=kc._schema._namespace)

    for elem_id in kc.element_ids():
        elem = kc.element(elem_id)
        type_name = elem.type
        kind = kc._schema._types.get(type_name, {}).get("kind", "vertex")
        attrs = {
            "type": type_name,
            "kind": kind,
            "dim": _DIM_BY_KIND.get(kind, 0),
            "uri": elem.uri,
            **elem.attrs,
        }
        G.add_node(elem_id, **attrs)

    # Directed boundary edges: element → boundary element (high dim → low dim)
    for elem_id in kc.element_ids():
        for boundary_id in kc.boundary(elem_id):
            G.add_edge(elem_id, boundary_id)

    return G

verify_networkx(G)

Validate that a DiGraph satisfies simplicial complex invariants.

Checks cardinality constraints and boundary closure:

• Every node has kind and dim attributes.
• Vertices (dim=0): out-degree = 0.
• Edges (dim=1): out-degree = 2, both targets are vertices (dim=0).
• Faces (dim=2): out-degree = 3, all targets are edges (dim=1).
• Closed-triangle: for each face, the 3 boundary edges share exactly 3 distinct vertices (forming a closed triangle, not an open fan).

Parameters:

Name	Type	Description	Default
G	DiGraph	A DiGraph produced by :func:to_networkx.	required

Returns:

Type	Description
bool	True if all invariants hold.

Raises:

Type	Description
ValueError	On the first invariant violation, with a descriptive message.
TypeError	If G is not a DiGraph.

Source code in knowledgecomplex/viz.py

def verify_networkx(G: Any) -> bool:
    """Validate that a DiGraph satisfies simplicial complex invariants.

    Checks cardinality constraints and boundary closure:

    - Every node has ``kind`` and ``dim`` attributes.
    - **Vertices** (dim=0): out-degree = 0.
    - **Edges** (dim=1): out-degree = 2, both targets are vertices (dim=0).
    - **Faces** (dim=2): out-degree = 3, all targets are edges (dim=1).
    - **Closed-triangle**: for each face, the 3 boundary edges share exactly
      3 distinct vertices (forming a closed triangle, not an open fan).

    Parameters
    ----------
    G : networkx.DiGraph
        A DiGraph produced by :func:`to_networkx`.

    Returns
    -------
    bool
        ``True`` if all invariants hold.

    Raises
    ------
    ValueError
        On the first invariant violation, with a descriptive message.
    TypeError
        If *G* is not a ``DiGraph``.
    """
    nx = _require_nx()
    if not isinstance(G, nx.DiGraph):
        raise TypeError(f"Expected nx.DiGraph, got {type(G).__name__}")

    for node in G.nodes:
        data = G.nodes[node]
        if "kind" not in data or "dim" not in data:
            raise ValueError(f"Node '{node}' missing 'kind' or 'dim' attribute")

        dim = data["dim"]
        out_deg = G.out_degree(node)
        successors = list(G.successors(node))

        if dim == 0:  # vertex
            if out_deg != 0:
                raise ValueError(
                    f"Vertex '{node}' has out-degree {out_deg}, expected 0"
                )

        elif dim == 1:  # edge
            if out_deg != 2:
                raise ValueError(
                    f"Edge '{node}' has out-degree {out_deg}, expected 2"
                )
            for s in successors:
                if G.nodes[s].get("dim") != 0:
                    raise ValueError(
                        f"Edge '{node}' boundary target '{s}' is not a vertex "
                        f"(dim={G.nodes[s].get('dim')})"
                    )

        elif dim == 2:  # face
            if out_deg != 3:
                raise ValueError(
                    f"Face '{node}' has out-degree {out_deg}, expected 3"
                )
            for s in successors:
                if G.nodes[s].get("dim") != 1:
                    raise ValueError(
                        f"Face '{node}' boundary target '{s}' is not an edge "
                        f"(dim={G.nodes[s].get('dim')})"
                    )
            # Closed-triangle: 3 edges must share exactly 3 distinct vertices
            face_vertices = set()
            for edge_node in successors:
                for v in G.successors(edge_node):
                    face_vertices.add(v)
            if len(face_vertices) != 3:
                raise ValueError(
                    f"Face '{node}' boundary edges span {len(face_vertices)} "
                    f"distinct vertices, expected 3 (closed triangle)"
                )

    return True

type_color_map(kc)

Build a type-name to hex-color mapping from the schema's type registry.

Uses matplotlib's tab10 colormap (or tab20 if > 10 types) for distinct, visually separable colors.

Parameters:

Name	Type	Description	Default
kc	KnowledgeComplex		required

Returns:

Type	Description
dict[str, str]	Mapping from type name to hex color string.

Source code in knowledgecomplex/viz.py

def type_color_map(kc: "KnowledgeComplex") -> dict[str, str]:
    """Build a type-name to hex-color mapping from the schema's type registry.

    Uses matplotlib's ``tab10`` colormap (or ``tab20`` if > 10 types)
    for distinct, visually separable colors.

    Parameters
    ----------
    kc : KnowledgeComplex

    Returns
    -------
    dict[str, str]
        Mapping from type name to hex color string.
    """
    _, plt = _require_mpl()
    import matplotlib.colors as mcolors

    type_names = sorted(kc._schema._types.keys())
    cmap_name = "tab10" if len(type_names) <= 10 else "tab20"
    cmap = plt.get_cmap(cmap_name)

    colors = {}
    for i, name in enumerate(type_names):
        colors[name] = mcolors.to_hex(cmap(i % cmap.N))
    return colors

plot_hasse(kc, *, ax=None, figsize=(10, 8), with_labels=True, node_size_by_dim=True)

Plot the Hasse diagram of the complex with type-based color coding.

Every element (vertex, edge, face) is drawn as a node. Directed arrows represent the boundary operator, pointing from each element to its boundary elements (higher dimension → lower dimension). Nodes are colored by type and sized by dimension (vertices largest, faces smallest).

This is not a geometric picture of the complex — it is the partially ordered set of simplices. For a geometric view where vertices are points, edges are line segments, and faces are filled triangles, see :func:plot_geometric.

Parameters:

Name	Type	Description	Default
kc	KnowledgeComplex		required
ax	matplotlib Axes	Axes to draw on. Created if not provided.	None
figsize	tuple	Figure size if creating a new figure.	(10, 8)
with_labels	bool	Show element ID labels on nodes.	True
node_size_by_dim	bool	Scale node size by dimension (vertex=large, face=small).	True

Returns:

Type	Description
(fig, ax)	The matplotlib Figure and Axes.

Source code in knowledgecomplex/viz.py

def plot_hasse(
    kc: "KnowledgeComplex",
    *,
    ax: Any = None,
    figsize: tuple[float, float] = (10, 8),
    with_labels: bool = True,
    node_size_by_dim: bool = True,
) -> tuple[Any, Any]:
    """Plot the Hasse diagram of the complex with type-based color coding.

    Every element (vertex, edge, face) is drawn as a node.  Directed arrows
    represent the boundary operator, pointing from each element to its
    boundary elements (higher dimension → lower dimension).  Nodes are colored
    by type and sized by dimension (vertices largest, faces smallest).

    This is **not** a geometric picture of the complex — it is the partially
    ordered set of simplices.  For a geometric view where vertices are points,
    edges are line segments, and faces are filled triangles, see
    :func:`plot_geometric`.

    Parameters
    ----------
    kc : KnowledgeComplex
    ax : matplotlib Axes, optional
        Axes to draw on. Created if not provided.
    figsize : tuple
        Figure size if creating a new figure.
    with_labels : bool
        Show element ID labels on nodes.
    node_size_by_dim : bool
        Scale node size by dimension (vertex=large, face=small).

    Returns
    -------
    (fig, ax)
        The matplotlib Figure and Axes.
    """
    nx = _require_nx()
    _, plt = _require_mpl()

    G = to_networkx(kc)
    fig, ax = _prepare_ax(ax, figsize)
    pos = _layout(G)
    colors = type_color_map(kc)

    if len(G) == 0:
        ax.set_title("Empty complex")
        ax.axis("off")
        return fig, ax

    node_colors = [colors.get(G.nodes[n].get("type", ""), "#999999") for n in G]
    if node_size_by_dim:
        node_sizes = [_SIZE_BY_DIM.get(G.nodes[n].get("dim", 0), 200) for n in G]
    else:
        node_sizes = 300

    nx.draw_networkx_edges(
        G, pos, ax=ax, edge_color="#cccccc", width=1.5,
        arrows=True, arrowstyle="-|>", arrowsize=12,
        connectionstyle="arc3,rad=0.05",
    )
    nx.draw_networkx_nodes(
        G, pos, ax=ax,
        node_color=node_colors,
        node_size=node_sizes,
        edgecolors="#333333",
        linewidths=0.5,
    )
    if with_labels:
        nx.draw_networkx_labels(G, pos, ax=ax, font_size=8)

    # Legend
    from matplotlib.lines import Line2D
    legend_handles = []
    for type_name in sorted(colors):
        kind = kc._schema._types.get(type_name, {}).get("kind", "?")
        legend_handles.append(
            Line2D([0], [0], marker="o", color="w",
                   markerfacecolor=colors[type_name], markersize=10,
                   label=f"{type_name} ({kind})")
        )
    if legend_handles:
        ax.legend(handles=legend_handles, loc="best", fontsize=8)

    ax.set_title(f"Hasse Diagram: {kc._schema._namespace}")
    ax.axis("off")
    return fig, ax

plot_hasse_star(kc, id, *, ax=None, figsize=(10, 8), with_labels=True)

Plot the Hasse diagram with the star of an element highlighted.

Elements in St(id) are drawn in full color with directed arrows; all other elements are dimmed to light gray. This is the Hasse-diagram view — see :func:plot_hasse for details on what that means.

Parameters:

Name	Type	Description	Default
kc	KnowledgeComplex		required
id	str	Element whose star to highlight.	required
ax	matplotlib Axes		None
figsize	tuple		(10, 8)
with_labels	bool		True

Returns:

Type	Description
(fig, ax)

Source code in knowledgecomplex/viz.py

def plot_hasse_star(
    kc: "KnowledgeComplex",
    id: str,
    *,
    ax: Any = None,
    figsize: tuple[float, float] = (10, 8),
    with_labels: bool = True,
) -> tuple[Any, Any]:
    """Plot the Hasse diagram with the star of an element highlighted.

    Elements in ``St(id)`` are drawn in full color with directed arrows;
    all other elements are dimmed to light gray.  This is the Hasse-diagram
    view — see :func:`plot_hasse` for details on what that means.

    Parameters
    ----------
    kc : KnowledgeComplex
    id : str
        Element whose star to highlight.
    ax : matplotlib Axes, optional
    figsize : tuple
    with_labels : bool

    Returns
    -------
    (fig, ax)
    """
    nx = _require_nx()
    _, plt = _require_mpl()

    G = to_networkx(kc)
    fig, ax = _prepare_ax(ax, figsize)
    pos = _layout(G)
    colors = type_color_map(kc)
    star_ids = kc.star(id)

    highlighted = [n for n in G if n in star_ids]
    dimmed = [n for n in G if n not in star_ids]

    if dimmed:
        nx.draw_networkx_nodes(
            G, pos, nodelist=dimmed, ax=ax,
            node_color="#dddddd", node_size=150,
            edgecolors="#cccccc", linewidths=0.5,
        )

    star_edges = [(u, v) for u, v in G.edges() if u in star_ids and v in star_ids]
    dim_edges = [(u, v) for u, v in G.edges() if (u, v) not in set(star_edges)]
    if dim_edges:
        nx.draw_networkx_edges(
            G, pos, edgelist=dim_edges, ax=ax, edge_color="#eeeeee", width=1.0,
            arrows=True, arrowstyle="-|>", arrowsize=8,
        )
    if star_edges:
        nx.draw_networkx_edges(
            G, pos, edgelist=star_edges, ax=ax, edge_color="#666666", width=2.0,
            arrows=True, arrowstyle="-|>", arrowsize=14,
        )

    if highlighted:
        h_colors = [colors.get(G.nodes[n].get("type", ""), "#999999") for n in highlighted]
        h_sizes = [_SIZE_BY_DIM.get(G.nodes[n].get("dim", 0), 200) for n in highlighted]
        nx.draw_networkx_nodes(
            G, pos, nodelist=highlighted, ax=ax,
            node_color=h_colors, node_size=h_sizes,
            edgecolors="#333333", linewidths=1.0,
        )

    if with_labels:
        nx.draw_networkx_labels(G, pos, ax=ax, font_size=8)

    ax.set_title(f"Hasse Star({id})")
    ax.axis("off")
    return fig, ax

plot_hasse_skeleton(kc, k, *, ax=None, figsize=(10, 8), with_labels=True)

Plot the Hasse diagram of the k-skeleton only.

Shows only elements of dimension ≤ k, with directed boundary arrows. This is the Hasse-diagram view — see :func:plot_hasse for details.

k=0: vertices only, k=1: vertices + edges, k=2: everything.

Parameters:

Name	Type	Description	Default
kc	KnowledgeComplex		required
k	int	Maximum dimension (0, 1, or 2).	required
ax	matplotlib Axes		None
figsize	tuple		(10, 8)
with_labels	bool		True

Returns:

Type	Description
(fig, ax)

Source code in knowledgecomplex/viz.py

def plot_hasse_skeleton(
    kc: "KnowledgeComplex",
    k: int,
    *,
    ax: Any = None,
    figsize: tuple[float, float] = (10, 8),
    with_labels: bool = True,
) -> tuple[Any, Any]:
    """Plot the Hasse diagram of the k-skeleton only.

    Shows only elements of dimension ≤ k, with directed boundary arrows.
    This is the Hasse-diagram view — see :func:`plot_hasse` for details.

    k=0: vertices only, k=1: vertices + edges, k=2: everything.

    Parameters
    ----------
    kc : KnowledgeComplex
    k : int
        Maximum dimension (0, 1, or 2).
    ax : matplotlib Axes, optional
    figsize : tuple
    with_labels : bool

    Returns
    -------
    (fig, ax)
    """
    nx = _require_nx()
    _, plt = _require_mpl()

    G = to_networkx(kc)
    skel_ids = kc.skeleton(k)
    subG = G.subgraph(skel_ids).copy()

    fig, ax = _prepare_ax(ax, figsize)
    pos = _layout(subG)
    colors = type_color_map(kc)

    if len(subG) == 0:
        ax.set_title(f"Hasse Skeleton({k}) — empty")
        ax.axis("off")
        return fig, ax

    node_colors = [colors.get(subG.nodes[n].get("type", ""), "#999999") for n in subG]
    node_sizes = [_SIZE_BY_DIM.get(subG.nodes[n].get("dim", 0), 200) for n in subG]

    nx.draw_networkx_edges(
        subG, pos, ax=ax, edge_color="#cccccc", width=1.5,
        arrows=True, arrowstyle="-|>", arrowsize=12,
    )
    nx.draw_networkx_nodes(
        subG, pos, ax=ax,
        node_color=node_colors,
        node_size=node_sizes,
        edgecolors="#333333",
        linewidths=0.5,
    )
    if with_labels:
        nx.draw_networkx_labels(subG, pos, ax=ax, font_size=8)

    ax.set_title(f"Hasse Skeleton({k})")
    ax.axis("off")
    return fig, ax

plot_complex(kc, **kwargs)

Deprecated: use :func:plot_hasse instead.

Source code in knowledgecomplex/viz.py

def plot_complex(kc, **kwargs):
    """Deprecated: use :func:`plot_hasse` instead."""
    warnings.warn("plot_complex is deprecated, use plot_hasse", DeprecationWarning, stacklevel=2)
    return plot_hasse(kc, **kwargs)

plot_star(kc, id, **kwargs)

Deprecated: use :func:plot_hasse_star instead.

Source code in knowledgecomplex/viz.py

def plot_star(kc, id, **kwargs):
    """Deprecated: use :func:`plot_hasse_star` instead."""
    warnings.warn("plot_star is deprecated, use plot_hasse_star", DeprecationWarning, stacklevel=2)
    return plot_hasse_star(kc, id, **kwargs)

plot_skeleton(kc, k, **kwargs)

Deprecated: use :func:plot_hasse_skeleton instead.

Source code in knowledgecomplex/viz.py

def plot_skeleton(kc, k, **kwargs):
    """Deprecated: use :func:`plot_hasse_skeleton` instead."""
    warnings.warn("plot_skeleton is deprecated, use plot_hasse_skeleton", DeprecationWarning, stacklevel=2)
    return plot_hasse_skeleton(kc, k, **kwargs)

plot_geometric(kc, *, ax=None, figsize=(10, 8), with_labels=True)

Plot the geometric realization of the complex in 3D.

KC vertices become points in 3D space (positioned by force-directed layout). KC edges become line segments connecting their two boundary vertices. KC faces become filled, semi-transparent triangular patches spanning their three boundary vertices.

This is the classical geometric realization — the view a topologist would draw. For the Hasse diagram where every element is a node and boundary relations are directed edges, see :func:plot_hasse.

Parameters:

Name	Type	Description	Default
kc	KnowledgeComplex		required
ax	matplotlib Axes3D	A 3D axes to draw on. Created if not provided.	None
figsize	tuple	Figure size if creating a new figure.	(10, 8)
with_labels	bool	Show vertex ID labels.	True

Returns:

Type	Description
(fig, ax)	The matplotlib Figure and Axes3D.

Source code in knowledgecomplex/viz.py

def plot_geometric(
    kc: "KnowledgeComplex",
    *,
    ax: Any = None,
    figsize: tuple[float, float] = (10, 8),
    with_labels: bool = True,
) -> tuple[Any, Any]:
    """Plot the geometric realization of the complex in 3D.

    KC vertices become points in 3D space (positioned by force-directed
    layout).  KC edges become line segments connecting their two boundary
    vertices.  KC faces become filled, semi-transparent triangular patches
    spanning their three boundary vertices.

    This is the classical geometric realization — the view a topologist
    would draw.  For the Hasse diagram where every element is a node and
    boundary relations are directed edges, see :func:`plot_hasse`.

    Parameters
    ----------
    kc : KnowledgeComplex
    ax : matplotlib Axes3D, optional
        A 3D axes to draw on.  Created if not provided.
    figsize : tuple
        Figure size if creating a new figure.
    with_labels : bool
        Show vertex ID labels.

    Returns
    -------
    (fig, ax)
        The matplotlib Figure and Axes3D.
    """
    _, plt = _require_mpl()
    from mpl_toolkits.mplot3d.art3d import Poly3DCollection

    colors = type_color_map(kc)
    pos = _vertex_positions_3d(kc)

    if ax is None:
        fig = plt.figure(figsize=figsize)
        ax = fig.add_subplot(111, projection="3d")
    else:
        fig = ax.get_figure()

    if not pos:
        ax.set_title("Empty complex")
        return fig, ax

    # Draw faces as filled triangles
    face_ids = kc.skeleton(2) - kc.skeleton(1)
    for fid in face_ids:
        verts = _face_vertices(kc, fid)
        if len(verts) == 3 and all(v in pos for v in verts):
            tri = [pos[v] for v in verts]
            face_type = kc.element(fid).type
            color = colors.get(face_type, "#999999")
            poly = Poly3DCollection([tri], alpha=0.25, facecolor=color,
                                    edgecolor=color, linewidths=0.5)
            ax.add_collection3d(poly)

    # Draw edges as line segments
    edge_ids = kc.skeleton(1) - kc.skeleton(0)
    for eid in edge_ids:
        boundary = list(kc.boundary(eid))
        if len(boundary) == 2 and all(v in pos for v in boundary):
            p0, p1 = pos[boundary[0]], pos[boundary[1]]
            edge_type = kc.element(eid).type
            color = colors.get(edge_type, "#999999")
            ax.plot3D(
                [p0[0], p1[0]], [p0[1], p1[1]], [p0[2], p1[2]],
                color=color, linewidth=2,
            )

    # Draw vertices as scatter points
    vertex_ids = list(kc.skeleton(0))
    for vid in vertex_ids:
        if vid in pos:
            x, y, z = pos[vid]
            vtype = kc.element(vid).type
            color = colors.get(vtype, "#999999")
            ax.scatter3D(x, y, z, color=color, s=80, edgecolors="#333333",
                         linewidths=0.5, zorder=5, depthshade=False)

    # Labels
    if with_labels:
        for vid in vertex_ids:
            if vid in pos:
                x, y, z = pos[vid]
                ax.text(x, y, z, f"  {vid}", fontsize=7)

    # Legend
    from matplotlib.lines import Line2D
    legend_handles = []
    for type_name in sorted(colors):
        kind = kc._schema._types.get(type_name, {}).get("kind", "?")
        legend_handles.append(
            Line2D([0], [0], marker="o", color="w",
                   markerfacecolor=colors[type_name], markersize=8,
                   label=f"{type_name} ({kind})")
        )
    if legend_handles:
        ax.legend(handles=legend_handles, loc="best", fontsize=7)

    ax.set_title(f"Geometric Realization: {kc._schema._namespace}")
    return fig, ax

plot_geometric_interactive(kc)

Plot an interactive 3D geometric realization of the complex.

Same geometry as :func:plot_geometric — KC vertices are points, KC edges are line segments, KC faces are filled triangles — but rendered with Plotly for interactive rotation, zoom, and hover inspection.

Requires plotly::

pip install knowledgecomplex[viz-interactive]

Parameters:

Name	Type	Description	Default
kc	KnowledgeComplex		required

Returns:

Type	Description
Figure	Call .show() to display or .write_html("file.html") to save.

Source code in knowledgecomplex/viz.py

def plot_geometric_interactive(
    kc: "KnowledgeComplex",
) -> Any:
    """Plot an interactive 3D geometric realization of the complex.

    Same geometry as :func:`plot_geometric` — KC vertices are points, KC edges
    are line segments, KC faces are filled triangles — but rendered with
    Plotly for interactive rotation, zoom, and hover inspection.

    Requires plotly::

        pip install knowledgecomplex[viz-interactive]

    Parameters
    ----------
    kc : KnowledgeComplex

    Returns
    -------
    plotly.graph_objects.Figure
        Call ``.show()`` to display or ``.write_html("file.html")`` to save.
    """
    go = _require_plotly()

    colors = type_color_map(kc)
    pos = _vertex_positions_3d(kc)
    fig = go.Figure()

    if not pos:
        fig.update_layout(title="Empty complex")
        return fig

    # Faces as Mesh3d triangles
    face_ids = kc.skeleton(2) - kc.skeleton(1)
    for fid in face_ids:
        verts = _face_vertices(kc, fid)
        if len(verts) == 3 and all(v in pos for v in verts):
            xs = [pos[v][0] for v in verts]
            ys = [pos[v][1] for v in verts]
            zs = [pos[v][2] for v in verts]
            face_type = kc.element(fid).type
            color = colors.get(face_type, "#999999")
            fig.add_trace(go.Mesh3d(
                x=xs, y=ys, z=zs,
                i=[0], j=[1], k=[2],
                color=color, opacity=0.3,
                hoverinfo="text",
                hovertext=f"{fid} ({face_type})",
                showlegend=False,
            ))

    # Edges as line segments
    edge_ids = kc.skeleton(1) - kc.skeleton(0)
    for eid in edge_ids:
        boundary = list(kc.boundary(eid))
        if len(boundary) == 2 and all(v in pos for v in boundary):
            p0, p1 = pos[boundary[0]], pos[boundary[1]]
            edge_type = kc.element(eid).type
            color = colors.get(edge_type, "#999999")
            fig.add_trace(go.Scatter3d(
                x=[p0[0], p1[0]], y=[p0[1], p1[1]], z=[p0[2], p1[2]],
                mode="lines",
                line=dict(color=color, width=4),
                hoverinfo="text",
                hovertext=f"{eid} ({edge_type})",
                showlegend=False,
            ))

    # Vertices as markers
    vertex_ids = [v for v in kc.skeleton(0) if v in pos]
    xs = [pos[v][0] for v in vertex_ids]
    ys = [pos[v][1] for v in vertex_ids]
    zs = [pos[v][2] for v in vertex_ids]
    vtypes = [kc.element(v).type for v in vertex_ids]
    vcolors = [colors.get(t, "#999999") for t in vtypes]
    hover = [f"{vid} ({vt})" for vid, vt in zip(vertex_ids, vtypes)]

    fig.add_trace(go.Scatter3d(
        x=xs, y=ys, z=zs,
        mode="markers+text",
        marker=dict(size=6, color=vcolors, line=dict(width=1, color="#333333")),
        text=vertex_ids,
        textposition="top center",
        textfont=dict(size=8),
        hoverinfo="text",
        hovertext=hover,
        showlegend=False,
    ))

    fig.update_layout(
        title=f"Geometric Realization: {kc._schema._namespace}",
        scene=dict(
            xaxis=dict(showgrid=False, zeroline=False, showticklabels=False, title=""),
            yaxis=dict(showgrid=False, zeroline=False, showticklabels=False, title=""),
            zaxis=dict(showgrid=False, zeroline=False, showticklabels=False, title=""),
        ),
        showlegend=False,
    )
    return fig