IFC Viewer Project – Detailed Documentation

Table of Contents

1. Introduction
2. Key Features
   1. IFC Model Workflow
   2. 3-D Viewport
   3. Sidebar Panels
   4. 🗺️ Minimap
   5. Measurement Suite
   6. Clipping Plane Tools
   7. Camera Management
   8. Performance HUD
   9. Robust Error-Handling Layer
3. Technology Stack
4. Project Structure
5. Getting Started
   1. Prerequisites
   2. Installation
   3. Available Scripts
   4. Development Playground
   5. Building for Production
6. Deployment Guide
7. Contributing
8. Roadmap & Known Limitations
9. License
10. Acknowledgements

Introduction

This repository contains a modern, fully-typed React + TypeScript web application that allows you to load, inspect, and interact with Building Information Model (IFC) files directly in the browser. It leverages the That Open Company ecosystem (OBC/Fragments/UI) on top of Three.js to deliver a desktop-grade BIM viewer experience with zero native installations.

What makes this fork special? – It adds an opinionated, production-ready architecture, advanced tooling (minimap, clipping, measurements, mobile UX), and a comprehensive error-handling layer while keeping the codebase framework-agnostic and vendor-neutral.

Key Features

IFC Model Workflow

• Drag-and-Drop / File Dialog Loader – Import one or multiple IFC files via the Load IFC button (powered by @thatopen/ui-obc helpers).
• Model Tree (Relations Tree) – Visualise the spatial structure of your model (Sites ⮕ Buildings ⮕ Storeys ⮕ Components). Includes fuzzy search and incremental loading.
• Visibility Controls – Toggle entire floors or IFC entity categories (IfcWall, IfcDoor, …) through auto-generated checkboxes.
• Element Properties – Select any fragment to inspect its raw IFC attributes in a responsive table that supports live search, expand/collapse, TSV export, and copy-to-clipboard.

3-D Viewport

• High-performance WebGL renderer (Three.js r175) with PBR materials and IFC fragment optimisation.
• Multiple Navigation Modes
  • Orbit – classic track-ball controls (default).
  • First-Person – walk-through with WASD & mouse-look.
  • Plan – orthographic, top-down navigation ideal for floor exploration.
• Camera Projections – instant switch between Perspective and Orthographic (with constraint logic to avoid invalid mode combinations).
• Zoom to Selection toggle – automatically frame the last selected element(s).
• Fit to Model action – centres the whole model in view, independent of its original world-coordinates.

Sidebar Panels

• Modular BUI‐driven layout – every tool lives inside its own panel section that can be collapsed, extended, or even replaced at runtime.
• Live-updating Classifier – on model load, entity groups are cached to speed up toggling.
• Element Properties, Minimap Settings, Clipping Tool, Camera Settings, Measurement Suite – see dedicated sections below.

🗺️ Minimap

• Real-time overhead view rendered by OBC.MiniMaps.
• Configurable: enabled, visible, lockRotation, zoom, frontOffset, sizeX, sizeY.
• Desktop Controls – tweak settings via the Minimap section in the sidebar.
• Mobile UX – a floating ⚙️ settings button reveals a touch-friendly panel; click-away listener auto-hides it.
• Dynamic Resize – settings propagate instantly without re-initialising the canvas.

Measurement Suite

• ✅ Volume Measurement (implemented)
  • Click an element ➜ surface area is analysed ➜ total volume displayed and stored.
  • Batch clear & enable/disable toggle.
• ⏳ Upcoming: Face, Edge, Angle, Area & Length measurements (place-holders scaffolded for future work). All share a common design language and event bus.

Clipping Plane Tools

• Axis-aligned plane (X, Y, Z) generated on demand.
• Adjustable via slider and Three.js TransformControls gizmo.
• Renderer-level clipping ensures correct draw order and supports transparent materials.
• Smart clean-up logic: removes helper, plane, and disposes controls when disabled or component un-mounted.

Camera Management

• Self-contained Camera Section exposes navigation mode, projection, user-input lock and fit-to-model.
• Guards against invalid combinations (e.g. First-Person × Orthographic) with user feedback.
• State synchronised through BIMContext; external tools can subscribe to zoomToSelection flag.

Performance HUD

• Stats.js overlay (memory, FPS, milliseconds) – toggle on/off and switch panels from the footer toolbar.
• Connected to the internal render-loop via world.renderer.onBeforeUpdate/onAfterUpdate hooks; zero overhead when disabled.

Robust Error-Handling Layer

• Centralised ErrorHandler with typed categories (BIM_INITIALIZATION, MODEL_LOADING, …).
• Provides handleBIMError, withErrorHandling helpers for async flows.
• Outputs granular console warnings/errors only in non-critical situations, preserving UX.

Technology Stack

• React 18 + TypeScript 5
• Vite 6 – lightning-fast bundling & HMR
• Three.js r175 – underlying WebGL engine
• @thatopen/components 2.4 – BIM logic & world management
• @thatopen/components-front 2.4 – front-facing helpers (highlighter, relations tree, …)
• @thatopen/fragments 3.0 – IFC fragment data model
• @thatopen/ui 2.4 – lightweight Web Components for design-system-agnostic UIs
• @thatopen/ui-obc 2.4 – high-level UI widgets for BIM (Ifc loader, relations tree, …)
• web-ifc 0.0.68 – WASM parser
• Stats.js 0.17 – performance widget

Project Structure

