Matterport Showcase SDK

https://matterport.github.io/showcase-sdk
Admin
The Matterport Showcase SDK is a JavaScript library that allows third-party developers to deeply...
Tokens:161,244
Snippets:1,504
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full SDK Integration Example

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent.html

Complete setup including HTML element configuration and JavaScript event handling.

```html
<matterport-viewer
  m="YOUR_MODEL_SID"
  application-key="YOUR_APPLICATION_KEY"
></matterport-viewer>
```

```javascript
import '@matterport/webcomponent';

const viewer = document.querySelector('matterport-viewer');
viewer.addEventListener('mpSdkPlaying', async (evt) => {
  const mpSdk = evt.detail.mpSdk;
  /* do something with mpSdk... */
});
```

--------------------------------

### Clone and install tutorial repository

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_setup.html

Commands to clone the repository and install dependencies using either SSH or HTTPS.

```bash
> git clone git@github.com:matterport/showcase-sdk-tutorial.git
> cd showcase-sdk-tutorial
> yarn install
```

```bash
> git clone https://github.com/matterport/showcase-sdk-tutorial.git
> cd showcase-sdk-tutorial
> yarn install
```

--------------------------------

### Start development server

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_setup.html

Launches the webpack-dev-server to host the local environment.

```bash
> yarn start
```

--------------------------------

### start

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/interfaces/scene.inode.html

Transitions the node to the Operating state.

```APIDOC
## start()

### Description
Transitions the node to Operating if it is in the Initializing state. Calling this function has no effect if the node is already Operating.

### Returns
- **void**
```

--------------------------------

### Install SDK Package

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

Commands to install the SDK using npm or yarn.

```bash
# npm
npm install @matterport/sdk

# yarn
yarn add @matterport/sdk
```

--------------------------------

### Run Development Server

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

Commands to start the development server.

```bash
# npm
npm run dev

# yarn 
yarn dev
```

--------------------------------

### start

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/interfaces/scene.iobject.html

Starts all nodes referenced by the scene object.

```APIDOC
## start

### Description
Starts all nodes referenced by this scene object.

### Signature
- `start(): void`

### Returns
- **void**
```

--------------------------------

### Full index.js Initialization

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

The complete index.js file after initial setup.

```javascript
import { setupSdk } from '@matterport/sdk'

const main = async () => {
  // Initialize SDK here
  const mpSdk = await setupSdk('yourSdkKey')
}
main().catch(err => console.error('Error:', err))
```

--------------------------------

### Install Three.js

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent_tutorial.html

Install the specific version of Three.js required by the SDK.

```bash
# yarn
yarn add three@0.151

# npm
npm install three@0.151
```

--------------------------------

### Project Structure

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

The expected file structure after initial setup.

```text
| node_modules
| index.js
| package.json
| webpack.config.json
```

--------------------------------

### Start the tour

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/modules/tour.html

Starts the tour, optionally beginning at a specific index.

```javascript
const tourIndex = 1;

mpSdk.Tour.start(tourIndex)
  .then(function() {
    // Tour start complete.
  })
  .catch(function(error) {
    // Tour start error.
  });
```

--------------------------------

### Install Static Assets

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent_tutorial.html

Copy required static assets to the project.

```bash
# yarn
yarn matterport-assets static

# npm
npx matterport-assets static
```

--------------------------------

### Check npm installation

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent_migration.html

Verify that npm is installed on your machine.

```bash
npm -v
```

--------------------------------

### mpSdk.Tour.start(index?)

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/modules/tour.html

Starts the tour playback, optionally beginning at a specific index.

```APIDOC
## mpSdk.Tour.start(index?)

### Description
Starts the tour. If an index is provided, the tour starts from that specific snapshot.

### Parameters
- **index** (number) - Optional - The index of the snapshot to start from.

### Returns
- **Promise<void>**
```

--------------------------------

### Tour.start

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/modules/tour.html

Starts the tour playback from a specified index.

```APIDOC
## Tour.start(index)

### Description
Starts the tour at the provided index.

### Parameters
- **index** (number) - The starting index of the tour.
```

--------------------------------

### Initialize Monorepo Dependencies

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_using_oauth.html

Run these commands in the project root to install dependencies and prepare the bundle.

```bash
> yarn install
> yarn install-bundle
```

--------------------------------

### Install Web Component

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent_tutorial.html

Add the Matterport web component package to the project.

```bash
# yarn
yarn add @matterport/webcomponent

# npm
npm install @matterport/webcomponent
```

--------------------------------

### Install Requests Library

Source: https://matterport.github.io/showcase-sdk//importapi_code_examples.html

Install the required requests library using pip.

```bash
 pip3 install requests
```

--------------------------------

### Sample Add-On Query Response

Source: https://matterport.github.io/showcase-sdk/modelapi_ordering_addons.html

Example JSON response showing the structure of bundle availability and asset details.

