Seeking Feedback💭 on the New Viewer API Structure

[alex]

Hey @Insiders ,

We have some exciting changes to our Viewer APIs, and we are eager to hear your thoughts and feedback! Your input is invaluable in shaping the future of the Speckle and the Viewer, and we want you to be a part of this conversation.

Why the change?

Our current API was originally developed with the needs of the Speckle Front-End in mind. This led to it being less open to other general-purpose applications and made it difficult to customize or develop on top of it.

Additionally, the current API only allows Speckle streams as input data, and we have seen the need for having traditional input sources like .gltf, .obj, .fbx, etc, or even custom non-standardised data formats.

Introducing Viewer API 2.0

We’re changing how you work with Viewer as a library by broadening the levels of APIs you can use. By breaking down Viewer API 1.0, into a core Viewer and Extensions, you now have access to API extensions and wider customization opportunities that were not available before.

You also have the possibility to extend the stock extensions and even create new ones, contributing to the Speckle ecosystem without limits.

This level of flexibility allows for better data manipulation and innovation. You can also make your own extensions and load any input data formats via customisable loaders and converters. Viewer will still work and look the same.

In a nutshell, Viewer API 2.0 will be split into:

• Viewer Core, which handles strictly basic internal workings of the Viewer and offers an API
• Viewer Extensions that handle specific functionalities, relying on Viewer Core and offering their own APIs

Your Feedback Matters!

We’re eager to hear your thoughts, suggestions, and concerns about this exciting transition. Your feedback will help us fine-tune the Viewer API 2.0 and ensure it meets your needs as developers.

Join us for our next Community StandUp, where we’ll provide a full explanation of the changes.

Stay tuned for more updates, and see you at the Community StandUp👋!

[haitheredavid (David Morgan)]

woot woot! thank you @alex and speckle crew looking forward to playing around!

[alex]

Hello,

In case some of you couldn’t make it to the community standup, I’ll leave here the links to the resources:

• Viewer API 2.0 Library @speckle/viewer - npm
• Quick Reference Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.

Code sandbox examples:

• Basic Setup
• Measurements Extension
• Obj Loader
• Expanding existing Extensions (Manipulating Objects)
• Custom Extension (Categorize)

Looking forward to your feedback!

Cheers

[gokermu (Mucahit Bilal GOKER)]

Did you miss out on the StandUp? No worries, we have got you covered! You can catch up on everything you missed by checking out Alex’s presentation and the full StandUp event on our YouTube channel. If you are interested in the new Viewer API, then you definitely don’t want to miss this👇!

Introducing Viewer API 2.0 - September 2023 Community StandUp

September 2023 Community Standup

[JoostGevaert]

Would it be possible to create a VTK visualization extension?

Visualization ToolKit (VTK) is a data standard, and open-source software that is especially useful for visualizing 3D data volumes, such as for example Computational Fluid Dynamics results (see Visualize simulation results in Speckle), or (uncertainty in) ground models (see VTK integration).

A 3D data volume is different from a 3D object in that for most 3D objects you only care about visualizing the outside of the object. Whereas, in the case of 3D data volumes, you want to be able to show scalar and vector fields for all points within the data volume, which means that you need to be able to cut sections, change opacity based on the values in a scalar field, draw flow lines based on a vector field, etc. VTK is an amazing data stabdard, and low-level open-source software for visualizing 3D data volumes.

ParaView is a desktop app that provides a GUI to explore VTK results. The issue with ParaView is that you can’t easily put the VTK results in context with the proposed and existing structures. Moreover, it’s of course not feasible to ask a project manager, or client to install ParaView such that they can explore the VTK results.

Considering all the above, I think it would be incredibly valuable to build a VTK extension for the Speckle viewer. There are several open-source frameworks and apps that use VTK, and that we could possibly use as a starting point or inspiration:

• Desktop: ParaView, 3D Slicer
• Python: PyVista, trame, Dash VTK (think plotly, Dash VTK uses react-vtk-js)
• Javascript: vtk.js, react-vtk-js

@TomSvilans, @sonomirco, @MaxT

[sanchez (Daniel Fitz)]

I have noticed that if you enable showStats param the canvas height becomes bigger than the parent dom element by a height approximately the same size as the showStats panel.

[alex]

Hello @Insiders

We’ve just release a new alpha version for viewer API 2.0!

Along with some fixed an improvements mentioned by you, this update includes support for hardware instancing. This will work together nicely with speckle instances as well as any other geometry you may wish to instance in your custom loaders!

The main benefits of hardware instancing are significant lower memory footprint as well as better runtime performance for streams containing instances.

Please note that instancing is a core feature of the viewer, still in it’s infancy, so you can expect some bugs here and there until it matures a bit. We will be focusing on stabilizing it.

As always, looking forward to your feedback!

Cheers

[vwb (Victor)]

Thank you @alex! In regards to loading an array of objects. We’ve been iterating through objectId’s we want to load, but if the array is large (e.g. +2000 ids of columns/beams etc) it becomes a bit slow and the tree structure doesn’t get as clean as loading from the root of a versionId.

Would you mind sharing your thoughts on these use case and what would be the most performant way of solving it?

