Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

LDrawLoader example: Add option to merge geometries after loading #23173

Merged
merged 18 commits into from
Jan 13, 2022
Merged

LDrawLoader example: Add option to merge geometries after loading #23173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
b03db2f
GPGPU Protoplanets example: fix pixel trails
yomboprime Mar 25, 2021
52a7c21
webgl_gpgpu_water.html: Remove mention to orbiting the camera.
yomboprime Mar 25, 2021
44abfc9
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Mar 25, 2021
1da4aa2
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Apr 9, 2021
a583f37
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Apr 12, 2021
7e9aa9e
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Jul 16, 2021
e885472
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Aug 18, 2021
e748beb
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Dec 9, 2021
272141d
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Jan 1, 2022
fcb8adf
Merge branch 'dev' of https://github.com/mrdoob/three.js into dev
yomboprime Jan 7, 2022
e29d759
LDrawLoader example: Add option to merge geometries after loading
yomboprime Jan 7, 2022
c6da3ed
Re-enable conditional lines option when merge model option is on
yomboprime Jan 7, 2022
cba2b60
Remove unnecessary segment vertices permutations
yomboprime Jan 7, 2022
c872aa6
Fix code format
yomboprime Jan 8, 2022
136d6d4
Move the mergeObject function into LDrawLoader
yomboprime Jan 11, 2022
e436526
Extract mergeObject() to LDrawUtils.js
yomboprime Jan 13, 2022
a8c6370
Documentation file for LDrawLoader
yomboprime Jan 13, 2022
04ed0da
Add comment about using LDrawUtils
yomboprime Jan 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 188 additions & 0 deletions docs/examples/en/loaders/LDrawLoader.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<base href="../../../" />
<script src="page.js"></script>
<link type="text/css" rel="stylesheet" href="page.css" />
</head>
<body>
[page:Loader] &rarr;

<h1>[name]</h1>

