# 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