API

new ViewerSDK(options).start()

Initialize 3D Viewer。

or

new ViewerUISDK(options)

Initialize 3D Viewer with the default layout

Options

Options shared by ViewerSDK and ViewerUISDK

Property	Description	type	Default	Required
mount	DOM node to mount	HTMLElement	null	true
modelId	model id (obsbgid)	string	null	false
styleId	style id (obsstyleid)	string	null	false
kpxGroupId	model group id (obsKpxGroupId)	string	null	false
pcdId	pcd id (pcdid)	string	null	false
onTap	Callback when the canvas is clicked	`(componentId) => void`	-	false
useCoohomAPI	Overseas API accelerated	boolean	false	false
useCoohomCDN	Overseas CDN accelerated	boolean	false	false
afterDidMount	Callback after loading complete	`() => void`	-	false
backgroundColor	background color	String(Hex color or all colors in English )	'#ffffff'	false
autoRotate	Model automatic rotation.	boolean	true	false
lengthUnit	Change length unit of ruler	'mm' or 'ft'	'mm'	false
pcdParams	Parametric model initialization setting parameters	object: { parmkey: { key : value } } ( i.e: { style: {HOOD: '223521041'},material: { SPCZ: '218533557'}});	null	flase

Note: When the model automatically rotates, it consumes more GPU resources, which may cause page freezes, computer freezes, computer heating, etc. The user should decide whether to enable automatic rotation according to the actual situation

Important ViewerSDK and ViewerUISDK Property Description

modelId

model id can also be named as obsbgid, can use this id to locate the model which need to present
, by typing the obsbgid=***(model id need to be present) behind 3dviewer?, we can get the model we want to see.

styleId

style id is used to locate selected model style, also by typing the obsstyleid=***(style id need to be present) behind 3dviewer?, so that we can get the model style.

kpxgroupId

group id is used to locate selected model group, also by typing the obsKpxGroupId=***(model group id need to be present) behind 3dviewer?, so that we can get the model group.

pcdId

pcd id is used to locate selected custom model, also by typing the pcdid=***(model pcd id need to be present) behind 3dviewer?, so that we can get the pcd custom group.

backgroundColor

model viewer page backgroundColor can be manually set by typing &background=***(color that you pick, color format can be Hex color or all colors in English) at the end of the URL. For example, we can set background to be red

lengthUnit

model viewer page has a property control, Ruler unit of measurement can be shown by typing &unit=***('mm' or 'ft') at the end of the URL. For example, we can display the Ruler to know the model size.

Extra ViewerUISDK Options

ViewerUISDK addition control options

Property	Description	type	Default	Required
locale	Page language	`zh_CN`（Simplified Chinese） `zh_TW`（Traditional Chinese） `en_US`（English） `ja_JP`（Japanese） `ko_KR`（Korean） `fr_FR`（French） `de_DE`（German） `ru_RU`（Russian） `ar_EG`（Arabic） `es_ES`（Spanish） `vi`（Vietnamese） `it_IT`（Italian） `pt_PT`（Portugal） `ro_RO`（Romania）	'zh_CN'	false
enableBrandGoodName	Show product name	boolean	true	false
enableBrandName	show brand name	boolean	true	false
enableDisplayLogo	Show LOGO	boolean	true	false
enablbeRulerIcon	Show ruler icon	boolean	true	false
enableFullscreenIcon	Full screen display icon	boolean	true	false
enableViewerIcon	Show multi-angle view icon	boolean	true	false
enableArIcon	Show AR display icon	boolean	true	false
enableShareIcon	Show share icon	boolean	true	false
enablePanel	Show panel	boolean	true	false
mobileToolbarPosition	mobile toolbar position	string `topRight`（Upper right corner of mobile layout） `topLeft`（Upper left corner of mobile layout）	`topRight`	false
loadingImgUrl	Custom initial load buffer image	string custom image link url	-	false
loadingImgWidth	Customize initial loading buffer image size	string unit: px	PC: `250px` Mobile: `170px`	false
initialProgressType	Customize initial loading Type （Image/ProgressBar）	string `icon` `bar`	PC: `icon` Mobile: `icon`	false
initialProgressColor	Customize initial loading Bar Color	string color（rgb, rgba, Hexadecimal, color）	PC: `#338BFF` Mobile: `#338BFF`	false
initialProgressWidth	Customize initial loading Bar Width	number unit: px	PC: `300` Mobile: `300`	false
pcdParams	Parametric model initialization setting parameters	object: { parmkey: { key : value } } ( i.e: { style: {HOOD: '223521041'},material: { SPCZ: '218533557'}});	null	flase
catchError	Catch the error when the initialization error is reported	`(err: Error) => void`	-	false

