trillion-viewer/README.md

Trillion 3D Viewer

# Trillion Viewer

This is Trillion Viewer that allow you to integrate Trillion SDK in your site. For more information please visit https://trillion.jewelry

## Installing

Using npm:

```shell
npm install trillion-viewer
```

Using yarn:

```shell
yarn add trillion-viewer
```

## How to use:
First of all **get your API key** from https://dashboard.trillion.jewelry/integration

Then you need to create an empty div element for viewer initialization.
For example:

```html
 <div id="trillion-viewer"></div>
```

Then, in your js code (**don't forget to set your API key**):

```js
import {TrillionViewerApp} from "trillion-viewer"

const elem = document.getElementById('trillion-viewer')
const trillionViewer = new TrillionViewerApp()
trillionViewer.init(elem)
trillionViewer.setServiceActivationKey("YOUR_API_KEY_HERE")
trillionViewer.setJewelryID('demo-ring')
trillionViewer.refresh()
```

For typescript:

```ts
const elem = document.getElementById('trillion-viewer') as HTMLElement
```

## Instance methods

* `trillionViewer.init()` - Create viewer on the provided HTML element
* `trillionViewer.setServiceActivationKey(KEY)` - Set API key for app
* `trillionViewer.refresh()` - reload viewer after changing parameters
* `trillionViewer.setJewelryID(sku)` - Set the id(SKU) of the jewelry to load
* `trillionViewer.getJewelryID()` - Get the id(SKU) of the uploaded jewelry
* `trillionViewer.setStartSize(number)` - Set the start size of the jewelry
* `trillionViewer.getStartSize()` - Get the start size of the jewelry
* `trillionViewer.setZoomMin(number)` - Set the minumum zoom value
* `trillionViewer.getZoomMin()` - Get the minumum zoom value
* `trillionViewer.setZoomMax(number)` - Set the maximum zoom value
* `trillionViewer.getZoomMax()` - Get the maximum zoom value
* `trillionViewer.setTryon(true)` - Enables Try-On btn above the model
* `trillionViewer.setCustomUrlTryOn('https://your-brand.com/tryon')` - Set the url for Try-On button

### Model configuration methods
Available colors and cuts depends on a model

```javascript
trillionViewer.configuratorController.changeColor({color: '#f5f5f5', materialName: 'metal'})
```
change color of material. Available materials names _can be retrieved from API in future_

```javascript
trillionViewer.configuratorController.changeCut({name: 'oval', frame: 'oval', band?: 'oval'}, RING_CUTS)
```
change cut of the stone. `RING_CUTS` - all available ring cuts, _can be retrieved from API in future_
and `band` - is optional param, used where band is also changed

```javascript
trillionViewer.configuratorController.engrave('text to engrave')
```
change engrave for a model, max length 15 symbols

```javascript
trillionViewer.configuratorController.changeLetter('A', LETTERS)
```
change engrave for a model, max length 15 symbols `LETTERS` - all available letters, _can be retrieved from API in future_

```javascript
trillionViewer.configuratorController.setSelectedMaterial("oval", 1, "demo-ring-v2")
```
Applies a set of material parameters to a mesh with name `"oval"`. `1` is the index in the material configs list and `"demo-ring-v2"` is the jewellery's SKU.

### Events
'VIEWER_LOADED_EVENT' will be fired when viewer is loaded and ready for any user interactions. Here is an example of subscription to that event
```javascript
document.addEventListener('VIEWER_LOADED_EVENT', () => {
  console.log('Viewer is loaded!');
})
```

### Styling
To change background for the loader screen, just call `trillionViewer.setBackground('#FF5733')` before .`refresh()` method.

To override default css variables, you need to define the external variables in your CSS. For example:
```css
:root {
  --font-family-main-external: 'Arial, sans-serif';
  --overlay-item-background-external: rgba(50, 50, 50, 0.5);
  --overlay-item-color-external: rgba(200, 200, 200, 1);
  --primary-external: #FF5733;
  --left-pos-external: 75%;
  --bottom-pos-external: 30px;
}
```
#### Explanation of Variables

    --font-family-main-external: Main font family for the application. Defaults to 'Montserrat, Helvetica, sans-serif'

    --overlay-item-background-external: Background color for overlay items. Defaults to rgba(0, 0, 0, 0.35) ~light-gray

    --overlay-item-color-external: Text color for overlay items. Defaults to rgba(255, 255, 255, 1) ~⬜

    --primary-external: Primary color for the background for the error page. Defaults to #222D33 ~⬛

    --left-pos-external: Horizontal position for an configurator panel. Defaults to 50%. ~center of the screen

    --bottom-pos-external: Vertical position for an configurator panel. Defaults to 20px. ~up to 20px from the bootom


## Using CDN to get Trillion Viewer

use this pattern:
`unpkg.com/:package@:version/:file`

For example:

```js
import {TrillionViewerApp} from "https://sdk.trillion.jewelry/viewer/latest/trillion-viewer.js"
```

## React component

This library also provides the React component for widget.

### How to use

import component:
```js
import { TrillionViewer } from "trillion-viewer";
```

use somewhere in your React application:

```js
function MyComponent() {
  return (
    <div className="MyComponent">
        <TrillionViewer jewelryId={'demo-ring'}/>
    </div>
  )
}
```