Skip to main content
Version: 4.x

Class: Cognite3DViewer

@cognite/reveal.Cognite3DViewer

Constructors

constructor

new Cognite3DViewer(options)

Parameters

NameType
optionsCognite3DViewerOptions

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:243

Accessors

cadBudget

get cadBudget(): CadModelBudget

Gets the current budget for downloading geometry for CAD models. Note that this budget is shared between all added CAD models and not a per-model budget.

Returns

CadModelBudget

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:197

set cadBudget(budget): void

Sets the current budget for downloading geometry for CAD models. Note that this budget is shared between all added CAD models and not a per-model budget.

Parameters

NameType
budgetCadModelBudget

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:207


cameraManager

get cameraManager(): CameraManager

Returns

CameraManager

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:647


canvas

get canvas(): HTMLCanvasElement

Returns the rendering canvas, the DOM element where the renderer draws its output.

Returns

HTMLCanvasElement

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:111


domElement

get domElement(): HTMLElement

The DOM element the viewer will insert its rendering canvas into. The DOM element can be specified in the options when the viewer is created. If not specified, the DOM element will be created automatically. The DOM element cannot be changed after the viewer has been created.

Returns

HTMLElement

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:121


models

get models(): CogniteModel[]

Gets a list of models currently added to the viewer.

Returns

CogniteModel[]

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:232


pointCloudBudget

get pointCloudBudget(): PointCloudBudget

Returns the point cloud budget. The budget is shared between all loaded point cloud models.

Returns

PointCloudBudget

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:217

set pointCloudBudget(budget): void

Sets the point cloud budget. The budget is shared between all loaded point cloud models.

Parameters

NameType
budgetPointCloudBudget

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:225


renderParameters

get renderParameters(): RenderParameters

Returns parameters of THREE.WebGLRenderer used by the viewer.

Returns

RenderParameters

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:128

Methods

add360ImageSet

add360ImageSet(datasource, eventFilter, add360ImageOptions?): Promise<Image360Collection>

Adds a set of 360 images to the scene from the /events API in Cognite Data Fusion.

Example

const eventFilter = { site_id: "12345" };
await viewer.add360ImageSet('events', eventFilter);

Parameters

NameTypeDescription
datasource"events"The CDF data source which holds the references to the 360 image sets.
eventFilterObjectThe metadata filter to apply when querying events that contains the 360 images.
add360ImageOptions?AddImage360OptionsOptions for behaviours when adding 360 images.

Returns

Promise<Image360Collection>

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:787


addCadModel

addCadModel(options): Promise<CogniteCadModel>

Add a new CAD 3D model to the viewer. Call fitCameraToModel to see the model after the model has loaded.

Example

const options = {
modelId: 'COGNITE_3D_MODEL_ID',
revisionId: 'COGNITE_3D_REVISION_ID',
};
viewer.addCadModel(options).then(model => {
viewer.fitCameraToModel(model, 0);
});

Parameters

NameType
optionsAddModelOptions

Returns

Promise<CogniteCadModel>

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:733


addModel

addModel(options): Promise<CogniteModel>

Add a new model to the viewer. Call fitCameraToModel to see the model after the model has loaded.

Example

const options = {
modelId: 'COGNITE_3D_MODEL_ID',
revisionId: 'COGNITE_3D_REVISION_ID',
};
viewer.addModel(options).then(model => {
viewer.fitCameraToModel(model, 0);
});

Parameters

NameType
optionsAddModelOptions

Returns

Promise<CogniteModel>

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:700


addObject3D

addObject3D(object): void

Add a THREE.Object3D to the viewer.

Example

const sphere = new THREE.Mesh(
new THREE.SphereGeometry(),
new THREE.MeshBasicMaterial()
);
viewer.addObject3D(sphere);

Parameters

NameType
objectObject3D<Event>

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:950


addPointCloudModel

addPointCloudModel(options): Promise<CognitePointCloudModel>

Add a new pointcloud 3D model to the viewer. Call fitCameraToModel to see the model after the model has loaded.

