354d6e8c14
Some checks failed
CI / backend-lint-and-test (push) Has been cancelled
- 8 pytest tests covering health, upload validation, API responses, schemas - Updated README with architecture diagram, feature list, design decisions - Live demo link and complete API reference
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# BIM Twin Viewer
|
|
|
|
Interactive IFC-based 3D building model viewer. Upload an IFC file to
|
|
inspect building elements, their properties, and navigate the model in
|
|
a browser-based 3D view.
|
|
|
|
**Live demo:** [bim.stifting.at](https://bim.stifting.at)
|
|
|
|
## Features
|
|
|
|
- Upload IFC files (IFC2x3, IFC4) via drag-and-drop or file picker
|
|
- Server-side conversion to glTF binary for efficient 3D rendering
|
|
- Interactive Three.js viewer with orbit, pan, and zoom controls
|
|
- Click any building element to inspect its IFC properties
|
|
- Filter elements by type (wall, door, window, slab, ...) and storey
|
|
- Double-click to set a new orbit pivot point
|
|
- Collapsible floating panels for unobstructed 3D viewing
|
|
- Full REST API with automatic OpenAPI documentation
|
|
|
|
## Tech stack
|
|
|
|
| Layer | Technology |
|
|
|----------------|------------------------------------------------|
|
|
| Backend | Python 3.12, FastAPI, SQLAlchemy (async) |
|
|
| IFC processing | IfcOpenShell (parsing + geometry serialization) |
|
|
| Frontend | Vue.js 3, Three.js, Vite |
|
|
| Database | PostgreSQL 16 |
|
|
| Infrastructure | Docker Compose, Caddy, Forgejo CI, Linux |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser Server
|
|
┌─────────────┐ HTTPS ┌──────────────────────────┐
|
|
│ Vue.js │◄───────────►│ Caddy (reverse proxy) │
|
|
│ Three.js │ └──────┬───────────────────┘
|
|
│ GLTFLoader │ │
|
|
└─────────────┘ ┌──────▼───────────────────┐
|
|
│ FastAPI │
|
|
│ ├─ /api/upload │
|
|
│ ├─ /api/projects │
|
|
│ ├─ /api/elements │
|
|
│ └─ /api/projects/*/model │
|
|
└──────┬───────────────────┘
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
▼ ▼ ▼
|
|
PostgreSQL IfcOpenShell glb files
|
|
(elements, (IFC parser + (3D models)
|
|
properties) geometry engine)
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env and set DB_PASSWORD
|
|
|
|
docker compose up -d
|
|
```
|
|
|
|
- **Frontend:** http://localhost:5173
|
|
- **API docs:** http://localhost:8000/docs
|
|
- **Health check:** http://localhost:8000/health
|
|
|
|
## API overview
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|---------------------------------------------------|----------------------------|
|
|
| GET | `/health` | Health check |
|
|
| POST | `/api/upload` | Upload and parse IFC file |
|
|
| GET | `/api/projects` | List all projects |
|
|
| GET | `/api/projects/{id}/elements` | List elements (filterable) |
|
|
| GET | `/api/projects/{id}/elements/by-global-id/{gid}` | Lookup element by GlobalId |
|
|
| GET | `/api/elements/{id}` | Element detail + properties|
|
|
| GET | `/api/projects/{id}/model.glb` | Download 3D model |
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
docker compose exec backend python -m pytest -v
|
|
```
|
|
|
|
## Project structure
|
|
|
|
```
|
|
.
|
|
├── backend/
|
|
│ ├── app/
|
|
│ │ ├── api/ # FastAPI route handlers
|
|
│ │ ├── models/ # SQLAlchemy ORM models
|
|
│ │ ├── schemas/ # Pydantic request/response schemas
|
|
│ │ └── services/ # IFC parsing and geometry conversion
|
|
│ ├── tests/ # pytest test suite
|
|
│ ├── Dockerfile
|
|
│ └── requirements.txt
|
|
├── frontend/
|
|
│ ├── src/
|
|
│ │ ├── components/ # Vue components
|
|
│ │ ├── composables/ # useApi, useViewer (Three.js)
|
|
│ │ └── App.vue # Main application
|
|
│ ├── Dockerfile
|
|
│ └── package.json
|
|
├── data/sample/ # Example IFC files
|
|
├── docker-compose.yml
|
|
└── README.md
|
|
```
|
|
|
|
## Design decisions
|
|
|
|
- **Server-side IFC→glb conversion** rather than client-side WASM processing.
|
|
IfcOpenShell's geometry engine produces optimized meshes with IFC GlobalIds
|
|
preserved as mesh names, enabling click-to-inspect without shipping heavy
|
|
WASM bundles to the browser.
|
|
|
|
- **Async SQLAlchemy** for non-blocking database access during concurrent
|
|
file uploads and API queries.
|
|
|
|
- **Floating UI panels** over a full-viewport 3D canvas for maximum spatial
|
|
awareness while inspecting element metadata.
|
|
|
|
## License
|
|
|
|
MIT
|
|
|