Scenes API Overview

Introduction

The Scenes API allows you to create and quickly access the pre-defined digital twin views. With this API, you can define, organize, share, and retrieve scenes of an iTwin, all seamlessly curated from various associated data repositories.

Key Features

• Selectively hide or show iTwin repositories and their geometric content while also controlling how that content is presented.
• Store display information, such as camera positions and angles, layer ordering (which is especially useful for managing the display order of 2D data layers), cutout definitions for any 3D tiles-based data layer. Refer to the scenes-client for the complete list of supported functionality.
• Curate individual iTwin scenes or create scenes that involve multiple associated iTwins.

Workflow

To curate the required scene, follow these steps:

1. Create Scene: Use the Create scene endpoint scenes/?iTwinId={iTwinId} to establish a scene associated with the specified iTwin. You can include up to 100 initial objects during creation or utilize the Create scene objects endpoint scenes/{sceneId}/objects?iTwinId={iTwinId} to add objects incrementally.
2. Get Scene Metadata: Use the Get scene endpoint scenes/{sceneId}?iTwinId={iTwinId} to retrieve scene metadata and relevant links.
3. Get Scene Data: Use the Get scene objects endpoint scenes/{sceneId}/objects?iTwinId={iTwinId}[&orderBy] to retrieve paginated scene objects.

Use Cases

Effective visualization is crucial for making complex data understandable. In digital twins, it connects fragmented datasets into coherent narratives. Enhance your applications by integrating all necessary data into a cohesive visualization experience.

Multi-dimensional data management: Allow the audience to explore and understand complex iTwin(s) data seamlessly. For example, curating a scene to visualize combined reality data, parts of one iModel, together with specific categories enabled from a different iModel, alongside 4D schedules and a map layer for design or condition comparisons. Or create data groups on themes such as environmental data groups or cost categories, regardless of the data type.

Discipline-specific isolation: Tailor visualizations for targeted audiences by highlighting the most relevant data for their roles. Whether it's providing electricians with crucial wiring details or giving commercial managers easy access to floor plans, create focused scenes that enhance understanding without overwhelming distractions.

Interactive design presentations: Utilize scene capabilities to create engaging visual narratives. For example, visualize curated scenes sequentially to guide the audience through a journey.

Permissions

The combination of user roles and permissions determines the extent of access granted or the actions permitted.

Core principles:

• The Scenes API provides two permissions: SCENES_READ and SCENES_WRITE. These permissions give more precise control over the actions that users are allowed to perform. For instance, SCENES_WRITE enables users to create and edit a scene, while SCENES_READ allows to view the scene in read-only state.
• The Scenes API does not alter existing permission levels for referenced data or the users accessing it. For example, sharing a scene with a user does not change their current permissions for any iTwin or iTwin Repository they access.

Illustrative scenario

---

Consider a scene curated for iTwin A, structured as follows:

• Layer A: References iModel A from iTwin A
• Layer B: References iModel B from iTwin B
• Layer C: References Reality Data A from iTwin A

Assuming the following permissions for users accessing the scene:

• User X is a team member in both iTwin A and B, holding a role with SCENES_READ and imodels_read permissions.
• User Y is a team member only in iTwin A, with a role that includes SCENES_READ but lacks imodels_read permissions for iModel A.
• User Z does not have access to either iTwin A or iTwin B.

Expected access outcomes:

• User X will have read-only access to the scene and all associated data.
• User Y will have read-only access to the scene, but the response will exclude the iModel A repository due to insufficient imodels_read permissions.
• User Z will encounter a 404 error, reflecting the lack of access to either iTwin A or iTwin B.

For more information on Role-Based Access Control (RBAC) principles, refer to the Access Control API.

Client Packages

Open source TypeScript client packages are available:

• @itwin/scenes-client - NPM registry