Matterport SDK for Embeds: read measurements a user draws with the built-in ruler (and why Pointer.intersection is the wrong tool)
Goal: let a user measure something in an embedded Matterport tour and get the length into your own app without typing.
Setup that worked (key accepted on localhost without registration):
// iframe src: https://my.matterport.com/show/?m=<MODEL>&play=1&qs=1&applicationKey=<SDK_KEY>
// script: https://static.matterport.com/showcase-sdk/latest.js
const sdk = await window.MP_SDK.connect(iframeEl, SDK_KEY, ""); // call after the iframe load eventTwo approaches, tested:
1. sdk.Pointer.intersection.subscribe(i => ...) does give a 3D position (metres), normal, floorId and object under the cursor. But the tour is a cross-origin iframe, so the parent page never sees the click, and you cannot draw feedback inside the tour. A two-click measuring tool built on this needs awkward keyboard triggers. Not worth it.
2. Use the tour's own ruler and read its result. This is the one to use:
await sdk.Measurements.toggleMode(true); // shows the "Add Measurement" button in the tour
sdk.Measurements.mode.subscribe(m => setActive(m.active));
sdk.Measurements.data.subscribe({ onCollectionUpdated: async () => {
const rows = await sdk.Measurements.getData(); // [{ sid, start:{x,y,z}, end:{x,y,z}, floor, label }]
// length in metres = Math.hypot(end.x-start.x, end.y-start.y, end.z-start.z)
}});Gotchas:
- The collection passed to onCollectionUpdated serialised as { sid: {} } for me (values are not plain objects). Treat the callback as a change signal and call getData() for the real points.
- In the ruler, a plain click on the scene navigates the camera until the user presses "Add Measurement". Then: click, click, and "Confirm". The line only appears in getData() after Confirm. Until then a rubber-band segment follows the cursor and is not committed.
- A multi-click polyline comes back as separate segments; decide whether you want the last segment or the sum.
- Computed length matched the on-screen label (1.016 m vs 3 ft 4 in; 0.45 m vs 1 ft 6 in), so no unit setting is involved: data is always metres.
- Cancel subscriptions and call sdk.disconnect() on unmount; remount the component (React key = model id) when switching models.
- SDK keys are domain-restricted. Localhost worked; a bare IP or new domain may be refused until registered in the Matterport account, so catch the connect rejection and fall back to the plain embed.
- Only publicly viewable models can be embedded at all.