```json
{
  "data": {
    "model": {
      "bundles": [
        {
          "id": "mp:matterpak",
          "name": "Matterpak",
          "description": "Order high resolution assets associated with the model.",
          "availability": "unlocked",
          "assets": [
            {
              "status": "available",
              "filename": "mp_matterpak_Southern-California-Luxury-Home_JGPnGQ6hosj.zip",
              "format": "zip",
              "url": "https://cdn-2.matterport.com/models/1a56eedeff7d4a7481b961c009ae9236/assets/9fa4913fb6064e79adf33ce70afd7d2a.zip?t=2-314fd1c4eb4f15df8324d907d3f64e9ba666a142-1722370226-1&download=mp_matterpak_Southern-California-Luxury-Home_JGPnGQ6hosj.zip&k=models%2F1a56eedeff7d4a7481b961c009ae9236%2Fassets%2F9fa4913fb6064e79adf33ce70afd7d2a.zip",
              "validUntil": "2024-07-30T20:10:26Z"
            }
          ],
          "processing": null
        },
        {
          "id": "mp:obj",
          "name": "Model Geometry",
          "description": "Order the model geometry files.",
          "availability": "unavailable",
          "assets": [
            {
              "status": "unavailable",
              "filename": "mp_obj_Southern-California-Luxury-Home_JGPnGQ6hosj.zip",
              "format": "obj",
              "url": null,
              "validUntil": null
            }
          ],
          "processing": null
        },
        {
```

--------------------------------

### Sample Response for Bundle Options

Source: https://matterport.github.io/showcase-sdk/modelapi_ordering_addons.html

Example JSON response showing the structure of bundle availability and available options for various add-ons.

```json
{
  "data": {
    "model": {
      "bundles": [
        {
          "id": "mp:matterpak",
          "availability": "locked",
          "availableOptions": []
        },
        {
          "id": "mp:obj",
          "availability": "unavailable",
          "availableOptions": []
        },
        {
          "id": "mp:obj-low-res",
          "availability": "unavailable",
          "availableOptions": []
        },
        {
          "id": "mp:object-detection",
          "availability": "unavailable",
          "availableOptions": []
        },
        {
          "id": "cubicasa:floorplan",
          "availability": "unavailable",
          "availableOptions": [
            {
              "description": "The color the floor plan should use represented as hex.",
              "key": "color",
              "values": []
            },
            {
              "description": "Target delivery time of the floor plan.",
              "key": "delivery_time",
              "values": []
            },
            {
              "description": "True to remove dimensions from all rooms on the floor plan.",
              "key": "hide_dimensions",
              "values": [
                "true",
                "false"
              ]
            },
            {
              "description": "True to remove the total area from the bottom of the floor plan.",
              "key": "hide_internal_area",
              "values": [
                "true",
                "false"
              ]
            },
            {
              "description": "The displayed units of measure.",
              "key": "unit_type",
              "values": [
                "imperial",
                "metric",
                "both"
              ]
            },
            {
              "description": "True to use the room labels created in Workshop.",
              "key": "use_custom_showcase_labels",
              "values": [
                "true",
                "false"
              ]
            },
            {
              "description": "True to use the orientation you see in Showcase (floor plan view) rather than a standardized orientation.",
              "key": "use_showcase_orientation",
              "values": [
                "true",
                "false"
              ]
            },
            {
              "description": "True to use size inch wall thickness.",
              "key": "use_six_inch_wall_thickness",
              "values": [
                "true",
                "false"
              ]
            }
          ]
        },
        {
          "id": "trueplan:schematic",
          "availability": "locked",
          "availableOptions": []
        },
        {
          "id": "mp:imagery",
          "availability": "locked",
          "availableOptions": []
        },
        {
          "id": "bim:cad",
          "availability": "locked",
          "availableOptions": [
            {
              "description": "The style of the BIM to be ordered. Standard is architecture, mep indicates mechanical and electrical notations should be added, furnished indicates that furniture should be added where possible.",
              "key": "style",
              "values": [
                "architecture",
                "mep",
                "furnished",
                "mep_furnished",
                "industrial"
              ]
            },
            {
              "description": "The displayed units of measure.",
              "key": "unit_type",
              "values": [
                "imperial",
                "metric"
              ]
            }
          ]
        },
        {
          "id": "mp:e57",
          "availability": "locked",
          "availableOptions": []
        },
        {
          "id": "floorplan:schematic",
          "availability": "locked",
          "availableOptions": [
            {
              "description": "True to include color in the floorplan",
              "key": "color",
              "values": [
                "true",
                "false"
              ]
            },
            {
              "description": "Target delivery time of the floor plan.",
              "key": "delivery_time",
              "values": [
                "normal",
                "fast",
                "urgent"
              ]
            },
            {
              "description": "True to include furniture in the floorplan",
              "key": "furniture",
              "values": []
```

--------------------------------

### Install Webpack Dependencies

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

Commands to install Webpack and required plugins as development dependencies.

```bash
# npm
npm install --save-dev webpack webpack-cli webpack-dev-server html-webpack-plugin

# yarn
yarn add --dev webpack webpack-cli webpack-dev-server html-webpack-plugin
```

--------------------------------

### Complete upload sample variables

Source: https://matterport.github.io/showcase-sdk//importapi_guide.html

