bim+ renderer

bim+ renderer is a javascript renderer core based on three js.

Quick Links

https://nemetschekprime.atlassian.net/wiki/spaces/bimpluspublic/pages/1090127443/Bimplus+Renderer+Reference

How to build

Install nodejs

http://www.nodejs.org/

Install local npm modules

Open up a normal command line (admin is not needed) and go to the renderer folder

npm install

(whenever package.json has changed, you might to do this again)

Install emscripten SDK

https://emscripten.org/ Install the emscripten toolchain to cross compile the performance critical parts written in c/c++ to web assembly

Build renderer

Library building process is using UMD (Universal Module Definition) output format so it's compatible with both cjs and amd module formats. The same library can be use in the client or on the server. Build process is using babel so it's possible to use new ES2015 code in source codes.

Library can be build in several ways as a dev or prod version. To run a dev build with source maps run:

npm run build

To build a prod version - uglified, minified run:

npm run build-prod

Pulish new release to npm (Hint: Before doing this npm login needs to be done and the package version adjusted) :

npm run npm-publish

Check content of npm package (result is bimplus-renderer@(version).tar.gz)

npm run npm-pack

Develop/Debug renderer

goto your renderer folder

npm link

goto your application folder which uses the renderer

npm link bimplus-renderer

Do you changes in the renderer and build

npm run build

or

grunt run build-prod

Your app will automatically get the changes done in the renderer

After developing it might be wise to unlink: goto your renderer folder

npm unlink

goto your application folder which uses the renderer

npm unlink bimplus-renderer npm install

Unit testing

Run tests from the renderer root. Vitest is the only installed test runner; the test files import Vitest APIs directly. Browser globals, fixtures, and test-only dependencies are initialized in test/setup/vitestBrowser.setup.js.

npm ci
npx playwright install firefox
npm test
npm run test-chrome-headed
npm run test-firefox-coverage

npm test runs the renderer and performance suites in headless Firefox and starts the Polly recording service. Every run generates Istanbul coverage at coverage/lcov.info and coverage/index.html for CI/CD and SonarQube. Jenkins must use Firefox with WebGL2; Chrome has memory/WebGL problems on that server. npm run test-chrome uses installed Google Chrome locally. npm run test-chrome and npm run test-firefox explicitly show the browser window. Both profiles run serially. The explicit modes are:

| Mode | Firefox | Chrome | | --- | --- | --- | | Headed | npm run test-firefox-headed | npm run test-chrome-headed | | Headless | npm run test-firefox-headless | npm run test-chrome-headless | | Watch (headed) | npm run test-firefox-watch | npm run test-chrome-watch | | Coverage (headless) | npm run test-firefox-coverage | npm run test-chrome-coverage |

npm test invokes test-firefox-coverage. These commands set the display mode explicitly, independently of BIMPLUS_HEADLESS.

To run just one test file with Polly, use the browser's task, for example:

npx npm-run-all -p -r test-polly-listen-task "test-chrome-task -- --browser.headless=false test/tests/OverlayPollyTests.js"

The Vitest compatibility middleware serves /data/ from test/data/ and provides the installed web-ifc WASM with the correct MIME type, preserving the asset routes previously supplied by Karma proxies.

Polly replays the checked-in HAR recordings. Older authorization entries have sanitized passwords but retain request IDs calculated before sanitization. The test helper handles these entries by matching the complete sanitized request and request order, without rewriting the recordings. Some legacy recordings also omit GLB requests because earlier Karma tests had populated IndexedDB. On a geometry replay miss, the helper reuses a recorded GET response for the same URL (including model, discipline, revision and all query parameters) and request fields from another HAR, ignoring only the authorization token. This allows isolated and filtered runs without depending on prior tests' caches. Locally, Polly enables recordIfMissing, so unmatched requests can fall through to the live API and be recorded. In CI, recording is disabled and missing recordings fail instead of falling back to the live API. A local login 401 followed by Cannot persist response can therefore indicate a missing or unmatched recording rather than an expired recorded token.

Modelviewer DDT runs are separate and require the sibling simple-ddt-server, the selected dataset, and stored reference results:

npm run test-modelviewer-ddt
npm run test-modelviewer-ddt-long
npm run test-vitest-modelviewer-chrome
npm run test-vitest-modelviewer-chrome-long

Vitest writes JUnit output under test-results/. Firefox Istanbul coverage is written under coverage/, including coverage/lcov.info for CI artifact collection. Coverage instruments renderer source under src/, excluding vendored and generated worker files. Two IFC references differ when tested against installed web-ifc 0.0.77, while the existing references were generated with copied 0.0.75 WASM; the DDT does not update reference data automatically. See the migration plan for remaining gates.

Documentation

Bimplus Renderer documentation is generated with the local JSDoc dependency and the repository-owned API Markdown renderer. Install the project dependencies with npm install before running the documentation scripts.

JSDoc source discovery and HTML output are configured in jsdoc.json; scripts/generate-api-markdown.js renders the API doclets and checks Markdown anchors. Regenerate the documentation after changing source JSDoc comments. Raw Markdown uses API anchors, while the Confluence output adds matching RendererApidescription- aliases.

To create documentation in html format go to your renderer folder and run :

npm run build-doc

Documentation output will be in renderer/documentation folder

To create documentation in markdown format go to your renderer folder and run :

npm run build-docMd

Documentation output will be in renderer/documentation/Bimplus_Renderer_doc.md file.

To create a markdown suitable for Confluence run script:

npm run build-docConf

Please note that python must be installed !! This script will convert generated markdown into Confluence format. See console output for converted file name. Default place is in ./documentation in file : Bimplus_Renderer_doc_confluence.md

Content of the confluence file can be inserted into Confluence page :

• start confluence page editation mode
• choose Insert more content / {} Markup option from toolbar
• in popup window choose to Insert Markdown format
• copy content of the converted confluence markdown file into the field in Confluence
• save it (Please note that page links doesn't work in page preview mode)

Typescript definitions

• typescript definition file is located in subfolder 'types'