The Speckle Viewer
Disclaimer
We're working to stabilize the 2.0 API, and until then there will be breaking changes.
Documentation
Comprehensive developer and user documentation can be found in our:
Getting started
Working with viewer (for more, check ./src/example.js
):
import { Viewer } from '@speckle/viewer'
const v = new Viewer({
container: document.getElementById('renderer'),
showStats: true
})
Development
For testing purposes you can see viewer in action by running npm run example
, which will run an example server at 'http://127.0.0.1:3002'.
To build the library run npm run build
, to build a dev (unminified w/ sourcemaps) build run npm run build:dev
and to run a dev build in watch mode run npm run dev
.
API
Syntax and examples for supported API methods. The examples assume a Viewer
instance named v
.
Load/Unload an object
v.loadObject( objectUrl )
/ v.unloadObject( objectUrl )
Example: v.loadObject( 'https://speckle.xyz/streams/3073b96e86/objects/e05c5834368931c9d9a4e2087b4da670' )
Get properties of loaded objects
v.getObjectsProperties()
This returns a dictionary with { propertyName: propertyInfo }
elements. The property information provided is:
-
type
( =='string'
/'number'
/'boolean'
): the property type -
objectCount
(int): How many objects in the scene have this property -
allValues
(array ofobjectCount
elements): The values for this property of all objects that have this property -
minValue
- the smallest value (using<
operator, works also on strings) -
maxValue
- the largest value -
uniqueValues
- a dictionary of{ uniqueValue: occurenceCount }
elements, secifying how many objects have the property set to that specific value
Filtering and coloring
Those calls filter and color the objects loaded in the scene, and drops the previous applied filters (filtering is not additive).
Syntax: await v.applyFilter( { filterBy, colorBy, ghostOthers } )
The 3 optional parameters are:
-
filterBy
: A dictionary that specify the filter. Elements are in the form{ propertyName: propertyValueFilter }
. The propertyValueFilter can be one of:- A specific value: (only objects with that property value pass the filter)
- An array of values: An object passes the filter if its value is in the array
- A range of values, specified by
{ 'gte': value1, 'lte': value2 }
(greater than or equal, lower than or equal) - An exclusion list, specified by
{ 'not': excludedValuesArray }
-
colorBy
: A dictionary that makes all objects colored based on a property value. Two types of coloring are supported:- Gradient (from a numeric property):
{ 'type': 'gradient', 'property': propertyName, 'minValue': propertyMinValue, 'maxValue': propertyMaxValue, 'gradientColors': [color1, color2], default: colorForObjectsWithMissingProperty }
- Category (for coloring each unique value differently):
{ 'type': 'category', 'property': propertyName, 'values': { value1: color1, value2: color2, ... }, 'default': colorForAnyOtherValue }
. Thevalues
and thedefault
parameters are optional: Random colors are generated if they are omitted.
- Gradient (from a numeric property):
-
ghostOthers
: A boolean (defaultfalse
). If set totrue
, then the objects that are filtered out are actually shown with very low opacity, so that the remaining objects have a better context.
For colorBy
, setting a color to null
will use the original material instead of coloring it.
To remove all filters: await v.applyFilter( null )
Community
If in trouble, the Speckle Community hangs out on the forum. Do join and introduce yourself! We're happy to help.
License
Unless otherwise described, the code in this repository is licensed under the Apache-2.0 License. If you have any questions, don't hesitate to get in touch with us via email.