From f4898c29f4ea86346ede5467e91ef72bcb61db60 Mon Sep 17 00:00:00 2001 From: Gabriel Cambreling <32667664+GabBimdata@users.noreply.github.com> Date: Wed, 26 Aug 2026 08:52:29 +0200 Subject: [PATCH 1/2] feat(viewer): rewrite getting started as an end-to-end path The page stopped at the demo snippet. Readers who wanted to switch to their own data had to reassemble the path themselves across the API and Viewer sections. The demo snippet now opens the page unchanged, so time to first render stays at zero. Everything else is new: - Add the "use your own models" path: application, cloud, project, model, token. - Move ProjectAccessToken into the viewer path. It was only documented in /api/guides/authentication, which is not where someone integrating the viewer looks. The current default path is pasting an ApiKey into the page. - Document the two main causes of a blank screen: ES modules blocked on file://, and a container with no height. - Add the ui config block for white labelling. - Move the format list to "Going further". - Link to existing reference pages instead of duplicating them. --- src/viewer/index.md | 196 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 180 insertions(+), 16 deletions(-) diff --git a/src/viewer/index.md b/src/viewer/index.md index 2348221..c89de37 100644 --- a/src/viewer/index.md +++ b/src/viewer/index.md @@ -9,28 +9,27 @@ import BIMDataIconFilePointCloud from "../.vitepress/components/BIMDataIconFileP import ViewerMainPage from "../.vitepress/components/ViewerMainPage.vue"; -## Introduction +The BIMData Viewer displays models of many formats in a web page. Each format is +handled by its own native built-in viewer, with **display**, **navigation**, +**measurement** and **annotation** available on all of them. -The BIMData Viewer is a tool for interacting with models of different formats like : --
IFC
--
Image (PDF, PNG, JPG)
--
DWG
--
DXF
--
Point Cloud (PLY, LAS, LAZ).
+
+
IFC
+
PDF, PNG, JPG
+
DWG
+
DXF
+
PLY, LAS, LAZ
+
-Each model format is handled by its own native built-in viewer and interactions include **display**, **navigation**, **measurement** and **annotation**. - -The BIMData Viewer is binded to the [BIMData API](/api/introduction/overview) and you can directly upload models using it or using the [BIMData platform](https://platform.bimdata.io/). - -[The UI can be customized](./guide/index#graphical-user-interface) to organize the workspace as you need and a flexible javascript API using -[Vue 3](https://vuejs.org/) allows to create custom plugins to match your business perfectly. -However, you don't need to master Vue.js to develop a plugin and you can still update the DOM with jQuery if you like! +This guide takes you from an empty file to a model running in your browser. No +account needed for the first step. Count about 15 minutes for the whole page. -## Installation +## See it running -You can directly download the BIMDataViewer from a **CDN** or you can install the [`@bimdata/viewer` package](https://www.npmjs.com/package/@bimdata/viewer) using **NPM**. +Create an `index.html` file, paste this, and open it. The identifiers below point +to our public demo model, so it works as-is. ::: code-group @@ -100,3 +99,168 @@ You can directly download the BIMDataViewer from a **CDN** or you can install th ``` ::: + +That is the entire integration: an import, four identifiers, and a `mount()`. + +::: warning Double-clicking the file will not work +ES modules are blocked on the `file://` protocol, so opening the file directly +gives you a blank page and a CORS error in the console. Serve it over HTTP +instead, with the *Live Server* extension in VS Code or `npx serve` in the folder. +::: + +::: tip Blank page, no error? +The viewer fills its parent element. If the container has no height, nothing +renders. That is what the `height: 100vh` wrapper above is for. +::: + +::: tip Pin the version in production +`@latest` is convenient while you experiment, but it means your page changes +whenever we ship a release. Pin an explicit version once you go live. +::: + +## Use your own models + +The demo identifiers are read-only and shared. To display your own data you need +your own `cloudId`, `projectId`, `modelIds` and `accessToken`. + +### 1. Create an application + +An **application** is your developer identity with BIMData, and it is what gives +you API credentials. + +1. Go to [connect.bimdata.io](https://connect.bimdata.io) and sign in. +2. Open **Manage your application** → **Create an application**. +3. Set the access type to **`Confidential`**. +4. `base_url` and `redirect_uri` are required even though you will not use them + here. `http://localhost:8080/oidc-callback` will do. + +You get a `client_id`, a `client_secret` and an `ApiKey`. See +[Create your application](/api/guides/application) for details. + +::: danger Keep these on your server +These credentials grant full access to your data. They belong in your backend, +never in a web page. Step 3 covers what to put in the browser instead. +::: + +### 2. Create a cloud, a project and a model + +The fastest route is our demo endpoint, which creates a project with a model +already in it, with no upload and no processing wait. + +```bash +# Create a cloud +curl --request POST 'https://api.bimdata.io/cloud' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: ApiKey YOUR_API_KEY' \ + --data '{"name": "My First Cloud"}' + +# Create a demo project inside it +curl --request POST 'https://api.bimdata.io/cloud/CLOUD_ID/create-demo' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: ApiKey YOUR_API_KEY' + +# List its models +curl --request GET 'https://api.bimdata.io/cloud/CLOUD_ID/project/PROJECT_ID/ifc' \ + --header 'Authorization: ApiKey YOUR_API_KEY' +``` + +Each response gives you the identifier for the next call. + +You can also create a project and upload your own IFC from the +[BIMData Platform](https://platform.bimdata.io/), then read the identifiers from +the URL. + +::: warning A project created by hand is not visible to your app +Your application does not automatically have access to your user's data, and the +reverse is also true. To connect the two, invite yourself into a cloud created by +your app. See +[Share data between App and Platform](/api/guides/share_data). +::: + +### 3. Create a token for the browser + +Whatever you write in the page is readable by your users. So the token you pass +to the viewer must not be your application's `ApiKey`, which can read *and +delete* everything you own. + +Use a **ProjectAccessToken** instead: temporary, read-only, limited to one +project. + +```bash +curl --request POST 'https://api.bimdata.io/cloud/CLOUD_ID/project/PROJECT_ID/access-token' \ + --header 'Content-Type: application/json' \ + --header 'Authorization: ApiKey YOUR_API_KEY' \ + --data '{ + "expires_at": "2026-12-31T23:59:00Z", + "scopes": ["model:read"] + }' +``` + +`model:read` opens models and is the minimum scope the viewer requires. See +[Scopes](/api/guides/scopes) for the full list, and +[Authentication](/api/guides/authentication) for other flows. + +::: tip In production +Generate a fresh 12-hour token from your backend each time a user opens the +viewer. Your `ApiKey` stays on your server, and the browser only ever holds a +short-lived, narrowly scoped token. +::: + +Drop your four values into the snippet above, and you are running on your own +data. + +## Make it yours + +The default interface carries BIMData branding. One configuration block removes +it and lets the viewer blend into your own product: + +```js +const bimdataViewer = makeBIMDataViewer({ + api: { /* ... */ }, + locale: "fr", + ui: { + header: false, + bimdataLogo: false, + version: false, + style: { backgroundColor: "F5F5F5" }, + }, +}); +``` + +Native plugins can be turned off entirely with `plugins: false`, or one by one: + +```js +plugins: { + bcf: false, + measure3d: false, + section: false, + viewer3d: { navCube: false, help: false }, +} +``` + +Full list of options: +[makeBIMDataViewer](/viewer/reference/makeBIMDataViewer) and +[Native Plugins](/viewer/reference/native_plugins). + +## Going further + +**Other formats.** Everything above works the same way for plans, DWG, DXF and +point clouds. Pass the relevant model ID and the matching viewer takes over. A +project can hold several formats at once, and you can display them side by side. + +**Rearrange the workspace.** Choose which panels appear where, split the window, +build your own layout. See +[User Interface](/viewer/guide/). + +**Add your own features.** The viewer exposes a JavaScript plugin API built on +[Vue 3](https://vuejs.org/). You don't need to master Vue.js to develop a plugin, +and you can still update the DOM with jQuery if you like. Start with +[Plugins](/viewer/guide/plugins), or clone the +[Viewer SDK](/viewer/viewer_sdk) for a pre-configured development environment. + +**Mobile and offline.** The viewer supports touch devices +([Mobile](/viewer/mobile)) and disconnected use +([Offline Mode](/viewer/reference/offline_mode)). + +The viewer is bound to the [BIMData API](/api/introduction/overview), which you +can use to upload and manage models programmatically. From 4c69ccee273b04347ba60ebee152acf0bb566372 Mon Sep 17 00:00:00 2001 From: Hugo Duroux <1349751+Amoki@users.noreply.github.com> Date: Wed, 26 Aug 2026 15:54:14 +0200 Subject: [PATCH 2/2] Update src/viewer/index.md --- src/viewer/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/viewer/index.md b/src/viewer/index.md index c89de37..ecb6692 100644 --- a/src/viewer/index.md +++ b/src/viewer/index.md @@ -160,7 +160,7 @@ curl --request POST 'https://api.bimdata.io/cloud/CLOUD_ID/create-demo' \ --header 'Authorization: ApiKey YOUR_API_KEY' # List its models -curl --request GET 'https://api.bimdata.io/cloud/CLOUD_ID/project/PROJECT_ID/ifc' \ +curl --request GET 'https://api.bimdata.io/cloud/CLOUD_ID/project/PROJECT_ID/model' \ --header 'Authorization: ApiKey YOUR_API_KEY' ```