Quickstart - Get started with 3D Scenes Studio (preview) for Azure Digital Twins

Azure Digital Twins 3D Scenes Studio (preview) is an immersive 3D environment, where business and front-line workers can consume and investigate operational data from their Azure Digital Twins solutions with visual context.

In this article, you'll set up all the required resources for using 3D Scenes Studio, including an Azure Digital Twins instance with sample data, and Azure storage resources. Then, you'll create a scene in the studio that's connected to the sample Azure Digital Twins environment.

This sample scene used in this quickstart monitors the carrying efficiency of robotic arms in a factory. The robotic arms pick up a certain number of boxes each hour, while video cameras monitor each of the arms to detect if the arm failed to pick up a box. Each arm has an associated digital twin in Azure Digital Twins, and the digital twins are updated with data whenever an arm misses a box. Given this scenario, this quickstart walks through setting up a 3D scene to visualize the arms in the factory, along with visual alerts each time a box is missed.

The scene will look like this:

Screenshot of a sample scene in 3D Scenes Studio.

Prerequisites

You'll need an Azure subscription to complete this quickstart. If you don't have one already, create one for free now.

You'll also need to download a sample glTF (Graphics Language Transmission Format) 3D file to use for the scene in this quickstart. Select this link to download RobotArms.glb.

Set up Azure Digital Twins and sample data

The first step in working with Azure Digital Twins is to create an Azure Digital Twins instance. After you create an instance of the service, you can link the instance to a 3D Scenes Studio visualization later in the quickstart.

The rest of this section walks you through the instance creation. If you already have an Azure Digital Twins instance set up from an earlier quickstart, you can skip to the next section.

Create an Azure Digital Twins instance

In this section, you'll create a new instance of Azure Digital Twins using the Azure portal. Navigate to the portal and log in with your credentials.

  1. Once in the portal, start by selecting Create a resource in the Azure services home page menu.

    Screenshot of the Azure portal, highlighting the 'Create a resource' icon from the home page.

  2. Search for azure digital twins in the search box, and choose the Azure Digital Twins service from the results.

    Leave the Plan field set to Azure Digital Twins and select the Create button to start creating a new instance of the service.

    Screenshot of the Azure portal, highlighting the 'Create' button from the Azure Digital Twins service page.

  1. Fill in the fields on the Basics tab of setup, including your Subscription, Resource group, a Resource name for your new instance, and Region. Check the Assign Azure Digital Twins Data Owner Role box to give yourself permissions to manage data in the instance.

    Screenshot of the Create Resource process for Azure Digital Twins in the Azure portal. The described values are filled in.

    Note

    If the Assign Azure Digital Twins Data Owner Role box is greyed out, it means you don't have permissions in your Azure subscription to manage user access to resources. You can continue creating the instance in this section, and then should have someone with the necessary permissions assign you this role on the instance before completing the rest of this quickstart.

    Common roles that meet this requirement are Owner, Account admin, or the combination of User Access Administrator and Contributor.

  2. Select Review + Create to finish creating your instance.

  3. You will see a summary page showing the details you've entered. Confirm and create the instance by selecting Create.

This will take you to an Overview page tracking the deployment status of the instance.

Screenshot of the deployment page for Azure Digital Twins in the Azure portal. The page indicates that deployment is in progress.

Wait for the page to say that your deployment is complete.

Collect host name

After deployment completes, use the Go to resource button to navigate to the instance's Overview page in the portal.

Screenshot of the deployment page for Azure Digital Twins in the Azure portal. The page indicates that deployment is complete.

Next, take note of the instance's host name value to use later.

Screenshot of the Azure portal showing the Overview page for an Azure Digital Twins instance. The host name is highlighted.

Generate sample models and twins

In this section, you'll use the Azure Digital Twins data simulator tool to generate sample models and twins to populate your instance. Then, you'll use the simulator to stream sample data to the twins in the graph.

Note

Models, twins, and simulated data are provided for you in this quickstart to simplify the process of creating an environment that you can view in 3D Scenes Studio. When designing your own complete Azure Digital Twins solution, you'll create models and twins yourself to describe your own environment in detail, and set up your own data flows accordingly.

This sample scenario represents a package distribution center that contains six robotic arms. Each arm has a digital twin with properties to track how many boxes the arm fails to pick up, along with the IDs of the missed boxes.

  1. Navigate to the data simulator in your web browser.

  2. In the Instance URL space, enter the host name of your Azure Digital Twins instance from the previous section. Set the Simulation Type to Robot Arms.

  3. Use the Generate environment button to create a sample environment with models and twins. (If you already have models and twins in your instance, this will not delete them, it will just add more.)

    Screenshot of the Azure Digital Twins Data simulator. The Generate environment button is highlighted.

  4. Select Start simulation to start sending simulated data to your Azure Digital Twins instance. The simulation will only run while this window is open and the Start simulation option is active.

