Build unique 3D user experiences with Phasma3D Viewer
Embedding a 3D model into your website is as simple as the markup below. To help with that, the <phasma-viewer> web component lets you declaratively add a 3D model to a web page, while hosting the model on your own site.
Step 1: Include the JS Library
Include the "Phasma3DViewer" library in the <head> section of your HTML file: 
<head>
<!-- Other head elements -->
<script type="module" src="https://phasmatic.com/viewer/dist/phasmaviewer.js">
</script>
</head>
Step 2: Add the Element
Create a <phasma-viewer> element in the body of your HTML file. Set the src attribute to the path of your 3D model file. Here's a basic example: 
<body>
<!-- Other HTML content -->
<phasma-viewer 
  src="path/to/your/model.glb"
  poster="path/to/your/poster_image.jpg"
  alt="alternative text explaining the 3D model"
  camera-enable-controls
  background-color="#ffffff"
>
</phasma-viewer>
<!-- Other HTML content -->
</body>
Next, configure it's styling as a regular HTML Element: 
phasma-viewer {
  width: 512px;
  height: 512px;
}
Step 3: Customize and Add Options
The <phasma-viewer> supports various attributes to customize its behavior. In the example above, we've added the following attributes:
  • src: Set this to the path of your 3D model file.
  • poster: Displays an image instead of the model.
  • alt: Provide a text description for accessibility.
  • camera-controls: Allows users to interact with the model using mouse and touch input.
  • background-color: Sets the background color of the viewer.
