npm package: @homee-ai/3d-space-viewer
Description: This package is a react package for rendering 3D space for viewing
Author: homee-ai
Latest version: 0.0.30-alpha

# 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
```bash
npm install @homee-ai/3d-space-viewer
```

# Quick Start
To initiate the viewer:
```jsx
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
```jsx
<HomeeViewerProvider>
  {children}
</HomeeViewerProvider>
```

### useHomeeViewer
```jsx
// 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
```jsx
<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.