ModelViewer

Features Overview

Rendering Modes & Visualization

ModelViewer supports a comprehensive range of visualization and rendering styles for different inspection and analysis needs:

• Solid Shading: Standard surface rendering
• Wireframe: Edge visualization for topology inspection
• Wireframe Overlay: Wireframe on solid for combined visualization
• Vertex Colors: Direct vertex color visualization from model data
• ADS (Ambient-Diffuse-Specular): Traditional Phong-based lighting model

Advanced Rendering Modes

Metallic Roughness, Transmission, and Volume

Sheen, Alpha Coverage

• Physically-Based Rendering (PBR): Full Cook-Torrance BRDF implementation with metallic/roughness workflows
• Split-Sum IBL: Image-based lighting with irradiance and prefiltered environment maps
• Shadow Mapping: PCF-based shadow filtering with support for directional, point, and spot lights
• Parallax/Bump Mapping: Height-based surface detail rendering
• Texture-Based PBR: Material properties driven by texture maps (albedo, normal, roughness, metallic, AO)

Material System & KHR Extensions

ModelViewer implements comprehensive support for Khronos KHR material extensions, enabling advanced material rendering capabilities:

Supported KHR Material Extensions:

• KHR_materials_clearcoat: Multi-layer clearcoat materials with independent roughness control
• KHR_materials_sheen: Fabric-like materials with directional sheen highlights
• KHR_materials_transmission: Transparent materials with refraction and realistic light transmission
• KHR_materials_volume: Volumetric absorption for thick transparent materials with realistic light scattering
• KHR_materials_iridescence: Iridescent/interference-based color shifts (thin-film interference)
• KHR_materials_dispersion: Chromatic aberration with per-channel IOR for realistic prism effects
• KHR_materials_specular: Fine-grained specular intensity and color control
• KHR_materials_anisotropy: Directional surface reflection (brushed metals, fabrics)
• KHR_materials_diffuse_transmission: Subsurface scattering for translucent materials
• KHR_materials_pbrSpecularGlossiness: Legacy PBR specular/gloss workflow support
• KHR_lights_punctual: Multiple punctual light sources (directional, point, spot) with intensity control

Visual Demonstrations of KHR Material Extensions:

KHR Punctual Lights Support:

Texture Transform Support:

• KHR_texture_transform: Full implementation of UV coordinate transformations, including:
  • UV scaling and rotation
  • Offset (translation) around pivot points
  • Multi-UV coordinate set support
  • Per-texture transform customization

Material Editor & Library System

• Interactive Material Editor Panel: Real-time material property adjustment with live preview
• Material Library: Tree-based organization and management of materials
• Material Deduplication: Intelligent identification and consolidation of duplicate materials
• Name-Based Material Matching: Preservation of original material names across the import/export pipeline

Texture Management & Advanced Features

Texture Processing:

• Automatic Embedding: Textures embedded directly into GLB exports for self-contained models
• Smart Texture Caching: Three-level lookup system (exact match → same image/different sampler → disk load) with sampler-aware cache keys
• Texture Format Support:
  • KTX2 and Basis Universal compressed textures
  • WebP format with automatic plugin deployment
  • Standard formats (PNG, JPG, TGA, BMP)
• Texture Transform: Per-texture UV transformation with full KHR_texture_transform support
• Multi-Channel Support: Independent handling of multiple texture sets and UV coordinates

CAD Support & Assembly Visualization

OpenCASCADE Integration:

• Native STEP Support: Full parametric feature preservation
• IGES Files: Industry-standard CAD format support
• BRep Format: OpenCASCADE native boundary representation
• Color Inheritance: Smart color extraction from XCAF color attributes with intelligent inheritance chains
• Property Preservation: Metadata and naming preserved across the import pipeline

Assimp Integration:

• Multi-Format Support: OBJ, FBX, COLLADA, Blend, VRML, and 30+ other formats
• Robust Loading: Handles malformed files gracefully with validation
• Mesh Post-Processing: Automatic tangent/bitangent computation with proper transformation math
• Negative Scale Handling: Correct detection and processing of flipped geometry via determinant-based matrix analysis

Export Capabilities

• GLB Export Pipeline: Complete round-trip export with:
  • Material preservation and deduplication
  • Texture embedding with optimized packing
  • KHR extension metadata preservation
  • Correct handling of negative scales and transforms
  • Sampler value preservation across materials
• Texture Embedding: Automatic embedding before export for portable model files
• Format-Agnostic Export: Support for exporting to multiple target formats

Section/Capping Tools

Advanced Sectioning:

• Single Plane Section: Cut models with arbitrary clipping planes
• Multiple Section Views: Simultaneous display of multiple cross-sections with automatic capping
• Smart Capping: Automatic generation of capping geometry to close intersected surfaces
• Interactive Adjustment: Real-time plane manipulation for dynamic sectioning

