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:
- Revit to Notion✨| Embed Your BIM Models into Notion Pages
- Show Model SpeckBIM In Jupyter Notebook
- Jupyter Speckle! (part Deux) speckle
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
https://speckle.xyz/streams/35ad6a0c9c/commits/a18aca18e6?c=%5B4.87554,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
| Server | https://speckle.xyz/ |
| 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:
filter={
"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:
https::/[server]/embed?stream=[streamId]&commit=[commitId]&filter={propertyInfoKey=[propertyName]
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]
