How To: Customising the embedded viewer programmatically

I was asked today if the colour-by-property feature of the viewer was accessible programmatically with the embedded viewer feature.

There have been a few of content posts here and in our tutorials that show how the embedded viewer can be used to enrich your own reports, web pages or apps with Speckle data:

The Embedded Viewer is functionally the same as the one in the Speckle Web UI, it has some of the surrounding chrome removed. This means the colour-by-property functionality is still there.

As you spin a model, colour and filter it, and isolate or hide objects, you may notice many of the query parameter values in the URL update as you interact. This is your embedded viewer “API”

Worked example: Kevin Bacon’s palette pig house,5.29936,4.48789,0.21304,-0.28739,0.74446,0,1%5D&filter=%7B%22hiddenIds%22%3A%5B%220237e708512f25137af9e94d170a467a%22, … snip … ,%2283662090fa7a820fd6422c189ef2f15a%22%5D,%22propertyInfoKey%22%3A%22speckle_type%22%7D

The components you see in this URL can be used while using the embedded viewer to exercise control of it from your host page or app, by manipulating the iframe src URL.

The data source is straightforward enough, this commit on that stream on that server. Urls can be difficult to read as they are encoded. So to start I’ll decode it

Stream streams/35ad6a0c9c/
Commit commits/a18aca18e6
Camera c=[4.87554, 5.29936, 4.48789, 0.21304, -0.28739, 0.74446,0,1]
Filter { “hiddenIds”: [“0237e708512f25137af9e94d170a467a”, …snip …, “83662090fa7a820fd6422c189ef2f15a”], “propertyInfoKey”: “speckle_type” }

Looking at that filter object:

  "hiddenIds": [ ... snip ... ],
  "propertyInfoKey": "speckle_type"

So amongst the noise, the two active parameters are hiddenIds which is, as it suggests, a list of Object Ids present in the commit but to be hidden from the viewer. This is generated typically by clicking the hide icon on a property in the filter list, but if your app or script is interfacing Speckle via REST, C# or SpecklePy APIs, you could grab these programagically.

That second parameter: propertyInfoKey is the instruction to color-by-property. You’ll have to experiment with your particular datasets in full server viewer to work out what is available, but once you are comfortable with what is possible, that would be the target.

Recomposing what we have found, we can assemble the URL to source

A typical construction of embed view the same Speckle content would be:


Populating all those values from above gives:

You’ll notice that the colouring happens post-object-load, but you now have control over it just by changing the property in the URL.

Extra credit:

Where the additional query parameters are the features, you can elect to use or hide. You can play with them in the Share dialog:

Super Extra credit
It is also possible to feed a single KevinObject to the embedded viewer with the form https::/[server]/embed?stream=[streamId]&object=[objectId]&filter={propertyInfoKey=[propertyName]


Is there a different way of passing the filters through? As far as I know there is a limitation on how long a URL can be, up to 2048 characters.

If I had a model which had more than 2000 objects, it wouldn’t be able to filter them all.

Is there a way of pushing the parameters through a POST request and embedding these in the body??

Or what’s the workaround for this?

Nevermind, I tried with a model with over 30000 elements. And got a URL of 906,000 characters!!! Wild

Some browsers, some of the time, in particular contexts limit the url.

They do this because some servers, some of the time in particular contexts stop parsing urls at a particular length.

I shared your concern and was testing when you posted that it works :slight_smile:


To your other question, there is no other way to do this on a single commit in the embedded viewer.

For some uses, it may become advisable to curate your stream content. You could filter elements to a separate commits, color each by a common parameter and overlaying them that way in the viewer.

I think I’ll add this to a blog post / tutorial soon.

1 Like

@shuzmm & @jonathon there is a simple work around actually: create a comment with your specific filters/visibility toggles turned on, and share the link to that comment. This would bypass any crazy url length limits!

Check it live here:

And here’s a link to the comment directly: Speckle


@jonathon is there a way to control the initial view via the url? Say, set it to an ortho-top view on load?

1 Like

I’m afraid ortho mode (due to its complicated history) made its way back to Speckle, but the setting of the initial camera ignores it because of previous bugs (that Alex fixed) now. It’s encoded in the url, but it’s not respected! Should be an easy fix though :crossed_fingers:

1 Like

Keen to try it out when its fixed! :slightly_smiling_face: