BIMSurfer Documentation

BIMSurfer v3 is a high-performance, WebGL-based IFC model viewer designed for BIMServer. This version has been completely rebuilt from scratch and focuses on performance through the introduction of 3D Tiles support.

Critical Requirement: BIMSurfer v3 requires WebGL 2.0 support in the browser. Note that WebGL 2.0 support is not universal (approximately 54% browser support according to WebGLStats).

Depending on your project requirements, you should choose between the following versions:

• v3 (Recommended for performance): Best for high performance and features like 3D Tiles support, measurements, and up to 6 section planes. Requires WebGL 2.0.
• v2 (Recommended for open standards/static files): Built around open standards like glTF (using ThreeJS, xeogl, and SVG). Use this if you need to view static files generated by IfcOpenShell.
• v1 (Not recommended): Uses XeoEngine and BIMServer. Avoid using this for new projects due to outdated library dependencies and an unstable API.

The Interactive application follows a specific lifecycle for exploring BIM models:

1. Connect Server: Establish a connection to a BIMserver via connectServer().
2. Login: Authenticate using login() with credentials provided to the BimServerClient API.
3. Select Project: Use showSelectProject() to load and display the project hierarchy via a TreeView and ProjectTreeModel.
4. Select Revision: Once a project is selected, showSelectRevision(project) fetches all available revisions for that project using the ServiceInterface.
5. View Model: Use showViewer(revision) to initialize a BimServerViewer on a canvas element and load the specific model revision.

The BIMsurfer entry point supports an automated way to set the authentication token via URL parameters. If a token parameter is present in the URL, the application will automatically save it to localStorage under the key token and then reload the page to apply the authentication state.

Usage Example: If you want to pass a token to the application, append ?token=YOUR_TOKEN_HERE to the URL.

https://<your-bimsurfer-url>/?token=YOUR_TOKEN_HERE

The Interactive class serves as the entry point for a user-driven BIM model exploration application. To start the application, instantiate the class and call the start() method. This method initializes the UI, sets up server connection listeners, and manages the application's tabbed navigation flow.

Note: The Interactive class relies on specific DOM elements (e.g., #login, #address, #tabs, #glcanvas) being present in your HTML to function correctly.

import { Interactive } from './path/to/apps/interactive.js';

const app = new Interactive();
app.start();

The getCredentials() method is the primary entry point for ensuring a user is authenticated before proceeding with BIMSurfer tasks.

Behavior:

1. Stored Token: It checks localStorage for a key named "token". If found, it attempts to set the token on the bimServerApi. If successful, the Promise resolves immediately.
2. Token Validation Failure: If a token exists but is invalid, it removes the invalid token from localStorage, injects a login form into the document.body, and waits for the user to log in manually.
3. No Token: If no token is found, it injects the login form into the document.body and waits for manual login.

Manual Login: When a user enters credentials and clicks "Login" (or presses Enter), the login() method is called, which interacts with bimServerApi.login() and stores the resulting token in localStorage upon success.

The Credentials class provides a UI-based mechanism for handling BIMServer authentication. It manages a login form (username and password inputs) and handles token persistence using localStorage.

To use it, instantiate the class with a bimServerApi instance and call getCredentials(). This method returns a Promise that resolves when authentication is successful (either via a valid stored token or a successful manual login) and rejects if authentication fails.

// Assuming bimServerApi is an initialized instance of the BIMServer API
const credentials = new Credentials(bimServerApi);

credentials.getCredentials()
  .then(() => {
    console.log("Authenticated successfully");
    // Proceed with BIMSurfer operations
  })
  .catch((err) => {
    console.error("Authentication failed", err);
  });

To connect the application to a BIMserver, use the connectServer(server) method. This method initializes a new BimServerClient using the provided server address and calls .init() to establish the connection. Upon successful initialization, the application transitions to the login state.

Expected server object shape:

{
  address: string; // e.g., "http://localhost:8080"
  title?: string;
  description?: string;
  username?: string;
  password?: string;
}

// Example of connecting to a specific server address
app.connectServer({
  address: "http://localhost:8080"
});

The displayStaticBuffer function is a utility for rendering model annotations from a prepared static buffer. It initializes a BimServerViewer instance on a specified DOM element and loads annotations from the provided buffer URL.

Parameters:

• domNode (string): The id of the HTML element (typically a <canvas>) where the viewer should be rendered.
• bufferPath (string): The URL or path to the prepared buffer file.

Note: This function configures the BimServerViewer with quantizeVertices: false and uses the current window dimensions (window.innerWidth, window.innerHeight) for the viewport size.

import { displayStaticBuffer } from './path/to/apps/static.js';

// Assuming you have a <canvas id="my-canvas"></canvas> in your HTML
displayStaticBuffer('my-canvas', '/path/to/prepared_buffer.bin');

The Address class provides a utility to automatically determine the API endpoint for a BIMserver client.

If the application is being served directly from a BIMserver under the /apps/bimsurfer3/ path, getApiAddress() extracts the base URL of the server. If the application is not served from a BIMserver (e.g., running locally or from a different domain), it defaults to http://localhost:8082 and logs a warning to the console.

import { Address } from './apps/address.js';

const apiAddress = Address.getApiAddress();
console.log('Connecting to:', apiAddress);