Streamlines

The Autodesk.DataVisualization viewer extension now provides another neat feature: streamlines! Let's take a quick look at how you can use this new visualization tool.

First of all, what exactly is a streamline? We're not going to follow the exact definition from Merriam-Webster here. In our case, streamline is a (potentially animated) 3D polyline with customizable thickness, color, and opacity, that can be used to represent movement or flow of things - people, cars, particles, whatever have you. Just like with the Data Visualization heatmaps, this feature has been inspired by the popular research project https://dasher360.com.

Now, how do you use streamlines in your app? Start by obtaining a reference to the StreamLineBuilder singleton from the Autodesk.DataVisualization viewer extension:

const dataVizExt = viewer.getExtension('Autodesk.DataVisualization');
const streamlineBuilder = dataVizExt.streamLineBuilder;

The builder can then create individual streamlines with specific positions, thickness, color, and opacity:

const streamline = streamlineBuilder.createStreamLine({
    lineWidth: 10.0,
    lineColor: new THREE.Color(0.0, 0.5, 1.0),
    opacity: 0.8,
    lineData: {
        points: new Float32Array([
            0.0, 0.0, 0.0,
            10.0, 0.0, 0.0,
            10.0, 10.0, 0.0,
            20.0, 10.0, 0.0,
            20.0, 20.0, 0.0
        ])
    }
});

Once a streamline is created, you can "advance" it by adding another point to its end. To keep things efficient, this will automatically remove the first point from the list, so that the GPU buffers allocated for the streamline can maintain a fixed size.

streamline.advance({ x: 30.0, y: 20.0, z: 0.0 });

And when the streamline is no longer needed, the StreamLineBuilder singleton can also remove it for you:

streamlineBuilder.destroyStreamLine(streamline);

And that's it.

Here's a simple, ready-to-run sample showcasing the feature: https://github.com/petrbroz/forge-simple-viewer-nodejs/tree/sample/streamlines. If you want to give it a shot, clone the sample/streamlines branch of the repo locally:

git clone https://github.com/petrbroz/forge-simple-viewer-nodejs.git -b sample/streamlines

And then follow the steps in the README file. When you open the app and load a 3D model, clicking anywhere on the model will create a new streamline that will follow a "conical spiral" path for a while, and then disappear. The function that takes care of creating the streamline looks like this:

function addStreamline(viewer, origin, width, color, count = 64) {
    // Simple function generating points along a conical spiral
    function generatePoint(i) {
        const angle = 0.02 * Math.PI * i;
        return {
            x: origin.x + 0.01 * i * Math.cos(angle),
            y: origin.y + 0.01 * i * Math.sin(angle),
            z: origin.z + 0.005 * i
        };
    }

    // Generate a streamline with an initial set of points
    const dataVizExt = viewer.getExtension('Autodesk.DataVisualization');
    /** @type {Autodesk.DataVisualization.Core.StreamLineBuilder} */
    const streamlineBuilder = dataVizExt.streamLineBuilder;
    let i = 0;
    let points = [];
    for (i = 0; i < count; i++) {
        const { x, y, z } = generatePoint(i);
        points.push(x, y, z);
    }
    const streamline = streamlineBuilder.createStreamLine({
        lineWidth: width,
        lineColor: color,
        opacity: 0.8,
        lineData: {
            points: new Float32Array(points)
        }
    });

    // Advance the streamline by another point every 50ms
    const interval = setInterval(function () {
        const point = generatePoint(i++);
        streamline.advance(point);
        viewer.impl.invalidate(false, false, true);
        if (i > 512) {
            clearInterval(interval);
            streamlineBuilder.destroyStreamLine(streamline);
        }
    }, 50);
}

Btw. the sample source code also makes use of the awesome @types/forge-viewer TypeScript definitions for Forge Viewer maintained by our colleague @JanLiska. These include the definitions for the StreamLineBuilder class as well, so if you open this sample in Visual Studio Code, you get a nice intellisense, too!