# Sverchok Impl Topologic

> Use when working with TopologicSverchok for building topology analysis -- CellComplex workflows, space adjacency graphs, dual graphs, or energy simulation preparation. Prevents the common mistake of using mesh-based operations for topology analysis instead of non-manifold TopologicSverchok operations. Covers CellComplex-based BIM workflows, room connectivity, and envelope analysis. Keywords: TopologicSverchok, CellComplex, adjacency graph, dual graph, topology, non-manifold, room connectivity, energy simulation, building envelope, daylight analysis, solar, space adjacency.

- Skill: `impertio-studio/sverchok-impl-topologic` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add impertio-studio/sverchok-impl-topologic`
- Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/sverchok-impl-topologic/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: Impertio-Studio (https://skillmd.com/u/impertio-studio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/impertio-studio/sverchok-impl-topologic

---


# sverchok-impl-topologic

## Quick Reference

### What Is TopologicSverchok

TopologicSverchok integrates the **topologicpy** non-manifold topology (NMT) library with Sverchok's parametric node system. It enables hierarchical and topological representations of architectural spaces, buildings, and artefacts through 326 nodes organized by topology class.

- **326 nodes** in the `nodes/Topologic/` directory
- **Non-manifold topology**: lines, surfaces, and volumes coexist simultaneously
- **AEC workflows**: envelope analysis, space adjacency, dual graphs, energy simulation
- **Integrations**: IFC (ifcopenshell), OpenStudio/EnergyPlus, Speckle, Neo4j, DGL
- **License**: AGPL-3.0
- **Repository**: https://github.com/wassimj/TopologicSverchok
- **Python API**: https://topologicpy.readthedocs.io

### Topology Class Hierarchy

| Class | Dimension | AEC Example | Key Nodes |
|-------|-----------|-------------|-----------|
| **Vertex** | 0D | Column insertion point | `VertexByCoordinates`, `VertexEnclosingCell` |
| **Edge** | 1D | Structural beam axis | `EdgeByVertices`, `EdgeLength`, `EdgeDirection` |
| **Wire** | 1D composite | Room boundary outline | `WireByEdges`, `WireRectangle`, `WireIsClosed` |
| **Face** | 2D | Wall surface, floor slab | `FaceByEdges`, `FaceArea`, `FaceTrimByWire` |
| **Shell** | 2D composite | Building envelope | `ShellByFaces`, `ShellByLoft`, `ShellIsClosed` |
| **Cell** | 3D | Room volume | `CellByFaces`, `CellVolume`, `CellInternalVertex` |
| **CellComplex** | 3D non-manifold | Multi-room building | `CellComplexByFaces`, `CellComplexDecompose` |
| **Cluster** | Mixed | Building group | `ClusterByTopologies`, `ClusterType` |

### Critical Warnings

**NEVER** confuse Topologic topology objects with Blender mesh data — they are completely different representations. Convert with `TopologyByGeometry` (Blender to Topologic) or `TopologyBlenderGeometry` (Topologic to Blender).

**NEVER** pass raw Blender vertex coordinates directly to Topologic nodes — always use `VertexByCoordinates` to create Topologic Vertex objects first.

**NEVER** assume all faces in a CellComplex are planar — TopologicSverchok requires planar geometry; use `TopologyIsPlanar` to verify before building CellComplex structures.

**ALWAYS** check optional dependency availability before using IFC, Energy, Speckle, or Neo4j nodes — these require separate installations of ifcopenshell, OpenStudio, specklepy, or py2neo.

**ALWAYS** use `CellComplexDecompose` to categorize faces as external/internal/non-manifold before querying building envelope — non-manifold faces are shared between cells and should not be treated as exterior surfaces.

### Decision Tree

```
Need to analyze building spaces topologically?
├── From Blender geometry → TopologyByGeometry -> CellComplexByFaces
├── From IFC file → IFCReadFile -> TopologyByImportedIFC
├── Room adjacency → CellComplexByFaces -> CellAdjacentCells
├── Dual graph (rooms=nodes, walls=edges) → GraphByTopology
└── Envelope faces → CellComplexDecompose -> filter external faces

Need to run energy simulation?
├── From topology → EnergyModelByTopology -> EnergyModelRunSimulation
├── From IFC → EnergyModelByImportedIFC -> EnergyModelExportToOSM
├── Export for EnergyPlus → EnergyModelExportToIDF
└── Query results → EnergyModelQuery (reports, tables, rows, columns)

Need to analyze space connectivity?
├── Space graph → GraphByTopology (CellComplex input)
├── Shortest path between rooms → GraphShortestPath
├── Centrality analysis → GraphBetweennessCentrality / GraphDegreeCentrality
└── Export graph → GraphExportToCSV