Example variables for the completeUpload mutation.

```json
{
  "importSessionId": "0cumin458wkndg4qke309xmm",
  "importFileId": "file1",
  "completedParts": [
    {
      "headers": [
        {
          "key": "ETag",
          "value": "69f67e056a3fad6395c42e3f1a5ea9"
        }
      ]
    }
  ]
}
```

--------------------------------

### Start OAuth Server

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_using_oauth.html

Command to launch the OAuth server component in a terminal tab.

```bash
> yarn start-app [--port <number>]
yarn run v1.22.10
$ yarn workspace @oauth/server serve
$ node ./index.js serve
```

--------------------------------

### Sample Request Variables

Source: https://matterport.github.io/showcase-sdk//importapi_guide.html

Example input variables for the requestPartUpload mutation.

```json
{
  "importSessionId": "0cumin458wkndg4qke309xmm",
  "importFileId": "file1",
  "part": 0,
  "size": 2090321920
}
```

--------------------------------

### Import Session Sample Variables

Source: https://matterport.github.io/showcase-sdk//importapi_guide.html

Example input variables for the addImportSession mutation.

```json
{
  "organizationId": "P79zdxVGgWq", 
  "processType": "E57",
  "name": "My Import API Demo",
  "description": "My Import API Demo description"
}
```

--------------------------------

### Construct and Initialize a Scene Object

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_using_scene_objects.html

Demonstrates creating a scene object, adding nodes for a GLTF model and lights, and starting the object.

```javascript
const [sceneObject] = await sdk.Scene.createObjects(1);

// add a scene node for the fbx model
const gltfNode = sceneObject.addNode();

// adjust the position of the scene node
gltfNode.obj3D.position.set(0, -0.68, 0);

// add the gltf loader component that loads a parrot model. Adjust the model's scale to make it fit inside the model.
const gltfComponent = gltfNode.addComponent('mp.gltfLoader', {
  url: 'https://cdn.jsdelivr.net/gh/mrdoob/three.js@dev/examples/models/gltf/Parrot.glb',
  localScale: {
      x: 0.03,
      y: 0.03,
      z: 0.03,
  },
});

// Add a path id 'gltfUrl' to the gltf component url property (not used in the this example).
sceneObject.addInputPath(gltfComponent, 'url', 'gltfUrl');

// add another scene node to contain the light objects.
const lightsNode = sceneObject.addNode();

// Add directional and ambient lights
const directionalLightComponet = lightsNode.addComponent('mp.directionalLight', {
  color: { r: 0.7, g: 0.7, b: 0.7 },
});
lightsNode.addComponent('mp.ambientLight', {
  intensity: 0.5,
  color: { r: 1.0, g: 1.0, b: 1.0 },
});

// Add a path id 'ambientIntensity' to the intensity property of the directional light component.
// The path will be used to set the value later.
const ambientIntensityPath = sceneObject.addInputPath(directionalLightComponet, 'intensity', 'ambientIntensity');

// Start the scene object and its nodes.
sceneObject.start();
```

--------------------------------

### Start Scene Node

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_models.html

Initializes the scene node to begin rendering and processing.

```typescript
modelNode.start();
```

--------------------------------

### Setup Redirect Page

Source: https://matterport.github.io/showcase-sdk/oauth_sdk_private_model

Define the structure and script for the OAuth redirect page.

```html
// redirect.html
<iframe id='model-select' style='width: 100vw; height: 100vh;'></iframe>
<script src='./redirect.js'></script>
```

```javascript
// redirect.js
const urlParams = new URLSearchParams(window.location.search);
const auth_code = urlParams.get('code');
```

--------------------------------

### Sample Response for All Custom Roles

Source: https://matterport.github.io/showcase-sdk/custom_roles_overview.html

Example JSON response containing a list of custom roles.

```json
{
  "data": {
    "roles": {
      "nextOffset": null,
      "totalResults": 7,
      "results": [
        {
          "id": "99a5c0m5qakpn16yhe9wbz25c",
          "name": "Custom Role 1"
        },
        {
          "id": "cdwxak49ihd8qbf1rku45z16d",
          "name": "Custom Role 2"
        },
        {
          "id": "09ucf41tzhm5tysk5issbu46a",
          "name": "Site 1 Viewer"
        },
        {
          "id": "dys7trhyn5t8rdu8ntzbap0bb",
          "name": "Test Role 1"
        },
        {
          "id": "zrc4c7hdk9xceptw86007e6zb",
          "name": "Test Role 2"
        }
      ]
    }
  }
}
```

--------------------------------

### Sample API Response

Source: https://matterport.github.io/showcase-sdk//importapi_guide.html

Example response containing the pre-signed URL and upload metadata.

```json
{
  "data": {
    "requestPartUpload": {
      "url": "https://mp-transient-qa.s3.amazonaws.com/import/0cumin458wkndg4qke309xmm/0waw9rsctf42u329if6zcr4da?...",
      "minSize": 2090321920,
      "maxSize": 2090321920,
      "headers": [],
      "method": "PUT",
      "completed": false,
      "partNumber": 0
    }
  }
}
```

