Skip to content

Docs: Add PLYLoader documentation #31848

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

Merged
Mugen87 merged 1 commit into from
Sep 8, 2025
Merged

Docs: Add PLYLoader documentation #31848

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
157 changes: 157 additions & 0 deletions docs/examples/en/loaders/PLYLoader.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,157 @@
<!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 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:
<ul>
<li>x, y, z (vertex positions)</li>
<li>nx, ny, nz (vertex normals)</li>
<li>s, t / u, v (texture coordinates)</li>
<li>red, green, blue (vertex colors)</li>
<li>vertex_indices (face indices)</li>
<li>Custom properties via property name mapping</li>
</ul>
</p>

<h2>Import</h2>

<p>
[name] is an add-on, and must be imported explicitly.
See [link:#manual/introduction/Installation Installation / Addons].
</p>

<code>
import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
</code>

<h2>Code Example</h2>

<code>

// instantiate a loader
const loader = new PLYLoader();

// load a resource
loader.load(
// resource URL
'models/ply/ascii/dolphins.ply',
// called when the resource is loaded
function ( geometry ) {
// compute vertex normals if not present in the file
geometry.computeVertexNormals();
const material = new THREE.MeshStandardMaterial( { color: 0x0055ff } );
const mesh = new THREE.Mesh( geometry, material );
scene.add( mesh );

},
// called when loading is in progress
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_ply]
</p>

<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>

<h3>[page:Object propertyNameMapping]</h3>
<p>
An object that maps default property names to custom ones. Used for handling non-standard PLY property names.
</p>

<h3>[page:Object customPropertyMapping]</h3>
<p>
An object that defines custom property mappings for attributes not covered by the standard position, normal, uv, and color 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 `.ply` file.<br />
[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 />
[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 />
[page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives the error as an argument.<br />
</p>
<p>
Begin loading from url and call onLoad with the parsed response content.
</p>

<h3>[method:BufferGeometry parse]( [param:ArrayBuffer data] )</h3>
<p>
[page:ArrayBuffer data] — The binary or text structure to parse.
</p>
<p>
Parse a PLY binary or ASCII structure and return a [page:BufferGeometry].<br />
The geometry contains vertex positions and may include vertex normals, texture coordinates, vertex colors, and face indices depending on the PLY file content.
</p>

<h3>[method:undefined setPropertyNameMapping]( [param:Object mapping] )</h3>
<p>
[page:Object mapping] — An object that maps default property names to custom ones.
</p>
<p>
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:
</p>
<code>
loader.setPropertyNameMapping( {
diffuse_red: 'red',
diffuse_green: 'green',
diffuse_blue: 'blue'
} );
</code>

<h3>[method:undefined setCustomPropertyNameMapping]( [param:Object mapping] )</h3>
<p>
[page:Object mapping] — An object that defines custom property mappings.
</p>
<p>
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:
</p>
<code>
loader.setCustomPropertyNameMapping( {
customAttribute: ['custom_property_a', 'custom_property_b']
} );
</code>

<h2>Source</h2>

<p>
[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/PLYLoader.js examples/jsm/loaders/PLYLoader.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 @@ -358,6 +358,7 @@
"OBJLoader": "examples/en/loaders/OBJLoader",
"PCDLoader": "examples/en/loaders/PCDLoader",
"PDBLoader": "examples/en/loaders/PDBLoader",
"PLYLoader": "examples/en/loaders/PLYLoader",
"SVGLoader": "examples/en/loaders/SVGLoader",
"TGALoader": "examples/en/loaders/TGALoader"
},
Expand Down