You can view the models and graph that have been created by using the Azure Digital Twins Explorer Graph tool. To switch to that tool, select the Graph icon from the left menu.

Screenshot of the Azure Digital Twins Data simulator where the button to switch to the Graph experience is highlighted.

Then, use the Run Query button to query for all the twins and relationships that have been created in the instance.

Screenshot of the Azure Digital Twins Explorer highlighting the Run Query button in the upper-right corner of the window.

You can select each twin to view them in more detail.

To see the models that have been uploaded and how they relate to each other, select Model graph.

Screenshot of the Azure Digital Twins Explorer highlighting the Model Graph button for the view pane.

Tip

For an introduction to Azure Digital Twins Explorer, see the quickstart Get started with Azure Digital Twins Explorer.

Create storage resources

Next, create a new storage account and a container in the storage account. 3D Scenes Studio will use this storage container to store your 3D file and configuration information.

You'll also set up read and write permissions to the storage account. In order to set these backing resources up quickly, this section uses the Azure Cloud Shell.

  1. Navigate to the Cloud Shell in your browser.

    Run the following command to set the CLI context to your subscription for this session.

    az account set --subscription "<your-Azure-subscription-ID>"
    
  2. Run the following command to create a storage account in your subscription. The command contains placeholders for you to enter a name and choose a region for your storage account, as well as a placeholder for your resource group.

    az storage account create --resource-group <your-resource-group> --name <name-for-your-storage-account> --location <region> --sku Standard_RAGRS
    

    When the command completes successfully, you'll see details of your new storage account in the output. Look for the ID value in the output and copy it to use in the next command.

    Screenshot of Cloud Shell output. The I D of the storage account is highlighted.

  3. Run the following command to grant yourself the Storage Blob Data Owner on the storage account. This level of access will allow you to perform both read and write operations in 3D Scenes Studio. The command contains placeholders for the email associated with your Azure account and the ID of your storage account that you copied in the previous step.

    az role assignment create --role "Storage Blob Data Owner" --assignee <your-Azure-email> --scope <ID-of-your-storage-account>
    

    When the command completes successfully, you'll see details of the role assignment in the output.

  4. Run the following command to configure CORS for your storage account. This will be necessary for 3D Scenes Studio to access your storage container. The command contains a placeholder for the name of your storage account.

    az storage cors add --services b --methods GET OPTIONS POST PUT --origins https://explorer.digitaltwins.azure.net --allowed-headers Authorization x-ms-version x-ms-blob-type --account-name <your-storage-account>
    

    This command doesn't have any output.

  5. Run the following command to create a private container in the storage account. Your 3D Scenes Studio files will be stored here. The command contains a placeholder for you to enter a name for your storage container, and a placeholder for the name of your storage account.

    az storage container create --name <name-for-your-container> --public-access off --account-name <your-storage-account>
    

    When the command completes successfully, the output will show "created": true.

Initialize your 3D Scenes Studio environment

Now that all your resources are set up, you can use them to create an environment in 3D Scenes Studio. In this section, you'll create a scene and customize it for the sample graph that's in your Azure Digital Twins instance.

  1. Navigate to the 3D Scenes Studio. The studio will open, connected to the Azure Digital Twins instance that you accessed last in the Azure Digital Twins Explorer. Dismiss the welcome demo.

    Screenshot of 3D Scenes Studio with welcome demo.

  2. Select the Edit icon next to the instance name to configure the instance and storage container details.

    Screenshot of 3D Scenes Studio highlighting the edit environment icon, which looks like a pencil.

    1. For the Azure Digital Twins instance URL, fill the host name of your instance from the Collect host name step into this URL: https://<your-instance-host-name>.

    2. For the Azure Storage container URL, fill the names of your storage account and container from the Create storage resources step into this URL: https://<your-storage-account>.blob.core.windows.net/<your-container>.

    3. Select Save.

    Screenshot of 3D Scenes Studio highlighting the Save button for the environment.

Add a new 3D scene

In this section you'll create a new 3D scene, using the RobotArms.glb 3D model file you downloaded earlier in Prerequisites. A scene consists of a 3D model file, and a configuration file that's created for you automatically.

