API Base URL: https://api-platform.vntana.com
For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.
With the release of the new VNTANA Viewer, additional functionality was added to simplify the process of editing and applying viewer settings to all of your assets. Presets can be created and applied at creation to ensure each asset automatically has the correct viewer settings without the need to revisit once Optimization is complete. Additionally, these presets can be saved on multiple levels to reach all assets or just a certain collection: System/Global level, Organization level, and Workspace level.
Creating a Viewer Preset
To create a viewer preset, you simply pass the stringified JSON object of viewer settings and indicate what type of preset it is. Use the following endpoint to create a preset:
1
2
3
4
5
6
7
8
9
Method: POST
Endpoint: /v1/viewer-presets
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“type” : “ORGANIZATION”,
“name” : “Sample Preset”,
“isDefault” : false,
“value” : “{\”autoRotate\”:false,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:true,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”
}
- type: [Required] Indicates the level of access for the preset. Can be ORGANIZATION or CLIENT. Passing CLIENT will change the requirements of the endpoint, see below for an example of the difference.
- name: [Required] Provides a name for the preset for easy identification on the Platform.
- isDefault: [Required] Indicates whether the preset should be set as the default preset for the type that it is.
- For example, if it is a CLIENT preset, making it the default will mean that all assets in the designated Workspace will have this preset by default.
- value: [Required] Stringified JSON object of the viewer settings making up the preset. See below for an example of the full object.
1
2
3
4
5
6
7
8
9
10
Method: POST
Endpoint: /v1/viewer-presets
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“type” : “CLIENT”,
“clientUuid” : “some-uuid”,
“name” : “Sample Preset”,
“isDefault” : false,
“value” : “{\”autoRotate\”:false,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:true,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
“scene”: {
“models”: [],
“environment”: {
“src”: “”,
“skybox”: false,
“rotation”: [0, 0, 0]
},
“shadow”: {
“intensity”: 0,
“radius”: 2,
“offset”: 0,
“samples”: 16,
“resolution”: 512
},
“lights”: {
“showModelLights”: false,
“lightRigIntensity”: 1,
“lightRigOverrideColor”: null,
“lightRig”: []
}
},
“rendering”: {
“exposure”: 1,
“toneMap”: “aces”,
“antiAliasing”: “ssaa”,
“msaaSamples”: 8,
“ssaaSamples”: 1,
“sharpen”: 0,
“bloomStrength”: 0,
“bloomRadius”: 0,
“bloomThreshold”: 0.85,
“ssaoStrength”: 4,
“ssaoRadius”: 1,
“hueShift”: 0,
“saturation”: 1,
“contrast”: 1,
“brightness”: 0,
“transparencyMode”: “normal”
},
“jewelry”: {
“enabled”: false,
“gemAntiAliasing”: false,
“depth”: 4
},
“styling”: {
“background” : “radial-gradient(#999999, #ffffff)”
}
}
A successful preset creation will return the following response:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
“success”: true,
“errors”: [],
“response”: {
“default”: true,
“uuid”: “some-preset-uuid”,
“type”: “ORGANIZATION”,
“organizationUuid”: “f276d86a-b33a-465a-9274-909dd5795c42”,
“name”: “Sample Preset”,
“value”: “{\”autoRotate\”:true,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:false,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”,
“isDefault”: false
}
}
Updating a Preset
Similar to updating an Asset or a Project, you can update a Viewer Preset so long as you have the presetUuid. Additionally, when updating a preset you can opt to have it apply the changes to every Product that is currently using the preset.
Asset Thumbnails
Choosing to update all Products with the Preset will reprocess their thumbnails as well as be immediately reflected in any embed links or iframes you have published. No disruption will occur as the publish status of the Product will not change.
To update a Preset, you can call the following endpoint:
1
2
3
4
5
6
7
8
9
10
Method: PUT
Endpoint: /v1/viewer-presets
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“uuid” : “some-preset-uuid”,
“name” : “Sample Preset”,
“isDefault” : false,
“updateProducts” : true,
“value” : “{\”autoRotate\”:false,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:true,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”
}
When updating, you do not need the type parameter, nor clientUuid in the case of a CLIENT preset as the uuid parameter carries this information with it. The updateProducts parameter indicates whether or not to apply the new values in the preset to any Products currently using this preset.
1
2
3
4
5
6
7
8
9
10
11
12
13
{
“success”: true,
“errors”: [],
“response”: {
“default”: true,
“uuid”: “some-preset-uuid”,
“type”: “ORGANIZATION”,
“organizationUuid”: “org-uuid”,
“name”: “Sample Preset”,
“value”: “{\”autoRotate\”:true,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:false,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”,
“isDefault”: true
}
}
Retrieving Preset Information
There are a number of methods to retrieve a presets information, by its uuid, searching within an organization, searching within a Workspace, or getting just the default of a specific Workspace. To begin, lets look at retrieving by the uuid.
This endpoint is a straightforward GET request with the uuid passed in the URL.
1
2
3
Method: GET
Endpoint: /v1/viewer-presets/{{uuid}}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
A successful request will return the following data:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
“success”: true,
“errors”: [],
“response”: {
“default”: true,
“uuid”: “some-preset-uuid”,
“type”: “ORGANIZATION”,
“organizationUuid”: “some-org-uuid”,
“name”: “Sample Preset”,
“value”: “{\”autoRotate\”:true,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:true,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”,
“isDefault”: true
}
}
The key parameter in the response is the value parameter. This is the stringified version of the viewer settings which can be parsed into a JSON object and updated if needed.
While retrieving by uuid is always the simplest solution, the requirement that you already have the uuid means it isn’t always going to be an option. To find the uuid or other information you can employ a number of additional search endpoints. To begin, a simple search request for viewer presets would look like the following:
1
2
3
4
5
6
7
8
9
10
Method: POST
Endpoint: /v1/viewer-presets/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“page”: 0,
“size”: 100,
“type”: “CLIENT”,
“clientUuid”: “some-client-uuid”,
“nameSearchTerm”: “sponge”
}
-
page: [REQUIRED] Indicates the page of results to return, with 0 representing the first page.
-
size: [REQUIRED] Indicates the number of results to be included in each page.
-
type: [OPTIONAL] Indicates the type with possible values being:
SYSTEM, ORGANIZATION, CLIENT. -
clientUuid: [OPTIONAL] Required if
typeisCLIENT, indicates the Workspace to search. -
nameSearchTerm: [OPTIONAL] A search term to filter results by, only checks against the name of the Presets.
This endpoint will return a list of Presets with the same data as above, the key being the
value parameter which contains the actual viewer settings. One thing to note is that the request parameters act to filter the response, however a fuzzy search is employed meaning results are returned based on relevancy. This means the results will still include presets of the other types than what was passed, however the type that is passed will be returned first. 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 2,
“grid”: [
{
“default”: false,
“uuid”: “string”,
“type”: “CLIENT”,
“organizationUuid”: “string”,
“clientUuid”: “string”,
“name”: “Sample Workspace Preset”,
“value”: “{\”autoRotate\”:false,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:true,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”,
“isDefault”: false
},
{
“default”: true,
“uuid”: “string”,
“type”: “CLIENT”,
“organizationUuid”: “string”,
“clientUuid”: “string”,
“name”: “Sample Workspace Preset 2”,
“value”: “{\”autoRotate\”:false,\”showEnvironment\”:false,\”environment\”:\”Neutral\”,\”exposure\”:1,\”shadowIntensity\”:0,\”shadowSoftness\”:0,\”presetBg\”:\”White\”,\”yaw\”:\”auto\”,\”pitch\”:\”auto\”,\”distance\”:\”auto\”,\”fov\”:\”auto\”,\”targetPointX\”:\”auto\”,\”targetPointY\”:\”auto\”,\”targetPointZ\”:\”auto\”,\”showHotspotNumbers\”:false,\”orientation\”:{\”roll\”:0,\”pitch\”:0,\”yaw\”:0},\”disableZoom\”:false,\”shadowFloorPosition\”:0,\”rotationSpeed\”:\”100%\”,\”postprocessing\”:{\”tonemap\”:\”TONEMAP_ACES_HILL_EXPOSURE_BOOST\”,\”smaa\”:false,\”sharpen\”:{\”amount\”:0},\”bloom\”:{\”strength\”:0,\”threshold\”:3,\”radius\”:0}},\”useAoMaps\”:true,\”lights\”:{\”useSceneLights\”:true,\”color\”:\”#ffffff\”,\”intensity\”:1},\”shading\”:\”metallic\”,\”depthTransparencyWrite\”:false}”,
“isDefault”: true
}
]
}
}
Get All Presets in Organization / Workspace
For a quick method to retrieve all presets in an Organization, the following endpoint can be called:
1
2
3
Method: GET
Endpoint: /v1/viewer-presets/by-organization
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
This will return a list of presets containing the same data as in the other requests above. This endpoint can be constrained to a single Workspace as well by adding the
clientUuid as a query param: 1
2
3
4
5
Method: GET
Endpoint: /v1/viewer-presets/by-organization
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Param: clientUuid={{clientUuid}}
Example: /v1/viewer-presets/by-organizaiton?clientUuid={{clientUuid}}
Get Workspace Default
It is also possible to retrieve the default preset of a Workspace using the following endpoint with the
clientUuid passed as a query parameter: 1
2
3
4
5
Method: GET
Endpoint: /v1/viewer-presets/default
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Param: clientUuid
Example: /v1/viewer-presets/default?clientUuid={{clientUuid}}
1
2
3
4
5
6
7
8
9
10
11
12
{
“success”: true,
“errors”: [],
“response”: {
“default”: true,
“uuid”: “string”,
“type”: “SYSTEM”,
“name”: “VNTANA”,
“value”: “{\”scene\”:{\”models\”:{\”src\”:\”path-to-glb\”,\”usdz\”:\”path-to-usdz\”,\”position\”:[5,1,4],\”rotation\”:[30,60,40],\”scale\”:[3,3,3],\”animation\”:{\”name\”:\”Some animation\”,\”repeatMode\”:\”repeat\”,\”autoPlay\”:true}},\”environment\”:{\”src\”:\”path-to-environment\”,\”skybox\”:false,\”rotation\”:[0,0,0]},\”shadow\”:{\”intensity\”:0,\”radius\”:2,\”offset\”:0,\”samples\”:16,\”resolution\”:512},\”lights\”:{\”showModelLights\”:false,\”rig\”:[{\”type\”:\”directional\”,\”intensity\”:2,\”color\”:16777215,\”position\”:[0,5,1],\”direction\”:[1,1,1]}]}},\”camera\”:{\”enableZoom\”:true,\”enablePan\”:true,\”fov\”:45,\”spherical\”:[30,40,8],\”target\”:[3,1,2],\”minOrbit\”:[0,0,0],\”maxOrbit\”:[0,0,0],\”enabled\”:true,\”enableSceneLimits\”:true,\”rotateSpeed\”:1.5},\”rendering\”:{\”exposure\”:1,\”toneMap\”:\”linear\”,\”antiAliasing\”:\”ssaa\”,\”msaaSamples\”:8,\”ssaaSamples\”:0,\”sharpen\”:0,\”bloomStrength\”:0,\”bloomRadius\”:0,\”bloomThreshold\”:0.85,\”ssaoStrength\”:0,\”ssaoRadius\”:1,\”hueShift\”:0,\”saturation\”:1,\”contrast\”:1,\”brightness\”:0,\”transparencyMode\”:\”normal\”},\”jewelry\”:{\”antialiasing\”:false,\”depth\”:4},\”styling\”:{\”background\”:\”red\”}”,
“isDefault”: true
}
}