Albedo

A local 3D asset viewer for Windows. Open a model, look at it properly, and inspect what it is actually made of. No account, no upload, no network round trip.

Built with three.js inside a Tauri shell. The entire application is a 5.5 MB executable with nothing to install alongside it, and that figure now includes a retopology engine and a texture baker.

_{3D Viewport Interface: Full-frame 3D rendering with floating translucent overlays, 11 unlit inspection channels, material contradiction flags, and 6-DOF camera control.}

Note

For demonstration and neutrality purposes, the 3D models featured in the screenshots throughout this README were generated using 3D AI.

---

Key Features

• Instant Startup: Launches in under a second with lazy-loaded format modules and deferred lighting passes.
• Broad Format Support: Reads standard 3D formats (GLB, glTF, FBX, OBJ, STL, PLY, DAE, 3MF, 3DS, VRML, VOX, AMF, PCD/XYZ) as well as complex legacy and binary formats:
  • NIF (NetImmerse / Gamebryo): Custom reader tested bit-exact across 10,001 Dark Age of Camelot files.
  • USD (Binary PXR-USDC & .usdz): Native binary crate decoder with LZ4 decompression and float array decoding.
• Inspection Tools: 11 unlit inspection channels (Albedo, Normals, Roughness, Metalness, AO, Emissive, Alpha, etc.) plus PBR/Unlit toggles and material contradiction detection.
• Windows Explorer Thumbnails: Native IThumbnailProvider COM extension generating high-resolution Windows Explorer thumbnails for all supported 3D formats (GLB, glTF, FBX, OBJ, STL, NIF, USD, PLY, DAE, 3DS, VOX, etc.) via background WebGL rendering.
• Forced File Association & Registry Integration: Easily register or force 3D file associations and thumbnail shell handlers in the Windows Registry (HKCU) with a single click from the application settings panel.
• Asset Manager: Local asset library with sidecar tagging (.albedo/library.json), search, filtering, and a non-leaking preview strip.
• Multi-Device Navigation: Orbit and Fly camera modes, full Xbox controller mapping, and 6-DOF 3Dconnexion SpaceMouse support via WebHID.
• Interactive Edit Mode: Position, rotation, and scale gizmo handles with numerical fine-tuning and full undo/redo.

---

Rendering & Post-Processing Pipeline

Albedo features a physically based rendering engine coupled with a studio-grade post-processing pipeline designed to deliver cinematic visual quality matching tools like Marmoset Toolbag and Sketchfab.

Render Inspector Controls

_{Render & Post-Processing Inspector: Real-time controls for custom light rigs, exposure, tone mapping, GTAO ambient occlusion, optical bloom, depth of field, color grading, sharpening, and SMAA antialiasing.}

• Linear Optical Passes (evaluated in linear light before tone mapping):
  • GTAO (Ground Truth Ambient Occlusion): High-precision contact shading providing realistic depth and spatial grounding.
  • Bloom: Adjustable threshold, strength, and radius for natural light spill on bright and emissive surfaces.
  • Depth of Field: Subject-relative focal control expressed as a fraction of model depth for a consistent look at any scale.
• Darkroom & Color Grading Passes (evaluated on tone-mapped pixels):
  • Color Grading: Real-time contrast, saturation, and color temperature tuning.
  • Unified Lens Pass: Vignette, film grain, chromatic aberration, and sharpening combined in a single GPU pass for zero performance overhead.
  • SMAA Antialiasing: Crisp subpixel morphological antialiasing on final output.
• Zero-Cost Idle & Tone Compensation:
  • On-Demand Rendering: The frame loop pauses when the viewport is static, drawing 0% GPU/CPU.
  • Clear Color Compensation: Backdrop colors are tone-curve pre-compensated so background gradients remain identical whether post-processing is active or inactive.

---

Interface Showcase

_{Asset Manager & Live Preview Strip: Dedicated asset browser featuring recursive folder trees, quick filter tags, multi-property sorting, and an interactive side-drawer preview strip that re-uses GPU memory cleanly.}

_{Windows Explorer Integration: High-resolution 3D thumbnail previews generated directly inside Windows Explorer for all supported file formats via Albedo's native COM shell provider.}

---

High-Fidelity Render Showcase

_{High-Detail Asset Render: Detailed PBR surface rendering with active GTAO, realistic depth of field, and micro-surface roughness fidelity.}

_{Cinematic Studio Lighting: High-resolution viewport render demonstrating multi-light dome positioning, exposure tuning, and SMAA antialiasing.}

---

Quick Reference & Documentation

Detailed technical documentation and reference guides are organized in the docs/ directory:

• Supported Formats & Decoders: Full format compatibility status matrix, NIF block size benchmarks, and USD crate parsing notes.
• Navigation & Controls Guide: Keyboard shortcuts, Xbox gamepad controls, SpaceMouse WebHID 6-DOF mapping, and Edit Mode handles.
• Architecture & System Design: Startup optimization metrics, memory disposal & leak prevention, material contradiction rules, shell thumbnail COM DLL architecture, and post-processing pipeline.
• Porting Beyond Windows: What survives a port and what does not, the Linux thumbnailer contract, the macOS Quick Look extension, and the signing each one demands.
• Feature Verification & Roadmap: Comprehensive feature verification checklist, test evidence log, and upcoming milestones.
• Retopology & Baking: How the plancton engine becomes the Retopo tab, what the viewer already provides for it, the startup contract it must not break, and the phased plan.

---

Building from Source

npm install
npm run dev          # Frontend only, running in browser
npm run tauri dev    # Full application inside Tauri shell
npm run tauri build  # Production release build and NSIS installer

For thumbnail provider development, register via the helper script:

tools\install-thumbnail-provider.ps1

---

Project Structure

src/
  main.js              Application wiring
  prefs.js             Roaming settings persistence
  ui/controls.js       Overlays, inspector, timeline
  library/
    index.js           Asset manager (lazy loaded)
    thumbs.js          Thumbnail cache interface
    library.css        Asset manager styles
  viewer/
    viewer.js          Viewport host & on-demand renderer
    loaders.js         Format dispatch
    channels.js        Inspection channels
    materials.js       PBR normalisation
    textures.js        Texture discovery
    navigation.js      Orbit, fly, gamepad, SpaceMouse
    post.js            Post-processing pipeline (GTAO, Bloom, DoF, SMAA)
    release.js         Memory disposal & GPU resource release
    specgloss.js       KHR_materials_pbrSpecularGlossiness handler
    usd.js             USD package loader
    usdc/              Binary USDC crate reader
    nif/               NetImmerse / Gamebryo NIF reader
src-tauri/             Rust shell, file association, texture search
shell-thumbnails/      IThumbnailProvider COM DLL, cache, registration
tools/
  make-samples.mjs     Sample generator per supported format