This sample scene contains a visualization of the distribution center and its arms. You'll connect this visualization to the sample twins you created in the Generate sample models and twins step, and customize the data-driven view in later steps.

  1. Select the Add 3D scene button to start creating a new scene. Enter a Name and Description for your scene, and select Upload file.

    Screenshot of the Create new scene process in 3D Scenes Studio.

  2. Browse for the RobotArms.glb file on your computer and open it. Select Create.

    Screenshot of creating a new scene in 3D Scenes Studio. The robot arms file has been uploaded and the Create button is highlighted.

    Once the file is uploaded, you'll see it listed back on the main screen of 3D Scenes Studio.

  3. Select the scene to open and view it. The scene will open in Build mode.

    Screenshot of the factory scene in 3D Scenes Studio.

Create a scene element

Next, you'll define an element in the 3D visualization and link it to a twin in the Azure Digital Twins graph you set up earlier.

  1. Select any robotic arm in the scene visualization. This will bring up the possible element actions. Select + Create new element.

    Screenshot of the factory scene in 3D Scenes Studio. A robotic arm is highlighted with an option to create a new element.

  2. In the New element panel, the Primary twin dropdown list contains names of all the twins in the connected Azure Digital Twins instance.

    1. Select Arm1. This will automatically apply the digital twin ID ($dtId) as the element name.

    2. Select Create element.

    Screenshot of the New element options in 3D Scenes Studio.

The element will now show up in the list of elements for the scene.

Create a behavior

Next, you'll create a behavior for the element. These behaviors allow you to customize the element's data visuals and the associated business logic. Then, you can explore these data visuals to understand the state of the physical environment.

  1. Switch to the Behaviors list and select New behavior.

    Screenshot of the New behavior button in 3D Scenes Studio.

  2. For Display name, enter Packing Line Efficiency. Under Elements, select Arm1.

    Screenshot of the New behavior options in 3D Scenes Studio, showing the Elements options.

  3. Skip the Twins tab, which isn't used in this quickstart. Switch to the Status tab. States are data-driven overlays on your elements to indicate the health or status of the element. Here, you'll set value ranges for a property on the element and associate certain colors with each range.

    1. Keep the Property expression on Single property and open the property dropdown list. It contains names of all the properties on the primary twin for the Arm1 element. Select FailedPickupsLastHr.

    2. In this sample scenario, you want to flag that an arm that misses three or more pickups in an hour requires maintenance, and an arm that misses one or two pickups may require maintenance in the future. Set two value ranges so that values 1-3 appear in one color, and values 3-Infinity appear in another (the min range value is inclusive, and the max value is exclusive).

    Screenshot of the New behavior options in 3D Scenes Studio, showing the Status options.

  4. Switch to the Alerts tab. Alerts help grab your attention to quickly understand that some situation is active for the associated element. Here, you'll create an alert badge that will appear when an arm fails to pick up a package. The primary arm twin has a property PickupFailedAlert that we will use to create a visual alert in the scene.

    1. For the Trigger expression, enter PrimaryTwin.PickupFailedAlert. PickupFailedAlert is a property on the primary twin that is set to True when a pickup was failed. Using it as the trigger expression means this alert will appear whenever the property value is True.

    2. Set the badge Icon and Color. For Scenario description, enter ${PrimaryTwin.PickupFailedBoxID} was missed, please track down this box and remediate. This will use the primary twin's property PickupFailedBoxID to display a message about which box the arm failed to pick up.

    Screenshot of the New behavior options in 3D Scenes Studio, showing the Alerts options.

  5. Switch to the Widgets tab. Widgets are data-driven visuals that provide additional context and data, to help you understand the scenario that the behavior represents. Here, you'll add two visual widgets to display property information for the arm element.

    1. First, create a widget to display a gauge of the arm's hydraulic pressure value.

      1. Select Add widget.

        Screenshot of the New behavior options in 3D Scenes Studio, showing the Widgets options.

        From the Widget library, select the Gauge widget and then Add widget.

      2. In the New widget options, add a Display name of Hydraulic Pressure, a Unit of measure of m/s, and a single-property Property expression of PrimaryTwin.HydraulicPressure.

        Set three value ranges so that values 0-40 appear one color, 40-80 appear in a second color, and 80-Infinity appear in a third color (remember that the min range value is inclusive, and the max value is exclusive).

      3. Select Create widget.

      Screenshot of the New widget options in 3D Scenes Studio for the gauge widget.

    2. Next, create a widget with a link to a live camera stream of the arm.

      1. Select Add widget. From the Widget library, select the Link widget and then Add widget.

      2. In the New widget options, enter a Label of Live arm camera. For the URL, you can use the example URL http://contoso.aws.armstreams.com/${PrimaryTwin.$dtId}. (There's no live camera hosted at the URL for this sample, but the link represents where the video feed might be hosted in a real scenario.)

      3. Select Create widget.

      Screenshot of the New widget options in 3D Scenes Studio for a link widget.

  6. The behavior options are now complete. Save the behavior by selecting Create behavior.

    Screenshot of the New behavior options in 3D Scenes Studio, highlighting Create behavior.

