Get Started

Welcome to the iTwin Platform

The iTwin Platform is a cloud-based ecosystem of APIs, tools, and services designed to create and manage digital twins, known as iTwins. These iTwins are virtual representations of physical assets, enabling users to monitor, analyze, and optimize their real-world counterparts. Whether you're working on infrastructure projects, industrial systems, or urban development, the iTwin Platform helps you unlock the full potential of your asset's digital twin.

Explore an example iTwin

---

Before we dive in, let’s take a quick tour of an iTwin. Below is an iTwin of a football stadium, rendered in an interactive web viewer.

Feel free to use the navigation tools on the top-right to explore the model. You can zoom, pan, rotate, and interact with the visualization.

The stadium above is visualized using the iTwin Viewer, a web-based tool from the iTwin Platform. The iTwin Viewer serves as a foundation for building custom iTwin Platform applications. With it, you can:

• Customize features to meet your project needs.
• Extend functionality with data overlays, real-time integrations, and more.
• Leverage iTwin Platform APIs to enrich your model with valuable functionality.

In this walkthrough, we will set up your very own iTwin Viewer for visualization. But first, we need to create an iTwin.

Create an iTwin

An iTwin is composed of various data types such as reality data, design data, IoT data, and more. This data is stored in specialized repositories. For design data, the iTwin Platform provides a dedicated repository called the iModel, which supports data from multiple engineering formats. For more details, see iTwin Platform concepts.

In this tutorial, we will focus on creating an iTwin and adding design data to its iModel.

You can create an iTwin and add data to it using the iTwin Platform APIs. However, the fastest way to create an iTwin is through the My iTwins portal. Follow these steps to get started:

1. Click your Profile button in the upper-right corner of the page and select My iTwins from the drop-down. If you don’t see your profile button, make sure you are logged in to your Bentley Account.
2. Click New to create a new iTwin.
3. Enter a name for your iTwin in the Name field.
4. Click Save.
5. An iTwin will be created, but initially, it will not have any iModels.
6. Click New under the iModel tab to create a new iModel.
7. Enter a name for your iModel in the Name field.
8. Select the iModel workflow you want to use.

Using a sample iModel

---

1. Select Bentley Sample.
2. Choose a sample from the Bentley iModel Template drop-down.
3. Click Save.
4. Once the iModel is created, you can select its tile to go to the iModel Home page.

Using your own design files

---

1. Select Empty iModel File.
2. Click Save.
3. On the iModel Home page, select the File Synchronization tile.
4. Click Upload file(s) and upload your design files.

Once you have successfully created your iTwin, be sure to capture the iTwin ID and iModel ID for referencing them in the iTwin Viewer later. You can get them by navigating to the iModel Home page, and clicking Copy IDs.

Now that we have an iTwin, we can start leveraging it in custom applications.

Register your Application

The iTwin Platform supports several application types:

• SPA: A single-page application where everything runs from a single web page.
• Web Apps: A traditional web application.
• Service: A machine-to-machine application that requires no user interaction.
• Desktop/Mobile: An application that runs natively on a user's device.

Our newly created iTwin can be used in any of the above application types. For this tutorial, we'll use the iTwin Viewer, which is an SPA. Before we can set up your iTwin Viewer, you'll need to register your application with the following steps.

1. Click your Profile button in the upper-right corner and select My Apps from the drop-down.
2. Click Register New.
3. Enter the name of your app.
4. Select the type of app you're registering: SPA.
5. Enter one or more Redirect URIs, including http://localhost:3000/signin-callback for running the app locally. These URIs specify where users will be redirected after signing in.

   http://localhost:3000/signin-callback
   

   Copy
6. (Optional) Enter one or more Post logout redirect URIs for redirection after signing out.
7. Click Register.
8. Copy the Client ID displayed under your app title for later use.

With your application now registered, you are ready to setup the iTwin Viewer on your local machine.

Setup the iTwin Viewer

Let's first setup your environment, and then the iTwin Viewer.

Prerequisites

---

In order you use the iTwin Viewer, ensure the following tools are installed on your machine.

Required tools

• Node.js (LTS version)
  This tool provides the backend JavaScript runtime necessary for running and rendering code. It also allows you to run NPM commands.

Recommended tools

• Google Chrome
  The recommended browser for developing and debugging frontend JavaScript applications.

• Visual Studio Code
  Our recommended code editor and debugger for developing iTwin.js applications. It's free, open source, and includes a GUI for working with Git.

• Git
  Git is the version control system used to manage your code.

Once your environment is set up, you are ready to use the iTwin Viewer react template.

iTwin Viewer Code

---

1. Open Terminal or Command Prompt.
2. In the terminal, run the following command:

   npx create-react-app your-app-name --template @itwin/web-viewer --scripts-version @bentley/react-scripts
   

   Copy
3. Replace "your-app-name" with the name you want to give your iTwin Viewer.
4. This will generate a new application based on the iTwin Viewer react template.

With the iTwin Viewer finally set up, you are ready to configure and run it to visualize iTwins.

Run your iTwin Viewer

Configure the Viewer

---

To configure the iTwin Viewer, open the .env file in the root of your project. It will include the following entries:

# ---- Authorization Client Settings ----
IMJS_AUTH_CLIENT_CLIENT_ID = ""
IMJS_AUTH_CLIENT_REDIRECT_URI = ""
IMJS_AUTH_CLIENT_LOGOUT_URI = ""
IMJS_AUTH_CLIENT_SCOPES ="imodelaccess:read imodels:read realitydata:read"
IMJS_AUTH_AUTHORITY="https://ims.bentley.com"

# ---- Test ids ----
IMJS_ITWIN_ID = ""
IMJS_IMODEL_ID = ""

1. Use the iTwin ID (IMJS_ITWIN_ID) and iModel ID (IMJS_IMODEL_ID) from the iTwin you created in create an iTwin.
2. Use the Client ID (IMJS_AUTH_CLIENT_CLIENT_ID) and Redirect URI (IMJS_AUTH_CLIENT_REDIRECT_URI) from the app you registered in register your application.

Run the Viewer

---

To run the iTwin Viewer:

1. Open a terminal in your app's directory.
2. In the terminal, enter:

   npm run start
   

   Copy

This will launch the viewer, which visualizes your iTwin. The viewer supports live reloading, so any changes you make are instantly reflected during development.

Next steps

You have successfully visualized your iTwin!

This is just the beginning. By leveraging the iTwin Platform, you can now explore endless possibilities, from adding custom functionality to integrating real-time data and beyond.