@cognite/3d-viewer
    TypeScript icon, indicating that this package has built-in type declarations

    6.1.4 • Public • Published

    Cognite REVEAL 3D Web Viewer

    Visualize Cognite's 3D models in a web browser with WebGL.

    Note: The component will by default send anonymous usage statistics. This is used to improve the 3D viewer. You can opt out from this in the Cognite3DViewer constructor.

    Table of Contents

    Prerequisites

    You need to install the Cognite SDK which needs to be authenticated before loading the 3D viewer.

    Install

    Install the package with yarn:

    yarn add @cognite/3d-viewer
    

    or npm:

    npm install @cognite/3d-viewer
    

    Cognite Data Fusion

    To be able to use this 3D viewer you need to have access to Cognite Data Fusion. You can upload 3D models using Cognite 3D ingestor, or by looking at Cognite's API documentation. You can then use this viewer to visualize the 3D model in any web-based application on desktop or mobile devices.

    Usage

    import { Cognite3DViewer, THREE, TWEEN } from '@cognite/3d-viewer';
    //  If you are loading a local file, then just pass it in the localPath when you addModel:
    const viewer = new Cognite3DViewer();
    // If you are loading more than just local file, you would need to specify a sdk:
    const viewer = new Cognite3DViewer({ sdk: new CogniteClient({ ... }) })
    // Create three.js objects
    const vector = new THREE.Vector3();
    // Use TWEEN to animate e.g. the camera, see npmjs.com/package/@tweenjs/tween.js

    Requirements

    To be able to use this package you need the following polyfills:

    Sample code

    Adding model from CDF

    // The viewer will render to a canvas inside a wrapper container.
    // You can specify the wrapper by setting options.domElement and passing the options argument
    // to the Cognite3DViewer constructor. If not set, it will create a div element for you.
    const viewer = new Cognite3DViewer({ sdk: new CogniteClient({ ... }) });
     
    // You can then add the div to your existing DOM:
    document.body.appendChild(viewer.domElement);
     
    // At this point you will only see a black canvas.
     
    // So let's add a 3D model:
    const options = {
      modelId, // 3D model id
      revisionId, // The model's revision id
    };
    viewer.addModel(options).then(function(model) {
      // Move camera to look at the model
      viewer.fitCameraToModel(model, 0);
    });

    Adding local model

    // The viewer will render to a canvas inside a wrapper container.
    // You can specify the wrapper by setting options.domElement and passing the options argument
    // to the Cognite3DViewer constructor. If not set, it will create a div element for you.
    const viewer = new Cognite3DViewer();
     
    // You can then add the div to your existing DOM:
    document.body.appendChild(viewer.domElement);
     
    // At this point you will only see a black canvas.
     
    // So let's add a 3D model:
    const options = {
      localPath: '...',
    };
    viewer.addModel(options).then(function(model) {
      // Move camera to look at the model
      viewer.fitCameraToModel(model, 0);
    });

    Note: You may need additional styling to the wrapper div container to make it fit your use-case. By default, the wrapper will have this style:

     {
      width: 100vw;
      height: 100vh;
    }

    The internal canvas will be styled to fill this wrapper.

    Add progress listeners

    function onProgress(progress) {
      console.log(progress);
    }
     
    function onComplete() {
      console.log('Model loaded');
    }
     
    const options = {
      modelId,
      revisionId,
      onProgress, // optional
      onComplete, // optional
    };
    viewer.addModel(options)...

    Make the viewer clickable

    viewer.on('click', function(event) {
      const { offsetX, offsetY } = event;
      const intersection = viewer.getIntersectionFromPixel(offsetX, offsetY);
      if (intersection !== null) {
        const { nodeId, point, model } = intersection;
        console.log('User clicked at world coordinate', point);
        // highlight the object
        model.selectNode(nodeId);
        // make the camera zoom to the object
        const boundingBox = model.getBoundingBox(nodeId);
        viewer.fitCameraToBoundingBox(boundingBox, 2000); // 2 sec
      } else {
        // Clicked outside the 3D model
        model.deselectAllNodes();
      }
    });

    Load saved camera position from the API

    Assume you have the revision object from Cognite Data Fusion which you can get from this endpoint.

    Here is a code snippet to use the saved camera position:

    const { target, position } = revision.camera;
    if (Array.isArray(target) && Array.isArray(position)) {
      // Create three.js objects
      const positionVector = new THREE.Vector3(...position);
      const targetVector = new THREE.Vector3(...target);
      // Apply transformation matrix
      positionVector.applyMatrix4(model.matrix);
      targetVector.applyMatrix4(model.matrix);
      // Set on viewer
      viewer.setCameraPosition(positionVector);
      viewer.setCameraTarget(targetVector);
    } else {
      viewer.fitCameraToModel(model, 0);
    }

    API Reference

    Table of Contents

    Cognite3DViewer

    Cognite3DViewer is the root class of a Cognite 3D viewer. It controls all aspects of the 3D viewer.

    Parameters

    • options Object (optional, default {})
      • options.domElement Element? -- An existing DOM element that we will render into. This corresponds to the domElement property below.
      • options.noBackground boolean? -- Transparent background or not (optional, default false)
      • options.logMetrics boolean -- Send anonymous usage statistics. (optional, default true)
      • options.highlightColor boolean -- Highlight color of the selected objects (optional, default THREE.Color(0,0,1))
      • options.viewCube string? -- If defined then show a view cube and snap location of the view cube to this value. One of: 'topleft', 'topright', 'bottomleft', 'bottomright'.

    Examples

    const viewer = new Cognite3DViewer({
      noBackground: true,
      sdk: <Instance of CogniteClient>
    });

    dispose

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

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

    domElement

    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.

    isBrowserSupported

    Check if the viewer supports the current browser

    Examples
    if (!Cognite3DViewer.isBrowserSupported()) {
      // create an error message to the user?
    }

    on

    Add event listener to the viewer call off to remove an event listener

    Parameters
    • type string -- Event type ('click' or 'cameraChange')
    • func function (event:PointerEvent) -- The callback function
    Examples
    const onClick = event => { ... };
    viewer.on('click', onClick);
    viewer.on('cameraChange', (position, target) => {
      console.log('Camera changed: ', position, target);
    });

    off

    Remove event listener from the viewer call on to add an event listener

    Parameters
    • type string -- Event type ('click' or 'cameraChange')
    • func function -- The callback function used in on
    Examples
    viewer.off('click', onClick);

    addModel

    Add a new 3D model to the viewer. Call fitCameraToModel to focus camera on the model after it has loaded.

    Parameters
    • options Object (optional, default {})
      • options.modelId number -- The model's id
      • options.revisionId number -- The model's revision id
      • options.geometryFilter { boundingBox?: THREE.Box3 } -- Filter out geometries. We currently only support bounding box filter, i.e. load only geometries inside the given bounding box.
      • options.onProgress function (progress: Object)? -- Callback for progress events
      • options.onComplete function? -- Callback when the model is fully loaded
    Examples
    // Load a model and focus camera on the model
    const options = {
      modelId: 'COGNITE_3D_MODEL_ID',
      revisionId: 'COGNITE_3D_REVISION_ID',
    };
    viewer.addModel(options).then(model => {
      viewer.fitCameraToModel(model, 0);
    });
    // Load only geometries inside a bounding box, then focus camera on that area
    const boundingBox = new THREE.Box3(
      new THREE.Vector3(0, 0, 0),
      new THREE.Vector3(10, 10, 10)
    );
     
    const options = {
      modelId: 'COGNITE_3D_MODEL_ID',
      revisionId: 'COGNITE_3D_REVISION_ID',
      geometryFilter: { boundingBox },
    };
     
    viewer.addModel(options).then(model => {
      // Transform the bounding box to model space
      boundingBox.applyMatrix4(model.matrix);
      // Focus camera on bounding box
      viewer.fitCameraToBoundingBox(boundingBox);
    });

    Returns Promise<Cognite3DModel>

    addObject3D

    Add a THREE.Object3D to the viewer

    Parameters
    • object THREE.Object3D -- A three.js object
    Examples
    const sphere = new THREE.Mesh(
      new THREE.SphereBufferGeometry(),
      new THREE.MeshBasicMaterial()
    );
    viewer.addObject3D(sphere);

    removeObject3D

    Remove a THREE.Object3D from the viewer

    Parameters
    • object THREE.Object3D -- A three.js object
    Examples
    const sphere = new THREE.Mesh(
      new THREE.SphereBufferGeometry(),
      new THREE.MeshBasicMaterial()
    );
    viewer.addObject3D(sphere);
    viewer.removeObject3D(sphere);

    setSlicingPlanes

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

    Parameters
    • slicingPlanes THREE.Plane[] -- The planes to use for slicing
    Examples
    // Hide pixels with values less than 0 in the x direction
    const plane = new THREE.Plane(new THREE.Vector3(1, 0, 0), 0);
    viewer.setSlicingPlanes([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.setSlicingPlanes([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.setSlicingPlanes([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.setSlicingPlanes([plane]);
    // Disable slicing planes
    viewer.setSlicingPlanes([]);

    getCameraPosition

    Returns camera's position

    Examples
    const position = viewer.getCameraPosition();

    Returns THREE.Vector3 Position in world space

    getCameraTarget

    Returns camera's target

    Examples
    const target = viewer.getCameraTarget();

    Returns THREE.Vector3 Target in world space

    setCameraPosition

    Set camera's position

    Parameters
    • position THREE.Vector3 -- Position in world space
    Examples
    // store position, target
    const position = viewer.getCameraPosition();
    const target = viewer.getCameraTarget();
    // restore position, target
    viewer.setCameraPosition(position);
    viewer.setCameraTarget(target);

    setCameraTarget

    Set camera's target

    Parameters
    • target THREE.Vector3 -- Target in world space
    Examples
    // store position, target
    const position = viewer.getCameraPosition();
    const target = viewer.getCameraTarget();
    // restore position, target
    viewer.setCameraPosition(position);
    viewer.setCameraTarget(target);

    fitCameraToBoundingBox

    • See: getBoundingBox Move camera to a place where the content of a bounding box is visible to the camera.
    Parameters
    • box THREE.Box3 -- The bounding box in world space
    • duration number? -- The duration of the animation moving the camera. Set this to 0 (zero) to disable animation.
    • radiusFactor number? -- The ratio of the distance from camera to center of box and radius of the box (optional, default 4)
    Examples
    // Focus camera on bounding box over 500 milliseconds
    viewer.fitCameraToBoundingBox(boundingBox, 500);
    // Focus camera on bounding box instantaneously
    viewer.fitCameraToBoundingBox(boundingBox, 0);
    // Place the camera closer to the bounding box
    viewer.fitCameraToBoundingBox(boundingBox, 500, 2);
    // Animate camera to focus on a specific object with a given node id
    const nodeId = 1234;
    const boundingBox = model.getBoundingBox(nodeId);
    viewer.fitCameraToBoundingBox(boundingBox, 1000);

    disableKeyboardNavigation

    Disables camera navigation with the keyboard.

    Examples
    // Disable keyboard navigation on textbox focus
    inputElement.addEventListener('focus', () => {
      viewer.disableKeyboardNavigation();
    });

    enableKeyboardNavigation

    Enables camera navigation with the keyboard.

    Examples
    // Enable keyboard navigation on textbox blur
    inputElement.addEventListener('blur', () => {
      viewer.enableKeyboardNavigation();
    });

    fitCameraToModel

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

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

    worldToScreen

    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.

    Parameters
    • point THREE.Vector3 -- World space coordinate.
    • normalize bool? -- Optional. If true, coordinates are normalized into [0,1]. If false, the values are in the range [0, <canvas_size>). (optional, default false)
    Examples
    // Find canvas coordinates, i.e. where on the screen it is rendered, for an object with a given node id
    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);
    // Find normalized canvas coordinates, i.e. where on the screen it is rendered, for an object with a given node id
    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);
    // Find canvas coordinates, i.e. where on the screen it is rendered, for an object with a given node id
    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
    }

    Returns (THREE.Vector2 | null) -- Returns 2D coordinates if the point is visible on screen, or null if object is outside screen.

    getIntersectionFromPixel

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

    Parameters
    • x number -- X coordinate in pixels (relative to the domElement)
    • y number -- Y coordinate in pixels (relative to the domElement)
    • cognite3DModel Cognite3DModel? -- If specified then only give results for this model
    Examples
    const intersection = viewer.getIntersectionFromPixel(50, 100); // x = 50 pixels from the left, y = 100 pixels from the top
    if (intersection)
      // it was a hit
      console.log(
        'You hit model ',
        intersection.model,
        ' at the node with id ',
        intersection.nodeId,
        ' at this exact point ',
        intersection.point
      );

    Returns (Intersection | null) -- If there was an intersection then return the intersection object - otherwise it returns null if there was no intersections.

    getScreenshot

    Take screenshot from the current camera position.

    Examples
    // Add 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(url);
    // Take screenshot with custom resolution
    const url = await viewer.getScreenshot(1920, 1080);
    Parameters
    • width number? -- Width of the final image. Default is current canvas size.
    • height number? -- Height of the final image. Default is current canvas size.

    Returns Promise<string> A Blob URL to the image ('image/png')

    Intersection

    Type: object

    Properties

    • model Cognite3DModel -- The node id
    • nodeId number -- The nodeId of the first intersected node
    • point THREE.Vector3 -- The 3D position of the intersection point in the world coordinate system

    Cognite3DModel

    Extends THREE.Object3D

    Cognite3DModel is the class representing a Cognite 3D model and its state

    modelId

    The id of the model in Cognite Data Fusion

    revisionId

    The id of the model revision in Cognite Data Fusion

    getSubtreeNodeIds

    Get all node ids in a subtree where the root node has id 'nodeId'

    Parameters
    • nodeId number -- The ID of the root node
    • subtreeSize number? -- If you already know the subtreeSize, this will avoid an extra API call

    Returns [number] List of nodeIds in the subtree

    getBoundingBox

    Get bounding box of a node

    Parameters
    • nodeId number -- The node's id
    • box THREE.Box3? -- Optional target. Specify this to increase performance if the box can be reused.
    Examples
    const box = model.getBoundingBox(nodeId);
    const reusableBox = new THREE.Box3();
    const box = model.getBoundingBox(nodeId, reusableBox);
    // box === reusableBox

    Returns THREE.Box3

    iterateNodes

    Go through the node tree and apply an action to each node that has a node ID.

    Examples
    const url = await model.iterateNodes(console.log);
    Parameters
    • action Callback -- Callback function taking in a nodeId and treeId

    Returns void

    iterateSubtree

    Go through the subtree a node of the tree and apply an action to each subtree node that has a node ID.

    Examples
    const url = await viewer.iterateSubtree(1111111111, console.log);
    Parameters
    • nodeId number -- The id of the node whose subtree will have action applied to
    • action Callback -- Callback function taking in a nodeId and treeId
    • treeIndex? number -- (Optional) The index within the tree for the given nodeId
    • subtreeSiuze? number -- (Optional) The size of the subtree starting from nodeId

    Returns Promise<boolean> Whether a valid nodeId was given or not

    getNodeColor

    Return the color on a node.

    Parameters
    • nodeId number -- The node's id

    Returns {r: number, g: number, b: number} (r, g, b in the range [0, 255])

    setNodeColor

    Set the color on a node.

    Parameters
    • nodeId number -- The node's id
    • r number -- The red color value (0-255)
    • g number -- The green color value (0-255)
    • b number -- The blue color value (0-255)

    resetNodeColor

    Reset a node's color to its original color.

    Parameters
    • nodeId number -- The node's id

    selectNode

    Mark a node as selected. Only visible nodes can be selected.

    Parameters
    • nodeId number -- The node's id

    deselectNode

    Mark a node as deselected.

    Parameters
    • nodeId number -- The node's id

    deselectAllNodes

    Mark all selected nodes as deselected.

    showNode

    Show a node.

    Parameters
    • nodeId number -- The node's id

    showAllNodes

    Show all nodes.

    hideAllNodes

    Hide all nodes.

    Parameters
    • ghost bool -- Hide with ghost effect (optional, default false)

    hideNode

    Hide a node.

    Parameters
    • nodeId number -- The node's id
    • ghost bool -- Hide with ghost effect (optional, default false)

    Support

    For support contact mailto:support@cognite.com

    Install

    npm i @cognite/3d-viewer

    DownloadsWeekly Downloads

    741

    Version

    6.1.4

    License

    UNLICENSED

    Unpacked Size

    230 kB

    Total Files

    5

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar