npm package: @lumiscaphe/ng-viewer
Description: Official Angular component for Lumiscaphe 3D Viewer
Latest version: 21.0.0

# ng-viewer

Official Angular component for Lumiscaphe 3D Viewer

## Installation

```
$ npm i @lumiscaphe/ng-viewer
```

or

```
$ yarn add @lumiscaphe/ng-viewer
```

## Usage

### Import

```javascript
import { NgViewerModule } from '@lumiscaphe/ng-viewer';
```

### Basic

```html
<NgViewer [server]="server" [scene]="scene" [view]="view"></NgViewer>
```

```javascript
server = 'https://wr.lumiscaphe.com';

scene = [
  {
    database: 'ee294840-5689-49b0-9edb-527598602df0',
    configuration: 'Bin.Blue/Cabin.Yellow/Style.Design1/Wheels.Red'
  }
];

view = {
  mode: 'image',
  camera: 'EXTER/1'
};
```

### Hotspot

Hotspots are interactive elements that can be selected to engage in additional content or media.\
Hotspots are overlaid on top of the viewer to provide additional media for informational purposes.

```html
<NgViewer ... [hotspots]="hotspots">
  <ng-template #hotspotTemplate let-hotspot let-index="index">
    @if (hotspot.visibility === 'Visible') {
      <button>{{ index + 1 }}</button>
    }
  </ng-template>
</NgViewer>
```

```typescript
hotspots = [{ x: 0, y: 0, z: 0 }];
```

### Pick

Pick allow to retrieve information of a 3D point from a 2D point.

```html
<NgViewer ...></NgViewer>

<button type="button" (click)="pick()">Pick</button>
```

```typescript
import { NgViewerComponent } from '@lumiscaphe/ng-viewer';

...

@ViewChild(NgViewerComponent) viewer: NgViewerComponent;
@ViewChild(ngViewerComponent, { read: ElementRef }) viewerElement: ElementRef<HTMLDivElement>;

...

pick(): void {
  this.viewerElement.nativeElement.addEventListener('click', e => {
    const position = { x: e.clientX, y: e.clientY };
    this.viewer.pick(position).then(pickResult => console.log(pickResult))
  }, { once: true });
};
```

## API

### Properties

| Name           | Type         | Default                                     | Description                      |
| -------------- | ------------ | ------------------------------------------- | -------------------------------- |
| **server**     | `string`     | `undefined`                                 | WebRender URL to use.            |
| **scene**      | `Scene`      | `undefined`                                 | Scene to render.                 |
| **view**       | `View`       | `undefined`                                 | View to render.                  |
| **api**        | `'v1'\|'v2'` | `'v1'`                                      | API version to use.              |
| **encoder**    | `Encoder`    | `{ format: 'jpeg', quality: 80 }`           | Image encoder to use.            |
| **parameters** | `Parameters` | `{ antialiasing: false, superSampling: 2 }` | Rendering parameters to use.     |
| **hotspots**   | `Vector3D[]` | `undefined`                                 | Hotspot array to display.        |
| **vrcube**     | `VRCube`     | `undefined`                                 | VRCube point of view to display. |
| **vrobject**   | `VRObject`   | `undefined`                                 | VRObject position to display.    |

### Emitters

| Name                      | Parameters           | Description                                            |
| ------------------------- | -------------------- | ------------------------------------------------------ |
| **onLoadStart**           | `progress: number`   | Callback to invoke when load starts.                   |
| **onLoadProgress**        | `progress: number`   | Callback to invoke when load makes progress.           |
| **onLoadEnd**             | `progress: number`   | Callback to invoke when load ends.                     |
| **onLoadError**           | `Error`              | Callback to invoke when load failed.                   |
| **onInteraction**         | `VRCube \| VRObject` | Callback to invoke when interaction happened.          |
| **onVrcubeInteraction**   | `VRCube`             | Callback to invoke when VRCube interaction happened.   |
| **onVrobjectInteraction** | `VRObject`           | Callback to invoke when VRObject interaction happened. |

### Methods

| Name         | Parameters                        | Description                          | Returns              |
| ------------ | --------------------------------- | ------------------------------------ | -------------------- |
| **pick**     | `position: Position`              | Get the 3D point from a 2D position. | `PickResult`         |
| **snapshot** | `type: string`, `quality: number` | Get a snapshot of the viewer.        | `string` - Image URL |

### Templates

| Name                | Parameters                                       | Description              |
| ------------------- | ------------------------------------------------ | ------------------------ |
| **hotspotTemplate** | `context: { $implicit: Hotspot, index: number }` | Custom hotspot template. |

### Interfaces

#### Scene

| Name              | Type       | Description                            |
| ----------------- | ---------- | -------------------------------------- |
| **database**      | `string`   | Database id of the 3D model.           |
| **configuration** | `string`   | Product configuration of the 3D model. |
| **animations**    | `string[]` | Animations of the 3D model             |

#### View

| Name       | Type                            | Description                              |
| ---------- | ------------------------------- | ---------------------------------------- |
| **mode**   | `'image'\|'vrcube'\|'vrobject'` | Mode of the view.                        |
| **camera** | `string`                        | Camera or camera group name of the view. |

#### Encoder

| Name        | Type     | Description                       |
| ----------- | -------- | --------------------------------- |
| **format**  | `'jpeg'` | Format of the encoder.            |
| **quality** | `number` | Quality of the encoder (0 - 100). |

#### Parameters

| Name              | Type   | Description                                    |
| ----------------- | ------ | ---------------------------------------------- |
| **superSampling** | number | Super sampling to use for antialiasing (1 -2). |

#### Hotspot

| Name         | Type        | Description                                                     |
| ------------ | ----------- | --------------------------------------------------------------- |
| `id`         | `string`    | Id of the hotspot (when hotspot is provided by the 3D model).   |
| `name`       | `string`    | Name of the hotspot (when hotspot is provided by the 3D model). |
| `position2D` | `Vector2D`  | 2D position of the hotspot in the viewer.                       |
| `position3D` | `Vector3D`  | 3D position of the hotspot.                                     |
| `visibility` | `Visiblity` | Visiblity of the hotspot.                                       |

##### Visibility

| Name           | Description                                    |
| -------------- | ---------------------------------------------- |
| `Visible`      | Hotspot found and visible.                     |
| `Occluded`     | Hotspot found but occluded by another surface. |
| `OutOfFrustum` | Hotspot not found.                             |

#### PickResult

| Name        | Type       | Description                             |
| ----------- | ---------- | --------------------------------------- |
| **product** | `string`   | Product id of the picked point.         |
| **surface** | `Surface`  | Surface of the picked point.            |
| **normal**  | `Vector3D` | Normal coordinates of the picked point. |
| **point**   | `Vector3D` | Point coordinates of the picked point.  |
| **uvw**     | `UVW`      | UV coordinates of the picked point.     |

##### Surface

| Name     | Type       | Description              |
| -------- | ---------- | ------------------------ |
| **id**   | `string`   | Id of the surface.       |
| **name** | `string`   | Name of the surface.     |
| **tags** | `string[]` | Tag list of the surface. |

##### UVW

| Name  | Type     | Description   |
| ----- | -------- | ------------- |
| **u** | `number` | U coordinate. |
| **v** | `number` | V coordinate. |
| **w** | `number` | W coordinate. |

#### Vector2D

| Name  | Type     | Description   |
| ----- | -------- | ------------- |
| **x** | `number` | X coordinate. |
| **y** | `number` | Y coordinate. |

#### Vector3D

| Name  | Type     | Description   |
| ----- | -------- | ------------- |
| **x** | `number` | X coordinate. |
| **y** | `number` | Y coordinate. |
| **z** | `number` | Z coordinate. |

#### VRCube

| Name | Type          | Description                                    |
| ---- | ------------- | ---------------------------------------------- |
| pov  | `PointOfView` | Point of view of the VRCube widget.            |
| fov  | `number`      | Field of view in degrees of the VRCube widget. |

#### VRObject

| Name       | Type     | Description                        |
| ---------- | -------- | ---------------------------------- |
| `position` | `number` | Image inde of the VRObject widget. |