vue-ifc-viewer v1.0.2

Vue IFC Viewer

Vue IFC Viewer is a VueJS plugin written in typescript that let developers integrate OpenBIM Components in their apps 🚀🚀.

Getting started

These getting started steps assumes you already have some basic VueJS knowledge.

1. Install vue-ifc-viewer in your VueJS app with npm i vue-ifc-viewer.
2. vue-ifc-viewer has openbim-components set as a peer dependency, so you need to install it with npm i openbim-components. Note: keep in mind openbim-components also has peer dependencies, so you need to install them as well. Please, refer to their docs to know more.

3. Once you've all dependencies installed, add the plugin to your vue app:

   import { createApp } from "vue"
   import { ifcViewer } from "vue-ifc-viewer"
   import App from "./components/App.vue"
   
   createApp(App).use(ifcViewer).mount("#app")

4. What the plugin does is to let you use the IFCViewer component anywhere you want and access it using a composable (useViewersManager). So, in the App component that is the entry point of this getting started guide you can have something like the following:

   <template>
     <IFCViewer />
   </template>
   
   <script setup lang="ts">
   import * as OBC from "openbim-components"
   import { onMounted } from 'vue';
   import IFCViewer from 'vue-ifc-viewer' //This is the VueJS component that will render the IFCViewer in your app.
   import { useViewersManager } from 'vue-ifc-viewer' //This is a VueJS composable that lets you access the viewer instance.
   
   const viewersManager = useViewersManager()
   const viewer = viewersManager.get()
   
   onMounted(() => {
     const ifcLoader = viewer.tools.get(OBC.FragmentIfcLoader)
     ifcLoader.onIfcLoaded.add(model => {
       console.log(`${model.name} loaded!`)
     })
   })
   </script>

How it works?

Vue-ifc-viewer relies on the provide/inject api from VueJS in order to provide to the whole app with a ViewersManager. The ViewersManager lets you create and access different instances of an OpenBIM Components viewer (yes! you can create more than one viewer at the time). The plugin comes with a default ready to go viewer setup, but you can customize it as you want to suit the needs of your app.

Customizing the viewer

When you use the plugin in your app, you've the chance to pass an optional configuration object to customize the viewer logic. This can be done as the following:

import * as OBC from "openbim-components"
import { createApp } from "vue"
import { ifcViewer, IfcPluginConfig, ViewerSetup } from "vue-ifc-viewer"
import App from "./components/App.vue"

//You can create this function in other file and import it here
const customViewer: ViewerSetup = async (viewer: OBC.Components, container: HTMLDivElement) => {

  //Initialize the viewer with some basics
  const sceneComponent = new OBC.SimpleScene(viewer)
  sceneComponent.setup()
  viewer.scene = sceneComponent

  const renderer = new OBC.PostproductionRenderer(viewer, container)
  viewer.renderer = renderer
  const camera = new OBC.OrthoPerspectiveCamera(viewer)
  viewer.camera = camera

  const raycaster = new OBC.SimpleRaycaster(viewer)
  viewer.raycaster = raycaster

  await viewer.init()
  camera.updateAspect()
  renderer.postproduction.enabled = true

  //You can start to add tools as you want!
  //Refer to the official documentation at docs.thatopen.com to know more, in the tutorials section you can see many examples.
}

const ifcPluginConfig: IfcPluginConfig = {
  defaultViewerSetup: viewer
}

createApp(App).use(ifcViewer, ifcPluginConfig).mount("#app")

When you use the IFCViewer component, it will use the above configuration to initialize the viewer.

Accessing the viewer

As said before, useViewersManager lets you access you viewers instances from any component in your VueJS app. In order to do it, you can go as the following:

In the component where you include the viewer:

<template>
  <IFCViewer />
</template>

<script setup lang="ts">
import IFCViewer from 'vue-ifc-viewer'
</script>

From any other component in your app:

<script setup lang="ts">
import { useViewersManager } from 'vue-ifc-viewer'

const viewersManager = useViewersManager()
const viewer = viewersManager.get()
//Do whatever you want with the viewer instance, like using other tools.
</script>

Creating multiple viewers

You can use the IFCViewer component from vue-ifc-viewer as many times as you want in order to create multiple viewers, the only thing to keep in mind is to give them unique names. You can do that as follows:

In the component where you include the viewers:

<template>
  <IFCViewer name="viewer-a" />
  <IFCViewer name="viewer-b" />
</template>

<script setup lang="ts">
import IFCViewer from 'vue-ifc-viewer'
</script>

If you don't give your viewer any name, it will be named "default". Also, all viewers will get initialized with the same settings you set in the plugin configuration.

From any other component in your app:

<script setup lang="ts">
import { useViewersManager } from 'vue-ifc-viewer'

const viewersManager = useViewersManager()
const viewerA = viewersManager.get("viewer-a")
const viewerB = viewersManager.get("viewer-b")
//Do whatever you want with both viewer instances.
</script>

If you don't give your viewer any name (meaning it will be named "default") you can call viewersManager.get() without any argument.