Top Related Projects
JavaScript 3D Library.
Babylon.js is a powerful, beautiful, simple, and open game and rendering engine packed into a friendly JavaScript framework.
glTF – Runtime 3D Asset Delivery
🇨🇭 A React renderer for Three.js
:a: Web framework for building virtual reality experiences.
JavaScript game engine built on WebGL, WebGPU, WebXR and glTF
Quick Overview
Model-viewer is an open-source web component for rendering interactive 3D models. It allows developers to easily embed 3D content into websites and applications, supporting various formats and offering features like AR viewing on compatible devices.
Pros
- Easy integration with web projects using a simple HTML tag
- Supports multiple 3D file formats (glTF, GLB)
- Offers AR functionality on supported devices
- Customizable appearance and behavior through attributes and CSS
Cons
- Limited support for older browsers
- Performance may vary depending on the complexity of 3D models
- Some advanced features require additional setup or polyfills
- Documentation can be overwhelming for beginners
Code Examples
- Basic usage:
<model-viewer src="path/to/model.glb" alt="A 3D model" auto-rotate camera-controls></model-viewer>
- Adding AR support:
<model-viewer src="path/to/model.glb" alt="A 3D model" ar ar-modes="webxr scene-viewer quick-look" camera-controls></model-viewer>
- Customizing appearance:
<style>
model-viewer {
width: 400px;
height: 600px;
background-color: #f0f0f0;
}
</style>
<model-viewer src="path/to/model.glb" alt="A 3D model" camera-controls exposure="0.5" shadow-intensity="1"></model-viewer>
Getting Started
- Include the model-viewer script in your HTML:
<script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>
- Add the model-viewer tag to your HTML:
<model-viewer src="path/to/your/model.glb" alt="A 3D model" auto-rotate camera-controls></model-viewer>
- Customize the model-viewer attributes as needed:
<model-viewer
src="path/to/your/model.glb"
alt="A 3D model"
auto-rotate
camera-controls
ar
ar-modes="webxr scene-viewer quick-look"
shadow-intensity="1"
camera-orbit="45deg 55deg 2.5m"
exposure="0.5"
></model-viewer>
Competitor Comparisons
JavaScript 3D Library.
Pros of three.js
- More flexible and powerful, allowing for complex 3D scenes and animations
- Larger ecosystem with extensive documentation and community support
- Supports a wider range of 3D file formats and rendering techniques
Cons of three.js
- Steeper learning curve, requiring more JavaScript knowledge
- Requires more code to set up basic 3D model viewing
- Less optimized for simple 3D model display use cases
Code Comparison
model-viewer:
<model-viewer src="model.glb" alt="3D model" auto-rotate camera-controls></model-viewer>
three.js:
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
const loader = new THREE.GLTFLoader();
loader.load('model.glb', (gltf) => scene.add(gltf.scene));
Summary
three.js offers more power and flexibility for complex 3D web applications, while model-viewer provides a simpler solution for basic 3D model viewing. three.js requires more setup and JavaScript knowledge but offers greater control over the 3D environment. model-viewer is easier to implement for straightforward 3D model display tasks but has limited customization options compared to three.js.
Babylon.js is a powerful, beautiful, simple, and open game and rendering engine packed into a friendly JavaScript framework.
Pros of Babylon.js
- More comprehensive 3D engine with advanced features like physics, animations, and particle systems
- Larger ecosystem with extensive documentation, plugins, and community support
- Highly customizable and suitable for complex 3D applications and games
Cons of Babylon.js
- Steeper learning curve due to its extensive feature set
- Larger file size and potentially higher performance overhead for simple 3D model viewing tasks
- Requires more setup and configuration for basic use cases
Code Comparison
model-viewer:
<model-viewer src="model.glb" alt="3D model" auto-rotate camera-controls></model-viewer>
Babylon.js:
const scene = new BABYLON.Scene(engine);
const camera = new BABYLON.ArcRotateCamera("camera", 0, 0, 10, BABYLON.Vector3.Zero(), scene);
const light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0), scene);
BABYLON.SceneLoader.ImportMesh("", "", "model.glb", scene, function (meshes) {
// Mesh loaded, additional setup if needed
});
model-viewer is simpler to use for basic 3D model viewing, while Babylon.js offers more control and flexibility for complex 3D applications at the cost of increased complexity.
glTF – Runtime 3D Asset Delivery
Pros of glTF
- Industry-standard 3D file format with wide support across various platforms and engines
- Lightweight and efficient, optimized for transmission and loading of 3D assets
- Extensible format allowing for custom features and metadata
Cons of glTF
- Requires additional viewers or engines to render and interact with 3D models
- Less user-friendly for web developers without 3D graphics expertise
- Limited built-in features for AR/VR experiences compared to model-viewer
Code Comparison
model-viewer:
<model-viewer
src="model.glb"
alt="A 3D model"
auto-rotate
camera-controls
></model-viewer>
glTF (using Three.js as an example):
const loader = new THREE.GLTFLoader();
loader.load('model.gltf', (gltf) => {
scene.add(gltf.scene);
});
model-viewer provides a more straightforward implementation for web developers, while glTF requires additional setup and rendering code. However, glTF offers more flexibility and can be used with various rendering engines and platforms.
🇨🇭 A React renderer for Three.js
Pros of react-three-fiber
- More flexible and customizable, allowing for complex 3D scenes and interactions
- Integrates seamlessly with React ecosystem and state management
- Supports a wider range of 3D models and formats
Cons of react-three-fiber
- Steeper learning curve, requiring knowledge of Three.js and React
- Higher performance overhead for simple 3D model viewing tasks
- Less out-of-the-box AR/VR support compared to model-viewer
Code Comparison
model-viewer:
<model-viewer
src="model.glb"
alt="A 3D model"
auto-rotate
camera-controls
></model-viewer>
react-three-fiber:
import { Canvas } from '@react-three/fiber'
import { OrbitControls, useGLTF } from '@react-three/drei'
function Model() {
const { scene } = useGLTF('model.glb')
return <primitive object={scene} />
}
function App() {
return (
<Canvas>
<OrbitControls autoRotate />
<Model />
</Canvas>
)
}
:a: Web framework for building virtual reality experiences.
Pros of A-Frame
- More comprehensive framework for building entire VR/AR experiences
- Larger ecosystem with numerous community-contributed components
- Supports a wider range of VR/AR devices and platforms
Cons of A-Frame
- Steeper learning curve due to its more extensive feature set
- Potentially heavier performance impact for simpler 3D model viewing tasks
- May be overkill for projects that only require basic 3D model display
Code Comparison
A-Frame example:
<a-scene>
<a-entity gltf-model="url(path/to/model.gltf)" position="0 1.5 -3"></a-entity>
</a-scene>
model-viewer example:
<model-viewer src="path/to/model.gltf" alt="3D model" auto-rotate camera-controls></model-viewer>
A-Frame provides a more extensible scene-based approach, while model-viewer offers a simpler, more focused solution for displaying 3D models. A-Frame requires more setup but allows for greater customization, whereas model-viewer is more straightforward for basic model viewing tasks.
JavaScript game engine built on WebGL, WebGPU, WebXR and glTF
Pros of PlayCanvas Engine
- Full-featured 3D game engine with advanced rendering capabilities
- Supports complex interactive experiences and game development
- Offers a complete ecosystem with editor, asset pipeline, and scripting
Cons of PlayCanvas Engine
- Steeper learning curve due to more extensive API and features
- Larger file size and potentially higher performance overhead
- May be overkill for simple 3D model viewing tasks
Code Comparison
model-viewer:
<model-viewer src="model.glb" alt="A 3D model" auto-rotate camera-controls></model-viewer>
PlayCanvas Engine:
var entity = new pc.Entity();
entity.addComponent('model', {
type: 'asset',
asset: modelAsset
});
app.root.addChild(entity);
Summary
Model Viewer is a lightweight, easy-to-use solution for embedding 3D models on web pages, while PlayCanvas Engine is a comprehensive 3D game engine. Model Viewer excels in simplicity and quick integration, whereas PlayCanvas Engine offers more power and flexibility for complex 3D applications and game development.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
The <model-viewer>
project
This is the main GitHub repository for the <model-viewer>
web component and
all of its related projects.
Getting started? Check out the <model-viewer>
project!
The repository is organized into sub-directories containing the various projects. Check out the README.md files for specific projects to get more details:
ð©âð <model-viewer>
⢠The <model-viewer>
web component (probably what you are looking for)
⨠<model-viewer-effects>
⢠The PostProcessing plugin for <model-viewer>
ð modelviewer.dev ⢠The source for the <model-viewer>
documentation website
ð¼ render-fidelity-tools ⢠Tools for testing how well <model-viewer>
renders models
ð¨ shared-assets ⢠3D models, environment maps and other assets shared across many sub-projects
ð space-opera ⢠The source of the <model-viewer>
editor
Development
When developing across all the projects in this repository, first install git, Node.js and npm.
Then, perform the following steps to get set up for development:
git clone --depth=1 git@github.com:google/model-viewer.git
cd model-viewer
npm install
Note: depth=1 keeps you from downloading our ~3Gb of history, which is dominated by all the versions of our golden render fidelity images.
The following global commands are available:
Command | Description |
---|---|
npm ci | Install dependencies and cross-links sub-projects |
npm run build | Runs the build step for all sub-projects |
npm run serve | Runs a web server and opens a new browser tab pointed to the local copy of modelviewer.dev (don't forget to build!) |
npm run test | Runs tests in all sub-projects that have them |
npm run clean | Removes built artifacts from all sub-projects |
You should now be ready to work on any of the <model-viewer>
projects!
Windows 10/11 Setup
Due to dependency issues on Windows 10 we recommend running <model-viewer>
setup from a WSL2 environment.
And installing Node.js & npm via NVM
You should clone model-viewer from inside WSL, not from inside Windows. Otherwise, you might run into line endings and symlink issues.
To clone via HTTPS in WSL (there are known file permissions issues with SSH keys inside WSL):
git clone --depth=1 https://github.com/google/model-viewer.git
cd model-viewer
npm install
To run tests in WSL, you need to bind CHROME_BIN
:
export CHROME_BIN="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
npm run test
Note that you should be able to run the packages/model-viewer
and packages/model-viewer-effects
tests with that setup, but running fidelity tests requires GUI support which is only available in WSL on Windows 11.
Additional WSL Troubleshooting â provided for reference only
These issues should not happen when you have followed the above WSL setup steps (clone via HTTPS, clone from inside WSL, bind CHROME_BIN). The notes here might be helpful if you're trying to develop model-viewer from inside Windows (not WSL) instead (not recommended).
Running Tests
Running npm run test
requires an environment variable on WSL that points to CHROME_BIN
.
You can set that via this command (this is the default Chrome install directory, might be somewhere else on your machine)
export CHROME_BIN="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
npm run test
Tests in packages/model-viewer
and packages/model-viewer-effects
should now run properly; fidelity tests might still fail (see errors and potential workarounds below).
Error: /bin/bash^M: bad interpreter: No such file or directory
Symptom
Running a .sh script, for example fetch-khronos-gltf-samples.sh
, throws an error message /bin/bash^M: bad interpreter: No such file or directory
Alternative error:
! was unexpected at this time.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! @google/model-viewer@1.10.1 prepare: `if [ ! -L './shared-assets' ]; then ln -s ../shared-assets ./shared-assets; fi && ../shared-assets/scripts/fetch-khronos-gltf-samples.sh`
Solution This is caused by incorrect line endings in some of the .sh files due to git changing these on checkout on Windows (not inside WSL). It's recommended to clone the model-viewer repository from a WSL session.
As a workaround, you can re-write line endings using the following command:
sed -i -e 's/\r$//' ../shared-assets/scripts/fetch-khronos-gltf-samples.sh
Error: ERROR:browser_main_loop.cc(1409)] Unable to open X display.
Symptom
When trying to npm run test
, errors are logged similar to:
âFail to analyze scenario :khronos-IridescentDishWithOlives! Error message: â Failed to capture model-viewer's screenshot
[836:836:0301/095227.204808:ERROR:browser_main_loop.cc(1409)] Unable to open X display.
Pupeteer tests need a display output; this means GUI support for WSL is required which seems to only be (easily) available on Windows 11, not Windows 10.
https://docs.microsoft.com/de-de/windows/wsl/tutorials/gui-apps#install-support-for-linux-gui-apps
So, the workaround seems to be running Windows 11 (but not tested yet).
Error: ERROR: Task not found: "'watch:tsc"
Symptom
Running npm run dev
in packages/model-viewer
on Windows throws error ERROR: Task not found: "'watch:tsc"
.
Solution (if you have one please make a PR!)
Top Related Projects
JavaScript 3D Library.
Babylon.js is a powerful, beautiful, simple, and open game and rendering engine packed into a friendly JavaScript framework.
glTF – Runtime 3D Asset Delivery
🇨🇭 A React renderer for Three.js
:a: Web framework for building virtual reality experiences.
JavaScript game engine built on WebGL, WebGPU, WebXR and glTF
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot