Skip to main content

SimpleScene

🌍 Let's create a 3D world!​

The SimpleScene component is the easiest way to create a 3D space to start working. Let's start by importing Components and Three.js:

import * as THREE from 'three';
import * as OBC from 'openbim-components';

Now, the first step is getting a container for our viewer. 📦 This is just a place where the 3D scene will be rendered. In this example we have just added an HTML div element with the ID "container".

const container = document.getElementById('container');

Now, let's create an awesome 3D scene inside that HTML element! 🔥

Are you using a library/framework like React, Angular or vue?

Then probably you have other mechanisms for getting a reference to the HTML div element. However you do it, as long as you get a reference in your code, you are good to go!

🧰 Setting up a components project​

Next, we will instantiate the main object of the library: Components. 🤖 This object will keep track of all the components that you create, making them easily accessible in all your application and making sure to update them in each frame, so you don't have to worry about that. 💪

The minimum components application

Any components app needs 4 things to work:

const components = new OBC.Components();
components.scene = new OBC.SimpleScene(components);
components.renderer = new OBC.SimpleRenderer(components, container);
components.camera = new OBC.SimpleCamera(components);
components.raycaster = new OBC.SimpleRaycaster(components);

Now that everything is set up, let's start the app! You can do that with the init method. It will start updating all the components at 60 fps, so that you don't have to worry about the animation loop: 🚗💨💨💨

components.init();

And that's it! You already have set up 3D scene that can run on any device. Easy, right? 🥳 But right now or scene is not very interesting, as it's only a infinite white void. Let's add some things to it! First, we need a reference to the scene, which you can get with the get() method. This method is present in all the components and is used to get the core of the component. We can do it like this:

const scene = components.scene.get();

🎥 Adjusting scene and camera​

Great! Now we will make the background of our scene transparent. You don't have to do it; we are doing it because that way this app will be more integrated with the documentation page when setting it to light/dark mode.

scene.background = null;

Now we will locate the camera in a nice starting position. We can control the SimpleCamera component through its controls attribute. This object is an instance of the camera-controls library, which makes it super easy to control the camera in our 3D scene. We will set the position of the camera to [10, 10, 10] and make it look at the origin ([0, 0, 0]).

components.camera.controls.setLookAt(10, 10, 10, 0, 0, 0);

🏀 Adding some 3D objects​

Awesome! We are now ready to start adding some objects. First, we will add a simple grid component. As the name implies, this component adds a simple 2D grid to the scene that we can use as a reference.

const grid = new OBC.SimpleGrid(components);
components.tools.add(grid);
Adding it to the tools component

The Tools Component will help you keep your code tidy. For more information about the Tools component, check out its own tutorial. 🔍

🚀 Also, let's add some real geometry to our small 3D app. All the components are built on top of Three.js, which means that Three.js code will work natively with them. This is great, because you can easily integrate components with any 3D app that you create. Let's try it by adding a simple red cube:

const boxMaterial = new THREE.MeshStandardMaterial({ color: 'red' });
const boxGeometry = new THREE.BoxGeometry(3, 3, 3);
const cube = new THREE.Mesh(boxGeometry, boxMaterial);
cube.position.set(0, 1.5, 0);
scene.add(cube);

🔦 Lighting things up​

Of course, everything is black because we have no lights! Let's fix it by adding some basic illumination:

const directionalLight = new THREE.DirectionalLight();
directionalLight.position.set(5, 10, 3);
directionalLight.intensity = 0.5;
scene.add(directionalLight);
const ambientLight = new THREE.AmbientLight();
ambientLight.intensity = 0.5;
scene.add(ambientLight);

🧹 Cleaning up​

As you might now, JavaScript has an automatic garbage collector that gets rid of the variables that you are no longer using. Unfortunately, that's not the case for Three.js. But don't worry: components takes care of this for you. When you are finished working with a Components instance, simply call components.dispose() and we will clean everything up for you!

Watch your variables!

When you dispose the memory, make sure that you don't have any object or array referencing anything inside the Components instance or this won't work, because JavaScript will detect that you are still using it!

Using React, Angular, Vue...?

This topic is especially relevant in Single Page Application technologies because they never reload the page (which would release all the memory automatically). If you are using some of these, make sure that you set up the disposing logic to fire when you re-render the component that has the 3D app.

And voilà! You have made your first 3D application using components. Easy, right? Of course, this is still far from a full-fledged BIM app, but don't worry! Keep following our tutorials and your app will go from zero to hero in no time! 🚀