Need to work with IFC?
├── Read IFC → IFCReadFile
├── Extract elements → IFCBuildingElements
├── Create spaces → IFCCreateSpaces
├── Clash detection → IFCClashDetection
└── Connect elements → IFCConnectBuildingElements
```

---

## Installation

### Requirements

| Dependency | Version | Required |
|------------|---------|----------|
| Blender | >= 4.0 | Yes |
| Sverchok | >= 1.2.0 | Yes |
| topologicpy | latest | Yes (auto-installed) |
| NumPy | >= 1.22.4 | Yes |
| ifcopenshell | latest | For IFC nodes |
| OpenStudio | >= 3.4.0 | For Energy nodes |
| honeybee-energy | >= 1.91.49 | For HB nodes |
| specklepy | >= 2.7.6 | For Speckle nodes |
| py2neo | >= 2021.2.3 | For Neo4j nodes |
| DGL | latest | For DGL/ML nodes |

### Installation Steps

1. Download TopologicSverchok ZIP from https://github.com/wassimj/TopologicSverchok
2. In Blender: Edit > Preferences > Add-ons > Install
3. Select the ZIP file — do NOT extract first
4. Enable the add-on in the list
5. Use the `InstallDependencies` node on first use to install topologicpy and optional packages

---

## Essential Patterns

### Pattern 1: Build a CellComplex from Blender Geometry

```
Sverchok node tree setup:
Object In (Blender object) -> [vertices, edges, faces]
   -> TopologyByGeometry (Topology object)
   -> CellComplexByFaces (CellComplex)
   -> CellComplexDecompose (external faces, internal faces, non-manifold faces)
```

The `TopologyByGeometry` node converts Blender mesh data (vertex coordinates + face indices) into a Topologic Topology. Planar geometry only — non-planar faces will cause errors. `CellComplexByFaces` merges all faces into a non-manifold structure where shared faces become internal boundaries between cells.

### Pattern 2: Room Adjacency Graph

```
CellComplex
   -> GraphByTopology (direct=True, viaSharedTopologies=True, toExteriorTopologies=False)
   -> Graph object
      -> GraphVertices -> list of room vertices
      -> GraphEdges -> list of shared-wall edges
      -> GraphShortestPath (vertexA, vertexB) -> Wire path
      -> GraphDepthMap (startVertex) -> distance map
```

`GraphByTopology` creates a dual graph where each Cell becomes a vertex and shared Faces (internal walls/slabs) become edges. Set `direct=True` for cell-to-cell edges via shared faces. The output Graph supports all standard graph operations (shortest path, centrality, community detection).

### Pattern 3: Building Envelope Analysis

```
CellComplex
   -> CellComplexDecompose
      -> externalFaces -> FaceArea (total envelope area)
      -> internalFaces -> FaceArea (total internal surface area)
      -> nonManifoldFaces -> (shared between cells — zero-thickness boundaries)
   -> filter externalFaces by FaceFacingToward (direction=[0,0,1]) -> roof faces
   -> filter externalFaces by FaceFacingToward (direction=[0,0,-1]) -> floor faces
   -> remaining externalFaces -> wall faces
```

### Pattern 4: Energy Simulation from Topology

```
CellComplex (building geometry)
   -> EnergyModelByTopology (
        building=cellcomplex,
        weatherFilePath="path/to/weather.epw",
        floorLevels=[0, 3, 6, 9],
        glazingRatio=0.4,
        coolingTemp=25.0,
        heatingTemp=20.0
      )
   -> EnergyModel
      -> EnergyModelRunSimulation (osBinaryPath, outputFolder)
      -> EnergyModelQuery (reportName, tableName, columnName)
      -> simulation results (heating/cooling loads)
```

### Pattern 5: IFC to Topologic Workflow

```
IFCReadFile (path) -> IFC file object
   -> IFCBuildingElements (ifc, elementType="IfcWall") -> wall topologies
   -> TopologyByImportedIFC -> Topology objects
   -> CellComplexByFaces -> building topology
   -> GraphByTopology -> adjacency graph
