Skip to content

Commit 642dd50

Browse files
mmjinglin163mmjinglin163
authored
Docs: Add PLYLoader documentation (#31848)
1 parent 307b00c commit 642dd50

File tree

2 files changed

+158
-0
lines changed

2 files changed

+158
-0
lines changed

‎docs/examples/en/loaders/PLYLoader.html‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<base href="../../../" />
6+
<script src="page.js"></script>
7+
<link type="text/css" rel="stylesheet" href="page.css" />
8+
</head>
9+
<body>
10+
[page:Loader] &rarr;
11+
12+
<h1>[name]</h1>
13+
14+
<p class="desc">
15+
A loader for the PLY (Polygon File Format) file format, also known as the Stanford Triangle Format. [name] supports both ASCII and binary files as well as the following PLY properties:
16+
<ul>
17+
<li>x, y, z (vertex positions)</li>
18+
<li>nx, ny, nz (vertex normals)</li>
19+
<li>s, t / u, v (texture coordinates)</li>
20+
<li>red, green, blue (vertex colors)</li>
21+
<li>vertex_indices (face indices)</li>
22+
<li>Custom properties via property name mapping</li>
23+
</ul>
24+
</p>
25+
26+
<h2>Import</h2>
27+
28+
<p>
29+
[name] is an add-on, and must be imported explicitly.
30+
See [link:#manual/introduction/Installation Installation / Addons].
31+
</p>
32+
33+
<code>
34+
import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
35+
</code>
36+
37+
<h2>Code Example</h2>
38+
39+
<code>
40+
41+
// instantiate a loader
42+
const loader = new PLYLoader();
43+
44+
// load a resource
45+
loader.load(
46+
// resource URL
47+
'models/ply/ascii/dolphins.ply',
48+
// called when the resource is loaded
49+
function ( geometry ) {
50+
// compute vertex normals if not present in the file
51+
geometry.computeVertexNormals();
52+
const material = new THREE.MeshStandardMaterial( { color: 0x0055ff } );
53+
const mesh = new THREE.Mesh( geometry, material );
54+
scene.add( mesh );
55+
56+
},
57+
// called when loading is in progress
58+
function ( xhr ) {
59+
60+
console.log( ( xhr.loaded / xhr.total * 100 ) + '% loaded' );
61+
62+
},
63+
// called when loading has errors
64+
function ( error ) {
65+
66+
console.log( 'An error happened' );
67+
68+
}
69+
);
70+
</code>
71+
72+
<h2>Examples</h2>
73+
<p>
74+
[example:webgl_loader_ply]
75+
</p>
76+
77+
<h2>Constructor</h2>
78+
79+
<h3>[name]( [param:LoadingManager manager] )</h3>
80+
<p>
81+
[page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
82+
</p>
83+
<p>
84+
Creates a new [name].
85+
</p>
86+
87+
<h2>Properties</h2>
88+
<p>See the base [page:Loader] class for common properties.</p>
89+
90+
<h3>[page:Object propertyNameMapping]</h3>
91+
<p>
92+
An object that maps default property names to custom ones. Used for handling non-standard PLY property names.
93+
</p>
94+
95+
<h3>[page:Object customPropertyMapping]</h3>
96+
<p>
97+
An object that defines custom property mappings for attributes not covered by the standard position, normal, uv, and color properties.
98+
</p>
99+
100+
<h2>Methods</h2>
101+
<p>See the base [page:Loader] class for common methods.</p>
102+
103+
<h3>[method:undefined load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
104+
<p>
105+
[page:String url] — A string containing the path/URL of the `.ply` file.<br />
106+
[page:Function onLoad] — (optional) A function to be called after loading is successfully completed. The function receives the loaded [page:BufferGeometry] as an argument.<br />
107+
[page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, which 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 />
108+
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives the error as an argument.<br />
109+
</p>
110+
<p>
111+
Begin loading from url and call onLoad with the parsed response content.
112+
</p>
113+
114+
<h3>[method:BufferGeometry parse]( [param:ArrayBuffer data] )</h3>
115+
<p>
116+
[page:ArrayBuffer data] — The binary or text structure to parse.
117+
</p>
118+
<p>
119+
Parse a PLY binary or ASCII structure and return a [page:BufferGeometry].<br />
120+
The geometry contains vertex positions and may include vertex normals, texture coordinates, vertex colors, and face indices depending on the PLY file content.
121+
</p>
122+
123+
<h3>[method:undefined setPropertyNameMapping]( [param:Object mapping] )</h3>
124+
<p>
125+
[page:Object mapping] — An object that maps default property names to custom ones.
126+
</p>
127+
<p>
128+
Sets a property name mapping that maps default property names to custom ones. For example, the following maps the properties "diffuse_(red|green|blue)" in the file to standard color names:
129+
</p>
130+
<code>
131+
loader.setPropertyNameMapping( {
132+
diffuse_red: 'red',
133+
diffuse_green: 'green',
134+
diffuse_blue: 'blue'
135+
} );
136+
</code>
137+
138+
<h3>[method:undefined setCustomPropertyNameMapping]( [param:Object mapping] )</h3>
139+
<p>
140+
[page:Object mapping] — An object that defines custom property mappings.
141+
</p>
142+
<p>
143+
Custom properties outside of the defaults for position, uv, normal and color attributes can be added using this method. For example, the following maps the element properties "custom_property_a" and "custom_property_b" to an attribute "customAttribute" with an item size of 2:
144+
</p>
145+
<code>
146+
loader.setCustomPropertyNameMapping( {
147+
customAttribute: ['custom_property_a', 'custom_property_b']
148+
} );
149+
</code>
150+
151+
<h2>Source</h2>
152+
153+
<p>
154+
[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/PLYLoader.js examples/jsm/loaders/PLYLoader.js]
155+
</p>
156+
</body>
157+
</html>

‎docs/list.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -358,6 +358,7 @@
358358
"OBJLoader": "examples/en/loaders/OBJLoader",
359359
"PCDLoader": "examples/en/loaders/PCDLoader",
360360
"PDBLoader": "examples/en/loaders/PDBLoader",
361+
"PLYLoader": "examples/en/loaders/PLYLoader",
361362
"SVGLoader": "examples/en/loaders/SVGLoader",
362363
"TGALoader": "examples/en/loaders/TGALoader"
363364
},

0 commit comments

Comments
 (0)