--------------------------------

### Start OAuth Application

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_using_oauth.html

Command to launch the OAuth client application in a separate terminal tab.

```bash
> yarn start-server [--port <number>]
yarn run v1.22.10
$ yarn workspace @oauth/app develop
$ webpack-dev-server
<i> [webpack-dev-server] Project is running at:
<i> [webpack-dev-server] Loopback: http://localhost:8080/
```

--------------------------------

### Check Python Version

Source: https://matterport.github.io/showcase-sdk//importapi_code_examples.html

Verify that Python 3.7 or higher is installed on the system.

```bash
 python3 --version
```

--------------------------------

### Sample View Query Response

Source: https://matterport.github.io/showcase-sdk/modelapi_views_and_layers.html

Example JSON response containing a list of Views for a model.

```json
{
  "data": {
    "model": {
      "id": "Dyc2vZg54be",
      "name": "Demo Space",
      "views": [
        {
          "id": "Dyc2vZg54be",
          "name": "Main View",
          "type": "matterport.model.layered",
          "modified": "2023-11-16T18:13:14Z"
        },
        {
          "id": "0ehmdabhd31ra7pyai5igb9sb",
          "name": "Training View",
          "type": "matterport.user.view",
          "modified": "2023-11-16T17:38:05Z"
        },
        {
          "id": "w3mc532z2qgs2i20z0wz1y0wc",
          "name": "Data View",
          "type": "matterport.user.view",
          "modified": "2023-11-16T18:12:45Z"
        }
      ]
    }
  }
}
```

--------------------------------

### Create Source Files

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent_tutorial.html

Create the source directory and initial files.

```bash
mkdir src
touch src/index.html
touch src/index.js
```

--------------------------------

### Setup Scene Lighting

Source: https://matterport.github.io/showcase-sdk/sdkbundle_tutorials_models.html

Adds a basic lighting component to a scene node to ensure models are visible.

```typescript
const [ sceneObject ] = await sdk.Scene.createObjects(1);
const lights = sceneObject.addNode();
lights.addComponent('mp.lights');
lights.start();
```

--------------------------------

### Sample Response for User Group Details

Source: https://matterport.github.io/showcase-sdk/custom_roles_overview.html

Example JSON response showing user group structure and shares.

```json
{
  "data": {
    "userGroups": {
      "nextOffset": null,
      "totalResults": 1,
      "results": [
        {
          "id": "i0aiuf25nrgdfh4yz7df5s3kc",
          "name": "User Group 1",
          "roles": [
            {
              "id": "99a5c0m5qakpn16yhe9wbz25c",
              "name": "Custom Role 1"
            }
          ],
          "members": {
            "results": [
              {
                "user": {
                  "email": "user@example.com",
                  "id": "tbenTcYfzTj"
                }
              },
            ]
          },
          "modelShares": {
            "results": []
          },
          "folderShares": {
            "results": [
              {
                "sharedObject": {
                  "id": "7ZQHTdNQziL",
                  "name": "My Spaces"
                },
                "roles": [
                  {
                    "id": "00000001001",
                    "name": "viewer"
                  }
                ]
              },
              {
                "sharedObject": {
                  "id": "AAd2PmNoFQT",
                  "name": "top level folder 1"
                },
                "roles": [
                  {
                    "id": "00000001002",
                    "name": "full"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Embed and Connect to Showcase Player

Source: https://matterport.github.io/showcase-sdk/sdk_quickstart

This example demonstrates how to configure the import map, embed the iframe, and initialize the SDK connection. Replace [YOUR_SDK_KEY_HERE] with a valid application key for your domain.

```html
<html>
  <head>
     <script type="importmap">
      {
        "imports": {
          "MP_SDK": "https://api.matterport.com/sdk/bootstrap/3.0.0-0-g0517b8d76c/sdk.es6.js?applicationKey=[YOUR_SDK_KEY_HERE]"
        }
      }
    </script>
  </head>
  <body>
    <iframe
      width="853"
      height="480"
      src="https://my.matterport.com/show?m=SxQL3iGyoDo&play=1&applicationKey=[YOUR_SDK_KEY_HERE]"
      frameborder="0"
      allow="fullscreen *"
      id="showcase-iframe">
    </iframe>
    <script type="module">
      import { connect } from 'MP_SDK';
      (async function connectSdk() {
        const iframe = document.getElementById('showcase-iframe');

        // connect the sdk; log an error and stop if there were any connection issues
        try {
          const mpSdk = await connect(iframe);
          onShowcaseConnect(mpSdk);
        } catch (e) {
          console.error(e);
        }
      })();

      async function onShowcaseConnect(mpSdk) {
        // insert your sdk code here. See the ref https://matterport.github.io/showcase-sdk//docs/reference/current/index.html

        // try retrieving the model data and log the model's sid
        try {
          console.log('Hello SDK', mpSdk);
          const modelData = await mpSdk.Model.getData();
          console.log('Model sid:' + modelData.sid);
        } catch (e) {
          console.error(e);
        }
      }
    </script>
  </body>
