InstanceCollection3D
Represents the full list of all instances of a model, and provides functions to access and manipulate them.
new InstanceCollection3D()
Methods
setVisibilityState(instanceId, state)
Set the visibility state (Visible, Hidden, Ghosted) of an instance.
Parameters
| instanceId* number | |
| state* |
Returns
| type | description |
|---|---|
| boolean | Whether this value changed |
getVisibilityState(instanceId)
Returns the visibility state (Visible, Hidden, Ghosted) of an instance.
Parameters
| instanceId* number |
Returns
| type | description |
|---|---|
| VisibilityState | The visibility state of the instance. |
setHighlighted(instanceId, value)
Set the highlighted state of an instance.
Parameters
| instanceId* number | |
| value* boolean | Whether the instance should be highlighted or not. |
Returns
| type | description |
|---|---|
| boolean | Whether the flag has changed |
setThemingColor(dbId, color)
Applies a theming color that is blended with the final instance color.
Parameters
| dbId* number | |
| color | theming color (in xyz) and intensity (in w). All components in [0,1]. Set to undefined for ‘no theming’ |
registerMaterialChangedCallback(callback)
Registers a callback that is invoked when the material of an instance is changed.
Parameters
| callback* | The callback to invoke on the event. |
removeMaterialChangedCallback(callback)
Deregisters a callback that has previously been registered via registerMaterialChangedCallback.
Parameters
| callback* | The callback to deregister. |
registerThemingColorChangedCallback(callback)
Registers a callback that is invoked when the theming color of an instance is changed.
Parameters
| callback* | The callback to invoke on the event. |
removeThemingColorChangedCallback(callback)
Deregisters a callback that has previously been registered via registerThemingColorChangedCallback.
Parameters
| callback* | The callback to deregister. |
registerHighlightingChangedCallback(callback)
Registers a callback that is invoked when the highlighting of an instance is changed.
Parameters
| callback* | The callback to invoke on the event. |
removeHighlightingChangedCallback(callback)
Deregisters a callback that has previously been registered via registerHighlightingChangedCallback.
Parameters
| callback* | The callback to deregister. |
registerVisibilityDirtyCallback(callback)
Registers a callback that is invoked when the visibility of any instance changes.
Parameters
| callback* | The callback to invoke on the event. |
removeVisibilityDirtyCallback(callback)
Deregisters a callback that has previously been registered via registerVisibilityDirtyCallback.
Parameters
| callback* | The callback to deregister. |
getMaterial(instanceId)
Returns the material for a specific instance. Materials that are not part of the public API (e.g. materials created by a model loader) are returned as Autodesk.Viewing.Scene.InternalMaterial, which can be passed to InstanceCollection3D#setMaterial or InstanceCollection3D#add.
Parameters
| instanceId* number |
Returns
| type | description |
|---|---|
| UnlitMaterial, StandardMaterial, LineMaterial, PointsMaterial, InternalMaterial, undefined | The material for the given instance, or undefined if no material is currently assigned to the instance. |
getGeometry(instanceId)
Returns the geometry for a specific instance.
Parameters
| instanceId* number |
Returns
| type | description |
|---|---|
| BufferGeometry, undefined | The geometry for the given instance, or undefined no geometry is currently assigned to the instance. |
setMaterial(instanceId, material)
Sets the material for a specific instance.
Parameters
| instanceId* number | |
| material* | The material to set for the given instance. |
Returns
| type | description |
|---|---|
| boolean | true, if the material was successfully set |
getMaxIndex()
Returns the highest instance id in the collection, or -1 if it is empty. Every instance has an id in [0, getMaxIndex()].
Note that remove() does not decrease this, so that ids stay stable. To get the number of instances that are still present, count them.
Returns
| type | description |
|---|---|
| number | The highest instance id. |
getDbId(instanceId)
Returns the dbId of a specific instance.
Parameters
| instanceId* number |
Returns
| type | description |
|---|---|
| number | The dbId of the given instance. |
setDbId(instanceId, dbId)
Assigns the dbId to an instance. Selecting, hiding or isolating the dbId affects the instance only if the dbId is a node of the model’s object tree.
Parameters
| instanceId* number | The instance to assign. |
| dbId number | If omitted, clears the dbId. |
getTransformWorld(instanceId, target)
Get the world transform of an instance.
Parameters
| instanceId* number | |
| target* | Target matrix to receive the result. |
Returns
| type | description |
|---|---|
| Matrix4 | The world matrix. |
getWorldBounds(instanceId, target)
Returns the world bounding box of an instance.
Parameters
| instanceId* number | |
| target* | result is saved here |
Returns
| type | description |
|---|---|
| Box3 | The world bounding box of the instance. |
registerTransformChangedCallback(callback)
Registers a callback that is invoked when the transform of an instance is changed. Important: This is to get notified about individual instance changes, it does not fire when the model matrix changes.
Parameters
| callback* | The callback to invoke on the event. |
removeTransformChangedCallback(callback)
Deregisters a callback that has previously been registered via registerTransformChangedCallback.
Parameters
| callback* | The callback to deregister. |
registerInstancesAddedCallback(callback)
Registers a callback that is invoked when instances are added via add().
Parameters
| callback* |
removeInstancesAddedCallback(callback)
Deregisters a callback previously registered via registerInstancesAddedCallback.
Parameters
| callback* |
registerInstancesRemovedCallback(callback)
Registers a callback that is invoked when instances are removed via remove().
Parameters
| callback* |
removeInstancesRemovedCallback(callback)
Deregisters a callback previously registered via registerInstancesRemovedCallback.
Parameters
| callback* |
registerGeometryChangedCallback(callback)
Registers a callback that is invoked when the geometry of an instance is changed via setGeometry().
Parameters
| callback* |
removeGeometryChangedCallback(callback)
Deregisters a callback previously registered via registerGeometryChangedCallback.
Parameters
| callback* |
setUsageHint(hint)
Sets how often the instances are expected to change. Defaults to Static for loaded models and Dynamic for programmatically created models.
Parameters
| hint* |
getUsageHint()
Gets how often the instances are expected to change.
Returns
| type | description |
|---|---|
| UsageHint | The usage hint set via InstanceCollection3D#setUsageHint. |
add(geometry, material, transform, bbox, dbId)
Add a new instance using the given geometry, materials and transform. If the geometry and material are not already in the model, they will be added. This transfers ownership of the geometry and material to the instance collection and the objects can change in the process.
Works on loaded and programmatically created models. On a loaded model, adding an instance reduces rendering performance until the model is optimized again, shortly after the last change. See InstanceCollection3D#setUsageHint.
Ids of loaded instances are never reused. The id of an instance removed after being added can be returned again.
Parameters
| geometry* | The geometry of the instance. |
| material* | The material of the instance. |
| transform | The transformation matrix of the instance. If not provided, it will be set to the identity matrix. |
| bbox | The bounding box of the instance relative to the model, if not provided, it will be computed. |
| dbId number | The dbId to assign to the instance. Same as calling #setDbId after adding. |
Returns
| type | description |
|---|---|
| number | The id of the new instance, -1 if the instance could not be added. |
remove(instanceIds)
Removes the instances from the collection. Unused geometries remain in the model and need to be removed manually.
Works on loaded and programmatically created models. Removing does not decrease getMaxIndex(), and only ids of added instances can be reused by a later add().
Parameters
| instanceIds* number, Array.<number> | The id or ids of instances to remove. |
addMaterial(material)
Add a material that can be referenced by an instance in the model. This transfers ownership of the material to the instance collection and the object can change in the process. A material is only added once and ignored after that.
Parameters
| material* | The material to add. |
Returns
| type | description |
|---|---|
| Material, InternalMaterial, null | The added material, or null if it could not be added because it is still in use by another model. |
addGeometry(geometry)
Adds a new geometry to the model and computes its bounding box if it is not already computed. This transfers ownership of the geometry to the instance collection and the object can change in the process. The geometry is only added once and ignored after that.
Parameters
| geometry* |
Returns
| type | description |
|---|---|
| BufferGeometry, null | The geometry. null if the geometry already belongs to another model. |
setGeometry(instanceId, geometry)
Set the geometry of an instance. It will replace the current instance geometry with the new one. If not already added, the geometry will be added to the collection.
Parameters
| instanceId* number | The id of the instance to set the geometry of. |
| geometry* | The geometry to set. |
Returns
| type | description |
|---|---|
| boolean | true, if the geometry was successfully set |
getTransformLocal(instanceId, target)
Get the model local transform of an instance.
Parameters
| instanceId* number | The id of the instance to get the transform of. |
| target* | The matrix to store the transform in. |
Returns
| type | description |
|---|---|
| Matrix4 | The transform of the instance. |
setTransformWorld(instanceId, transform)
Set the world transform of an instance.
Parameters
| instanceId* number | The id of the instance to set the transform of. |
| transform* | The world transform to set. |
setTransformLocal(instanceId, transform)
Set the model local transform of an instance.
Parameters
| instanceId* number | The id of the instance to set the transform of. |
| transform* | The local transform to set. |
getSceneGraph(create)
Returns the scene graph root node for the model. If create is true and the scene graph does not exist, it will be created.
Parameters
| create boolean | Whether to create the scene graph if it doesn’t exist. |
Returns
| type | description |
|---|---|
| Node3D, null | The scene graph root node. null if the scene graph is not created. |