samien
/
three.js
mirror of https://github.com/mrdoob/three.js.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381
							<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<title>LDrawLoader - Three.js Docs</title>
	<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
	<script src="../scripts/highlight.min.js"></script>
	<link type="text/css" rel="stylesheet" href="../styles/highlight-three.css">
	<link type="text/css" rel="stylesheet" href="../styles/page.css">
</head>
<body>
		<p class="inheritance" translate="no"><a href="Loader.html">Loader</a> → </p>
	<h1 translate="no">LDrawLoader</h1>
		<section>
			<header>
				<div class="class-description"><p>A loader for the LDraw format.</p>
<p>[LDraw](https://ldraw.org/} (LEGO Draw) is an <a href="https://ldraw.org/article/218.html" target="_blank" rel="noopener">open format specification</a>
for describing LEGO and other construction set 3D models.</p>
<p>An LDraw asset (a text file usually with extension .ldr, .dat or .txt) can describe just a single construction
piece, or an entire model. In the case of a model the LDraw file can reference other LDraw files, which are
loaded from a library path set with <code>setPartsLibraryPath</code>. You usually download the LDraw official parts library,
extract to a folder and point setPartsLibraryPath to it.</p>
<p>Library parts will be loaded by trial and error in subfolders 'parts', 'p' and 'models'. These file accesses
are not optimal for web environment, so a script tool has been made to pack an LDraw file with all its dependencies
into a single file, which loads much faster. See section 'Packing LDraw models'. The LDrawLoader example loads
several packed files. The official parts library is not included due to its large size.</p>
<p><code>LDrawLoader</code> supports the following extensions:</p>
<ul>
<li>!COLOUR: Color and surface finish declarations.</li>
<li>BFC: Back Face Culling specification.</li>
<li>!CATEGORY: Model/part category declarations.</li>
<li>!KEYWORDS: Model/part keywords declarations.</li>
</ul></div>
				<h2>Code Example</h2>
				<div translate="no"><pre><code class="language-js">const loader = new LDrawLoader();
loader.setConditionalLineMaterial( LDrawConditionalLineMaterial ); // the type of line material depends on the used renderer
const object = await loader.loadAsync( 'models/ldraw/officialLibrary/models/car.ldr_Packed.mpd' );
scene.add( object );
</code></pre></div>
			</header>
			<article>
				<h2 class="subsection-title">Import</h2>
				<p><span translate="no">LDrawLoader</span> is an addon, and must be imported explicitly, see <a href="https://threejs.org/manual/#en/installation" target="_blank" rel="noopener">Installation#Addons</a>.</p>
				<pre><code class="language-js">import { LDrawLoader } from 'three/addons/loaders/LDrawLoader.js';</code></pre>
				<div class="container-overview">
					<h2>Constructor</h2>
					<h3 class="name name-method" id="LDrawLoader" translate="no">new <a href="#LDrawLoader">LDrawLoader</a><span class="signature">( manager : <span class="param-type"><a href="LoadingManager.html">LoadingManager</a></span> )</span> </h3>
					<div class="method">
						<div class="description">
							<p>Constructs a new LDraw loader.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>manager</strong>
									</td>
									<td class="description last">
										<p>The loading manager.</p>
									</td>
								</tr>
							</tbody>
						</table>
					</div>
				</div>
				<h2 class="subsection-title">Methods</h2>
					<h3 class="name name-method" id="addDefaultMaterials" translate="no">.<a href="#addDefaultMaterials">addDefaultMaterials</a><span class="signature">()</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Initializes the loader with default materials.</p>
						</div>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="addMaterial" translate="no">.<a href="#addMaterial">addMaterial</a><span class="signature">( material : <span class="param-type"><a href="Material.html">Material</a></span> )</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Adds a single material to the loader's material library.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>material</strong>
									</td>
									<td class="description last">
										<p>The material to add.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="addMaterials" translate="no">.<a href="#addMaterials">addMaterials</a><span class="signature">( materials : <span class="param-type">Array.&lt;<a href="Material.html">Material</a>></span> )</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Adds a list of materials to the loader's material library.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>materials</strong>
									</td>
									<td class="description last">
										<p>The materials to add.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="clearMaterials" translate="no">.<a href="#clearMaterials">clearMaterials</a><span class="signature">()</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Clears the loader's material library.</p>
						</div>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="getMainEdgeMaterial" translate="no">.<a href="#getMainEdgeMaterial">getMainEdgeMaterial</a><span class="signature">()</span><span class="type-signature"> : <a href="Material.html">Material</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Returns the material for the edges main LDraw color.</p>
						</div>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> The material. Returns <code>null</code> if no material has been found.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="getMainMaterial" translate="no">.<a href="#getMainMaterial">getMainMaterial</a><span class="signature">()</span><span class="type-signature"> : <a href="Material.html">Material</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Returns the Material for the main LDraw color.</p>
<p>For an already loaded LDraw asset, returns the Material associated with the main color code.
This method can be useful to modify the main material of a model or part that exposes it.</p>
<p>The main color code is the standard way to color an LDraw part. It is '16' for triangles and
'24' for edges. Usually a complete model will not expose the main color (that is, no part
uses the code '16' at the top level, because they are assigned other specific colors) An LDraw
part file on the other hand will expose the code '16' to be colored, and can have additional
fixed colors.</p>
						</div>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> The material. Returns <code>null</code> if no material has been found.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="getMaterial" translate="no">.<a href="#getMaterial">getMaterial</a><span class="signature">( colorCode : <span class="param-type">string</span> )</span><span class="type-signature"> : <a href="Material.html">Material</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Returns a material for the given color code.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>colorCode</strong>
									</td>
									<td class="description last">
										<p>The color code.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> The material. Returns <code>null</code> if no material has been found.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="load" translate="no">.<a href="#load">load</a><span class="signature">( url : <span class="param-type">string</span>, onLoad : <span class="param-type">function</span>, onProgress : <span class="param-type"><a href="global.html#onProgressCallback">onProgressCallback</a></span>, onError : <span class="param-type"><a href="global.html#onErrorCallback">onErrorCallback</a></span> )</span> </h3>
					<div class="method">
						<div class="description">
							<p>Starts loading from the given URL and passes the loaded LDraw asset
to the <code>onLoad()</code> callback.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>url</strong>
									</td>
									<td class="description last">
										<p>The path/URL of the file to be loaded. This can also be a data URI.</p>
									</td>
								</tr>
								<tr>
									<td class="name">
										<strong>onLoad</strong>
									</td>
									<td class="description last">
										<p>Executed when the loading process has been finished.</p>
									</td>
								</tr>
								<tr>
									<td class="name">
										<strong>onProgress</strong>
									</td>
									<td class="description last">
										<p>Executed while the loading is in progress.</p>
									</td>
								</tr>
								<tr>
									<td class="name">
										<strong>onError</strong>
									</td>
									<td class="description last">
										<p>Executed when errors occur.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-overrides"><strong>Overrides:</strong> <a href="Loader.html#load">Loader#load</a></dt>
						</dl>
					</div>
					<h3 class="name name-method" id="parse" translate="no">.<a href="#parse">parse</a><span class="signature">( text : <span class="param-type">string</span>, onLoad : <span class="param-type">function</span>, onError : <span class="param-type"><a href="global.html#onErrorCallback">onErrorCallback</a></span> )</span> </h3>
					<div class="method">
						<div class="description">
							<p>Parses the given LDraw data and returns the resulting group.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>text</strong>
									</td>
									<td class="description last">
										<p>The raw VRML data as a string.</p>
									</td>
								</tr>
								<tr>
									<td class="name">
										<strong>onLoad</strong>
									</td>
									<td class="description last">
										<p>Executed when the loading/parsing process has been finished.</p>
									</td>
								</tr>
								<tr>
									<td class="name">
										<strong>onError</strong>
									</td>
									<td class="description last">
										<p>Executed when errors occur.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-overrides"><strong>Overrides:</strong> <a href="Loader.html#parse">Loader#parse</a></dt>
						</dl>
					</div>
					<h3 class="name name-method" id="preloadMaterials" translate="no">.<a href="#preloadMaterials">preloadMaterials</a><span class="signature">( url : <span class="param-type">string</span> )</span><span class="type-signature"> : Promise</span> <span class="type-signature">(async) </span></h3>
					<div class="method">
						<div class="description">
							<p>This async method preloads materials from a single LDraw file. In the official
parts library there is a special file which is loaded always the first (LDConfig.ldr)
and contains all the standard color codes. This method is intended to be used with
not packed files, for example in an editor where materials are preloaded and parts
are loaded on demand.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>url</strong>
									</td>
									<td class="description last">
										<p>Path of the LDraw materials asset.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A Promise that resolves when the preload has finished.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="setConditionalLineMaterial" translate="no">.<a href="#setConditionalLineMaterial">setConditionalLineMaterial</a><span class="signature">( type : <span class="param-type">LDrawConditionalLineMaterial.constructor | LDrawConditionalLineNodeMaterial.constructor</span> )</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Sets the conditional line material type which depends on the used renderer.
Use <a href="LDrawConditionalLineMaterial.html">LDrawConditionalLineMaterial</a> when using <code>WebGLRenderer</code> and
LDrawConditionalLineNodeMaterial when using <code>WebGPURenderer</code>.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>type</strong>
									</td>
									<td class="description last">
										<p>The conditional line material type.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="setFileMap" translate="no">.<a href="#setFileMap">setFileMap</a><span class="signature">( fileMap : <span class="param-type">Object.&lt;string, string></span> )</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Sets a map which maps referenced library filenames to new filenames.
If a fileMap is not specified (the default), library parts will be accessed by trial and
error in subfolders 'parts', 'p' and 'models'.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>fileMap</strong>
									</td>
									<td class="description last">
										<p>The file map to set.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="setMaterials" translate="no">.<a href="#setMaterials">setMaterials</a><span class="signature">( materials : <span class="param-type">Array.&lt;<a href="Material.html">Material</a>></span> )</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>Sets the loader's material library. This method clears existing
material definitions.</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>materials</strong>
									</td>
									<td class="description last">
										<p>The materials to set.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
					<h3 class="name name-method" id="setPartsLibraryPath" translate="no">.<a href="#setPartsLibraryPath">setPartsLibraryPath</a><span class="signature">( path : <span class="param-type">string</span> )</span><span class="type-signature"> : <a href="LDrawLoader.html">LDrawLoader</a></span> </h3>
					<div class="method">
						<div class="description">
							<p>This method must be called prior to <code>load()</code> unless the model to load does not reference
library parts (usually it will be a model with all its parts packed in a single file).</p>
						</div>
						<table class="params">
							<tbody>
								<tr>
									<td class="name">
										<strong>path</strong>
									</td>
									<td class="description last">
										<p>Path to library parts files to load referenced parts from.
This is different from Loader.setPath, which indicates the path to load the main asset from.</p>
									</td>
								</tr>
							</tbody>
						</table>
						<dl class="details">
							<dt class="tag-returns"><strong>Returns:</strong> A reference to this loader.</dt>
						</dl>
					</div>
				<h2 class="subsection-title">Source</h2>
				<p>
					<a href="https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/LDrawLoader.js" translate="no" target="_blank" rel="noopener">examples/jsm/loaders/LDrawLoader.js</a>
				</p>
			</article>
		</section>
<script src="../scripts/linenumber.js"></script>
<script src="../scripts/page.js"></script>
</body>
</html>