Important ViewerUISDK Property Description

locale

model viewer page display language can be changed by typing &locale=***(language substraction in the format type) at the end of the URL. For example:

other Enable property

you can hide or display other property by typing &hideName&hideBrand&hideLogo&hideRuler&hideFullscreen&hideCamera&hideAR&hideShare in the end of the URL to disable the properties belong to the ui model.

Viewer Methods

Methods provided by the initialized 3D Viewer instance.

`asyn start()`

Acquire model data and start 3D Viewer display. Only used in SDK schemes without styles.

`getComponents()`

Get a list of components and materials.
return:

[
  {
    // component item
    id: 'obj_5be575dca25e6b13eba79b58', // component id
    materials: [
      {
        // material item
        id: 'obj_5be575dca25e6b13eba79b58-1', // material id
        name: 'Default',
        thumbnail:
          '//qhyxpicoss.coohom.com/materialtexture/e17/84d/8cacb73dcaae4ff165029bf21ec44275892617f.jpg',
      },
    ],
    defaultMaterial: 'obj_5be575dca25e6b13eba79b58-1',
    name: 'component 1', // component name
  },
];

demo:

const viewer = new koolViewer.ViewerSDK({
    mount: document.querySelector('#app'),
    modelId: '3FO4K59BM9VT',    
    afterDidMount() {},
});

async function start() {
    try {
        await viewer.start(); 
        console.log(viewer.getComponents(), viewer.getPCDModel(), viewer.getPCDModels());
        viewer.changeModel(modelId);
        viewer.changeMaterial(componentId,materailId);
    } catch (err) {
        console.log('viewer init error:', err);
    }
}

start();

`async changeModel(modelId: string) => Promise<void>`

Replace the current model with a single product model

`async changeStyleModel(styleId: string) => Promise<void>`

Replace the current model with a certain style model

`async changeGroupModel(groupId: string) => Promise<void>`

Replace the current model with a combined model

`async changeKpxModel(id: string, dropId: string, component?: object) => Promise<void>`

Replace the pre-selected model in the current product list, and replace it with others in the same list. The third parameter is the relative position information of the model

`getKpxGroups()`

Get all product model data of the group model, position information of all items in the combination and replaceable product ID
The returned data:

{
  "kpxViewInfos": {    //All single product information
      "1273~3FO4GCVA4AOR": { //single product id
          "arUrl ": "https://qhmodel-viewer-oss.kujiale.com/ar/dev/M3DYRSZo6wcr1YAAQAACA/model.usdz",
          "components": Array,        //the option of material replacement for the current product
          "designUrl ": "https://qhmodel-viewer-oss.kujiale.com/3dmodelviewer/DEV/YSyakKwcmmMAAQAAAQ/design.ksf",
          "gltfArUrl ": "https://qhmodel-viewer-oss.kujiale.com/3dmodelviewer/DEV/YSyakKwcmmMAAQAAAQ/design.gltf" ，
          "modelViewerExtraInfo ": Object ，      //
This item is additional product information, including logo and other information
          "obsBrandGoodId  ": "3FO4GCVA4AOR" ， //single product id
          "shaderConfig  ": Object ，
      },
  },
  "sceneData": {
      "components"：[{options: Object}]        //Replaceable items included in the list
      "id": 'YRSZo6wcr1YAAQAAABA',  //group id
              // ...
      },
  },
}

`async changeMaterial(componentId: string, materialId: string)`

Replace the material of the component.

`async changeMaterialAndPanel([{ componentId: string, materialId: string }])`

It is used to switch materials and panels in batches using single models with panels: pass parameters as an array, and the composition method is [{ componentId: xxx, materialId: xxx }] , where componentId is the part id, and materialId is the optional material id
For Example:

``  // Get the components and materials
    const components = viewer.getComponents();

    // Replace materials of components
    viewer.changeMaterialAndPanel([
      {componentId: components[0].id, materialId: components[0].materials[2].id},  
      {componentId: components[1].id, materialId: components[1].materials[2].id},
    ]);

`getPCDModel()`

Get the currently selected state data of the parameterized model
The returned data:

{
    "size": {
        "width": "911",
        "height": "647.7",
        "depth": "450"
    },
    "material": {
        "materialBrandGoodId": "107440169",
        "MBCZ": "107720852",
        "VT": "108040916",
        "VM": "107722515"
    },
    "style": {
        "LSYS": 101150343
    }
}

