Request

Response

    Autodesk.Viewing.Scene
    Version 8 preview
    This page documents a preview of the Viewer SDK v8. APIs and content can still change before the final release.

    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*
    * Required

    Returns

    typedescription
    boolean Whether this value changed

    getVisibilityState(instanceId)

    Returns the visibility state (Visible, Hidden, Ghosted) of an instance.

    Parameters

    instanceId*
    number
    * Required

    Returns

    typedescription
    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.
    * Required

    Returns

    typedescription
    boolean Whether the flag has changed

    setThemingColor(dbId, color)

    Applies a theming color that is blended with the final instance color.

    Parameters

    dbId*
    number
    colortheming color (in xyz) and intensity (in w). All components in [0,1]. Set to undefined for ‘no theming’
    * Required

    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.
    * Required

    removeMaterialChangedCallback(callback)

    Deregisters a callback that has previously been registered via registerMaterialChangedCallback.

    Parameters

    callback*The callback to deregister.
    * Required

    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.
    * Required

    removeThemingColorChangedCallback(callback)

    Deregisters a callback that has previously been registered via registerThemingColorChangedCallback.

    Parameters

    callback*The callback to deregister.
    * Required

    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.
    * Required

    removeHighlightingChangedCallback(callback)

    Deregisters a callback that has previously been registered via registerHighlightingChangedCallback.

    Parameters

    callback*The callback to deregister.
    * Required

    registerVisibilityDirtyCallback(callback)

    Registers a callback that is invoked when the visibility of any instance changes.

    Parameters

    callback*The callback to invoke on the event.
    * Required

    removeVisibilityDirtyCallback(callback)

    Deregisters a callback that has previously been registered via registerVisibilityDirtyCallback.

    Parameters

    callback*The callback to deregister.
    * Required

    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
    * Required

    Returns

    typedescription
    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
    * Required

    Returns

    typedescription
    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.
    * Required

    Returns

    typedescription
    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

    typedescription
    number The highest instance id.

    getDbId(instanceId)

    Returns the dbId of a specific instance.

    Parameters

    instanceId*
    number
    * Required

    Returns

    typedescription
    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.
    * Required

    getTransformWorld(instanceId, target)

    Get the world transform of an instance.

    Parameters

    instanceId*
    number
    target*Target matrix to receive the result.
    * Required

    Returns

    typedescription
    Matrix4 The world matrix.

    getWorldBounds(instanceId, target)

    Returns the world bounding box of an instance.

    Parameters

    instanceId*
    number
    target*result is saved here
    * Required

    Returns

    typedescription
    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.
    * Required

    removeTransformChangedCallback(callback)

    Deregisters a callback that has previously been registered via registerTransformChangedCallback.

    Parameters

    callback*The callback to deregister.
    * Required

    registerInstancesAddedCallback(callback)

    Registers a callback that is invoked when instances are added via add().

    Parameters

    callback*
    * Required

    removeInstancesAddedCallback(callback)

    Deregisters a callback previously registered via registerInstancesAddedCallback.

    Parameters

    callback*
    * Required

    registerInstancesRemovedCallback(callback)

    Registers a callback that is invoked when instances are removed via remove().

    Parameters

    callback*
    * Required

    removeInstancesRemovedCallback(callback)

    Deregisters a callback previously registered via registerInstancesRemovedCallback.

    Parameters

    callback*
    * Required

    registerGeometryChangedCallback(callback)

    Registers a callback that is invoked when the geometry of an instance is changed via setGeometry().

    Parameters

    callback*
    * Required

    removeGeometryChangedCallback(callback)

    Deregisters a callback previously registered via registerGeometryChangedCallback.

    Parameters

    callback*
    * Required

    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*
    * Required

    getUsageHint()

    Gets how often the instances are expected to change.

    Returns

    typedescription
    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.
    transformThe transformation matrix of the instance. If not provided, it will be set to the identity matrix.
    bboxThe 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.
    * Required

    Returns

    typedescription
    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.
    * Required

    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.
    * Required

    Returns

    typedescription
    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*
    * Required

    Returns

    typedescription
    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.
    * Required

    Returns

    typedescription
    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.
    * Required

    Returns

    typedescription
    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.
    * Required

    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.
    * Required

    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

    typedescription
    Node3D, null The scene graph root node. null if the scene graph is not created.