Example

const options = {
modelId: 'COGNITE_3D_MODEL_ID',
revisionId: 'COGNITE_3D_REVISION_ID',
};
viewer.addPointCloudModel(options).then(model => {
viewer.fitCameraToModel(model, 0);
});

Parameters

NameType
optionsAddModelOptions

Returns

Promise<CognitePointCloudModel>

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:761


determineModelType

determineModelType(modelId, revisionId): Promise<"" | SupportedModelTypes>

Use to determine of which type the model is.

Example

const viewer = new Cognite3DViewer(...);
const type = await viewer.determineModelType(options.modelId, options.revisionId)
let model: CogniteModel
switch (type) {
case 'cad':
model = await viewer.addCadModel(options);
break;
case 'pointcloud':
model = await viewer.addPointCloudModel(options);
break;
default:
throw new Error('Model is not supported');
}
viewer.fitCameraToModel(model);

Parameters

NameTypeDescription
modelIdnumberThe model's id.
revisionIdnumberThe model's revision id.

Returns

Promise<"" | SupportedModelTypes>

Empty string if type is not supported.

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:917


dispose

dispose(): void

Dispose of WebGL resources. Can be used to free up memory when the viewer is no longer in use.

See

https://threejs.org/docs/#manual/en/introduction/How-to-dispose-of-objects

// Viewer is no longer in use, free up memory
viewer.dispose();
```.

#### Returns

`void`

#### Defined in

[packages/api/src/public/migration/Cognite3DViewer.ts:427](https://github.com/cognitedata/reveal/blob/e9e26d38/viewer/packages/api/src/public/migration/Cognite3DViewer.ts#L427)

___

### enter360Image

▸ **enter360Image**(`image360`, `revision?`): `Promise`<`void`\>

Enter visualization of a 360 image.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `image360` | [`Image360`](/reveal-docs/docs/api/interfaces/cognite_reveal.Image360) | The 360 image to enter. |
| `revision?` | [`Image360Revision`](/reveal-docs/docs/api/interfaces/cognite_reveal.Image360Revision) | The image revision to use. If not provided the newest revision will be shown. |

#### Returns

`Promise`<`void`\>

#### Defined in

[packages/api/src/public/migration/Cognite3DViewer.ts:835](https://github.com/cognitedata/reveal/blob/e9e26d38/viewer/packages/api/src/public/migration/Cognite3DViewer.ts#L835)

___

### exit360Image

▸ **exit360Image**(): `void`

Exit visualization of the 360 image.

#### Returns

`void`

#### Defined in

[packages/api/src/public/migration/Cognite3DViewer.ts:845](https://github.com/cognitedata/reveal/blob/e9e26d38/viewer/packages/api/src/public/migration/Cognite3DViewer.ts#L845)

___

### fitCameraToBoundingBox

▸ **fitCameraToBoundingBox**(`box`, `duration?`, `radiusFactor?`): `void`

Move camera to a place where the content of a bounding box is visible to the camera.

**`Example`**

```js
// Fit camera to bounding box over 500 milliseconds
viewer.fitCameraToBoundingBox(boundingBox, 500);
// Fit camera to bounding box instantaneously
viewer.fitCameraToBoundingBox(boundingBox, 0);
// Place the camera closer to the bounding box
viewer.fitCameraToBoundingBox(boundingBox, 500, 2);

Parameters

NameTypeDefault valueDescription
boxBox3undefinedThe bounding box in world space.
duration?numberundefinedThe duration of the animation moving the camera. Set this to 0 (zero) to disable animation.
radiusFactornumber2The ratio of the distance from camera to center of box and radius of the box.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1142


fitCameraToModel

fitCameraToModel(model, duration?): void

Move camera to a place where the 3D model is visible. It uses the bounding box of the 3D model and calls fitCameraToBoundingBox.

Example

