3D Objects
The Phenix Multimedia System includes support for rendering 3D models using Three.js integration. This allows you to easily display interactive 3D content in your web applications.
3D Viewer Type
The 3d-viewer
type creates a canvas element that renders 3D models using Three.js.
Basic Usage
<div class="px-media ratio-16x9"
data-type="3d-viewer"
data-src="path/to/model.gltf"
data-background="#f0f0f0"
data-auto-rotate="true"
data-controls="orbit">
</div>
JavaScript Initialization
Phenix('.px-media').multimedia({
type: '3d-viewer',
src: 'path/to/model.gltf',
// Additional options can be set via data attributes
});
Supported Model Formats
The system automatically detects the model type based on the file extension:
.gltf
/.glb
- GL Transmission Format (recommended).obj
- Wavefront OBJ format.fbx
- Filmbox format
If no extension is detected or it's not recognized, the system defaults to GLTF.
Configuration Options
Option | Type | Default | Description |
---|---|---|---|
type | String | 'background' | Must be set to '3d-viewer' |
src | String | null | Source URL for the 3D model |
background | String | 'transparent' | Background color for the 3D scene |
auto-rotate | Boolean | false | Enable automatic rotation of the model |
controls | String | 'orbit' | Controls type for interacting with the model |
size | String | null | Aspect ratio: '1x1', '4x3', '16x9', '16x10', '21x9', or percentage |
Implementation Details
The 3D viewer implementation works as follows:
- Creates a canvas element with the class
px-3d
- Detects the model type from the file extension
- Sets up the canvas with the appropriate attributes
- Loads the Three.js utilities script if not already loaded
- Initializes the 3D viewer with the specified options
The system uses a utility script called three-utils.js
that handles the Three.js initialization and provides a consistent API for rendering different model types.
Asset Base Path
The system uses the window.PDS_WP_KEY.assetsBasePath
value to determine the base path for loading Three.js resources. This is typically set by WordPress when the Phenix Design System is initialized.
Example with Custom Background
<div class="px-media ratio-1x1"
data-type="3d-viewer"
data-src="path/to/model.gltf"
data-background="#000000"
data-auto-rotate="true"
data-controls="orbit">
</div>
Example with Transparent Background
<div class="px-media ratio-16x9"
data-type="3d-viewer"
data-src="path/to/model.glb"
data-background="null"
data-auto-rotate="false"
data-controls="orbit">
</div>
Setting data-background="null"
will create a transparent background, allowing the 3D model to blend with the page background.
Control Types
The system supports different control types for interacting with the 3D model:
orbit
- Orbit controls that allow rotating around the model- Other control types may be available depending on the Three.js implementation
Best Practices
- Use GLTF/GLB formats for the best compatibility and performance
- Optimize 3D models for web use (reduce polygon count, texture sizes)
- Provide appropriate aspect ratios to contain the 3D viewer
- Consider using auto-rotate for decorative models
- Test 3D functionality across different devices and browsers
- Be mindful of file sizes for 3D models to ensure good performance
Browser Compatibility
The 3D viewer functionality requires WebGL support, which is available in all modern browsers. However, performance may vary depending on the device's graphics capabilities. The system will gracefully handle cases where WebGL is not supported.