Refer to the following table for a full list of attributes and options you can use to customize the appearance and behavior of the 3D viewer.
ATTRIBUTE DESCRIPTION OPTIONS
customerID The unique activation identifier of client. (Mandatory value) Any legal ID.
src The path to the 3D model. (Mandatory value) Supported 3D formats "gltf/glb" and Phasmatic's "pha".
alt Specifies an alternate text for the viewer who use a screen reader. Any description
poster The path to the poster image. Display an image until the model is ready. Supported 2D formats "jpg", "png", "webp", "gif".
env-image The path to the environmental image. Supported 2D formats "jpg", "png", "hdr" and Phasmatic's "pha". If not specified, default environment lighting will be applied.
env-intensity Controls the exposure of the environment image. Any positive floating point value. Default "1.0".
env-image-rotation Controls the rotation of the environment image. Any positive floating point value between 0.0 and 180.0 for X and Y axes. Default "0.0, 0.0".
env-blur Enables the blurring of the displayed environment image. Boolean value. Default "true".
loading Specifies how the model should be preloaded. The supported values are "prefetch", "lazy" and "eager". Lazy loads the model after interaction, Eager loads the model immediately and Prefetch preloads the model in background before interaction. Default "lazy".
variant Specifies the material variant of the model. Any valid material variant of the model.
animation Specifies the animation track. Animation is played after loading. Any valid animation track.
camera-enable-controls Enables camera controls via mouse/touch. Any positive floating point value. Default "1.0".
camera-disable-zoom Disables user zoom. -
camera-invert-zoom Inverse the mouse wheel scrolling direction. -
camera-fov Specifies the vertical field of view of the camera. Accepts values in degrees. Any positive floating point value between "0.0" and "180.0". Default "60.0".
camera-smooth-rotation Specifies the continuation of the camera rotation. Any positive floating point value. Default "0.05".
camera-orbit-limits Specifies the minimum and maximum permitted orbit angles of the camera Yaw and Pitch rotation actions in degrees. Additionally, specifies the minimum permitted zoom distance of the camera movement in meters. Any floating point value between 0.0 and 180.0 for Yaw and -180.0 and 180.0 for Pitch respectively. For minimum distance, any positive floating point value. Default "0.0:180.0, -180.0:180.0, 0.1:auto".
camera-target Specifies the target axis that the camera will orbit around. "X Y Z", here units are in meters. Default: "auto, auto, auto", which corresponds to the default position at the center of the model.
camera-auto-rotate Enables the auto rotation of the 3D model. -
camera-auto-rotate-speed Specifies the Yaw and Pitch auto-rotation speed in degrees. "Yaw, Pitch". Default: "10, 0".
camera-interpolate Enables the camera interpolation from the default point of view to a user-specified. Camera animation starts after the model has been loaded. -
camera-interpolate-duration Specifies the time duration of the camera interpolation in seconds. Any positive floating point value. Default "5".
camera-interpolate-cycle Specifies the camera interpolation rotation angles and ending zoom position. "Yaw, Pitch, Zoom", where Yaw and Pitch are in degrees, Zoom is meters from the center of the model. Default: "360, 0, 1".
background-color Specifies the background color. "rgb(r,g,b)" or "rgba(r,g,b,a)", where r/g/b/a are in [0,255] range. "#xxxxxx" hex color can be used instead. Default: "rgb(209,207,206)".
gradient-color-A Specifies the background gradient color A. "rgb(r,g,b)" or "rgba(r,g,b,a)", where r/g/b/a are in [0,255] range. "#xxxxxx" hex color can be used instead. Default: "rgb(209,207,206)".
gradient-color-B Specifies the background gradient color B. "rgb(r,g,b)" or "rgba(r,g,b,a)", where r/g/b/a are in [0,255] range. "#xxxxxx" hex color can be used instead. Default: "rgb(0,0,0)".
gradient-color-A Specifies the background gradient location A. Any positive floating point value in the range [0,1]. Default "0.0".
gradient-color-B Specifies the background gradient location B. Any positive floating point value in the range [0,1]. Default "1.0".
gradient-direction Specifies the background gradient direction. Acceptance values are "horizontal" or "vertical". Default "horizontal".
background-image The path to the background image. Supported 2D formats "jpg", "png", "webp", and "gif".
pp-sharpen Enables the sharpening post process filter. Specifies the strength of the effect. Any positive floating point value in the range [0,1]. Default "0.0" (disabled).
pp-vignette Enables the vignette post process filter. Specifies the strength of the effect. Any positive floating point value in the range [0,1]. Default "0.0" (disabled).
pp-filmgrain Enables the film grain post process filter. Specifies the strength of the effect. Any positive floating point value in the range [0,1]. Default "0.0" (disabled).
pp-tonemapping Enables the tone mapping post process filter and selects the function. Accepted values are "gamma", "filmic", "aces_filmic", "reinhard", "uncharted". Default "gamma".
ground-shadow Enables shadows. Specifies the strength of the effect. Any positive floating point value in the range [1,10]. Default "1.1" .
ui-fullscreen Allows users to enable full-screen functionality. -
immersive Allow users to enable the ability to launch Virtual and Augmented Reality experiences on supported devices. Accepted values are "VR", "AR", and "XR". XR enables both VR & AR buttons.
ar-mode Select the AR experience type. Accepted values are "scene-viewer" and "webxr". Default "scene-viewer".
ar-resizable Enables the scaling behavior in AR mode, which allows the model to be resized by pinch. -
ar-enable-vertical-placement Enable to place the object on the floor (horizontal surface) as well as on the wall (vertical surface) in AR. Note that the different AR modes handle the placement UX differently. -
ios-src The path to the 3D model to support AR on iOS 12+ devices via AR Quick Look. (Optional value) Supported 3D formats "uszd".
Step 4: Test Locally
Save your HTML file and open it in a web browser to test the embedded 3D model locally. Ensure that the model is displayed correctly and that the interactive features work as expected.
Step 5: Deploy to Your Website
Upload your HTML file and the 3D model file to your web server or hosting provider. Make sure the file paths in your HTML code match the actual paths on your server.
Step 6: API Documentation
Step 6.1: Enable Animations on 3D Assets
To enable a specific animation of your model by clicking a button, you have to include JavaScript directly within the HTML file using the <script> tag and follow the corresponding calls. Here's a basic example: 
// Inline JavaScript at the end of the body section
const phasma_viewer = document.getElementById("phasma_id");
const animation_btn = document.getElementById("animation_btn");
animation_btn.onclick = () => {
  let animation_name = "ANIM_TRACK_NAME";
  phasma_viewer.triggerAnimation(animation_name);
};
Step 6.2: Select Variant on 3D Assets
To enable a specific color variant of your model by clicking a button, you have to include JavaScript directly within the HTML file using the <script> tag and follow the corresponding calls. Here's a basic example: 
// Inline JavaScript at the end of the body section
const phasma_viewer = document.getElementById("phasma_id");
const variant_btn = document.getElementById("variant_btn");
variant_btn.onclick = () => {
  let variant_name = "VARIANT_NAME";
  phasma_viewer.triggerVariant(variant_name);
};
Step 6.3: More options
Refer to the following table for a full list of API options you can use to customize the interactive behavior of the 3D viewer.
METHODS DESCRIPTION
resetCamera() Places camera to its initial position.
setCameraPosition(x: number, y: number, z: number) Places camera to the (x,x,z) position in 3D space.
triggerVisibility(name: string, visible: boolean) Enable or disable the visibility of a geometry mesh by name.
availableVariants() Reports an array of strings, corresponding to variants in the loaded model that can be triggered.
triggerVariant(name: string) Displays a model variant by name.
availableAnimations() Reports an array of strings, corresponding to animations in the loaded model that can be triggered.
triggerAnimation(name: string) Plays the animation by name.
triggerAnimationPause(name: string) Pauses the animation by name.
triggerAnimationStop(name: string) Stops the animation by name.
availableAnnotations() Reports an array, corresponding to annotation information in the loaded model that can be triggered to enable camera movement, init mesh animation or alter color variant.
triggerVisibilityAnnotations() Enable (or disable) the visibility of all available annotations.
triggerAR() Enter in Augmented Reality mode.
onLoadPromise() Returns a Promise that is resolved when the 3D asset is loaded.
Step 7: Add Annotations
Annotations refer to interactive elements that can be added to 3D scenes to provide additional information or interactivity to users. These annotations can include text labels or clickable areas that trigger actions when interacted with. There are four predefined trigger actions that can be applied on click:
  • Navigate to a camera view.
  • Enable a specific animation.
  • Change a specific color variant.