// Fit camera to model
viewer.fitCameraToModel(model);
// Fit camera to model over 500 milliseconds
viewer.fitCameraToModel(model, 500);
// Fit camera to model instantly
viewer.fitCameraToModel(model, 0);

Parameters

NameTypeDescription
modelCogniteModelThe 3D model.
duration?numberThe duration of the animation moving the camera. Set this to 0 (zero) to disable animation.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1097


fitCameraToModels

fitCameraToModels(models?, duration?, restrictToMostGeometry?): void

Move camera to a place where a set of 3D models are visible.

Parameters

NameTypeDefault valueDescription
models?CogniteModel[]undefinedOptional 3D models to focus the camera on. If no models are provided the camera will fit to all models.
duration?numberundefinedThe duration of the animation moving the camera. Set this to 0 (zero) to disable animation.
restrictToMostGeometrybooleanfalseIf true, attempt to remove junk geometry from the bounds to allow setting a good camera position.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1108


get360AnnotationIntersectionFromPixel

get360AnnotationIntersectionFromPixel(offsetX, offsetY): Promise<null | Image360AnnotationIntersection>

Check for intersections with 360 annotations through the given pixel. Similar to {getIntersectionFromPixel}, but checks 360 image annotations instead of models.

Parameters

NameType
offsetXnumber
offsetYnumber

Returns

Promise<null | Image360AnnotationIntersection>

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1381


getClippingPlanes

getClippingPlanes(): Plane[]

Returns the current active global clipping planes.

Deprecated

Use getGlobalClippingPlanes instead.

Returns

Plane[]

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1048


getGlobalClippingPlanes

getGlobalClippingPlanes(): Plane[]

Returns the current active global clipping planes.

Returns

Plane[]

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1055


getIntersectionFromPixel

getIntersectionFromPixel(offsetX, offsetY): Promise<null | Intersection>

Raycasting model(s) for finding where the ray intersects with the model.

See

https://en.wikipedia.org/wiki/Ray_casting For more details on Ray casting.

Example

For CAD model

const offsetX = 50 // pixels from the left
const offsetY = 100 // pixels from the top
const intersection = await viewer.getIntersectionFromPixel(offsetX, offsetY);
if (intersection) // it was a hit
console.log(
'You hit model ', intersection.model,
' at the node with tree index ', intersection.treeIndex,
' at this exact point ', intersection.point
);

Example

For point cloud

const offsetX = 50 // pixels from the left
const offsetY = 100 // pixels from the top
const intersection = await viewer.getIntersectionFromPixel(offsetX, offsetY);
if (intersection) // it was a hit
console.log(
'You hit model ', intersection.model,
' at the point index ', intersection.pointIndex,
' at this exact point ', intersection.point
);

Parameters

NameTypeDescription
offsetXnumberX coordinate in pixels (relative to the domElement).
offsetYnumberY coordinate in pixels (relative to the domElement).

Returns

Promise<null | Intersection>

A promise that if there was an intersection then return the intersection object - otherwise it returns null if there were no intersections.

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1364


getScreenshot

getScreenshot(width?, height?, includeUI?): Promise<string>

Take a screenshot from the current camera position. When drawing UI, only the viewer DOM element and its children will be included in the image. The DOM is scaled to fit any provided resolution, and as a result some elements can be positioned incorrectly in regards to the 3D render.

html2canvas is used to draw UI and this has some limitations on what CSS properties it is able to render. See the html2canvas documentation for details.

Example

// Take a screenshot with custom resolution
const url = await viewer.getScreenshot(1920, 1080);
// Add a screenshot with resolution of the canvas to the page
const url = await viewer.getScreenshot();
const image = document.createElement('img');
image.src = url;
document.body.appendChild(image);

Parameters

NameTypeDefault valueDescription
widthnumberundefinedWidth of the final image. Default is current canvas size.
heightnumberundefinedHeight of the final image. Default is current canvas size.
includeUIbooleantrueIf false the screenshot will include only the rendered 3D. Default is true.

Returns

Promise<string>

A Data URL of the image ('image/png').

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1234


getVersion