ifc-viewer-project/
├── index.html                # ⚛️ React entry-point (mounted at <div id="root" />)
├── package.json              # npm scripts & dependencies
├── tsconfig.json             # TypeScript compiler options
├── vite.config.ts            # Dev-server & build config
├── start-both.bat            # Windows batch script to run both servers
├── intro/                    # 🆕 Introduction page (runs on port 4000)
│   ├── index.html            # Introduction page HTML
│   ├── styles.css            # Introduction page styles
│   ├── package.json          # Intro page server config
│   ├── README.md             # Intro page documentation
│   └── QUICKSTART.md         # Quick start guide
└── src/
    ├── App.tsx               # Root component – wraps providers & error boundary
    ├── main.tsx              # ReactDOM.createRoot bootstrap
    ├── context/
    │   └── BIMContext.tsx    # Global state provider (world, components, UI flags)
    ├── hooks/
    │   └── useBIMInitialization.ts # One-shot initialiser with retries & deduping
    ├── components/
    │   ├── bim/              # Viewer-centric components
    │   │   ├── Viewport.tsx
    │   │   ├── Minimap.tsx
    │   │   └── MinimapMobileToggle.tsx
    │   ├── sidebar/          # Feature sections mounted inside <Sidebar />
    │   │   ├── ClippingSection.tsx
    │   │   ├── CameraSection.tsx
    │   │   ├── MeasurementSection.tsx
    │   │   └── VolumeMeasurement.tsx
    │   └── layout/           # High-level layout primitives
    │       ├── Layout.tsx
    │       ├── Sidebar.tsx
    │       ├── FooterToolbar.tsx
    │       └── ModelLoader.tsx
    ├── utils/
    │   └── errorHandler.ts   # Centralised error logic
    └── styles/               # Pure CSS modules scoped per component
        └── main.css

Each component is self-contained and ships with its own stylesheet to avoid global leakage.

Getting Started

Prerequisites

• Node.js ≥ 16 (18 recommended)
• npm (comes with Node) or Yarn (v1) / pnpm.

Installation

# Fork ⮕ Clone ⮕ Enter directory
$ git clone <your-fork-url>
$ cd ifc-viewer-project

# Install all dependencies
$ npm install   # or yarn / pnpm install

Available Scripts

| Command | Description | |-------------------|---------------------------------------------------------| | npm run dev | Start Vite dev-server with HMR on http://localhost:5173 | | npm run build | Type-check & produce a production-optimised build under dist/ | | npm run preview | Locally preview the build as it will run in prod | | npm run intro | Start the introduction page on http://localhost:4000 |

Note: TypeScript is run in --noEmit mode during npm run dev; a full tsc pass executes during build to guarantee type-safety.

Development Playground

1. Fire up the dev server:

   npm run dev

2. Open the browser ➜ load an IFC file via the Load IFC button.
3. Explore the tools in the sidebar, tweak minimap settings, enable clipping, etc.
4. Hot-module-reloading (HMR) will instantly update UI changes and preserve React state, including loaded models.

Introduction Page

A separate introduction page is available in the intro/ directory that provides:

• Welcome message and project overview
• Information about the team and key features
• Embedded IFC viewer for demonstration

To run the introduction page:

# Option 1: Using the convenience script (Windows)
start-both.bat

# Option 2: Manual start (run in separate terminals)
# Terminal 1 - Main viewer
npm run dev

# Terminal 2 - Introduction page
npm run intro

The introduction page will be available at http://localhost:4000 and will embed the main viewer running on port 3000.

For more details, see intro/README.md.

Building for Production

npm run build      # Generates static assets under ./dist
npm run preview    # Serves ./dist locally for smoke testing

The output is a fully static site (HTML + JS + WASM) which can be hosted on GitHub Pages, Netlify, Vercel, S3, or any static file server.

Deployment Guide

A generic deployment pipeline is described in DEPLOYMENT.md. In short:

1. Ensure WEBIFC_PATH environment variable (or importScripts) points to the WASM bundle when serving from a sub-folder.
2. Upload the content of dist/ to your hosting provider.
3. For single-page-apps behind a static server, enable fallback to index.html.

CI/CD Pipeline

This project includes a GitLab CI/CD pipeline with automated quality checks, building, and deployment to GitLab Pages.

📚 Complete CI/CD Documentation

➡️ .gitlab/README.md - Start here for all CI/CD documentation

Pipeline Features:

• ✅ Automated code quality checks (linting, formatting)
• ✅ Smart caching for faster builds (5-10x speedup)
• ✅ Conditional builds (skip when unnecessary)
• ✅ TypeDoc documentation generation
• ✅ GitLab Pages deployment
• ✅ Multi-branch support (main, development, production)

Quick Start:

# Run quality checks locally
npm run lint
npm run format:check

# Build for production
npm run build

Pipeline Configuration: .gitlab-ci.yml

For detailed guides, troubleshooting, and best practices, see the CI/CD Documentation.

Contributing

We :heart: contributions! Feel free to open issues or PRs for bugs, improvements, or new features.

1. Fork ➜ Clone ➜ create a feature branch.
2. Run npm run dev and reproduce your changes.
3. Ensure npm run build succeeds and that lint/formatting rules are respected.
4. Open a pull-request with a clear title, description, and screenshots/GIF when applicable.

Tip: the project uses semantic-release & conventional commits behind the scenes (CI pipeline). Follow the pattern feat:, fix:, chore: for commit messages to trigger correct changelog entries.

Roadmap & Known Limitations

• [ ] Implement remaining measurement tools (Face, Edge, Angle, Area, Length).
• [ ] Optimise fragment renderer for extremely large (>5 M triangles) models.
• [ ] Add section-box tool and multi-plane clipping.
• [ ] Migrate UI to Lit v3 once stable.
• [ ] Unit/E2E tests with Playwright covering mobile interactions.

License

Licensed under the MIT License – see LICENSE for full text.

Acknowledgements

• That Open Company for OSS tooling & inspiration.
• Three.js community for the underlying rendering engine.
• Everyone who reports bugs, suggests improvements, or contributes code ♥️.