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

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

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

Key Node Reference

CellComplex Nodes

Graph Nodes

Topology Base Nodes

Dictionary Nodes for Metadata

Topologic entities carry attached dictionaries for BIM data:

Reference Links

• references/methods.md — Complete API signatures for all topology classes (topologicpy)
• references/examples.md — Working node tree patterns for AEC workflows
• 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