size, material, style represent size, material, and style respectively.
materialBrandGoodId/MBCZ/VT/VM is the key of a certain material, and the corresponding 107440169 is the id of a certain material.

`getPCDModels()`

Obtain parametric model data
returned data：

{
    "size": {
        "width": {
            "type": "free",
            "min": "100",
			"max": "1000",
            "value": "911" // Rule: When type is free, value is between [min, max]
        },
        "height": {
            "type": "optional",
            "options": [
                "647.7"
            ],
            "value": "647.7" // Rule: When type is optional, value is the enumeration value in options
        },
        "depth": {
            "type": "optional",
            "options": [
                "450"
            ],
            "value": "450"
        }
    },
    "material": {
        "materialBrandGoodId": {
            "displayName": "Casing",
            "options": [
                {
                    "id": "107721818",
                    "previewImg": "//qhcmsoss.kujiale.com/ttex/L6ZYL6VMDE5PGAABAAAAABI8.jpg?x-oss-process=image/resize,m_fill,w_96",
                    "name": "M27 Medium Ash"
                }，
				// ...
            ]
        },
        "MBCZ": {
            "displayName": "Front",
            "options": [
                {
                    "id": "107721818",
                    "previewImg": "//qhcmsoss.kujiale.com/ttex/L6ZYL6VMDE5PGAABAAAAABI8.jpg?x-oss-process=image/resize,m_fill,w_96",
                    "name": "M27 Medium Ash"
                },
				// ...
            ]
        }
    },
    "style": {
        "LSYS": {
            "displayName": "Pull",
            "options": [
                {
                    "id": 101150343,
                    "previewImg": "//qhrenderpicoss.kujiale.com/r/2020/11/18/L4D1500S53ENDIKVU2WAUI5N7ELUF3P3X2888_400x400.jpg?x-oss-process=image/resize,m_fill,w_96",
                    "name": "WEDGE PULL CW"
                },
				// ...
            ]
        }
    }
}

`async updateMultiParamPCD(newPcdParams: object)`

Batch Update Parameters of Parametric Models

Where 'newPcdParams' is the' key '(ie. MBCZ) in the' size ',' style ', and' material 'attributes of the object obtained by' getPCDModels() ', and' id 'is the' id '(ie.107721818) of an item in the' options' attribute of the value corresponding to 'key'

  i.e：let newPcdParams = {
  size: {
    D: '3350', // value
  },
  material: {
    SPCZ: '218533557', // obsBgId
  },
  style: {
    HOOD: '223521041', // obsBgId
  },
};

`async updatePCDModelMaterial(key: string, id: string)`

Update a certain material of the parametric model

Among them, key is the key (ieMBCZ) in the material property of the object obtained by getPCDModels(), and id is a certain item of the options property of the value corresponding to key id` (ie107721818)

`async updatePCDModelStyle(key: string, id: string)`

Update a certain style of the parametric model

Where key is the key (ieLSYS) in the style property of the object obtained by getPCDModels(), and id is one of the items of the options property of the value corresponding to the key id` (ie101150343)

`async updatePCDModelSize(key: string, value: string)`

Update the size of the parametric model

Among them, key is width/height/depth, and the rules of the value of value refer to the example description in getPCDModels()

`setBackgroundColor(value: string)`

Set the background color of the model. The parameter is String (Hex color or all colors word).

`getAutoRotate(): boolean`

`setAutoRotate(value: boolean)`

Set whether to rotate automatically.

`getAutoRotate(): boolean`

Get whether to rotate automatically. ("False" means no)

`setCameraView(value: string)`

Set the camera position and switch the angle of view.
Value enumeration：

enumerate	description
top	Top view
left	Left view
front	Front view
product	30 degree view

`async setScreen(isToFull: boolean): Promise<Boolean>`

Set full screen or exit full screen
Return promise, whether the resolve operation succeeded

`destroy()`

Destroy the 3D Viewer display instance and clear the DOM node.

`reload()`

Destroy and reload the 3D Viewer.

`resize(width: number, height: number)`

Reset the width and height of the model container in the 3D viewer, which can be used when the container size changes.

`showRuler(value: boolean)`

Whether to show the ruler

`takeScreenShot(value: string)`

screenshot function, the variable is the name of the screenshot img defined by the operator

`async takeScreenShotBase64()`

return promise，promiseResult is base64 image encoding