Homee 3D Space Viewer

This viewer enables the rendering of 3D spaces, enhancing visual detail through precise spatial information (e.g., dimensions, object coordinates). It offers features for navigating and adjusting the camera view within the space. Additionally, this library includes a chat UI component that interacts with an AI service, allowing users to communicate with a custom AI designed to understand the rendered space. Interaction between the chat and the viewer is facilitated through a context function provided by the library.

Installation

npm install @homee-ai/3d-space-viewer

Quick Start

To initiate the viewer:

import { HomeeViewer, HomeeViewerProvider } from '@homee-ai/3d-space-viewer'

const Viewer = () => {
  return <HomeeViewer source={{ scene: 'homee-scene.ply', model: 'homee-room.glb' }} />
}

const App = () => {
  return (
    <HomeeViewerProvider>
      <Viewer />
    </HomeeViewerProvider>
  )
}

export default App

API

HomeeViewerProvider

<HomeeViewerProvider>
  {children}
</HomeeViewerProvider>

useHomeeViewer

// pattern for getting global states under `HomeeViewerProvider`
const initViewer = useHomeeViewerContext(state =>  state.initViewer)
const disposeViewer = useHomeeViewerContext(state =>  state.disposeViewer)

Returns

• isDimensionShown: boolean
  • when true indicate space dimensions are visible in the viewer.
  • when false indicates space dimensions are not visible in the viewer.
• isPreviewMode: boolean
  • when true indicate space is in preview mode and mouse movement is disabled.
  • when false indicates that space is not in preview mode.
• initViewer: ({ ref?: HTMLDivElement, sharedMemoryForWorkers?: boolean, preview?: boolean }) => Promise<void>
  • bind the viewer to div element.
  • if no ref is provided, by default the viewer will bind to document.body.
  • sharedMemoryForWorkers tells the viewer to use shared memory via a SharedArrayBuffer (for better performance) to transfer data to and from the sorting web worker. Refer to the CORS section below when setting this field to true.
    • default false
  • preview when set to true it will enable preview mode which will disable mouse movement and only allow user to rotate the view angle of the space on a fixed point.
    • default false
• disposeViewer: () => Promise<void>
  • require viewer to be init before calling.
  • dispose the viewer
• loadSpace: (arg: { sceneSrc: string, modelSrc: string }) => Promise<void>
  • require viewer to be init before calling.
  • sceneSrc should be either a .ply or .kspat source, used for loading the 3D scene.
  • modelSrc should be a .glb source, used to map to the 3D scene on load to provide accurate coordinates and dimensions for interactions.
• setCameraHeight: (level: number) => void
  • min:0, max:1
  • require viewer to be init before calling.
  • adjust the viewer's camera height (y).
• moveCamera: (arg: { position: { x: number, z: number }, target?: { x: number, z: number } | null }) => void
  • require viewer to be init before calling.
  • position will move the camera position to x and z.
  • target will move the camera view to x and z.
  • height (y) of the camera will remain the same when moving camera.
• toggleDimensionView: (bool? boolean) => void
  • if bool is provided it will set isDimensionShown to value, else it will toggle isDimensionShown value.

HomeeViewer

<HomeeViewer source={{ scene: 'homee-scene.ply', model: 'homee-plan.glb' }} />

Props

• source: { scene: string, model: string }
  • required
  • scene should be either a .ply or .kspat source, used for loading the 3D scene.
  • model should be a .glb source, used to map to the 3D scene on load to provide accurate coordinates and dimensions for interactions.
• sharedMemoryForWorkers?: boolean
  • optional (default: false)
  • tells the viewer to use shared memory via a SharedArrayBuffer (for better performance) to transfer data to and from the sorting web worker. Refer to the CORS section below when setting this field to true.
• preview?: boolean
  • optional (default: false)
  • when set to true it will enable preview mode which will disable mouse movement and only allow user to rotate the view angle of the space on a fixed point.

CORS issue and SharedArrayBuffer

By default, the Viewer class uses shared memory (via a typed array backed by a SharedArrayBufffer) to communicate with the web worker to enhance the performance. This mechanism presents a potential security issue that is outlined here: https://web.dev/articles/cross-origin-isolation-guide. Shared memory can be disabled by passing false for the sharedMemoryForWorkers parameter to the constructor for Viewer, but if you want to leave it enabled, a couple of extra CORS HTTP headers need to be present in the response from the server that is sent when loading the application.