getVersion(): string

Returns reveal version installed.

Returns

string

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:400


getViewState

getViewState(): ViewerState

Gets the current viewer state which includes the camera pose as well as applied styling.

Returns

ViewerState

JSON object containing viewer state.

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:664


loadCameraFromModel

loadCameraFromModel(model): void

Attempts to load the camera settings from the settings stored for the provided model. See https://docs.cognite.com/api/v1/#operation/get3DRevision and https://docs.cognite.com/api/v1/#operation/update3DRevisions for information on how this setting is retrieved and stored. This setting can also be changed through the 3D models management interface in Cognite Fusion. If no camera configuration is stored in CDF, fitCameraToModel is used as a fallback.

Parameters

NameTypeDescription
modelCogniteModelThe model to load camera settings from.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1069


off

off(event, callback): void

Example

viewer.off('click', onClick);

Parameters

NameType
event"click" | "hover"
callbackPointerEventDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:563

off(event, callback): void

Example

viewer.off('cameraChange', onCameraChange);

Parameters

NameType
event"cameraChange"
callbackCameraChangeDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:570

off(event, callback): void

Example

viewer.off('cameraStop', onCameraStop);

Parameters

NameType
event"cameraStop"
callbackCameraStopDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:577

off(event, callback): void

Unsubscribe the 'beforeSceneRendered'-event previously subscribed with on.

Parameters

NameType
event"beforeSceneRendered"
callbackBeforeSceneRenderedDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:581

off(event, callback): void

Example

viewer.off('sceneRendered', updateStats);

Parameters

NameType
event"sceneRendered"
callbackSceneRenderedDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:588

off(event, callback): void

Example

viewer.off('disposed', clearAll);

Parameters

NameType
event"disposed"
callbackDisposedDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:595


on

on(event, callback): void

Triggered when the viewer is disposed. Listeners should clean up any resources held and remove the reference to the viewer.

Parameters

NameType
event"disposed"
callbackDisposedDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:467

on(event, callback): void

Example

const onClick = (event) => { console.log(event.offsetX, event.offsetY) };
viewer.on('click', onClick);

Parameters

NameType
event"click" | "hover"
callbackPointerEventDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:476

on(event, callback): void

Example

viewer.on('cameraChange', (position, target) => {
console.log('Camera changed: ', position, target);
});

Parameters

NameType
event"cameraChange"
callbackCameraChangeDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:485

on(event, callback): void

Example

viewer.on('cameraStop', () => {
console.log('Camera stopped');
});

Parameters

NameType
event"cameraStop"
callbackCameraStopDelegate

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:494

on(event, callback): void

Event that is triggered immediately before the scene is rendered.

Parameters

NameTypeDescription
event"beforeSceneRendered"Metadata about the rendering frame.
callbackBeforeSceneRenderedDelegateCallback to trigger when event occurs.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:500

on(event, callback): void

Event that is triggered immediately after the scene has been rendered.

Parameters

NameTypeDescription
event"sceneRendered"Metadata about the rendering frame.
callbackSceneRenderedDelegateCallback to trigger when the event occurs.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:506


remove360Images

remove360Images(...image360Entities): Promise<void>

Remove a set of 360 images.

Parameters

NameType
...image360EntitiesImage360[]

Returns

Promise<void>

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:823


removeModel

removeModel(model): void

Removes a model that was previously added using addModel, addCadModel or addPointCloudModel .

Parameters

NameType
modelCogniteModel

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:858


removeObject3D

removeObject3D(object): void

Remove a THREE.Object3D from the viewer.

Example

const sphere = new THREE.Mesh(new THREE.SphereGeometry(), new THREE.MeshBasicMaterial());
viewer.addObject3D(sphere);
viewer.removeObject3D(sphere);

Parameters

NameType
objectObject3D<Event>

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:970


requestRedraw

requestRedraw(): void

Typically used when you perform some changes and can't see them unless you move camera.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1149


setBackgroundColor

setBackgroundColor(backgroundColor): void