</html>
```

--------------------------------

### Sample View Data Response

Source: https://matterport.github.io/showcase-sdk/modelapi_views_and_layers.html

Example JSON response showing metadata and mattertags for a specific View.

```json
{
  "data": {
    "model": {
      "id": "w3mc532z2qgs2i20z0wz1y0wc",
      "created": "2023-11-16T17:38:16Z",
      "modified": "2023-11-16T18:55:35Z",
      "mattertags": [
        {
          "id": "p3fUvV5RLEY",
          "label": "Data Tag",
          "description": "My Data here"
        }
      ]
    }
  }
}
```

--------------------------------

### Update Callback Response Example

Source: https://matterport.github.io/showcase-sdk/webhooks_home.html

Example JSON response for the patchModelEventWebhookCallback mutation.

```json
{
  "data": {
    "patchModelEventWebhookCallback": {
      "id": "887n9rwrdxytnttms0t1h02mc",
      "eventTypes": ["inserted", "updated", "deleted"],
      "callback": {
        "scheme": "https",
        "host": "myawesomeapi.com",
        "path": "v2/my/api/path"
        ...
      }
    }
  }
}
```

--------------------------------

### Sample Response for Unlock Bundle

Source: https://matterport.github.io/showcase-sdk/modelapi_ordering_addons.html

Example JSON response structure returned after successfully unlocking the imagery bundle.

```json
{
 "data": {
     "unlockModelBundle": {
         "id": "mp:imagery",
         "name": "Advanced Imagery Pack",
         "description": "Enables access to high resolution panoramic images",
         "availability": "unlocked",
         "assets": [
             {
                 "format": "skybox",
                 "id": "ba62e8gh2ctuact6fcr220xxd",
                 "status": "available",
                 "validUntil": "2023-09-20T20:19:46Z"
             },
             ...
        ]
    }
  }
}
```

--------------------------------

### Call setupSdk

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

Pass your SDK key to the setupSdk function.

```javascript
  // Initialize SDK here
  const mpSdk = await setupSdk('yourSdkKey')