Please note that all available actions can be either enabled all at once in a single interaction or completely omitted. To add annotations to a 3D model, you typically use the <phasma-viewer> and include annotations as part of the model's attributes. Here's a basic example: 
<phasma-viewer  
.
.
.
>
<button
slot="annotation-default-1"
data-position="0.0 0.0 0.0"
data-normal="-0.0 1.0 0.0"
data-camera="0.1 0.3 0.4"
data-animation="ΑΝΙΜ_TRACK_NAME"
data-variant="VARIANT_NAME"
data-visible="true">
1
</button> 
</phasma-viewer>
where, <button> tag defines a clickable hotspot with a text label. slot assigns the button to a specific hotspot slot on the model. data-position and data-normal attributes specify the position and orientation of the hotspot relative to the model. Additionally, you can use more attributes to handle events triggered by user interactions with the annotations. Specifically, data-camera specifies the final camera position, data-animation specifies the animation name and data-variant specifies the color variant of the model. Inside the <button> tag, you can include any content you want to display when the hotspot is clicked, such as additional text or images. Annotations can be further customized with CSS to control their appearance and behavior.
Step 8: Further Training and Support
If you encounter specific challenges or wish to explore advanced features beyond the scope of this guide, we are here to assist you. Please feel free to reach out to our dedicated support team at support@phasmatic.com for personalized assistance.
Conclusion!
That's it! You've successfully embedded a 3D model using the <phasma-viewer> web component. Feel free to explore additional customization options and features available in the documentation to enhance the user experience on your website.