debim 0.2.0

A minimal, Git-native, declarative BIM engine (Building-as-Code) designed for AI agents and humans.

---

💻 Modern CLI, QTO & Costing Engine

🌐 Zero-Install 3D Web Viewer (Try Live Demo)

_{🏛️ Showcase: Ludwig Mies van der Rohe's iconic Farnsworth House (1951) — compiled from declarative YAML (examples/farnsworth_house/project.yaml) into standard IFC4 and rendered in real-time in a lightweight 3D web viewer.}

---

🎯 Why debim? (จุดกำเนิดและปรัชญาของ debim)

"หัวใจของ debim เริ่มจากการอยากให้ AI ทำ BOQ แต่การให้ AI คำนวณตึกทั้งหลังตรงๆ AI ตายแน่ จึงต้องใช้แบบจำลองคณิตศาสตร์ (BIM) ทว่ามาตรฐาน IFC ดั้งเดิมก็ซับซ้อนเกินไป หนักสมอง AI อีก จึงกลั่นออกมาเป็น Declarative YAML — แต่ผลพลอยได้ที่ได้รับกลับยิ่งใหญ่กว่าเป้าหมายแรกเริ่ม"

Traditional BIM tools (like Revit or Archicad) were built over 25 years ago for humans clicking with computer mice. They lock architectural data in heavy, proprietary gigabyte files (.rvt), charge thousands of dollars in annual licenses, and remain completely opaque to modern automation and AI agents.

debim ยึดมั่นใน 5 เสาหลักแห่งการออกแบบ (Core Tenets):

1. Building-as-Code & Git-Native: อาคารคือซอฟต์แวร์ แสดงออกเป็นข้อความ YAML ขนาดกะทัดรัด (Kilobytes ไม่ใช่ Gigabytes) เพื่อให้ทำ Version Control, Git diff, และ Branching ตรวจสอบการแก้ไขได้ทีละบรรทัด
2. Deterministic Code Compliance: กฎหมายอาคารและข้อกำหนดวิศวกรรมถูกแปลงเป็น Unit Test (pytest) รันตรวจจับข้อผิดพลาดและระยะร่นใน 0.01 วินาทีก่อนลงมือก่อสร้างจริง
3. Zero-License & Zero-Friction Visualization: ตรวจสอบความถูกต้องทางเรขาคณิตได้ทันทีผ่าน 3D HTML Viewer น้ำหนักเบา เปิดบนเบราว์เซอร์หรือมือถือได้ทันที ไม่ต้องมีไลเซนส์ซอฟต์แวร์ราคาแพง
4. Universal Bridge & Dual Representation: ตัวกลางเชื่อมโยง 2D, 3D (SketchUp/Blender), และ IFC โดยผสมผสาน 90% Primitives สำหรับคำนวณโครงสร้างและ BOQ + 10% Baked GLB Asset สำหรับงานสถาปัตย์ประณีต
5. Human & AI Super-Collaboration: ออกแบบให้มี Explicit Uncertainty (review_status: needs_review) ให้มนุษย์และ AI ร่วมมือกันตรวจและเติมเต็มสเปกได้อย่างไร้รอยต่อ

---

🤖 AI-Agent Installation (ติดตั้งง่ายที่สุดในโลกด้วย AI ของคุณ)

If you use an AI coding assistant (like Antigravity, Cursor, Claude Code, Jules, or ChatGPT/Copilot), you don't even need to install it manually!

Just copy and send this prompt to your AI:

"Please read https://github.com/PRIDA-TAKON/debim and AGENTS.md, install debim in my environment, and run debim --help to verify."

Your agent will inspect the repository, install the dependencies, and verify everything automatically.

---

🚀 Manual Quickstart

1. Installation

# Clone the repository
git clone https://github.com/PRIDA-TAKON/debim.git
cd debim

# Install in editable mode
pip install -e .

# Or with full dev & IFC compiler tools
pip install -e ".[ifc,dev]"

2. Basic Commands

# Initialize a new project
debim init my-project

# Validate schema syntax & grid references
debim validate -m examples/farnsworth_house/project.yaml

# Run automated building code compliance checks (pytest)
debim test

# Calculate Quantitative Take-Off (Steel weight, stone volume, glass area)
debim qto -m examples/farnsworth_house/project.yaml

# Generate project-scoped price template with international classifications
debim cost template -m examples/farnsworth_house/project.yaml -o prices.template.yaml

# Estimate project budget & export BOQ to CSV
debim cost -m examples/farnsworth_house/project.yaml -p examples/farnsworth_house/prices.yaml -o dist/boq.csv

# Scaffold a new BIM element class boilerplate
debim scaffold element IfcRailing

# Preview 3D model in your browser (Three.js with Hierarchical Layer Explorer)
debim view -m examples/farnsworth_house/project.yaml

# Compile declarative YAML to standard IFC4 building model
debim compile -m examples/farnsworth_house/project.yaml -o dist/farnsworth_house.ifc

---

🏗️ Example project.yaml

schema: IFC4-Minimal
project:
  id: PRJ-2026-001
  name: "Townhouse-Feasibility"
  units: { length: METER, area: SQUARE_METER, volume: CUBIC_METER }

# 1. Spatial Structure
spatial_structure:
  storeys:
    - id: L1
      name: "Level 1"
      elevation: 0.00
      height: 3.50
    - id: L2
      name: "Level 2"
      elevation: 3.50
      height: 3.20

# 2. Reference Grid Axes
grids:
  axes_x: { A: 0.00, B: 4.00, C: 8.00 }
  axes_y: { 1: 0.00, 2: 5.00, 3: 10.00 }

# 3. Materials
materials:
  - id: CONC_240
    name: "Concrete 240 ksc"
    category: concrete
    unit_cost_ref: "MAT-CONC-01"
  - id: AAC_75
    name: "AAC Block 7.5cm"
    category: masonry
    unit_cost_ref: "MAT-AAC-01"

# 4. Elements
elements:
  # Column placed at grid intersection [A, 1]
  - class: IfcColumn
    tag: C-A1
    material: CONC_240
    profile: { shape: BOX, width: 0.20, depth: 0.20 }
    placement:
      grid: [A, 1]
      base_storey: L1
      top_storey: L2
    reinforcement:
      main: "4-DB16"
      stirrups: "RB6 @ 0.15m"

  # Beam spanning between [A, 1] and [B, 1]
  - class: IfcBeam
    tag: B-A1_B1
    material: CONC_240
    profile: { shape: BOX, width: 0.20, depth: 0.40 }
    placement:
      from_grid: [A, 1]
      to_grid: [B, 1]
      storey: L2
    reinforcement:
      main_top: "2-DB16"
      main_bottom: "3-DB20"
      stirrups: "RB9 @ 0.15m"

  # Wall with door host-child relationship
  - class: IfcWall
    tag: W-A1_A2
    material: AAC_75
    thickness: 0.075
    height: 3.10
    placement:
      from_grid: [A, 1]
      to_grid: [A, 2]
      storey: L1
    children:
      - class: IfcDoor
        tag: D1
        dimensions: { width: 0.90, height: 2.00 }
        offset_distance: 1.20

---

🔬 Empirical Research & Benchmark (การทดสอบระดับอุตสาหกรรม)

debim ให้ความสำคัญกับความถูกต้องทางวิศวกรรมและการทดสอบแบบเปิดเผย ตรวจสอบซ้ำได้จริง (100% Reproducible Open Science) บน Kaggle Cloud Multi-Core Benchmark Suite:

1. ⚖️ 3D Visual Regression & Alignment Benchmark (255 อาคารจริงสากล)

การทดสอบความแม่นยำด้านเรขาคณิต 3 มิติ (3D Visual Fidelity) แบบปิดตาเทียบกับ IFC ต้นฉบับผ่าน Geometry Variant Deduplication + Balanced Macro-Averaging บน 4,695 ชิ้นส่วนตัวแทน:

• 🎯 85.50% Median Visual Fidelity: ทะลุเกณฑ์มาตรฐานสากล ($\ge 85%$) ครอบคลุมเกินกึ่งหนึ่งของโมเดลทดสอบ
• 🏗️ 89.07% Structural Match: งานโครงสร้างรับแรงหลัก (เสา คาน ผนัง ฐานราก) มีความเสถียรระดับเกรด A+
• ⚡ 82.64% MEP System Match: งานระบบท่อ ระบบปรับอากาศ และอุปกรณ์ไฟฟ้าอยู่ในตำแหน่งและระนาบที่ถูกต้อง

📈 วิวัฒนาการเปรียบเทียบข้าม 3 เจเนอเรชัน (Progression Across Waves):

ตัวชี้วัดสากล (Global Metric)	V1 (Baseline)	V2 (Wave 1-2)	V3 (Wave 4 ล่าสุด)	$\Delta$ พัฒนาขึ้นสะสม
🎯 Median Visual Match (ค่ามัธยฐาน)	80.90%	84.90%	85.50%	🏆 +4.60% (ทะลุเป้า 85%)
⚖️ Macro Average Visual Match	70.57%	77.60%	77.71%	🟢 +7.13%
📊 Micro Average Visual Match	72.24%	80.35%	80.46%	🟢 +8.23%
ชิ้นส่วนที่ผ่านเกณฑ์ ($\ge 85%$)	2,865 ชิ้น	3,140 ชิ้น	3,135 ชิ้น	🟢 +270 ชิ้น
หมวดหมู่งานระบบและตกแต่งที่ก้าวกระโดด
• ฝ้าเพดาน (IfcCovering)	11.4%	89.0%	89.0%	🟢 +77.6% (ผ่านเกณฑ์)
• วาล์วระบบท่อ (IfcValve)	0.0%	82.2%	82.4%	🟢 +82.4% (พุ่งจากศูนย์)
• แผ่นเหล็กโครงสร้าง (IfcPlate)	10.2%	88.9%	87.1%	🟢 +76.9% (ผ่านเกณฑ์)
• เหล็กค้ำยันเฉียง (IfcMember)	91.8%	91.6%	92.4%	🟢 +0.8% (3D Vector Pitch)

👉 ต้องการตรวจสอบการทดลองเชิงลึกหรือรันซ้ำด้วยตนเอง? ดูโค้ดและดาต้าเซ็ตได้ที่ Kaggle Benchmark Notebook

---

2. 📦 Roundtrip Retention & Storage Reduction Study (407 อาคารสากล)

debim ได้รับการทดสอบอย่างเข้มงวดกับโมเดลอาคารจริงกว่า 407 โครงการ (สถาปัตยกรรม โครงสร้าง และ MEP โรงพยาบาล):

• 100.0% Median Retention Rate: โมเดลส่วนใหญ่สามารถสกัดและ Re-compile กลับสู่มาตรฐาน IFC4 ได้ครบถ้วนทุกชิ้นงาน
• 91.6% Average Storage Reduction: ลดขนาดไฟล์จาก IFC ดิบลงเฉลี่ย 91%
• 558M+ LLM Tokens Saved: ประหยัดบริบทของโมเดลภาษาไปได้มากกว่า 558,629,804 โทเคน
• 100.0% Modern Schema Crash-Resilience: ไม่พบ Fatal Crash หรือ Unhandled Exception บนมาตรฐาน IFC2X3 และ IFC4

📖 อ่านรายงานวิจัยฉบับเต็ม: debim: An Empirical Study of Declarative Building-as-Code on 407 Heterogeneous Real-World OpenBIM Models
📦 Kaggle Public Benchmark Dataset: debim-5000-ifc-benchmark
⚡ Kaggle Automated Stress Test: debim-ifc-stress-test

---

❓ Frequently Asked Questions (FAQ)

Why YAML instead of JSON, Python, or Excel?

YAML is clean, concise, supports nested hierarchies, and allows comments (essential for architectural notes). Unlike JSON, it has no noisy braces. Unlike Excel, it is 100% Git-friendly, diffable, and conflict-resolvable. It serves as a pure declarative DSL (Domain-Specific Language)—just like Kubernetes, Docker Compose, and GitHub Actions.

How do I place off-grid items (internal partitions, cantilever beams)?

Use relative offsets: `placement: { grid: [A, 1], offset: [1.20, 0.50] }`. Just like pulling a tape measure on site from the nearest grid line.

Does this replace Revit or AutoCAD?

No, it complements them. debim handles the early-stage upstream workload: rapid feasibility, parametric sizing, AI generation, instant QTO/costing, and automated building law validation. Once validated, run debim compile to export standard IFC4 and load it directly into BlenderBIM, FreeCAD, or Revit for 2D drafting and detail annotations.

---

📄 License & Attribution

• Software Code: Licensed under the MIT License — Copyright (c) 2026 Prida Takon.
• Research & Technical Reports: Licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
• Benchmark Datasets & Sample Models: Test fixtures in tests/fixtures/ originate from buildingSMART International and the Open IFC Model Repository under CC BY 4.0 / CC-BY-3.0.