Using Custom Building Models

NUS Digital Twin is built on CesiumJS, which supports a variety of 3D models. There are several ways to add a custom building model into the application.

Tip

Add the building data into src/content/buildings/buildings.json before adding a custom model to ensure picking works correctly. See Update Building Data for instructions.

Using Cesium ion

Models uploaded to Cesium ion can be added into the platform. Use the Cesium3DTileset.fromIonAssetId method in Cesium to include a model hosted in Cesium ion.

1. Upload the model to Cesium ion. Refer to the Cesium ion 3D Tiling Documentation for the steps to upload the model.

   Tip

   Under ‘What kind of data is this?’ in Cesium ion, it is recommended to select ‘3D Model (tile as 3D Tiles)’ to ensure the best performance.

2. Add the code to retrieve the model from Cesium ion. A featureIdLabel which corresponds to the elementId in src/content/buildings/buildings.json should be included to allow building selection to function properly. The helper function getModelFromCesiumIon() is used to retrieve the model and is provided in src/components/cesium/cesiumUtils.ts.

   src/components/cesium/CesiumScene.astro

   const newModel = getModelFromCesium3DTileset({
     assetId: <assetId>, // example: 2686261
     featureIdLabel: <elementId>,
   });

3. Add the newModel to the correct array to ensure it is attached to the correct group of models. This ensures that the model will be toggled on and off correctly.

   For example, when adding a building level rhino model, add the newModel to the rhinoBuildingModels array.

   const rhinoBuildingModels: Array<Model | Cesium3DTileset> = [
     ...
     newModel,
   ]

Using Local or Remote Files

Model files stored locally within the repository or on remote storage such as AWS S3, Cloudflare R2 can also be loaded in the application, using the Model.fromGltfAsync method in Cesium.

For model files stored within the repository, it is recommended to store them in the public/ directory. See the public/ directory documentation for more details.

1. Ensure the model is provided in .glTF format. Otherwise, convert the model file into a .gltf file. Refer to the section below for the conversion steps.

2. Add the code to retrieve the model from the repository and position it correctly on the map. The helper function getModelFromGltf() is used to retrieve the model and is provided in src/components/cesium/cesiumUtils.ts.

   src/components/cesium/CesiumScene.astro

   const newModel = await getModelFromGltf({
    longitude: <longitude>,
    latitude: <latitude>,
    height: <height>,
    heading: <heading in degrees>,
    pitch: <pitch in degrees>,
    roll: <roll in degrees>,
    url: <url to gltf file>, // example: '/rvrc/rvrc-g-rhino.gltf'
    featureIdLabel: <element id>,
   })

3. Add the newModel to the correct array to ensure it is attached to the correct group of models. This ensures that the model will be toggled on and off correctly.

   For example, when adding a building level rhino model, add the newModel to the rhinoBuildingModels array.

   const rhinoBuildingModels: Array<Model | Cesium3DTileset> = [
     ...
     newModel,
   ]

Convert from Other File Types to .gltf

To use local or remote model files, they have to be converted to .gltf format first.

Wavefront Files (.obj, .mtl)

The recommend method is to use obj2gltf.

Example conversion

obj2gltf -i model.obj

COLLANDA Files (.dae)

The recommended method is to use COLLADA2GLTF.

Example conversion

./COLLADA2GTF-bin model.dae

Rhino3D Files (.3dm)

The recommended method is to open the model in Rhino3D, and re-export it as a .gltf file.