|
|
<!DOCTYPE html><html lang="en"><head>
|
|
|
<meta charset="utf-8">
|
|
|
<title>Loading 3D Models</title>
|
|
|
<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
|
|
|
<meta name="twitter:card" content="summary_large_image">
|
|
|
<meta name="twitter:site" content="@threejs">
|
|
|
<meta name="twitter:title" content="Three.js – Loading 3D Models">
|
|
|
<meta property="og:image" content="https://threejs.org/files/share.png">
|
|
|
<link rel="shortcut icon" href="../../files/favicon_white.ico" media="(prefers-color-scheme: dark)">
|
|
|
<link rel="shortcut icon" href="../../files/favicon.ico" media="(prefers-color-scheme: light)">
|
|
|
|
|
|
<link rel="stylesheet" href="../resources/lesson.css">
|
|
|
<link rel="stylesheet" href="../resources/lang.css">
|
|
|
<script type="importmap">
|
|
|
{
|
|
|
"imports": {
|
|
|
"three": "../../build/three.module.js"
|
|
|
}
|
|
|
}
|
|
|
</script>
|
|
|
</head>
|
|
|
<body>
|
|
|
<div class="container">
|
|
|
<div class="lesson-title">
|
|
|
<h1>Loading 3D Models</h1>
|
|
|
</div>
|
|
|
<div class="lesson">
|
|
|
<div class="lesson-main">
|
|
|
|
|
|
<p>
|
|
|
3D models are available in hundreds of file formats, each with different
|
|
|
purposes, assorted features, and varying complexity. Although
|
|
|
<a href="https://github.com/mrdoob/three.js/tree/dev/examples/jsm/loaders" target="_blank" rel="noopener">
|
|
|
three.js provides many loaders</a>, choosing the right format and
|
|
|
workflow will save time and frustration later on. Some formats are
|
|
|
difficult to work with, inefficient for realtime experiences, or simply not
|
|
|
fully supported at this time.
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
This guide provides a workflow recommended for most users, and suggestions
|
|
|
for what to try if things don't go as expected.
|
|
|
</p>
|
|
|
|
|
|
<h2>Before we start</h2>
|
|
|
|
|
|
<p>
|
|
|
If you're new to running a local server, begin with
|
|
|
<a href="installation.html">Installation</a>
|
|
|
first. Many common errors viewing 3D models can be avoided by hosting files
|
|
|
correctly.
|
|
|
</p>
|
|
|
|
|
|
<h2>Recommended workflow</h2>
|
|
|
|
|
|
<p>
|
|
|
Where possible, we recommend using glTF (GL Transmission Format). Both
|
|
|
<small>.GLB</small> and <small>.GLTF</small> versions of the format are
|
|
|
well supported. Because glTF is focused on runtime asset delivery, it is
|
|
|
compact to transmit and fast to load. Features include meshes, materials,
|
|
|
textures, skins, skeletons, morph targets, animations, lights, and
|
|
|
cameras.
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
Public-domain glTF files are available on sites like
|
|
|
<a href="https://sketchfab.com/models?features=downloadable&sort_by=-likeCount&type=models" target="_blank" rel="noopener">
|
|
|
Sketchfab</a>, or various tools include glTF export:
|
|
|
</p>
|
|
|
|
|
|
<ul>
|
|
|
<li><a href="https://www.blender.org/" target="_blank" rel="noopener">Blender</a> by the Blender Foundation</li>
|
|
|
<li><a href="https://www.allegorithmic.com/products/substance-painter" target="_blank" rel="noopener">Substance Painter</a> by Allegorithmic</li>
|
|
|
<li><a href="https://www.foundry.com/products/modo" target="_blank" rel="noopener">Modo</a> by Foundry</li>
|
|
|
<li><a href="https://www.marmoset.co/toolbag/" target="_blank" rel="noopener">Toolbag</a> by Marmoset</li>
|
|
|
<li><a href="https://www.sidefx.com/products/houdini/" target="_blank" rel="noopener">Houdini</a> by SideFX</li>
|
|
|
<li><a href="https://labs.maxon.net/?p=3360" target="_blank" rel="noopener">Cinema 4D</a> by MAXON</li>
|
|
|
<li><a href="https://github.com/KhronosGroup/COLLADA2GLTF" target="_blank" rel="noopener">COLLADA2GLTF</a> by the Khronos Group</li>
|
|
|
<li><a href="https://github.com/facebookincubator/FBX2glTF" target="_blank" rel="noopener">FBX2GLTF</a> by Facebook</li>
|
|
|
<li><a href="https://github.com/AnalyticalGraphicsInc/obj2gltf" target="_blank" rel="noopener">OBJ2GLTF</a> by Analytical Graphics Inc</li>
|
|
|
<li>…and <a href="http://github.khronos.org/glTF-Project-Explorer/" target="_blank" rel="noopener">many more</a></li>
|
|
|
</ul>
|
|
|
|
|
|
<p>
|
|
|
If your preferred tools do not support glTF, consider requesting glTF
|
|
|
export from the authors, or posting on
|
|
|
<a href="https://github.com/KhronosGroup/glTF/issues/1051" target="_blank" rel="noopener">the glTF roadmap thread</a>.
|
|
|
</p>
|
|
|
|
|
|
<p>
|
|
|
When glTF is not an option, popular formats such as FBX, OBJ, or COLLADA
|
|
|
are also available and regularly maintained.
|
|
|
</p>
|
|
|
|
|
|
<h2>Loading</h2>
|
|
|
|
|
|
<p>
|
|
|
Only a few loaders (e.g. `ObjectLoader`) are included by default with
|
|
|
three.js — others should be added to your app individually.
|
|
|
</p>
|
|
|
|
|
|
<pre class="prettyprint notranslate lang-js" translate="no">
|
|
|
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
|
|
|
</pre>
|
|
|
|
|
|
<p>
|
|
|
Once you've imported a loader, you're ready to add a model to your scene. Syntax varies among
|
|
|
different loaders — when using another format, check the examples and documentation for that
|
|
|
loader. For glTF, usage with global scripts would be:
|
|
|
</p>
|
|
|
|
|
|
<pre class="prettyprint notranslate lang-js" translate="no">
|
|
|
const loader = new GLTFLoader();
|
|
|
|
|
|
loader.load( 'path/to/model.glb', function ( gltf ) {
|
|
|
|
|
|
scene.add( gltf.scene );
|
|
|
|
|
|
}, undefined, function ( error ) {
|
|
|
|
|
|
console.error( error );
|
|
|
|
|
|
} );
|
|
|
</pre>
|
|
|
|
|
|
<h2>Troubleshooting</h2>
|
|
|
|
|
|
<p>
|
|
|
You've spent hours modeling an artisanal masterpiece, you load it into
|
|
|
the webpage, and — oh no! 😭 It's distorted, miscolored, or missing entirely.
|
|
|
Start with these troubleshooting steps:
|
|
|
</p>
|
|
|
|
|
|
<ol>
|
|
|
<li>
|
|
|
Check the JavaScript console for errors, and make sure you've used an
|
|
|
`onError` callback when calling `.load()` to log the result.
|
|
|
</li>
|
|
|
<li>
|
|
|
View the model in another application. For glTF, drag-and-drop viewers
|
|
|
are available for
|
|
|
<a href="https://gltf-viewer.donmccurdy.com/" target="_blank" rel="noopener">three.js</a> and
|
|
|
<a href="https://sandbox.babylonjs.com/" target="_blank" rel="noopener">babylon.js</a>. If the model
|
|
|
appears correctly in one or more applications,
|
|
|
<a href="https://github.com/mrdoob/three.js/issues/new" target="_blank" rel="noopener">file a bug against three.js</a>.
|
|
|
If the model cannot be shown in any application, we strongly encourage
|
|
|
filing a bug with the application used to create the model.
|
|
|
</li>
|
|
|
<li>
|
|
|
Try scaling the model up or down by a factor of 1000. Many models are
|
|
|
scaled differently, and large models may not appear if the camera is
|
|
|
inside the model.
|
|
|
</li>
|
|
|
<li>
|
|
|
Try to add and position a light source. The model may be hidden in the dark.
|
|
|
</li>
|
|
|
<li>
|
|
|
Look for failed texture requests in the network tab, like
|
|
|
`"C:\\Path\To\Model\texture.jpg"`. Use paths relative to your
|
|
|
model instead, such as `images/texture.jpg` — this may require
|
|
|
editing the model file in a text editor.
|
|
|
</li>
|
|
|
</ol>
|
|
|
|
|
|
<h2>Asking for help</h2>
|
|
|
|
|
|
<p>
|
|
|
If you've gone through the troubleshooting process above and your model
|
|
|
still isn't working, the right approach to asking for help will get you to
|
|
|
a solution faster. Post a question on the
|
|
|
<a href="https://discourse.threejs.org/" target="_blank" rel="noopener">three.js forum</a> and, whenever possible,
|
|
|
include your model (or a simpler model with the same problem) in any formats
|
|
|
you have available. Include enough information for someone else to reproduce
|
|
|
the issue quickly — ideally, a live demo.
|
|
|
</p>
|
|
|
|
|
|
</div>
|
|
|
</div>
|
|
|
</div>
|
|
|
|
|
|
<script src="../resources/prettify.js"></script>
|
|
|
<script src="../resources/lesson.js"></script>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</body></html>
|