Sets the color used as the clear color of the renderer.

Parameters

NameType
backgroundColorObject
backgroundColor.alpha?number
backgroundColor.color?Color

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:985


setCameraManager

setCameraManager(cameraManager): void

Sets the active camera manager instance for current Cognite3Dviewer.

Parameters

NameTypeDescription
cameraManagerCameraManagerCamera manager instance.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:655


setClippingPlanes

setClippingPlanes(clippingPlanes): void

Sets per-pixel clipping planes. Pixels behind any of the planes will be sliced away.

Deprecated

Use setGlobalClippingPlanes instead.

Parameters

NameType
clippingPlanesPlane[]

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1040


setGlobalClippingPlanes

setGlobalClippingPlanes(clippingPlanes): void

Sets per-pixel clipping planes. Pixels behind any of the planes will be sliced away.

Example

// Hide pixels with values less than 0 in the x direction
const plane = new THREE.Plane(new THREE.Vector3(1, 0, 0), 0);
viewer.setGlobalClippingPlanes([plane]);
// Hide pixels with values greater than 20 in the x direction
const plane = new THREE.Plane(new THREE.Vector3(-1, 0, 0), 20);
viewer.setGlobalClippingPlanes([plane]);
// Hide pixels with values less than 0 in the x direction or greater than 0 in the y direction
const xPlane = new THREE.Plane(new THREE.Vector3(1, 0, 0), 0);
const yPlane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 0);
viewer.setGlobalClippingPlanes([xPlane, yPlane]);
// Hide pixels behind an arbitrary, non axis-aligned plane
const plane = new THREE.Plane(new THREE.Vector3(1.5, 20, -19), 20);
viewer.setGlobalClippingPlanes([plane]);
// Disable clipping planes
viewer.setGlobalClippingPlanes([]);

Parameters

NameTypeDescription
clippingPlanesPlane[]The planes to use for clipping.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1030


setLogLevel

setLogLevel(level): void

Sets the log level. Used for debugging. Defaults to 'none' (which is identical to 'silent').

Parameters

NameType
level"error" | "debug" | "none" | "trace" | "info" | "warn" | "silent"

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:409


setResolutionOptions

setResolutionOptions(options): void

Set options to control resolution of the viewer. This includes settings for max resolution and limiting resolution when moving the camera.

Parameters

NameTypeDescription
optionsResolutionOptionsOptions to apply.

Returns

void

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:387


setViewState

setViewState(state): Promise<void>

Restores camera settings from the state provided, and clears all current styled node collections and applies the state object.

Parameters

NameTypeDescription
stateViewerStateViewer state retrieved from getViewState.

Returns

Promise<void>

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:674


worldToScreen

worldToScreen(point, normalize?): null | Vector2

Convert a point in world space to its coordinates in the canvas. This can be used to place HTML objects near 3D objects on top of the 3D viewer.

See

https://www.w3schools.com/graphics/canvas_coordinates.asp For details on HTML Canvas Coordinates.

Example

const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId).getCenter(boundingBoxCenter);
// Screen coordinates of that point
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter);
const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId).getCenter(boundingBoxCenter);
// Screen coordinates of that point normalized in the range [0,1]
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter, true);
const boundingBoxCenter = new THREE.Vector3();
// Find center of bounding box in world space
model.getBoundingBox(nodeId).getCenter(boundingBoxCenter);
// Screen coordinates of that point
const screenCoordinates = viewer.worldToScreen(boundingBoxCenter);
if (screenCoordinates == null) {
// Object not visible on screen
} else {
// Object is visible on screen
}

Parameters

NameTypeDescription
pointVector3World space coordinate.
normalize?booleanOptional. If true, coordinates are normalized into [0,1]. If false, the values are in the range [0, <canvas_size>).

Returns

null | Vector2

Returns 2D coordinates if the point is visible on screen, or null if object is outside screen.

Defined in

packages/api/src/public/migration/Cognite3DViewer.ts:1187