@matterport/r3f

A MatterportSDK adapter for react-three/fiber.

Why?

Building on top of the @matterport/webcomponent package as a way to run the matterport viewer outside of an iframe. This opens up a lot of possibilities for allowing devs to control their build process in a more 'npm' friendly fashion, and allows them to leverate packages created by the react-three/fiber / three.js ecosystems at large.

Build your scene declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in React's ecosystem.

# install packages
npm install react-dom react
npm install three @types/three @react-three/fiber
npm install @matterport/webcomponent @matterport/r3f

# Ensure the matterport assets are available on your server
# this path will be the `assetBase` in the component
npx matterport-assets ./public/matterport-assets

What does it look like?

import '@matterport/webcomponent'
import { MatterportViewer, MpSdk, useMatterportSdk } from '@matterport/r3f'
import { createRoot } from 'react-dom/client'
import React, { useRef, useState } from 'react'
import { useFrame } from '@react-three/fiber'

function Box(props) {
  // reference the connected Matterport SDK from within r3f components
  const mpSdk = useMatterportSdk()
  // This reference gives us direct access to the THREE.Mesh object
  const ref = useRef()
  // Hold state for hovered and clicked events
  const [hovered, hover] = useState(false)
  const [clicked, click] = useState(false)
  // Subscribe this component to the render-loop, rotate the mesh every frame
  useFrame((state, delta) => (ref.current.rotation.x += delta))
  // Return the view, these are regular Threejs elements expressed in JSX
  return (
    <mesh
      {...props}
      ref={ref}
      scale={clicked ? 1.5 : 1}
      onClick={(event) => {
        click(!clicked)
      }}
      onPointerOver={(event) => hover(true)}
      onPointerOut={(event) => hover(false)}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color={hovered ? 'hotpink' : 'orange'} />
    </mesh>
  )
}

createRoot(document.getElementById('root')).render(
  <MatterportViewer
    m="YOUR-PUBLIC-MATTERPORT-MODEL-ID"
    assetBase="matterport-assets/"
    applicationKey="YOUR-MATTERPORT-APPLICATION-KEY"
    onPlaying={(mpSdk) => {
      mpSdk.Camera.rotate(-10, 0)
    }}
  >
    <ambientLight />
    <pointLight position={[10, 10, 10]} />
    <Box position={[-1.2, 0, 0]} />
    <Box position={[1.2, 0, 0]} />
  </MatterportViewer>
)

Components

MatterportViewer

A limited replacement for the react-three/fiber Canvas component which inserts children components into the Matterport 3d view.

MatterportPointer

Allows configuring the pointer reticle, and handling global raycast pointer events. Can only be used within a <MatterportViewer>.

<MatterportPointer
  visible={true}
  textureSrc="/images/custom-cursor.png"
  onClick={handleGlobalClick}
/>

MatterportModel

Allows handling raycast pointer events on the Matterport model mesh. Can only be used within a <MatterportViewer>.

<MatterportModel
  onClick={handleModelClick}
/>

Hooks

useMatterportSdk()

Hook that gives access to the Matterport SDK object within a React component.

import { useMatterportSdk } from '@matterport/r3f';

function ScreenshotTrigger() {
  const sdk = useMatterportSdk();
  return (
    <mesh onClick={() => { sdk.Renderer.takeScreenShot(); }}>
      ...
    </mesh>
  );
}