[alex]

Hello @vwb

This is an interesting use case indeed! There are several things I need to mention, which will hopefully also be available in the soon upcoming new and improved viewer documentation

Generally speaking, correct viewer functionality needs to be preserved regardless of how you choose to load objects in. However there are some deliberate design choices we’ve made along the way which have an impact on performance when it comes to loading things one way or another.

The default SpeckleLoader will load the requested objects and store them as a distinct subtree under the worldtree root. The main reason you’re loosing performance when loading a lot of individual objects is becase the viewer only batches objects which belong to the same loaded subtree. Each call to loadObject will create it’s own subtree and objects inside it will never get batched together with other existing objects from other subtrees.

Because of the same reason mentioned above, you’ll get a very wide (and possibly short) world tree, but that’s not really such a big issue since it’s just a representation

To avoid loosing performance in scenarios where you need to selectively load multiple (and possibly a large amount) of object ids, I recommend you make your own loading routine instead of using the default loadObject and possibly extend SpeckleLoader. If you can provide me with a specific example, maybe I can even make a code sandbox for it

Cheers

[arnars (Anders Hallundbæk)]

Hi there,

I’m working with Gaiup Real Time LCA, and we want to use the new viewer as a main entry point for a lot of the stuff happening in our app. We really like the fact, that it’s been decoupled from speckle, and also the possibilities we have with extensions.

I’ve been tinkering a bit with it this morning, but it seems to be to unstable/documented to actually perform and use in our app at the moment.

Do you have any idea as to when it will become “more available” and better supported?

All the best,
Anders

[gokermu (Mucahit Bilal GOKER)]

Hey @arnars ,

Welcome to the community! Feel free to Introduce yourself to the community if you want to! Great to have another Real Time LCA team member here.

@arnars

I’ve been tinkering a bit with it this morning, but it seems to be to unstable/documented to actually perform and use in our app at the moment.

What do you mean by unstable/documented? Currently, we are in the process of replacing the current viewer with this one and also working on documenting it. If you are looking for a documentation, please refer to this quick reference guide written by @alex .

@alex

• Quick Reference Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.

[arnars (Anders Hallundbæk)]

It was perhaps written a bit harsher than it was meant!

I looked at the documentation, and the examples that the NPM refers to, but when I tried installing the latest version of the viewer, I got a message that e.g. CameraController was not part of “@speckle/viewer”.

So I reverted (for the sake of the POC that I am playing with), to the basic example/version from the Youtube where alex explains the changes and showcases the new API.

My thoughts were then that I would wait a bit, until there were som examples and not just a code repo “for the brave”

[alex]

Hi @arnars

You can find the latest viewer API 2.0 version on npm as 2.17.0-alpha.11

Some examples to get you started are linked on the same page, and I’ll put a few of them here as well:

• Basic Setup
• Measurements Extension
• Obj Loader
• Expanding an Extension (Manipulating Objects)
• Custom Extension (Categorize)

You can find additional examples on my codesandbox dashboard here. All sandboxes are live running examples of viewer API 2.0.

An important thing to note, is that API 2.0 is not a drop in update. If you have an application build with the old viewer API, updating to API 2.0 will not work out of the box. The good news is that the new viewer version also comes with a LegacyViewer implementation designed specifically to make API 1.0 to API 2.0 transition easier.

A very good example for viewer API 2.0 running in the wild is actually https://latest.speckle.systems/

Regarding official documentation, guides and examples, we’re working on it as we speak and will be publicly available very soon.

Let me know if I can help further with anything

Cheers

[arnars (Anders Hallundbæk)]

Thanks @alex - I’ll make sure to test it out a bit more thoroughly. I was playing around with 2.17.13 apparently.

We don’t have the old API implemented currently, so this will mark a new beginning for our app.

Good to hear with the documentation.

Is the code for latest.speckle.systems available anywhere?

Best,
Anders

[alex]

Glad to be of help @arnars !

latest.speckle.systems is the speckle frontend and it’s available here.

Not sure about the application you want to develop, but the speckle frontend is quite a complex project, so you might want to start with something more simple, like say the sandbox

Cheers

[arnars (Anders Hallundbæk)]

It would just be for examining the viewer and how it’s set up. But thanks for all the other references.

[alex]

Hello,

As of yesterday, Viewer API 2.0 is now available in the stable channel from version 2.18.1.

For those using the viewer in their applications and concerned about compatibility, we have good news! API 2.0 includes a built-in legacy implementation that emulates the old API precisely. By using the LegacyViewer, you can benefit from API 2.0’s numerous enhancements with minimal changes to your existing code. A quick migration guide will be available shortly.

We’re finalising the comprehensive documentation, which will be released soon.

We welcome any feedback you may have.

Cheers,

[alex]

Hello,

Following up on the previous post, here’s the link to the Migration Guide for anybody who is looking for backwards compatibility.

Cheers

[alex]

Hello,

We’re happy to announce that the viewer API complete documentation is available here:

Introduction | Speckle Docs

We will continue to keep it up to date and add more examples and information as we move along. As always you’re feedback is very important to us and we’re looking forward to hearing it

Cheers