START DOCUMENTATION

BITBYBIT VIEWER

This theme app extension block provides functionality to present 3D models as products without ever touching bitbybit.dev editors. You can upload your 3D models to Shopify CDN or any other publically available cloud storage and then use the url of the file to display it on the product page. This is the simplest way to present 3D models on your product page. We also allow you to load several 3D models at once via special JSON configuration which you can configure easily by using a new tool called VIEWER editor.

Demo store product that uses BITBYBIT VIEWER block

Demo store product that uses BITBYBIT VIEWER block

Examples

Here are the few examples of demo store products that use BITBYBIT VIEWER block

Supported Formats

Currently, we support the following formats: gltf, glb, splat, ply, obj, stl.

How does it work?

First, you will need to upload your 3D model to Shopify CDN or any other publically available cloud storage. Then you will need to create a new product template and dynamically link "Model URL" setting of BITBYBIT VIEWER block to "3D Bits Model Url" product metafield. Then you can copy and paste the url of the 3D model to the 3D Bits Model Url metafield.

If you configured the VIEWER block correctly you should see this kind of output on your product template page.

BITBYBIT VIEWER block after dynamically linking all the settings to metafields

BITBYBIT VIEWER block after dynamically linking all the settings to metafields

When the linking of the settings is done correctly, you should be able to copy paste the file URL to the "3D Bits Model Url" metafield and see the 3D model on the product page after hitting preview.

Demo store product that uses BITBYBIT VIEWER block

Paste your file url's into this metafield

Building More Complex 3D Experiences

Sometimes it is not enough to simply load a 3D model into your scene. You may want to customize things such as camera settings, lighting or even load multiple 3D models at once and make them react to changing Shopify variants. This is where Scene Config JSON comes in. We have recently announced the release of a new Viewer editor which you can use to create a JSON configuration via simple UI. You can load multiple 3D models, set camera settings, enable skybox, lighting and shadows.

We suggest you check this in-depth tutorial where Matas explains how to use the editor and set up the 3D chair configurator product.

This is how the viewer editor looks like in 3D Bits app environment

Viewer editor that helps create 3D scene configurations

Viewer editor that helps create 3D scene configurations

Below we also provide you with an example JSON configuration that you can use to load 3D models - it was generated by using the editor mentioned before. You can copy this JSON file to the "3D Bits Scene Config" metafield on your product page.

{ "$schema": "https://ik.imagekit.io/bitbybit/app/assets/start/shopify/viewer-scene-config-schema-0-20-0-1.json", "models": [ { "url": "https://cdn.shopify.com/3d/models/ac59b22b4c310cdb/vases-serenity-5.glb", "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scaling": [ 1, 1, 1 ], "animatedRotations": [ { "axis": "y", "speed": -2 } ] } ], "arcRotateCamera": { "position": [ 20, 20, 20 ], "target": [ 0, 0, 0 ], "angularSensibilityX": 3000, "angularSensibilityY": 3000, "lowerRadiusLimit": 1, "upperRadiusLimit": 150, "lowerBetaLimit": 0, "upperBetaLimit": 179, "panningSensibility": 4000, "wheelPrecision": 3, "maxZ": 1000, "minZ": 0 }, "skybox": { "type": "city", "size": 500, "blur": 0.4, "environmentIntensity": 1 }, "directionalLights": [ { "direction": [ -100, -100, -100 ], "intensity": 3, "diffuse": "#ffffff", "specular": "#ffffff", "shadowGeneratorMapSize": 2000, "enableShadows": true, "shadowDarkness": 0, "shadowUsePercentageCloserFiltering": true, "shadowContactHardeningLightSizeUVRatio": 0.2, "shadowBias": 0.001, "shadowNormalBias": 0.002, "shadowMaxZ": 1000, "shadowMinZ": 0 } ] }

This is the metafield which you should use to paste the JSON configuration.

Paste your Scene Configuration JSON into this metafield

Paste your Scene Configuration JSON into this metafield

If you configured the template correctly and pasted this JSON configuration you should see the 3D model in the scene that has shadows and enabled rotation around y axis.

Demo store product that uses BITBYBIT VIEWER block and Scene Configuration metafield

Demo store product that uses BITBYBIT VIEWER block and Scene Configuration metafield

Editing JSON of scene config

You can edit JSON with any text editor. We recommend using our editor as it is built for this specific purpose, but any other editor that supports JSON syntax highlighting should work fine.

To make your life easier when editing JSON in external tools, we set up basic schema which editors will parse and give you intellisense. You can find the schema here. Note that the schema may change in the future and you will need to update your scene description.

Make sure to also check this video tutorial that gives step by step guidance on setting up BITBYBIT-VIEWER