```

--------------------------------

### Model Event Callbacks Response Example

Source: https://matterport.github.io/showcase-sdk/webhooks_home.html

Example JSON response for the modelEventWebhookCallbacks query.

```json
{
  "data": {
    "modelEventWebhookCallbacks": {
      "totalResults": 1,
      "results": [
        {
          "id": "887n9rwrdxytnttms0t1h02mc",
          "eventTypes": ["inserted", "updated", "deleted"],
          "callback": {
            "scheme": "https",
            "port": 80,
            "path": "myawesomeapi.com"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Execute a GET request via cURL

Source: https://matterport.github.io/showcase-sdk//api_home.html

Use this cURL command to perform a GET request against the GraphQL endpoint. Ensure parameters are properly escaped for the shell.

```bash
curl \
--user [apiKey]:[apiSecret] \
-v 'https://api.matterport.com/api/models/graph?query=\{models\{totalResults%20results\{id%20created%20modified%20visibility\}\}\}'
```

--------------------------------

### Initialize Basic Components

Source: https://matterport.github.io/showcase-sdk/sdk_scene_intro.html

Import and execute the startBasicComponents function using an initialized mpSdk instance.

```javascript
import { startBasicComponents } from './basicComponent';

const mpSdk; // initialized from a successful `connect` call
startBasicComponents(mpSdk);
```

--------------------------------

### Import SDK Function

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

Import the setupSdk function into your project.

```javascript
import { setupSdk } from '@matterport/sdk'
```

--------------------------------

### Initialize Showcase with Token

Source: https://matterport.github.io/showcase-sdk/oauth_sdk_private_model

Connects to the Showcase SDK using the retrieved authentication token.

```javascript
const showcaseWindow = showcaseElement.contentWindow;
const bundleConnector = showcaseWindow.MP_SDK;
bundleConnector.connect(showcaseWindow, {
   auth: token
});
```

--------------------------------

### Initialize Project

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

Commands to initialize a new NPM or Yarn project.

```bash
# npm
npm init

# yarn
yarn init
```

--------------------------------

### beginUpload Mutation

Source: https://matterport.github.io/showcase-sdk//importapi_guide.html

Signals to the API that you are ready to start uploading the file.

```APIDOC
## mutation beginUpload

### Description
Signals to the API that you are ready to start uploading the file.

### Parameters
- **importSessionId** (ID) - Required - Import Session ID from Step 1.
- **importFileId** (ID) - Required - File identifier from Step 2 (use the clientId).

### Request Example
{
  "importSessionId": "0cumin458wkndg4qke309xmm",
  "importFileId": "file1"
}

### Response Example
{
  "data": {
    "beginUpload": {
      "id": "0waw9rsctf42u329if6zcr4da",
      "clientId": "file1",
      "name": "SampleDemo.e57",
      "type": "application/octet-stream",
      "size": 2090321920,
      "uploadStatus": "STARTED"
    }
  }
}
```

--------------------------------

### Register and Run the Adder Component

Source: https://matterport.github.io/showcase-sdk/sdk_connecting_components

Demonstrates registering the Adder component, adding it to a node with initial data, and updating inputs to trigger recalculations.

```javascript
// --- reuse code from the "intro" example that creates `sceneObject` and `node` ---
await mpSdk.Scene.register('adder', () => new Adder());
const adder = node.addComponent('adder', {
  // this object is optional but sets the initial values of the Adder
  arg1: 2,
  arg2: 1,
});

sceneObject.start();

// set the inputs of `adder`
adder.inputs.arg1 = 40;
adder.inputs.arg2 = 2;

// ...some time later; this needs to be deferred until the next frame to get the updated sum
// we'll see how Spies can make this easier to manage later
console.log('outputs.sum', adder.outputs.sum);
```

--------------------------------

### Retrieve a Vertex

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/interfaces/graph.idirectedgraph.html

Get a vertex object by its ID if it exists in the graph.

```typescript
const a = graph.vertex('a');
if (a) {
  console.log(`Found a vertex with id "${a.id}"`);
}
```

--------------------------------

### Create Project Directory

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

Commands to create and enter the project directory.

```bash
mkdir mp-sdk
cd mp-sdk
```

--------------------------------

### Initialize OAuth Flow and Showcase SDK

Source: https://matterport.github.io/showcase-sdk/oauth_sdk_private_model

Handles the OAuth button click, opens the authentication window, listens for the authorization message, and initializes the Showcase player.

```javascript
const showcaseElement = document.getElementById('showcase');
const oauthOverlay = document.getElementById('oauth-overlay');
const oauthButton = document.getElementById('oauth-diag-submit');

// Origins we possibly expect to receive messages over `postMessage` from
const safeOrigins = [
   'https://static.matterport.com',
   'https://static.matterportvr.cn',
  window.location.origin,
];

// when the user auths through the button provided, start everything and get it running
oauthButton.addEventListener('click', async function () {
  async function onAuthMessage(msg) {
     if (!authWindow) return;
     // validate that we received a message from a known source
     if (
          msg.source === authWindow &&
          safeOrigins.includes(msg.origin) &&
          msg.data.type === 'auth_model'
     ) {
       // cleanup a bit: remove the message listener, and close the auth window
       window.removeEventListener('message', onAuthMessage);
       authWindow.close();

       // set up some url params for Showcase
       const { token, modelId } = msg.data;
       const showcaseParams = new URLSearchParams(window.location.search);
       showcaseParams.set('m', modelId);
       showcaseParams.set('applicationKey', config.applicationKey);
       showcaseParams.set('apiHost', 'https://my.matterport.com');
       // start the Showcase player, hide the OAuth overlay, and connect the SDK
       await loadShowcase(showcaseParams);
       oauthOverlay.classList.add('collapsed');
       await connectSdk({
         auth: token,
       });
    }
  }
  window.addEventListener('message', onAuthMessage);

  // open a window to start the user down the OAuth flow
  const authWindow = window.open(
    'https://authn.matterport.com/oauth/authorize?client_id=<client_id>&response_type=code&scope=ViewDetails',
    'sdk auth',
    'width=800,height=800'
  );
});

// load the bundle in the IFrame and return a promise to await its load
export function loadShowcase(params) {
   return new Promise((res) => {
      showcaseElement.onload = res;
      const src = './bundle/showcase.html';
      // append the other url params -- make sure `apiHost` is defined so that the bundle properly connects
      showcaseElement.src = src + '?' + params.toString();
   });
}

// connect to the Bundle SDK
async function connectSdk(options) {
   const showcaseWindow = showcaseElement.contentWindow;
   const bundleConnector = showcaseWindow.MP_SDK;
   return bundleConnector.connect(showcaseWindow, options);
}
```

--------------------------------

### Start and Stop Scene Objects

Source: https://matterport.github.io/showcase-sdk/sdk_scene_intro.html

Control the execution state of the scene object.

```javascript
sceneObject.start();
```

```javascript
// stop our Object after 1 second
setTimeout(() => sceneObject.stop(), 1000);
```

--------------------------------

### Create a Component Path

Source: https://matterport.github.io/showcase-sdk/sdkbundle_architecture.html

Demonstrates initializing a scene object and adding an output path to a component.

```javascript
// Create a scene object, node, and component
const [sceneObject] = await sdk.Scene.createObjects(1);
const node = sceneObject.addNode();
const component = node.addComponent('sum');

// create and add a path that references the component's output
const sumOutputPath = sceneObject.addOutputPath(component, 'sum');
```

--------------------------------

### Initialize and control the showcase camera

Source: https://matterport.github.io/showcase-sdk/sdkbundle_components_camera.html

Demonstrates creating a three.js camera, attaching it to a scene node, and handling access events.

```typescript
// Create a three.js camera object that will be the acting as the source for the camera component.
const myCamera = new THREE.PerspectiveCamera( 45, 1.333, 1, 1000 );

// Create a scene object and node with a camera component.
// Set it up to request control after
// the node is started by setting enabled to true.
const [ sceneObject ] = await sdk.Scene.createObjects(1);
const node = sceneObject.addNode();
const cameraComponent = node.addComponent('mp.camera', {
  enabled: true,
  camera: myCamera,
});

// Define a spy that intercepts ONACCESSGRANTED events
class AccessGrantedSpy {
  public eventType: 'ONACCESSGRANTED';
  public onEvent(payload: unknown) {
    // myCamera is now enabled, changes to your camera will
    // be reflected on the showcase camera.
  }
}

// spy on the camera before it starts.
cameraComponent.spyOnEvent( new AccessGrantedSpy());

// start the camera node
node.start();
```

--------------------------------

### setActive

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/interfaces/view.view-1.html

Sets the current View as active, optionally returning to the start location.

```APIDOC
## setActive(returnToStart?: boolean)

### Description
Set this View as the currently active one optionally, returning to the start location for the new View. Only one View can be active at a time.

### Parameters
- **returnToStart** (boolean) - Optional - Whether to return to the start location.

### Returns
- **Promise<void>**
```

--------------------------------

### Initialize SDK via Promise

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent.html

Wait for the viewer's playingPromise to access the SDK instance.

```javascript
   const viewer = document.querySelector('matterport-viewer');
   const mpSdk = await viewer.playingPromise;
```

--------------------------------

### Initialize SDK via Event Listener

Source: https://matterport.github.io/showcase-sdk/sdkbundle_webcomponent.html

Listen for the mpSdkPlaying event to access the SDK instance when the viewer is ready.

```javascript
   const viewer = document.querySelector('matterport-viewer');
   viewer.addEventListener('mpSdkPlaying', async (evt) => {
 const mpSdk = evt.detail.mpSdk;
 /* do something with mpSdk... */
   });
```

--------------------------------

### Initialize Bound Components

Source: https://matterport.github.io/showcase-sdk/sdk_connecting_components

Import the startBoundComponents function and execute it using a successfully connected mpSdk instance.

```javascript
import { startBoundComponents } from './basicComponent';

const mpSdk; // initialized from a successful `connect` call
startBoundComponents(mpSdk);
```

--------------------------------

### Dimensional Data Response

Source: https://matterport.github.io/showcase-sdk/modelapi_snippets.html

Example JSON response for the dimensional data query.

```json
{
    "data": {
        "model": {
            "name": "Model Name",
            "description": "Model Description",
            "dimensions": {
                "areaFloor": 270.23811626434326,
                "areaFloorIndoor": 245.12091588974,
                "volume": 1185.8062753677368,
                "units": "metric"
            },
            "floors": [
                {
                    "label": "Floor 1",
                    "dimensions": {
                        "areaFloor": 1811.2674341550348,
                        "areaFloorIndoor": 1763.751272911024,
                        "areaWall": 4200.7835074106215,
                        "volume": 30221.99651317749,
                        "units": "imperial"
                    }
                },
                {
                    "label": "Floor 2",
                    "dimensions": {
                        "areaFloor": 1097.5486255027295,
                        "areaFloorIndoor": 874.7057536345482,
                        "areaWall": 2896.4391288173674,
                        "volume": 11654.396359551525,
                        "units": "imperial"
                    }
                }
            ],
            "rooms": [
                {
                    "id": "h26t7ky77ew74yb0pg8qqf5rd",
                    "label": "6",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 12.459799766540527,
                        "areaFloorIndoor": 12.459799766540527,
                        "areaWall": 41.87590026855469,
                        "volume": 37.56352996826172,
                        "height": 3.0147781372070312,
                        "units": "metric"
                    }
                },
                {
                    "id": "tt6gm2a0463x9wmnx7rn6gugc",
                    "label": "5",
                    "tags": [
                        "laundry"
                    ],
                    "dimensions": {
                        "areaFloor": 5.239500045776367,
                        "areaFloorIndoor": 5.239500045776367,
                        "areaWall": 25.518861770629883,
                        "volume": 15.819963455200195,
                        "height": 3.019364833831787,
                        "units": "metric"
                    }
                },
                {
                    "id": "kuc0fpmsgqxff63egrxrycfud",
                    "label": "16",
                    "tags": [
                        "bedroom"
                    ],
                    "dimensions": {
                        "areaFloor": 19.056400299072266,
                        "areaWall": 54.98054504394531,
                        "volume": 57.81614303588867,
                        "height": 3.0339488983154297,
                        "units": "metric"
                    }
                },
                {
                    "id": "wbpb7dkfuwnikd1kq2a9hz70a",
                    "label": "14",
                    "tags": [
                        "bathroom"
                    ],
                    "dimensions": {
                        "areaFloor": 1.646399974822998,
```

--------------------------------

### Commented Wait State Example

Source: https://matterport.github.io/showcase-sdk/sdk_tutorials_package.html

An annotated version of the wait state logic.

```javascript
// use the SDK to wait until the app's state meets a condition...
await mpSdk.App.state.waitUntil(state => 
  // ...specifically, when the state's `phase` property matches the `mpSdk.App.Phase.PLAYING` value
  // (ie, when the app is ready to accept input)
  state.phase === mpSdk.App.Phase.PLAYING
)
```

--------------------------------

### Initialize and add OBJ Loader component

Source: https://matterport.github.io/showcase-sdk/sdkbundle_components_objloader.html

Demonstrates creating a scene object, adding a node, and attaching the mp.objLoader component with initial configuration.

```javascript
var [ sceneObject ] = await sdk.Scene.createObjects(1);
var node = sceneObject.addNode();
var initial = {
  url: "http://test.com/bunny.obj",
  visible: true,
  localScale: {
    x: 1.1, y: 1.1, z: 1.1,
  },
  localPosition: {
    x: 0, y: 0, z: 0.5,
  },
};

node.addComponent('mp.objLoader', initial);
node.start();
```

--------------------------------

### vertex(id: string): Graph.Vertex<T> | undefined

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/interfaces/graph.idirectedgraph.html

Get the vertex associated with id.

```APIDOC
## vertex

### Description
Get the vertex associated with id.

### Parameters
- **id** (string) - The vertex's id.

### Returns
- **Graph.Vertex<T> | undefined** - Returns the Vertex if it exists, otherwise undefined.
```

--------------------------------

### neighborsOf

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/interfaces/graph.icollectionadaptor.html

Get a list of ids for other vertices that should be considered neighbors to an item in the collection.

```APIDOC
### neighborsOf(item: Graph.Vertex<T>): IterableIterator<string>

Get a list of ids for other vertices that should be considered neighbors to an item in the collection.

#### Parameters
- **item** (Graph.Vertex<T>) - A vertex to find neighbors for

#### Returns
- **IterableIterator<string>** - An iterator of neighbor vertex IDs.
```

--------------------------------

### Configure and Listen to Input Events

Source: https://matterport.github.io/showcase-sdk/sdkbundle_components_input.html

Demonstrates initializing the mp.input component, setting up event spies for clicks and keyboard interactions, and toggling component properties at runtime.

```javascript
// Create a scene object and node with an input component.
// Note you will probably only need one instance of an input component
// for your entire application.
const [ sceneObject ] = await sdk.Scene.createObjects(1);
const node = sceneObject.addNode();
const inputComponent = node.addComponent('mp.input', {
  eventsEnabled: true,
  userNavigationEnabled: false,
});
sceneObject.start();

// Define an emit path to listen for mouse click emits
const clickEmitPath = sceneObject.addEmitPath(
  inputComponent,
  "INTERACTION.CLICK"
);

// Define a click event spy
const clickSpy = sceneObject.spyOnEvent({
  path: clickEmitPath,
  onEvent(payload: any) {
      console.log('received', payload);
  }
});

// Define an emit path to listen for keyboard interaction
const keyEmitPath = sceneObject.addEmitPath(
  inputComponent,
  "INTERACTION.KEY"
);

// Define a keypress event spy
const keySpy = sceneObject.spyOnEvent({
  path: keyEmitPath,
  onEvent(payload: any) {
    // Log the key to the browser console.
    console.log(payload.key);
    if (payload.key === 90 && payload.state === 2) {
      // Bind to keydown state for 'z'
      console.log('z');
    }
    if (payload.key === 88 && payload.state === 2) {
      // Bind to keydown state for 'x'
      console.log('x');
    }
  },
});

// You can enable navigation after starting the node.
inputComponent.inputs.userNavigationEnabled = true;

// You can turn off all events and the spy wont receive any callbacks.
inputComponent.inputs.eventsEnabled = false;
```

--------------------------------

### Create and Configure a Scene Node

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/interfaces/scene.inode.html

Demonstrates creating a node, adding a GLTF loader component, setting its position, and starting the node lifecycle.

```typescript
const [sceneObject] = await sdk.Scene.createObjects(1);
const node = sceneObject.addNode();
node.addComponent('mp.gltfLoader', {
  url: 'http://www.someModelSite.com/rabbit.gltf'
});

node.position.set(0, 1, 0);
node.start();
```

--------------------------------

### createAStarRunner<T>

Source: https://matterport.github.io/showcase-sdk/docs/reference/current/modules/graph.html

Creates an A* algorithm runner for a specified graph, start vertex, and end vertex.

```APIDOC
## createAStarRunner<T>

### Description
Create a "runner" for the A* algorithm around a graph, and start and end vertices. The runner encapsulates the details of the graph and search, caches the results of A*, and provides a way to subscribe to potential changes in the path.

### Signature
`createAStarRunner<T>(graph: Graph.IDirectedGraph<T>, start: Graph.Vertex<T>, end: Graph.Vertex<T>, options?: Partial<Graph.SearchOptions<T>>): Graph.IAStarRunner<T>`

### Parameters
- **graph** (Graph.IDirectedGraph<T>) - Required - The graph to traverse.
- **start** (Graph.Vertex<T>) - Required - The start vertex.
- **end** (Graph.Vertex<T>) - Required - The end vertex.
- **options** (Partial<Graph.SearchOptions<T>>) - Optional - An optional heuristic function.

### Returns
- **Graph.IAStarRunner<T>** - A runner for A* that can execute the search or be subscribed to.
```
Tokens:
Raw