@bimdata/viewer 1.7.1 → 1.7.3-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -396
- package/dist/bimdata-viewer.esm.min.js +13 -13
- package/dist/bimdata-viewer.min.js +13 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,404 +1,14 @@
|
|
|
1
1
|
# BIMData Viewer
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
```html
|
|
6
|
-
<body>
|
|
7
|
-
<div id="app"></div>
|
|
8
|
-
<script type="module">
|
|
9
|
-
import makeBIMDataViewer from "@bimdata/viewer"; // fake path
|
|
10
|
-
|
|
11
|
-
const bimdataViewer = makeBIMDataViewer({
|
|
12
|
-
api: {
|
|
13
|
-
// api informations to fetch data on the BIMData api.
|
|
14
|
-
cloudId: 515,
|
|
15
|
-
projectId: 756,
|
|
16
|
-
ifcIds: [2283],
|
|
17
|
-
accessToken: "fc83e49ca9444d3ea41d212599f39040", // Demo token
|
|
18
|
-
apiUrl: "https://api-staging.bimdata.io",
|
|
19
|
-
},
|
|
20
|
-
});
|
|
21
|
-
|
|
22
|
-
bimdataViewer.mount("#app");
|
|
23
|
-
</script>
|
|
24
|
-
</body>
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
## makeBIMDataViewer
|
|
28
|
-
|
|
29
|
-
The viewer can be customized at startup using the parameter object of the makeBIMDataViewer function :
|
|
30
|
-
|
|
31
|
-
```javascript
|
|
32
|
-
const viewer = makeBIMDataViewer({
|
|
33
|
-
locale: "fr", // the locale of the viewer (fr, en).
|
|
34
|
-
api: {
|
|
35
|
-
// informations to fetch data from BIMData api.
|
|
36
|
-
ifcIds: [2283],
|
|
37
|
-
cloudId: 515,
|
|
38
|
-
projectId: 756,
|
|
39
|
-
accessToken: "XXXXXXXXXXXXXXXXXXX",
|
|
40
|
-
apiUrl: "https://api-staging.bimdata.io",
|
|
41
|
-
},
|
|
42
|
-
ui: {
|
|
43
|
-
// ui customization
|
|
44
|
-
style: {
|
|
45
|
-
backgroundColor: "red",
|
|
46
|
-
},
|
|
47
|
-
headerVisible: false, // default to true. If false, the header will be hidden.
|
|
48
|
-
windowManager: false, // default to true. If false, it will be impossible to the user to add, delete, swap or split windows.
|
|
49
|
-
version: false, // default to true. If false, the viewer version will be hidden.
|
|
50
|
-
bimdataLogo: false, // default to true. If false, the BIMData logo will be hidden.
|
|
51
|
-
},
|
|
52
|
-
// BIMData plugins can be customized.
|
|
53
|
-
// Some plugins are disabled by default like the split plugin.
|
|
54
|
-
// If the user wants to use it, split need to be set at true.
|
|
55
|
-
// To set a plugin, the plugin name can be set at true or with a configuration object that can be accessed in the plugin usin this.$options.$cfg.
|
|
56
|
-
plugins: {
|
|
57
|
-
split: true,
|
|
58
|
-
"window-split": false,
|
|
59
|
-
"structure-properties": false,
|
|
60
|
-
bcf: {
|
|
61
|
-
headers: {},
|
|
62
|
-
apiUrl:
|
|
63
|
-
"https://custom-BCF-2-1-API.example.com, taking BIMData API by default",
|
|
64
|
-
projectId:
|
|
65
|
-
"your custom project ID, taking BIMData's project id by default",
|
|
66
|
-
async fetchUsers() {
|
|
67
|
-
// If you want to fetch users from somewhere else
|
|
68
|
-
try {
|
|
69
|
-
return (await fetch("https://example.com/users")).json();
|
|
70
|
-
} catch (e) {
|
|
71
|
-
return [];
|
|
72
|
-
}
|
|
73
|
-
},
|
|
74
|
-
mergeUsers: true, // Decide if you merge your users list with BIMData users list or if yours overrides BIMData list
|
|
75
|
-
async fetchCurrentUser() {
|
|
76
|
-
return {id: "john.doe@example.com"}
|
|
77
|
-
};
|
|
78
|
-
},
|
|
79
|
-
projection: false,
|
|
80
|
-
section: false,
|
|
81
|
-
fullscreen: false,
|
|
82
|
-
search: false,
|
|
83
|
-
viewer3d: {
|
|
84
|
-
navCube: false,
|
|
85
|
-
},
|
|
86
|
-
viewer2d: false,
|
|
87
|
-
"structure-properties": {
|
|
88
|
-
merge: true,
|
|
89
|
-
export: true,
|
|
90
|
-
editProperties: true,
|
|
91
|
-
},
|
|
92
|
-
addPlugins: true // enable the possibility to add plugins from the marketplace in the window selector
|
|
93
|
-
},
|
|
94
|
-
logger: {
|
|
95
|
-
level: "INFO",
|
|
96
|
-
},
|
|
97
|
-
// The viewer can be used offline
|
|
98
|
-
offlineOptions: {
|
|
99
|
-
allowUnmockedMethodsOnNetwork: true,
|
|
100
|
-
data: [
|
|
101
|
-
{
|
|
102
|
-
id: 2318,
|
|
103
|
-
name: "LC_Audibert_2_à_12.ifc",
|
|
104
|
-
status: "C",
|
|
105
|
-
structure_file: "http://localhost:8081/2318_structure.json",
|
|
106
|
-
xkt_file: "http://localhost:8081/2318_model.xkt",
|
|
107
|
-
project_id: 761,
|
|
108
|
-
world_position: [0.0, 0.0, 0.0],
|
|
109
|
-
errors: [],
|
|
110
|
-
warnings: [],
|
|
111
|
-
rawElements: Object.freeze(rawElements),
|
|
112
|
-
zones: Object.freeze(zones),
|
|
113
|
-
},
|
|
114
|
-
],
|
|
115
|
-
},
|
|
116
|
-
});
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
## UI
|
|
120
|
-
|
|
121
|
-
<p align="center">
|
|
122
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-1_window.png" alt="Viewer with one window.">
|
|
123
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-2_windows.png" alt="Viewer with two windows.">
|
|
124
|
-
</p>
|
|
125
|
-
<p align="center">
|
|
126
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-3_windows.png" alt="Viewer with three windows.">
|
|
127
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-1_window_special.png" alt="Viewer with one window without header.">
|
|
128
|
-
</p>
|
|
129
|
-
|
|
130
|
-
The viewer UI is decomposed in three main parts :
|
|
131
|
-
|
|
132
|
-
- First, there is the header. The header is where some usefull actions can be performed like accessing the main menu, loading models or customizing the rest of the UI using the window manager. The header is not displayed on the bottom-right image. It is a special case where user only wants a floating header and a button (top-right) to customize windows.
|
|
133
|
-
- Next, there is the main view where windows are displayed. The user can add, delete, split or swap windows to create his own workspace, according to his needs. On the images above there is one, two or three windows with spatial arborescence, a 2d and 3d representations of the model displayed on different windows.
|
|
134
|
-
- Last, there are plugins displayed as menu inside windows. Different display possibilities are shown on the image below (left, right, small...). These possibilities are described in the [plugin](#Plugin) part.
|
|
135
|
-
|
|
136
|
-
<p align="center">
|
|
137
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-1_window_plugins.png" alt="Viewer with opened plugins.">
|
|
138
|
-
</p>
|
|
139
|
-
|
|
140
|
-
### Plugin
|
|
141
|
-
|
|
142
|
-
The viewer is shipped with native BIMData plugins but others can be added to add new features and more possibilities. A plugin is mainly either a Vuejs component or/and a simple function that is run when the viewer is mouted into the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model).
|
|
143
|
-
|
|
144
|
-
A plugin is added to the viewer by registering it :
|
|
145
|
-
|
|
146
|
-
```javascript
|
|
147
|
-
import makeBIMDataViewer from "@bimdata/viewer"; // fake path
|
|
148
|
-
import MyPlugin from "@myOrganisation/plugin"; // fake path
|
|
149
|
-
|
|
150
|
-
const bimdataViewer = makeBIMDataViewer(/* {...} */);
|
|
151
|
-
|
|
152
|
-
bimdataViewer.registerPlugin(MyPlugin);
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
#### Plugin registration API
|
|
156
|
-
|
|
157
|
-
The registerPlugin method take an object as argument. The options are the followings:
|
|
158
|
-
|
|
159
|
-
| Property | Description |
|
|
160
|
-
| :------------------------- | :---------------------------------------------------------------------------------------------- |
|
|
161
|
-
| `name`: `string` | **Required** The name of the plugin. Must be unique. |
|
|
162
|
-
| `component`: `object` | A Vuejs (v2.x) component. |
|
|
163
|
-
| `i18n`: `object` | An object containing translations for internationalization. |
|
|
164
|
-
| `startupScript($viewer)` | A function that is executed when the viewer is mounted, with [`$viewer`](#$viewer) as argument. |
|
|
165
|
-
| `button`: `object` | An [object](#Button) that disribe the display of the plugin if the plugin is shown as button. |
|
|
166
|
-
| `window`: `object` | An [object](#Window) used to register a window with this plugin in it. |
|
|
167
|
-
| `addToWindows`: `string[]` | An array of [window](#Window) name in wich to include this plugin. |
|
|
168
|
-
|
|
169
|
-
#### Button
|
|
170
|
-
|
|
171
|
-
| Property | Description |
|
|
172
|
-
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
|
|
173
|
-
| `position`: `string` | "left" or "right". The position of the button in the window. |
|
|
174
|
-
| `content`: `string` | "simple", "panel" or "free"(default). Different way to display the component when the button is clicked. (see images below) |
|
|
175
|
-
| `tooltip`: `string` | A string that is displayed when the plugin button is hovered. It can be a key to be translated ex: "myPluginName.tooltip" |
|
|
176
|
-
| `keepOpen`: `boolean` | Default to `false`. If `true`, the plugin will close by clicking away from the viewer. |
|
|
177
|
-
| `icon.imgUri`: `string` | An uri to an image for the button. |
|
|
178
|
-
|
|
179
|
-
If only the `icon` is defined, the corresponding image is always displayed on the button.
|
|
180
|
-
A similar option, iconOpen can be defined to display a icon different when the button is open.
|
|
181
|
-
|
|
182
|
-
The images below show the different way to display plugin as button. (top-left : content = `simple`, top-right : content = `free`, bottom : content = `panel`)
|
|
3
|
+
A powerful, flexible and customizable BIM models viewer by [BIMData.io](https://bimdata.io/).
|
|
183
4
|
|
|
184
5
|
<p align="center">
|
|
185
|
-
<img src="./
|
|
186
|
-
<img src="./
|
|
6
|
+
<img width="400" height="230" src="./img/viewer-1.png" alt="Viewer with one window.">
|
|
7
|
+
<img width="400" height="230" src="./img/viewer-2.png" alt="Viewer with two windows.">
|
|
187
8
|
</p>
|
|
188
|
-
<p align="center">
|
|
189
|
-
<img src="./documentation/assets/Viewer-PluginButton-panel.png" alt="Viewer plugin button panel.">
|
|
190
|
-
</p>
|
|
191
|
-
|
|
192
|
-
The `simple` mode display the component in a small div adapted for small menu interfaces like switching between few options.
|
|
193
|
-
The `free` mode display the component in a div. The developper of the plugin is responsible to decide the style of the component because the div is related to the component size.
|
|
194
|
-
The `panel` mode open the component in a Panel. The panel height is 100% of the window (minus few margins) and it can be unpined. Once unpined, the panel can be resized and moved inside the window like on the gif below.
|
|
195
|
-
|
|
196
|
-
<p align="center">
|
|
197
|
-
<img src="./documentation/assets/Viewer-panel.gif" alt="Viewer Panel.">
|
|
198
|
-
</p>
|
|
199
|
-
|
|
200
|
-
#### Window
|
|
201
|
-
|
|
202
|
-
A window can be registered using two ways :
|
|
203
|
-
|
|
204
|
-
- The first is by adding a window configuration object in a plugin configuration
|
|
205
|
-
- The second is by registering it directly on the BIMData viewer object :
|
|
206
|
-
|
|
207
|
-
The window configuration object :
|
|
208
|
-
|
|
209
|
-
| Property | Description |
|
|
210
|
-
| :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
211
|
-
| `name`: `string` | **Required** The name of the window. Must be unique. |
|
|
212
|
-
| `label`: `string` | The label that is displayed to the user. Can be a key to be translated like : "viewer3d.window_label". |
|
|
213
|
-
| `plugins`: `array` | An array of plugins which will be added to the window. |
|
|
214
|
-
| `flyingHeader`: `boolean` | Default to false. If true, the header bar is replaced by a flying header and a window manager button if this window is the only one displayed. |
|
|
215
|
-
|
|
216
|
-
```javascript
|
|
217
|
-
const bimdataViewer = makeBIMDataViewer(/* {...} */);
|
|
218
|
-
|
|
219
|
-
const windowConfigurationObject = {
|
|
220
|
-
name: "windowName",
|
|
221
|
-
plugins: [
|
|
222
|
-
/* plugins */
|
|
223
|
-
],
|
|
224
|
-
};
|
|
225
|
-
|
|
226
|
-
// first way
|
|
227
|
-
makeBIMDataViewer.registerPlugin({
|
|
228
|
-
/* plugin specific fields */
|
|
229
|
-
window: windowConfigurationObject,
|
|
230
|
-
});
|
|
231
|
-
|
|
232
|
-
// second way
|
|
233
|
-
bimdataViewer.registerWindow(windowConfigurationObject);
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
### mount
|
|
237
|
-
|
|
238
|
-
Once created, the BIMDataViewer must be mounted to a [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) element in order to be displayed to the user.
|
|
239
|
-
|
|
240
|
-
```javascript
|
|
241
|
-
bimdataViewer.mount("#app"); // 'app' is the id of an existing element.
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
The mount methode take an optional second argument: the [`layout`](#Layout). The [`layout`](#Layout) is the configuration of the windows displayed at startup. The default value is "3d", which is the name of a window registered by default. The "3d" window includes many BIMData plugins like "viewer3d", "section", "projection", "structure-properties"...
|
|
245
|
-
|
|
246
|
-
#### Layout
|
|
247
|
-
|
|
248
|
-
The layout object can be either a `string` or an `object`. If `string`, it must be the name of a registered window. If `object`, the `layout` is a recursive object representing a container of window names. A container have ratios that represent the amount of space taken by given windows, a direction that can be "column" or "row"(default) and an array of children. A child can be a window name as "string" or another container.
|
|
249
|
-
|
|
250
|
-
Examples :
|
|
251
|
-
|
|
252
|
-
```javascript
|
|
253
|
-
bimdataViewer.mount("#app", "3d");
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-1_window_special.png" alt='Layout "3d"'>
|
|
257
|
-
|
|
258
|
-
```javascript
|
|
259
|
-
bimdataViewer.mount("#app", {
|
|
260
|
-
ratios: [40, 60],
|
|
261
|
-
direction: "row",
|
|
262
|
-
children: ["structure", "2d"],
|
|
263
|
-
});
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-2_windows.png" alt='Layout row 2 windows'>
|
|
267
|
-
|
|
268
|
-
```javascript
|
|
269
|
-
bimdataViewer.mount("#app", {
|
|
270
|
-
ratios: [55, 45],
|
|
271
|
-
direction: "column",
|
|
272
|
-
children: [
|
|
273
|
-
{
|
|
274
|
-
ratios: [50, 50],
|
|
275
|
-
children: ["structure", "2d"],
|
|
276
|
-
},
|
|
277
|
-
"3d",
|
|
278
|
-
],
|
|
279
|
-
});
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-3_windows.png" alt='Layout 3 windows'>
|
|
283
|
-
|
|
284
|
-
### Complete UI example
|
|
285
|
-
|
|
286
|
-
```html
|
|
287
|
-
<body>
|
|
288
|
-
<div id="app"></div>
|
|
289
|
-
<script type="module">
|
|
290
|
-
import makeBIMDataViewer from "@bimdata/viewer";
|
|
291
|
-
|
|
292
|
-
const bimdataViewer = makeBIMDataViewer({
|
|
293
|
-
api: {
|
|
294
|
-
cloudId: 515,
|
|
295
|
-
projectId: 756,
|
|
296
|
-
ifcIds: [2283],
|
|
297
|
-
accessToken: "fc83e49ca9444d3ea41d212599f39040", // Demo token
|
|
298
|
-
apiUrl: "https://api-staging.bimdata.io",
|
|
299
|
-
},
|
|
300
|
-
});
|
|
301
|
-
|
|
302
|
-
bimdataViewer.registerPlugin({
|
|
303
|
-
name: "buttonPlugin",
|
|
304
|
-
component: {
|
|
305
|
-
render(h) {
|
|
306
|
-
return h("div", "Plugin Button component content.");
|
|
307
|
-
},
|
|
308
|
-
},
|
|
309
|
-
button: {
|
|
310
|
-
position: "left",
|
|
311
|
-
content: "panel",
|
|
312
|
-
},
|
|
313
|
-
});
|
|
314
|
-
|
|
315
|
-
bimdataViewer.registerPlugin({
|
|
316
|
-
name: "windowPlugin",
|
|
317
|
-
component: {
|
|
318
|
-
render(h) {
|
|
319
|
-
return h(
|
|
320
|
-
"div",
|
|
321
|
-
{
|
|
322
|
-
style:
|
|
323
|
-
"display: flex; justify-content: center; align-items: center; height: 100%;",
|
|
324
|
-
},
|
|
325
|
-
"Plugin Window component content."
|
|
326
|
-
);
|
|
327
|
-
},
|
|
328
|
-
},
|
|
329
|
-
window: {
|
|
330
|
-
name: "window-1",
|
|
331
|
-
plugins: ["buttonPlugin"],
|
|
332
|
-
},
|
|
333
|
-
});
|
|
334
|
-
|
|
335
|
-
bimdataViewer.registerWindow({
|
|
336
|
-
name: "window-2",
|
|
337
|
-
plugins: ["buttonPlugin"],
|
|
338
|
-
});
|
|
339
|
-
|
|
340
|
-
bimdataViewer.mount("#app", {
|
|
341
|
-
ratios: [30, 70],
|
|
342
|
-
children: [
|
|
343
|
-
"window-1",
|
|
344
|
-
{
|
|
345
|
-
ratios: [40, 60],
|
|
346
|
-
direction: "column",
|
|
347
|
-
children: ["window-2", "3d"],
|
|
348
|
-
},
|
|
349
|
-
],
|
|
350
|
-
});
|
|
351
|
-
</script>
|
|
352
|
-
</body>
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
<img width="400" height="230" src="./documentation/assets/Viewer-layout.png" alt='Complete layout example.'>
|
|
356
|
-
|
|
357
|
-
## \$viewer
|
|
358
|
-
|
|
359
|
-
[`$viewer`](./src/viewer/README.md#$viewer) is an object that can be accessed in plugins component (or as first parameter of the startupScript function) :
|
|
360
|
-
|
|
361
|
-
```javascript
|
|
362
|
-
// on components methods, computed...
|
|
363
|
-
this.$viewer;
|
|
364
|
-
```
|
|
365
|
-
|
|
366
|
-
It contains all utilities to interact with the viewer.
|
|
367
|
-
|
|
368
|
-
## Contribute
|
|
369
|
-
|
|
370
|
-
This repo use semantic-release for tag management and deployment.
|
|
371
|
-
|
|
372
|
-
It is possible to automatically publish a new npm package from the semantics of a commit message.
|
|
373
|
-
The keywords are `MAJOR`, to publish a major version (X.0.0), `MINOR`, to publish a minor version (1.X.0), and `PATCH`, to publish a fix (1.0.X).
|
|
374
|
-
|
|
375
|
-
They must correspond to the following syntax:
|
|
376
|
-
|
|
377
|
-
```
|
|
378
|
-
/(MAJOR|MINOR|PATCH): .*/
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
Example :
|
|
382
|
-
|
|
383
|
-
```bash
|
|
384
|
-
git commit -m "MINOR: explain the new feature to deploy"
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
The branches on which it is possible to publish are the following:
|
|
388
|
-
|
|
389
|
-
| Branches | Git tag | Npm version | Bimdata Platform |
|
|
390
|
-
| ------------- | :----------: | ----------------------- | :--------------: |
|
|
391
|
-
| develop | 1.3.0-rc.1\* | 1.0.3-rc.1<br>tag: next | staging |
|
|
392
|
-
| release/X.X.x | 1.1.6 | 1.1.6<br>tag: 1.1.x | |
|
|
393
|
-
| master | 1.2.8 | 1.2.8<br>tag: latest | prod |
|
|
394
|
-
|
|
395
|
-
\* The `develop` branch will only release `rc.x` in succession until the release candidate or a higher version has been deployed to `master`.
|
|
396
9
|
|
|
397
|
-
|
|
398
|
-
After deploying a new latest tag with master branch, merge master into develop to update `package.json` and `CHANGELOG.md`.
|
|
10
|
+
## :red_haired_woman: :green_book: User Documentation
|
|
399
11
|
|
|
400
|
-
|
|
12
|
+
BIMData Viewer has its own documentation that you can find at https://developers.bimdata.io/viewer/.
|
|
401
13
|
|
|
402
|
-
|
|
403
|
-
./deploy.sh
|
|
404
|
-
```
|
|
14
|
+
Please refer to this doc if you want to use the viewer and/or develop plugins to extend it.
|