The Packing Line Efficiency behavior will now show up in the list of behaviors for the scene.

View scene

So far, you've been working with 3D Scenes Studio in Build mode. Now, switch the mode to View.

Screenshot of the factory scene in 3D Scenes Studio, highlighting the View mode button.

From the list of Elements, select the Arm1 element that you created. The visualization will zoom in to show the visual element and display the behaviors you set up for it.

Screenshot of the factory scene in 3D Scenes Studio, showing the viewer for the arm.

Apply behavior to additional elements

Sometimes, an environment might contain multiple similar elements, which should all display similarly in the visualization (like the six different robot arms in this example). Now that you've created a behavior for one arm and confirmed what it looks like in the viewer, this section will show you how to quickly add the behavior to other arms so that they all display the same type of information in the viewer.

  1. Return to Build mode. Like you did in Create a scene element, select a different arm in the visualization, and select Create new element. Screenshot of the factory scene in 3D Scenes Studio. A different arm is highlighted with an option to create a new element.

  2. Select a Primary twin for the new element, then switch to the Behaviors tab. Screenshot of the New element options for Arm2 in 3D Scenes Studio.

  3. Select Add behavior. Choose the Packing Line Efficiency behavior that you created in this quickstart. Screenshot of the New element behavior options for Arm2 in 3D Scenes Studio.

  4. Select Create element to finish creating the new arm element.

Switch to the View tab to see the behavior working on the new arm element. All the information you selected when creating the behavior is now available for both of the arm elements in the scene.

Screenshot of the factory scene in 3D Scenes Studio, showing the viewer for the second arm.

Tip

If you'd like, you can repeat the steps in this section to create elements for the remaining four arms, and apply the behavior to all of them to make the visualization complete.

Review and contextualize learnings

This quickstart shows how to create an immersive dashboard for Azure Digital Twins data, to share with end users and increase access to important insights about your real world environment.

In the quickstart, you created a sample 3D scene to represent a package distribution center with robotic arms that pick up packages. This visualization was connected to a digital twin graph, and you linked an arm in the visualization to its own specific digital twin that supplied backing data. You also created a visual behavior to display key information about that arm when viewing the full scene, including which box pickups have been failed by that arm in the last hour.

In this quickstart, the sample models and twins for the factory scenario were quickly created for you, using the Azure Digital Twins Data simulator. When using Azure Digital Twins with your own environment, you'll create your own models and twins to accurately describe the elements of your environment in detail. This quickstart also used the data simulator to simulate "live" data driving digital twin property updates when packages were missed. When using Azure Digital Twins with your own environment, ingesting live data is a process you'll set up yourself according to your own environment sensors.

Clean up resources

To clean up after this quickstart, choose which Azure Digital Twins resources you want to remove, based on what you want to do next.

  • If you plan to continue to the Azure Digital Twins tutorials, you can reuse the instance in this quickstart for those articles, and you don't need to remove it.
  • If you want to continue using the Azure Digital Twins instance you set up in this article, but clear out some or all of its models, twins, and relationships, you can use the az dt CLI commands in an Azure Cloud Shell window to delete the elements you want to remove.
  • If you don't need your Azure Digital Twins instance anymore, you can delete it using the Azure portal.

    Navigate back to the instance's Overview page in the portal. (If you've already closed that tab, you can find the instance again by searching for its name in the Azure portal search bar and selecting it from the search results.)

    Select Delete to delete the instance, including all of its models and twins.

    Screenshot of the Overview page for an Azure Digital Twins instance in the Azure portal. The Delete button is highlighted.

You can delete your storage resources by navigating to your storage account's Overview page in the Azure portal, and selecting Delete. This will delete the storage account and the container inside it, along with the 3D scene files that were in the container.

Screenshot of the Overview page for an Azure storage account in the Azure portal. The Delete button is highlighted.

You may also want to delete the downloaded sample 3D file from your local machine.

Next steps

Next, continue on to the Azure Digital Twins tutorials to build out your own Azure Digital Twins environment.