```

Alternatively use `EnergyModelByImportedIFC` for direct IFC-to-energy-model conversion without intermediate topology steps.

---

## Common Operations

### Node Categories Overview

| Category | Node Count | Purpose |
|----------|-----------|---------|
| Vertex | 10 | Point creation, distance, containment |
| Edge | 12 | Linear elements, direction, length |
| Wire | 16 | Connected edge paths, primitives |
| Face | 26 | Surface elements, area, normals |
| Shell | 10 | Connected face collections |
| Cell | 20 | Volumetric elements, primitives |
| CellComplex | 10 | Non-manifold building models |
| Cluster | 2 | Mixed topology collections |
| Topology | 50 | Base operations (boolean, transform, I/O) |
| Graph | 36 | Adjacency, pathfinding, analysis |
| EnergyModel | 20 | OpenStudio/EnergyPlus simulation |
| IFC | 10 | IFC file operations |
| HB (Honeybee) | 8 | Honeybee energy model |
| DGL | 18 | Deep graph learning |
| Speckle | 17 | Speckle interoperability |
| Dictionary | 8 | Metadata key-value storage |
| Color | 5 | Visualization coloring |
| Neo4j | 5 | Graph database export |
| Matrix | 4 | Transformation matrices |

### Key Node Reference

#### CellComplex Nodes

| Node | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `CellComplexByFaces` | faces, tolerance | cellcomplex | Merge faces into non-manifold CellComplex |
| `CellComplexByCells` | cells | cellcomplex | Merge cells by shared faces |
| `CellComplexDecompose` | cellcomplex | externalFaces, internalFaces, nonManifoldFaces, externalVertices, internalVertices | Decompose by location/type |
| `CellComplexExternalBoundary` | cellcomplex | shell | Get outer envelope shell |
| `CellComplexInternalBoundaries` | cellcomplex | faces | Get internal boundary faces |
| `CellComplexNonManifoldFaces` | cellcomplex | faces | Get non-manifold (shared) faces |
| `CellComplexPrism` | origin, width, length, height, uSides, vSides, wSides | cellcomplex | Subdivided box |

#### Graph Nodes

| Node | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `GraphByTopology` | topology, direct, viaSharedTopologies, toExteriorTopologies | graph | Build dual graph from topology |
| `GraphShortestPath` | graph, vertexA, vertexB | path (Wire) | Dijkstra shortest path |
| `GraphAllPaths` | graph, vertexA, vertexB | paths | All paths between vertices |
| `GraphDepthMap` | graph, startVertex | depthMap | Distance from start vertex |
| `GraphAdjacentVertices` | graph, vertex | vertices | Direct neighbors |
| `GraphVertices` | graph | vertices | All graph vertices |
| `GraphEdges` | graph | edges | All graph edges |
| `GraphDensity` | graph | density | Edge density ratio |
| `GraphDiameter` | graph | diameter | Maximum shortest path |
| `GraphMST` | graph | mst | Minimum spanning tree |

#### Topology Base Nodes

| Node | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `TopologyByGeometry` | vertices, edges, faces | topology | Blender mesh to Topologic |
| `TopologyBlenderGeometry` | topology | vertices, edges, faces | Topologic to Blender mesh |
| `TopologyBoolean` | topologyA, topologyB, operation | topology | Union/Difference/Intersection |
| `TopologyAdjacentTopologies` | topology, topologyType | topologies | Find adjacent entities |
| `TopologySubTopologies` | topology, subTopologyType | topologies | Extract sub-entities |
| `TopologySuperTopologies` | topology, superTopologyType | topologies | Find containing entities |
| `TopologySharedTopologies` | topologyA, topologyB, topologyType | topologies | Find shared entities |
| `TopologyDictionary` | topology | dictionary | Get attached metadata |
| `TopologySetDictionary` | topology, dictionary | topology | Attach metadata |
| `TopologyAnalyze` | topology | string | Describe topology structure |
| `TopologyExportToJSONMK2` | topology, path | success | Export to JSON file |
| `TopologyByImportedJSONMK2` | path | topology | Import from JSON file |

### Dictionary Nodes for Metadata

Topologic entities carry attached dictionaries for BIM data:

| Node | Purpose |
|------|---------|
| `DictionaryByKeysValues` | Create dictionary from key-value lists |
| `DictionaryValueAtKey` | Read value for a specific key |
| `DictionarySetValueAtKey` | Write/update a value |
| `DictionaryKeys` | Get all keys |
| `DictionaryValues` | Get all values |
| `DictionaryByObjectProperties` | Extract Blender object custom properties |

---

## Reference Links

- [references/methods.md](references/methods.md) — Complete API signatures for all topology classes (topologicpy)
- [references/examples.md](references/examples.md) — Working node tree patterns for AEC workflows
- [references/anti-patterns.md](references/anti-patterns.md) — What NOT to do with TopologicSverchok

### Cross-References

- `ifcos-impl-geometry` — IFC geometry input for TopologicSverchok workflows
- `sverchok-impl-custom-nodes` — Custom node development for TopologicSverchok extension

### Official Sources

- https://github.com/wassimj/TopologicSverchok
- https://topologic.app/software/
- https://topologicpy.readthedocs.io
- https://github.com/wassimj/topologicpy