<p class="desc"> A loader for <em>LDraw</em> resources. <br /><br />
[link:https://ldraw.org LDraw] (LEGO Draw) is an
[link:https://ldraw.org/article/218.html open format specification] 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 [page:Function setPartsLibraryPath]. 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>


<h2>Extensions</h2>

<p>
LDrawLoader supports the following extensions:
</p>

<ul>
<li>!COLOUR: Colour 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>

<h2>Code Example</h2>

<code>
// Instantiate a loader
const loader = new LDrawLoader();

// Optionally set library parts path
// loader.setPartsLibraryPath( path to library );

// Load a LDraw resource
loader.load(
// resource URL
'models/car.ldr_Packed.mpd',
// called when the resource is loaded
function ( group ) {

// Optionally, use LDrawUtils.mergeObject() from
// 'examples/jsm/utils/LDrawUtils.js' to merge all
// geometries by material (it gives better runtime
// performance, but construction steps are lost)
// group = LDrawUtils.mergeObject( group );

scene.add( group );

},
// called while loading is progressing
function ( xhr ) {

console.log( ( xhr.loaded / xhr.total * 100 ) + '% loaded' );

},
// called when loading has errors
function ( error ) {

console.log( 'An error happened' );

}
);
</code>

<h2>Examples</h2>

<p>
[example:webgl_loader_ldraw]
</p>

<h2>Packing LDraw models</h2>

<p>To pack a model with all its referenced files, download the
[link:https://www.ldraw.org/parts/latest-parts.html Official LDraw parts library]
and use the following Node script:
[link:https://github.com/mrdoob/three.js/blob/master/utils/packLDrawModel.js utils/packLDrawModel.js]
It contains instructions on how to setup the files and execute it.</p>

<h2>Metadata in .userData</h2>

<p>LDrawLoader returns a [page:Group] object which contains an object hierarchy. Depending of each subobject
type, its .userData member will contain the following members: <br />
In a [page:Group], the userData member will contain: <br />
<ul>
<li>.numConstructionSteps: Only in the root [page:Group], Indicates total number of construction steps in
the model. These can be used to set visibility of objects to show different construction steps, which is
done in the example.</li>
<li>.constructionStep: Indicates the construction index of this step.</li>
<li>.category: Contains, if not null, the [page:String] category for this piece or model.</li>
<li>.keywords: Contains, if not null, an array of [page:String] keywords for this piece or model.</li>
</ul>
</p>
<p>In a [page:Material], the userData member will contain:
<ul>
<li>.code: Indicates the LDraw code for this material.</li>
<li>.edgeMaterial: Only in a [page:Mesh] material, indicates the [page:LineBasicMaterial] belonging to edges
of the same color code (in the LDraw format, each surface material is also related to an edge material)</li>
<li>.conditionalEdgeMaterial: Only in a [page:LineSegments] material, indicates the [page:Material] belonging
to conditional edges of the same color code.</li>
<ul>
</p>

<br>
<hr>

<h2>Constructor</h2>

<h3>[name]( [param:LoadingManager manager] )</h3>
<p>
[page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
</p>
<p>
Creates a new [name].
</p>

<h2>Properties</h2>
<p>See the base [page:Loader] class for common properties.</p>

<h2>Methods</h2>
<p>See the base [page:Loader] class for common methods.</p>

<h3>[method:undefined load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
<p>
[page:String url] — A string containing the path/URL of the LDraw file.<br />
[page:Function onLoad] — A function to be called after the loading is successfully completed. The function receives the loaded JSON response returned from [page:Function parse].<br />
[page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .[page:Integer total] and .[page:Integer loaded] bytes. If the server does not set the Content-Length header; .[page:Integer total] will be 0.<br />
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.<br />
</p>
<p>
Begin loading from url and call the callback function with the parsed response content.
</p>

<h3>[method:this setPartsLibraryPath]( [param:String path] )</h3>
<p>
[page:String path] — Path to library parts files to load referenced parts from. This is different from [page:Loader.setPath], which indicates the path to load the main asset from.<br />
</p>
<p>
This method must be called prior to [page:.load] 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>

<h3>[method:this setFileMap]( [param:Map fileMap] )</h3>
<p>
[page:Map map] — Set a map from [page:String] to [page:String] 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>

<h3>[method:undefined parse]( [param:String text], [param:String path], [param:Function onLoad], [param:Function onError] )</h3>
<p>
[page:String text] — LDraw asset to parse, as string.<br />
[page:String path] — The base path from which to find other referenced LDraw asset files.<br />
[page:Function onLoad] — A function to be called when parse completes.<br />
</p>
<p>
Parse a LDraw file contents as a String and fire [page:Function onLoad] callback when complete. The argument to [page:Function onLoad] will be an [page:Group] that contains hierarchy of [page:Group], [page:Mesh] and [page:LineSegments] (with other part data in .userData fields).
</p>

<h3>[method:Material getMaterial]( [param:String colourCode] )</h3>
<p>
[page:String colourCode] — For an already loaded LDraw asset, returns the [page:Material] associated with the parameter colour code.
</p>

<h2>Source</h2>

<p>
[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/LDrawLoader.js examples/jsm/loaders/LDrawLoader.js]
</p>
</body>
</html>
1 change: 1 addition & 0 deletions docs/list.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,7 @@
"FontLoader": "examples/en/loaders/FontLoader",
"GLTFLoader": "examples/en/loaders/GLTFLoader",
"KTX2Loader": "examples/en/loaders/KTX2Loader",
"LDrawLoader": "examples/en/loaders/LDrawLoader",
"MMDLoader": "examples/en/loaders/MMDLoader",
"MTLLoader": "examples/en/loaders/MTLLoader",
"OBJLoader": "examples/en/loaders/OBJLoader",
Expand Down
1 change: 1 addition & 0 deletions examples/jsm/loaders/LDrawLoader.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import {
LineBasicMaterial,
LineSegments,
Loader,
Matrix3,
Matrix4,
Mesh,
MeshStandardMaterial,
Expand Down
Loading