Metadata-Version: 2.4
Name: syntopic-aec
Version: 0.1.0
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Syntopic 🌐

[![Continuous Integration](https://github.com/moaminmo90/Syntopic/actions/workflows/CI.yml/badge.svg)](https://github.com/moaminmo90/Syntopic/actions/workflows/CI.yml)
[![PyPI version](https://img.shields.io/pypi/v/syntopic.svg)](https://pypi.org/project/syntopic/)
[![Rust Edition](https://img.shields.io/badge/rust-2021-blue.svg)](https://www.rust-lang.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An ultra-high-performance, parallel 3D spatial topology, non-manifold cell complex, and **Spatial GraphRAG** compiler for the Architecture, Engineering, and Construction (AEC) industry. Built in pure Rust and exposed natively to Python with Stable ABI.

---

## ⚡ The Syntopic Computational Value Proposition

Traditional topological modeling tools wrap heavyweight, single-threaded C++ kernels (like Open CASCADE or CGAL) in python layers, introducing heavy memory translation overheads and UI freezes in CAD systems.

**Syntopic** solves this bottleneck with:

- **Scaleless Spatial Pruning**: Uses bulk-loaded $O(\log N)$ **R\*-Trees** for parallel multi-mesh intersection sweeps.
- **Robust Input Sanitization**: Employs an $O(N)$ spatial hashing **Weld Filter** to automatically repair dirty vertices and duplicate collinear faces common in Rhino/BIM models.
- **BIM-to-GraphRAG Compiler**: Generates native Neo4j **Cypher queries** and Graph Neural Network (GML) structures directly within Rust's parallel execution memory, bypassing GIL locks.
- **Möller-Trumbore Ray Tracing**: Incorporates micro-perturbed 3D vertical ray tracers to accurately check 1D-3D elements (columns inside rooms) without diagonal boundary errors.

---

## 🏗 System Architecture & Topology Hierarchy

```text
       [Raw CAD / BIM IFC Stream]
                   │
                   ▼ (Weld & Clean Filter - O(N))
           [Sanitized Meshes]
                   │
                   ▼ (R*-Tree Broad Phase Spatial Index)
       ┌───────────┴───────────┐
       ▼                       ▼
 [3D Freeform Slicing]    [Exact 2D Boolean Intersection]
       │                       │
       │                       ▼ (Apertures/Windows subtracted)
       │                 [Adjacency Matrix]
       │                       │
       └───────────┬───────────┘
                   ▼ (Main Thread GIL Serialization)
           [Spatial Graph] ──► (Dijkstra Solver / Cypher Compiler)
```

### Topological Hierarchy Entity Mapping

```text
Cell (3D Volume/Room) ──► Shell (Boundary) ──► Face (2D Wall/Slab) ──► Wire (1D Column) ──► Vertex (3D Point)
```

---

## 🚀 Installation & Build

### 1. Simple Installation (via PyPI)

For standard use inside Python 3.9+ environments (including Rhino 8 & 9):

```bash
pip install syntopic-aec
```

### 2. Compile From Source (For Developers)

To compile the raw Rust code for maximum local optimization:

```bash
# Clone the repository
git clone https://github.com/moaminmo90/Syntopic.git
cd Syntopic

# Setup a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install maturín build system and compile in release mode
pip install maturin
maturin develop --release
```

---

## ⚡ Quick Start: Freeform Spatial Graph & Neo4j Ingest

Create a file `run.py` and execute the following complete GraphRAG compilation:

```python
import syntopic

# 1. Define closed room geometries
room_cube_verts = [
    syntopic.Vector3D(0, 0, 0), syntopic.Vector3D(4, 0, 0),
    syntopic.Vector3D(4, 4, 0), syntopic.Vector3D(0, 4, 0),
    syntopic.Vector3D(0, 0, 2), syntopic.Vector3D(4, 0, 2),
    syntopic.Vector3D(4, 4, 2), syntopic.Vector3D(0, 4, 2)
]
room_cube_faces = [[3, 2, 1, 0], [4, 5, 6, 7], [0, 1, 5, 4], [1, 2, 6, 5], [2, 3, 7, 6], [3, 0, 4, 7]]
cube_room = syntopic.Mesh(room_cube_verts, room_cube_faces)

room_pyramid_verts = [
    syntopic.Vector3D(1, 1, 2), syntopic.Vector3D(3, 1, 2),
    syntopic.Vector3D(3, 3, 2), syntopic.Vector3D(1, 3, 2),
    syntopic.Vector3D(2, 2, 4)
]
room_pyramid_faces = [[3, 2, 1, 0], [0, 1, 4], [1, 2, 4], [2, 3, 4], [3, 0, 4]]
pyramid_room = syntopic.Mesh(room_pyramid_verts, room_pyramid_faces)

# 2. Build spatial registry and compile Adjacency Dual-Graph
registry = syntopic.SpatialRegistry([cube_room, pyramid_room], [], [])
graph = registry.build_spatial_graph(0.001)

# 3. Attach Semantic BIM properties inside Rust memory
graph.nodes[0].set_attribute("zone_name", "Main_Hall_Floor")
graph.nodes[1].set_attribute("zone_name", "Glass_Dome_Ceiling")

# 4. Compile database-ready Cypher queries for Neo4j / GraphRAG ingestion
cypher_payload = graph.to_cypher_queries()
for query in cypher_payload:
    print(query)
```

---

## 🔌 AEC Ecosystem Integrations

### 1. Rhino 8 / 9 & Grasshopper Component

Inside the new Python 3 (CPython) script component in Grasshopper, append the library path and execute:

```python
import sys
import Rhino.Geometry as rg

# Append virtual environment directory where syntopic is installed
sys.path.append(r"D:\programming\grasshopper\Syntopic\.venv\Lib\site-packages")
import syntopic

# Convert native Rhino meshes to Syntopic Rust Mesh
verts = [syntopic.Vector3D(v.X, v.Y, v.Z) for v in RhinoMesh.Vertices]
faces = [[f.A, f.B, f.C, f.D] if f.IsQuad else [f.A, f.B, f.C] for f in RhinoMesh.Faces]
rust_mesh = syntopic.Mesh(verts, faces).clean(0.001)

print("Syntopic successfully parsed Rhino Common geometry!")
```

### 2. ETH Zürich COMPAS Framework Integration

Directly convert COMPAS mesh objects to high-precision Syntopic structures utilizing our bridge connector:

```python
import compas.geometry
from syntopic.compas_bridge import from_compas_mesh

# Create standard COMPAS mesh
compas_mesh = compas.geometry.Mesh.from_polyhedron(4)

# Translate to native Rust topology mesh
syntopic_mesh = from_compas_mesh(compas_mesh)
print(f"Bridges: Extracted {len(syntopic_mesh.vertices)} vertices from COMPAS Mesh!")
```

---

## 👨‍💻 Author

Developed with passion by **Moamin**

[![GitHub](https://img.shields.io/badge/GitHub-moaminmo90-181717?logo=github)](https://github.com/moaminmo90)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-moaminmo90-0A66C2?logo=linkedin)](https://www.linkedin.com/in/moaminmo90)

---

## ⚖️ License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
