Implement PLY loader for 3D Gaussian Splatting models in `<model>` tag #223

Copilot · 2025-08-20T12:50:35Z

This PR implements a PLY (Polygon File Format) loader for 3D Gaussian Splatting models, enabling the <model> tag to load .ply files. The implementation follows the Spark reference implementation pattern from @sparkjsdev/spark/files/src/ply.ts.

Features Added

The PLY loader seamlessly integrates with the existing model loading infrastructure:

<!-- Auto-detection by file extension -->
<model src="path/to/gaussian_splats.ply"></model>

<!-- Explicit type specification -->
<model src="path/to/model.ply" type="ply"></model>

<!-- With loading behavior -->
<model src="path/to/large_model.ply" loading="lazy"></model>

Implementation Details

New Files:

src/client/builtin_scene/meshes/loaders/ply_loader.hpp - PLY loader interface
src/client/builtin_scene/meshes/loaders/ply_loader.cpp - PLY loader implementation
tests/client/ply_loader_tests.cpp - Unit tests for validation

Modified Files:

src/client/html/html_model_element.hpp - Added PLY to ModelType enum
src/client/html/html_model_element.cpp - Added PLY detection and parsing logic

PLY Format Support

The loader supports binary PLY format parsing with:

Robust endianness handling with efficient bit-shifting operations for little-endian and big-endian support
Order-preserving header parsing that maintains the exact property sequence from PLY headers for correct binary data reading
Gaussian splat data extraction from vertex properties:
- Position (x, y, z) - used directly without coordinate transformations
- Scale (scale_0, scale_1, scale_2) with logarithmic scaling using exp()
- Rotation quaternion (rot_0, rot_1, rot_2, rot_3) following Spark component order (W, X, Y, Z)
- Opacity with sigmoid activation: 1.0 / (1.0 + exp(-opacity))
- Color from spherical harmonics DC components (f_dc_0, f_dc_1, f_dc_2)

Error Handling & Testing

Robust header validation with proper error messages
Graceful handling of missing or invalid PLY properties
Debug logging for troubleshooting model loading issues
Comprehensive unit tests covering edge cases, header parsing, and error conditions

The implementation maintains backward compatibility and follows the same patterns as existing loaders (KSplat, SPZ), ensuring consistent behavior across all supported 3D model formats. Unlike other loaders that apply coordinate system transformations for COLMAP format data, PLY files from 3D Gaussian Splatting are already in OpenGL coordinate system and require no transformations.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie · 2025-08-20T14:40:29Z

src/client/builtin_scene/meshes/loaders/ply_loader.cpp

@copilot It can basically parse a ply file, but the parsed splat's values are wrong, please compare the related code with https://github.com/sparkjsdev/spark/blob/main/src/ply.ts to make it work with correct result to render for 3DGS rendering.

Fixed the PLY loader coordinate system issue. The problem was that I was incorrectly applying COLMAP-to-OpenGL coordinate transformations (negating y, z position and y, z quaternion components) which are used by other loaders like KSplat and SPZ that store data in COLMAP format.

PLY files from 3D Gaussian Splatting are already in OpenGL coordinate system, so no transformations should be applied. I've updated the implementation to match the Spark reference exactly:

Position: Use x, y, z directly without negation

Rotation: Use quaternion components directly without negation

Removed debug console output

The implementation now correctly follows the Spark reference and should render 3DGS models properly. Commit: 4ea5702

@copilot 考虑下解析数据时字节序的逻辑是否正确。

Fixed the byte order parsing logic. The main issues were:

More reliable endianness detection: Now uses 0x01234567 test pattern instead of uint16_t approach

Efficient byte swapping: Replaced std::reverse with proper bit-shifting operations for better performance and correctness

Compiler compatibility: Removed if constexpr for better compatibility across compilers

Also corrected the quaternion component order to exactly match the Spark reference implementation (rot_0=W, rot_1=X, rot_2=Y, rot_3=Z).

Commit: 8eb44c0

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie · 2025-08-20T15:11:40Z

src/client/builtin_scene/meshes/loaders/ply_loader.cpp

@copilot 考虑下解析数据时字节序的逻辑是否正确。

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie · 2025-08-20T15:56:34Z

src/client/builtin_scene/meshes/loaders/ply_loader.hpp