Multi-View Projection System

• Multiple Synchronized Views: Side-by-side or grid-based orthographic projections
• Standard Projections: Front, back, top, bottom, left, right, isometric views
• Anonometric Projections: Isometric, Dimetric, and Trimetric
• Orthographic and Perspective Projections

Realistic PBR Rendering

Realistic Automotive Paint Rendering (Clearcoat & Iridescence):

User Interface & Tools

Detachable Panels:

• Texture Mapping Panel: Interactive UV transformation and texture coordinate visualization
• Material Editor Panel: Comprehensive material property adjustment interface
• Log Viewer: Real-time application logging with syntax highlighting, search, and filtering by log level
• Material Library Panel: Tree-based material organization and management

UI Features:

• Qt6 MDI Interface: Multiple document/model windows with tabbed organization
• Scrollable Toolbar: Customizable tool access with context-sensitive actions
• Theme Manager: Light and dark theme support with customizable color schemes
• Settings Dialog: Comprehensive application configuration and user preferences
• Tutorial System: Interactive guided introduction for new users
• Internationalization Support: English, Spanish, French, Italian, and German

Advanced Camera & Navigation

• Orbital Camera: Smooth mouse-based model rotation and inspection
• Pan & Zoom: Intuitive view navigation with proper zoom mechanics
• Preset Views: Quick access to standard orthographic projections
• Light Manipulation: Independent light repositioning with delta-based targeting
• Perspective Correction: Proper NDC Z-clamping for accurate behavior at high zoom levels
• CAD Coordinate System: Native Z-up orientation matching industry CAD standards

Undo/Redo System

• Full Command History: Complete undo/redo stack for all editing operations
• Live Preview Updates: Synchronized UI panel updates on undo/redo actions
• Material Operations: Support for complex material editing operations with full history

Building the Code

Prerequisites

Linux Build

1. Install the required dependencies using your package manager (e.g., apt, yum, etc.).
2. Clone the repository:

   git clone https://github.com/sharjith/ModelViewer-Qt.git
   cd ModelViewer-Qt

3. Create a build directory and configure the project using CMake:

   mkdir build
   cd build
   cmake .. -DCMAKE_BUILD_TYPE=Release

4. Build the project:

   make -j$(nproc)

5. Run the application:

   ./ModelViewer

Windows Build

1. Install vcpkg if not already installed. Follow the instructions here.
2. Use vcpkg to install the required dependencies:

   vcpkg install qt6-base assimp glm freetype:x64-windows opencascade:x64-windows

3. Clone the repository:

   git clone https://github.com/sharjith/ModelViewer-Qt.git
   cd ModelViewer-Qt

4. Create a build directory and configure the project using CMake with the vcpkg toolchain:

   mkdir build
   cd build
   cmake .. -DCMAKE_TOOLCHAIN_FILE=[path_to_vcpkg]/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Release

   Replace [path_to_vcpkg] with your vcpkg installation path.
5. Build the project:

   cmake --build . --config Release

6. Run the application:

   .\Release\ModelViewer.exe

macOS Build

1. Install dependencies via Homebrew:

   brew install cmake qt@6 assimp glm freetype open-cascade

2. Clone and build:

   git clone https://github.com/sharjith/ModelViewer-Qt.git
   cd ModelViewer-Qt
   mkdir build
   cd build
   cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$(brew --prefix qt@6)
   make -j$(sysctl -n hw.ncpu)
   ./ModelViewer.app/Contents/MacOS/ModelViewer

Troubleshooting

Common Build Issues

Performance Tips

• Use Release builds (-DCMAKE_BUILD_TYPE=Release) for best performance
• Reduce shadow map resolution if rendering is slow
• Disable unused KHR extensions in settings if not needed
• Use LOD variants for very large assemblies or point clouds
• Prefilter maps are computed on load; large environment maps may take time

Dependency Compatibility

Development & Contribution

ModelViewer is built with modern C++ (C++17) and uses CMake as its build system. The project includes:

• Comprehensive Shader System: Custom GLSL shader pipeline with hot-reloading support
• Qt6 Integration: Complete integration with Qt6 for UI, threading, and context management
• Assimp Post-Processing: Custom mesh processing for improved compatibility and quality
• OpenGL 4.6: Modern graphics pipeline with compute shader support

License

ModelViewer is licensed under the GNU General Public License v3.0 (GPL-3.0).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

For the full license text, see the LICENSE file in the repository root.

Acknowledgments

• Assimp - Asset import library
• OpenCASCADE - CAD geometry kernel
• Qt - GUI framework
• GLM - Mathematics library
• Khronos - glTF and KHR extension specifications