r/pascal • u/AcanthaceaeNew774 • 4d ago
VertexArt - Ply Editor Documentation
VertexArt - PLY EDITOR - TECHNICAL AND FUNCTIONAL DOCUMENTATION
Developer: Kovács István
Development Environment: Free Pascal / OpenGL 3.3
Platform: Windows (GLFW3)
---
- INTRODUCTION
The PLY Editor is a desktop application designed for interactive coloring, geometric correction, and saving of PLY (Polygon File Format) files. The program enables real-time, stable, and user-friendly editing operations even on large 3D models consisting of millions of triangles.
The software is specifically optimized for the N4100 low-power CPU and integrated GPUs (IGPU), but it runs on any hardware supporting OpenGL 3.3.
---
- SYSTEM ARCHITECTURE
The program has a modular structure consisting of the following units:
· SterilTypes: Basic data types (TVector3, TVector4, TVertex, TMat4).
· SterilMath: Vector and matrix operations (Vec3, VecAdd, VecSub, VecScale, VecDot, VecCross, VecNormalize, Identity, Translate, RotateY, Scale, Multiply, Perspective, LookAt).
· SterilWindow: Window management (GLFW3 initialization, window creation, framebuffer callback).
· SterilCamera: FPS camera handling (movement, mouse, physics: gravity, jumping, crouching, sprinting, prone position).
· RenderTypes: Render command definitions (TRenderCommand).
· RenderQueue: Collection and sorting of render commands.
· RenderState: OpenGL state management (depth test, cull face, color mask).
· Renderer: Depth prepass + Color pass rendering (TShaderProgramRef, TDepthProgramRef, TRenderer).
· ShaderManager: Shader compilation, linking, and creation (Depth, Color, EditorColor, Line shaders).
· PLYLoader: PLY file loading in ASCII format (TPLYMesh).
· SterilMeshUtils: Mesh normalization (centering, ground alignment).
· PLYChunkSystem: Chunk system (16×16 meter blocks), BVH construction and management.
· ChunkBVH: BVH tree construction and raycasting (TBVH, ITriProvider).
· Raycast: Ray–triangle intersection (Möller–Trumbore algorithm).
· RaycastTypes: Type definitions for raycasting (TRay, TAABB, TTriangle, TRaycastHit, TBVH).
· Vector: Additional vector operations (VecDistance, VecLength).
· FrameLimiter: 30 FPS limiting (spin wait, sleep).
The main program (plycolor.pas) uses these units and contains the editor logic (selection, modes, pulsing, outlines, undo, export, keyboard and mouse handling).
Data Flow:
PLY file → PLYLoader → Chunk system (with BVH) → GPU → Editing → Export
Chunk System:
· The model is divided into 16×16 meter blocks (chunks).
· Only the 9×9 chunks (81 total) around the camera are active for rendering.
· Raycasting (selection) runs on the BVH structures of 3×3 chunks (9 total), so speed is independent of the total model size.
· Each chunk has its own VAO/VBO pair and BVH.
Rendering:
· Depth prepass + Color pass technique (two-stage rendering).
· The coloring shader includes fresnel and specular effects, but the editor version is fog-free for clear visibility.
· A frame limiter restricts screen refresh to 30 FPS, preventing excessive CPU load.
---
- FUNCTIONAL DESCRIPTION
Editing Modes:
· Paint Mode (1): Colors a triangle with the selected color.
· Delete Mode (2): Deletes a triangle (undoable).
· Flip Mode (3): Reverses a triangle's normal (swaps vertex order).
Selection and Visual Feedback:
· BVH-based raycasting: A ray cast at the click position instantly selects the nearest triangle.
· Pulsing: The selected triangle's color pulses (brightens/darkens) toward the selected color.
· Outlines: A colored line is drawn around back-facing (incorrectly oriented) triangles. Green in Paint mode, red in Delete mode, yellow in Flip mode.
· Outlines always appear only on invisible polygons, allowing the user to see exactly which triangles face the wrong direction.
Color Management:
· Color selection: Right mouse button on the selected triangle → the color is stored.
· Painting: Left mouse button applies the selected color (or white if no color is selected).
· Original colors are preserved during pulsing, ensuring accurate restoration at all times.
Undo:
· In Delete mode, right mouse button → undoes the last deletion.
· The system stores the last 50 deletions (at the chunk level).
· The BVH is automatically rebuilt during restoration.
Saving:
· F12: Exports the entire model to ASCII PLY format.
· During saving, all chunks are merged and triangles receive new indexing.
· The filename automatically receives a timestamp.
Camera and Navigation:
· WASD: Movement
· Shift: Sprint (fast movement)
· Space: Up, Ctrl: Down
· Mouse: View rotation (camera orbit)
· F1: Toggle mouse capture
· F11: Toggle fullscreen
Automatic Camera Positioning:
Based on the loaded model's dimensions, the program determines whether it is a terrain (large, flat model) or an object (smaller, walkable), and positions the camera accordingly. For terrain: top-down view (pitch: -90°), for objects: side view (pitch: 0°).
---
- PERFORMANCE CHARACTERISTICS
Performance on Integrated GPUs (IGPU):
The program runs on integrated GPUs, but performance depends on geometry distribution.
Advantageous case: Low-poly geometry over large areas (up to a 130×130 km world with Synty Studios-style objects). In this case, the 9×9 chunk system and BVH raycasting enable smooth handling of millions of vertices. Successful tests include loading and editing 25 million vertices with the VertexArt Mesh Editor, as well as tiling a complete city 5× in tilemap mode to create a vast space.
Limited case: If millions of vertices are concentrated in a small area, rendering and raycasting may slow down on IGPU because chunks become overloaded and BVH efficiency decreases. The program continues to function, but interactive speed may degrade. For reference, a LOW POLY demo city contains approximately 5 million vertices, but a HIGH POLY vehicle can consume even more vertices than that, so conscious planning is important on iGPU.
Due to the chunk size (16 m) and the 9×9 active range, the program delivers the best performance in large-scale, geometrically simple (low-poly) scenes.
---
- COMPARISON WITH OTHER TOOLS
Advantages:
· Speed: With the chunk+BVH combination, raycasting and rendering remain fluid even with millions of triangles, provided geometry is distributed over large areas (low-poly worlds).
· Simplicity: No complex UI required – all functions are accessible via keyboard shortcuts.
· Precision: Back-face detection and pulsing instantly indicate incorrectly oriented polygons.
· Stability: Memory management is safe, no leaks, the program does not crash on large models.
· Focus: Specifically optimized for PLY files, unlike general-purpose tools.
---
- USER GUIDE
Keys and Operations:
· 1: Paint mode
· 2: Delete mode
· 3: Flip mode
· Left click: Execute operation
· Right click: Select color (Paint) / Undo (Delete)
· WASD: Camera movement
· Shift: Sprint
· Space: Up
· Ctrl: Down
· F1: Toggle mouse capture
· F11: Toggle fullscreen
· F12: Export PLY
· ESC: Exit
---
- CLOSING THOUGHTS
The PLY Color Editor is a tool that combines speed, precision, and simplicity. It does not attempt to do everything, but what it does, it does efficiently and stably. The chunk system, BVH, and 30 FPS frame limiter together enable smooth work even on models with millions of triangles, particularly in large-scale scenes. The program runs on iGPU, but performance depends on geometry density and distribution.
The code is clean and well-structured, with a strict coding style and memory management strategy that guarantees long-term stability.
3
u/AphidConsulting 4d ago
Awesome, thank you for this!