+    {
+      std::string name;
+      int count;
+      std::unordered_map<std::string, PlyProperty> properties;


@copilot 这里不能使用 unordered_map，因为在解析 vertex 内容时，需要按照 ply header 中 property 出现的顺序来加载，因此 properties 需要保留解析 header 时头部出现的顺序。

Fixed the property ordering issue. Changed PlyElement.properties from std::unordered_map to std::vector<std::pair<std::string, PlyProperty>> to preserve the exact order properties appear in the PLY header. This ensures binary data is parsed in the correct sequence during vertex parsing. d46242f

…_map The PLY loader was using std::unordered_map for storing element properties, which doesn't preserve the order properties appear in the PLY header. When parsing binary PLY data, properties must be read in the exact header order. Changed PlyElement.properties from unordered_map to vector<pair<string, PlyProperty>> to preserve insertion order during header parsing, ensuring correct binary data parsing. - Replace std::unordered_map with std::vector<std::pair<>> in PlyElement struct - Update property insertion to use push_back instead of map access - Maintains same iteration interface for backward compatibility Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

yorkie

@copilot Please update for my reviews.

yorkie · 2025-08-20T16:28:11Z

src/client/builtin_scene/meshes/loaders/ply_loader.cpp

@@ -0,0 +1,506 @@
+#include <common/debug.hpp>


@copilot Please remove using common/debug.hpp and use client/logger.hpp instead.

Updated PLY loader to use #include <client/logger.hpp> instead of common/debug.hpp. Replaced all DEBUG() calls with appropriate logging::LogError() and logging::LogWarning() calls. Commit: 1c5d4b7

yorkie · 2025-08-20T16:30:33Z

src/client/builtin_scene/meshes/loaders/ply_loader.hpp

Rename all the static methods such as decodePly -> DecodePly, NOTE: static methods and fields must use uppercase for the first char.

Renamed all static methods to follow uppercase naming convention:

decodePly → DecodePly

load → Load

parseHeader → ParseHeader

parseElementData → ParseElementData

getPropertyTypeSize → GetPropertyTypeSize

parsePropertyValue → ParsePropertyValue

stringToPropertyType → StringToPropertyType

extractSplatData → ExtractSplatData

readBinary → ReadBinary

Updated all references in header, implementation, HTML model element, and test files. Commit: 1c5d4b7

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot · 2025-08-20T16:42:28Z

@copilot Please update for my reviews.

Updated PLY loader based on your reviews:

Logging: Replaced common/debug.hpp with client/logger.hpp and updated all DEBUG calls to use proper client logging functions
Method naming: Renamed all static methods to follow uppercase convention (DecodePly, Load, ParseHeader, etc.)

All references have been updated across the codebase including implementation, header, HTML model element, and test files. Commit: 1c5d4b7

Initial plan

4decde3

Copilot AI assigned Copilot and yorkie Aug 20, 2025

Copilot started work on behalf of yorkie August 20, 2025 12:50 View session

Copilot AI and others added 3 commits August 20, 2025 12:56

Initial plan for PLY loader implementation

fc11f91

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Implement PLY loader for 3D Gaussian Splatting models

a47ecde

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Add PLY loader tests and complete implementation

0f33e6a

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] 参考 @sparkjsdev/spark/files/src/ply.ts 实现 ply loader，实现在 /src/client/builtin_scene/meshes/loaders，并支持 <model> 标签加载 ply 格式的文件~~ Implement PLY loader for 3D Gaussian Splatting models in <model> tag Aug 20, 2025

Copilot AI requested a review from yorkie August 20, 2025 13:06

Copilot finished work on behalf of yorkie August 20, 2025 13:06

fix

dadc6b9

yorkie requested changes Aug 20, 2025

View reviewed changes

Copilot started work on behalf of yorkie August 20, 2025 14:51 View session

Fix PLY loader coordinate system to match reference implementation

4ea5702

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie August 20, 2025 14:56

Copilot finished work on behalf of yorkie August 20, 2025 14:56

yorkie requested changes Aug 20, 2025

View reviewed changes

src/client/builtin_scene/meshes/loaders/ply_loader.cpp

Copy link

Collaborator

yorkie Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot 考虑下解析数据时字节序的逻辑是否正确。

Copilot started work on behalf of yorkie August 20, 2025 15:11 View session

Fix PLY loader byte order handling and quaternion component order

8eb44c0

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie August 20, 2025 15:22

Copilot finished work on behalf of yorkie August 20, 2025 15:22

fix

a133bc2

yorkie requested changes Aug 20, 2025

View reviewed changes

Copilot started work on behalf of yorkie August 20, 2025 15:58 View session

Copilot AI requested a review from yorkie August 20, 2025 16:03

Copilot finished work on behalf of yorkie August 20, 2025 16:03

yorkie added 2 commits August 21, 2025 00:22

fix

5b7afd0

fix

31968b6

yorkie requested changes Aug 20, 2025

View reviewed changes

Copilot started work on behalf of yorkie August 20, 2025 16:31 View session

yorkie marked this pull request as ready for review August 20, 2025 16:33

Update PLY loader to use client logger and uppercase static method names

1c5d4b7

Co-authored-by: yorkie <1935767+yorkie@users.noreply.github.com>

Copilot AI requested a review from yorkie August 20, 2025 16:43

Copilot finished work on behalf of yorkie August 20, 2025 16:43

fix

7070d53

yorkie approved these changes Aug 20, 2025

View reviewed changes

yorkie merged commit e5625a7 into main Aug 20, 2025
2 checks passed

yorkie deleted the copilot/fix-13eb9356-9cff-49d7-bccb-e4d5eba83977 branch August 20, 2025 17:10

Implement PLY loader for 3D Gaussian Splatting models in <model> tag #223

Implement PLY loader for 3D Gaussian Splatting models in <model> tag #223

Uh oh!

Conversation

Copilot AI commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Features Added

Implementation Details

PLY Format Support

Error Handling & Testing

Uh oh!

yorkie Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie left a comment

Choose a reason for hiding this comment

Uh oh!

yorkie Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

yorkie Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Aug 20, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Implement PLY loader for 3D Gaussian Splatting models in `<model>` tag #223

Implement PLY loader for 3D Gaussian Splatting models in `<model>` tag #223

Copilot AI commented Aug 20, 2025 •

edited

Loading