Viewer API Reference
The Viewer
class is responsible for initializing and rendering the iJewelMiniViewer in a specified container.
Constructor
constructor(container: HTMLElement, project: Project, options?: ViewerOptions)
- Parameters:
container
: The HTML element in which the viewer will be rendered.project
: An object containing the project configuration details.options
: An optional object containing various viewer options.
Methods
render(project: any)
Parameters:
project
: The project configuration to be rendered.
Description: Renders the viewer with the given project configuration. This method sets up the viewer with the specified options and displays the UI components. To update the project and the 3D model, call
viewer.render(project)
. This will clear the previous project and render the new one.
TIP
You can call viewer.render(newProject)
to load new models and clear the previous scene on the same Viewer
instance.
ViewerOptions
The ViewerOptions
interface provides several optional properties to control the appearance and behavior of the viewer.
Property | Type | Description | Default |
---|---|---|---|
viewer | ViewerApp | An existing viewer instance to be used for rendering. If not provided, a new viewer will be created. | undefined |
showLogo | boolean | Determines whether the logo is displayed in the viewer. | true |
showCard | boolean | Controls the visibility of the floating card that displays model details. | true |
showSwitchNode | boolean | Show or hide swich nodes from the configurator. | false |
splitMaterialTabs | boolean | Determines if material options are displayed in separate tabs. | undefined |
hideQuality | boolean | Controls the visibility of quality settings in the UI. | false |
logoScale | number | Specifies the scale of the logo. | 1 |
logoPositionX | number | Determines the horizontal position of the logo on the screen. The value ranges from 0 to 1, where 0 positions the logo at the far left and 1 positions the logo at the far right. | 1 |
logoPositionY | number | Similar to logoPositionX but vertically | 0 |
showZoomButtons | boolean | Determines whether zoom buttons are displayed in the viewer. | false |
showUiButtons | boolean | Determines whether ui buttons bar is displayed in the viewer. | true |
enableZoom | boolean | Enables or disables zoom functionality. | true |
enableScrollWheel | boolean | Enables or disables zooming with the scroll wheel. | true |
hideCameraViews | boolean | Hides the UI button for switching between defined camera views. | false |
hideRotateCamera | boolean | Hides the UI button for toggling automatic camera rotation. | false |
hideGltfAnimations | boolean | Hides the UI controls for playing embedded GLTF animations. | false |
hideFitScene | boolean | Hides the UI button used to reset the camera and fit the model to the view. | false |
hideFullScreen | boolean | Hides the UI button for toggling fullscreen mode. | false |
showProfile | boolean | Displays a profile section using profileName , profileUrl , etc., from the Project config. | false |
shareUrl | string | Overrides the default URL used by the share button. | window.location.href |
autoGroundTonemap | boolean | Automatically applies tonemapping to the ground plane, to match the background tonemaping. | false |
showShareButton | boolean | Controls the visibility of the share button in the UI. | false |
showConfigurator | boolean | Controls the visibility of the entire configurator UI panel. | true |
showPosterInLoadingScreen | boolean | Determines if the posterUrl from the Project config should be displayed while the 3D model is loading. | true |
disableInteractionPrompt | boolean | Disables the initial overlay hand prompt that instructs users how to interact with the model. | false |
runRotateCamera | boolean | Starts the turntable camera rotation immediately after the model loads. | false |
headerComponent | React.ReactNode | Allows injecting a custom React component into the viewer's header area. | undefined |
transparentBg | boolean | Makes the background of the viewer's canvas transparent instead of using a scene background. identical to clipBackground . | false |
isModal | boolean | Indicates if the viewer is being rendered within a modal context, potentially altering some UI behavior or layout. | false |
hideNameNumbers | boolean | Hides automatically generated numerical suffixes from option names displayed in the configurator. | false |
configuratorBottomOffsetPx | number | Adds a specified pixel offset to the bottom of the configurator UI, useful for avoiding overlap with other fixed elements. | undefined |
useDefaultVJSON | boolean | If true , attempts to load a default scene configuration (vjson) if one isn't explicitly provided in the project config. | false |
Project Configuration
When initializing the iJewel Viewer, you need to provide a project configuration object that includes various settings for your 3D model, environment, materials, and more. Below is a detailed explanation of the properties that can be included in the project configuration object.
Project Properties
Property | Type | Description |
---|---|---|
modelUrl | string | URL of the 3D model file (e.g., a .glb file). |
basePath | string | Base URL path where your assets are stored. Can be an empty string if not needed. |
posterUrl | string | URL of the poster image. |
logo | string | URL of the logo to be displayed in the viewer. |
name | string | Name of the project. |
description | string | Description of the project. |
sceneConfig | object | Configuration for the scene environment, including background and ground settings. |
cameraConfig | object | Configuration for the camera settings. |
materialConfig | object | Configuration for the materials used in the model. |
configuratorConfig | array | [Deprecated] Use plugins["MaterialConfiguratorPlugin"] instead. Configuration for the configurator options available in the viewer. |
plugins | object | Configuration for the plugins used in the viewer. |
category | string | Specify the category of the model, e.g. Ring, Necklace or Watch. |
tags | string[] | An array of strings containing tags for the model. |
profileName | string | The name to be displayed on the profile card (used when ViewerOptions.showProfile is true). |
profileUrl | string | A URL associated with the profile (e.g., website, portfolio link), used in the profile card. |
profileDescription | string | Descriptive text for the profile card. |
profileImage | string | URL for the image to be displayed on the profile card. |
version | string | A version identifier for the assets and configurator format (e.g., "v6"). |
currentPose | { position: number[]; rotation: [number, number, number, EulerOrder] } | null | Specifies an initial pose (position and rotation of the 3d model) to set when the viewer loads. Set to null to disable. |
shouldApplyModelStageConfig | boolean | Indicates whether the viewer settings included with the specifed model stage in sceneConfig (like background color or related configs) should be applied on load. |
Detailed Explanation
- modelUrl: The URL pointing to the 3D model file you want to load.
- basePath: The base path for your assets, which can be left empty if not needed.
- posterUrl: The URL of the poster image to be displayed before the model loads.
- logo: The URL of the logo image to be displayed within the viewer.
- name: name of the model to be displayed in the floating card.
- description: A brief description of the model to be displayed in the floating card.
- presetLib: The library of presets for the
sceneConfig
. - materialLib: The library of materials used in
materialConfig
andconfiguratorConfig
. - sceneConfig:
Environment
: Path to the environment HDR file.GemEnvironment
: Path to the gem environment EXR file.Ground
: Path to the ground configuration JSON file.Background
: Path to the background image for the 3d scene.
- cameraConfig: Configuration for the camera settings.
- materialConfig: The materials that are going to be applied to the model on load
materials
: An array of material objects, each with aname
and apath
to the material file.type
: The type of material configuration, typicallyMaterialPresetPlugin
.
- configuratorConfig: An array of configurator option objects used in the material configurator ui, each with:
name
: The name of the material layer in the 3d file.title
: The display title for the option.options
: An array of available options for this configurator, each with:name
: The name of the material or gem file.type
: The type of option, e.g.,metal
orgem
.
- plugins:
SimpleBackgroundEnvUiPlugin2
: Configuration for the background and environment UI plugin, including:sceneEnvironmentRotation
: Rotation of the environment.sceneEnvironmentIntensity
: Intensity of the environment lighting.sceneEnvironmentFixedDirection
: Boolean indicating if the environment direction is fixed.tonemapBackground
: Boolean indicating if background tonemapping is enabled.tonemapGround
: Boolean indicating if ground tonemapping is enabled.type
: The type of the plugin, typicallySimpleBackgroundEnvUiPlugin2
.
MaterialConfiguratorPlugin
: Defines the materials available within the configurator UI.type
: Must be set to"MaterialConfiguratorPlugin"
.resources
: An object containing various resource such as materials and textures.materials
: A key-value store where each key is a unique identifier (UUID) for a material, and the value is an object defining the material's properties.
variations
: An array of objects defining the structure and options presented in the configurator UI. Each object represents a layer of the model:uuid
: An identifier corresponding to the layer group (e.g., Metal01 Gem04).title
: The display name for this section in the UI (e.g., "Head", "Gemstone").preview
: Specifies how the options under this variation should be previewed (e.g.,"color"
).materials
: An array listing the available material choices for this variation. Each item links to a material defined inresources.materials
:uuid
: The UUID of the material fromresources.materials
.resource
: The type of resource, typically"materials"
.
TIP
The paths for the scene presets and materials can either be absolute URLs or relative to the basePath
specified in your project configuration. This flexibility allows you to organize and reference your assets in a way that best fits your project structure.
Event Listener
The Viewer
class emits a custom event ijewel-viewer-ready
when the viewer is fully initialized and ready for interaction. You can listen for this event to perform additional actions once the viewer is ready.
Example Usage
const project = {
modelUrl: "https://example.com/model.glb",
basePath: "https://example.com/assets/",
logo: "https://example.com/logo.png",
sceneConfig: { /* scene configuration */ },
materialConfig: { /* material configuration */ },
configuratorConfig: [/* configurator configuration */],
};
const viewerOptions = {
showLogo: true,
showCard: true,
showSwitchNode: false,
splitMaterialTabs: true,
useIjewelLogo: false,
hideQuality: true,
logoScale: 1.5,
};
const viewer = new ijewelViewer.Viewer(document.getElementById("root"), project, viewerOptions);
// To update the project and the 3D model
viewer.render(newProject);
// Event listener for viewer ready event
window.addEventListener("ijewel-viewer-ready", async (ev) => {
const viewer = ev.detail.viewer;
// Additional actions to perform with the viewer instance
//Example
//set the max and min zoom for mobile and desktop
viewer.scene.activeCamera.addEventListener('update', (ev)=>{
if(window.innerWidth < window.innerHeight){
(viewer.scene.activeCamera.getControls()).minDistance = 14;
(viewer.scene.activeCamera.getControls()).maxDistance = 9;
}else{
(viewer.scene.activeCamera.getControls()).maxDistance = 12;
(viewer.scene.activeCamera.getControls()).minDistance = 7;
}
});
});