google/model-viewer

The modelviewer.dev package contains the source code and build processes used to generate the live documentation website at modelviewer.dev.

Note: This package is for the documentation site itself. If you want to use the <model-viewer> web component in your own projects, use the <model-viewer> package instead.

Use npm run test to run a render fidelity check comparing <model-viewer> to other renderers.

Note: When passing arguments to the underlying script via npm run, you must use -- to separate the npm command from the script arguments.

To view test results after running the command, start a local web server (e.g., npx http-server) in the package directory and open test/results-viewer.html in a browser.

npm run test -- --scenario=texture --quiet

To develop across all projects in the repository, ensure you have git, Node.js, and npm installed. Clone the repository with --depth=1 to avoid downloading large historical assets (approx. 3GB).

git clone --depth=1 git@github.com:google/model-viewer.git
cd model-viewer
npm install

To use <model-viewer-effects> in a Node.js project, install it along with its required dependencies: three and @google/model-viewer.

npm install three @google/model-viewer @google/model-viewer-effects

Due to dependency issues on Windows 10, it is recommended to use a WSL2 environment.

1. Install WSL2 and Node.js/npm via NVM within WSL.
2. Important: Clone the repository from inside the WSL environment (using HTTPS to avoid SSH key permission issues) rather than from Windows to prevent line ending and symlink issues.

To clone via HTTPS in WSL:

git clone --depth=1 https://github.com/google/model-viewer.git
cd model-viewer
npm install

To use <model-viewer> in a modern JavaScript project, install the package and its required peer dependency, three.

Note: <model-viewer> requires a specific version of three.js to maintain rendering quality. If you need to use a different version of three.js than the one specified by <model-viewer>, you may need to use the --legacy-peer-deps flag during installation, but be aware that this is unsupported and may lead to issues.

# install peer dependency ThreeJS
npm install three 
# install package
npm install @google/model-viewer

import '@google/model-viewer';

To apply effects to your 3D models, place an <effect-composer> element inside your <model-viewer> component. You can then nest specific effect components (like <bloom-effect>) inside the composer.

Note: Effects are not supported in <model-viewer> XR modes; in those modes, the model will render without effects.

<model-viewer src="...">
  <effect-composer>
    <bloom-effect></bloom-effect>
  </effect-composer>
</model-viewer>

To use the npm run render-goldens command, you must have imagemagick installed on your system.

• macOS: Install via Homebrew: brew install imagemagick
• Debian/Ubuntu/Pop!_OS: Install via apt: sudo apt install imagemagick