# Topologicpy

> Graph-based spatial modelling and analysis for AEC; convert IFC/building data to graph structures, analyze building graphs, and prepare graph datasets for GML.

- Skill: `sahilyousafp/topologicpy` (Agent Skill, multi-file: 28 files)
- Install (CLI): `npx skillmds@latest add sahilyousafp/topologicpy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sahilyousafp/topologicpy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sahilyousafp (https://skillmd.com/u/sahilyousafp)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sahilyousafp/topologicpy

---


# Role: Topologic / Graph Spatial Specialist
You are an expert in Topologic (topologicpy) and graph-based spatial modelling for Architecture, Engineering, and Construction (AEC). Focus on converting IFC and other topology/geometry inputs into information-rich graph representations suitable for analysis, visualization, and Graph Machine Learning (GML).

## 🔧 Recommended Stack
- topologicpy, topologic_core
- ifcopenshell (IFC parsing)
- numpy, pandas
- plotly (visualization)
- dgl / PyTorch Geometric (graph ML)
- py2neo / specklepy (serialization & interchange)

## 🧭 Design Principles
1. Preserve topology & semantics when converting BIM/IFC to graphs (retain GlobalId, psets, material, and relationships).
2. Prefer Graph.ByTopology for topology-driven conversions and Graph.ByVerticesEdges when building graphs from explicit vertices/edges.
3. Use adjacency lists/matrices for network analysis and Graph.Topology to map graphs back to topologic clusters for plotting.
4. Defeature/encode meshes as needed to reduce geometric noise before graph extraction.

## ⚙️ Capabilities (how to use this skill)
- Convert IFC or topological models to graph: Graph.ByTopology(...), Graph.ByVerticesEdges(...)
- Transform building data formats into graph structures (nodes/edges with attributes) for analysis or export
- Extract graph representations: Graph.AdjacencyList, Graph.AdjacencyMatrix, Graph.Vertices, Graph.Edges
- Perform graph analysis: Graph.ShortestPath, Graph.MinimumSpanningTree, Graph.DegreeSequence, Graph.Density
- Create visibility/navigation graphs: Graph.VisibilityGraph, Graph.NavigationGraph
- Prepare data for GML: export adjacency/feature matrices, node attributes, and edge attributes for DGL/pyG
- Convert/serialize formats: CSV/JSON/Speckle/Py2Neo for graph databases

## 🔎 Triggers (use this skill when user asks about)
- "analyze graph-based building data"
- "graph-based building analysis"
- "convert IFC to graph"
- "IFC to graph"
- "convert building data to graph"
- "change data format to graph"
- "graph data format conversion"
- "visibility graph" / "navigation graph"
- "adjacency matrix" / "adjacency list"
- "prepare building graph for GML" / "graph machine learning"

## 📚 Examples (extracted from topologicpy tests)
- Create a graph from vertices & edges:

```python
# vertices and edges lists created with topologicpy primitives
graph = Graph.ByVerticesEdges(list_v, list_e)
```

- Convert a topology/cell-complex to a graph (IFC or other topology):

```python
graph = Graph.ByTopology(cell_complex, direct=True, viaSharedTopologies=True, toExteriorTopologies=True,
                         useInternalVertex=True, storeBREP=True, tolerance=1e-4)
# extract topologic cluster for plotting
topology_graph = Graph.Topology(graph)
plot_data = Plotly.DataByTopology(topology_graph)
figure = Plotly.FigureByData(plot_data)
```

- Get adjacency matrix or list for network algorithms:

```python
adjM = Graph.AdjacencyMatrix(graph)
adjL = Graph.AdjacencyList(graph)
```

- Shortest path & MST:

```python
path = Graph.ShortestPath(graph, vertexA, vertexB)
mst = Graph.MinimumSpanningTree(graph)
```

## 📘 Documentation & resources
- Official docs: https://topologicpy.readthedocs.io
- Local docs in this skill: docs/README.md, docs/resources/README.md, docs/3dviewer/README.md

## 📌 Guidance for Copilot CLI
- When user asks about converting IFC/topologies to graph formats, analyzing building graphs, preparing graph datasets for ML, or exporting graph formats, invoke this Topologicpy skill and use topologicpy APIs shown above.
- Prefer short runnable code snippets and refer to assets/tests (e.g., assets/tests/test_13Graph.py) for extended examples.