Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
151 lines (110 loc) · 5.94 KB

GETTING_STARTED.md

File metadata and controls

151 lines (110 loc) · 5.94 KB
Raw

Getting Started

DirectLStudio is a native Windows application for viewing trained 3D Gaussian Splatting scenes on autostereoscopic light-field displays. You can start with the portable release or build the complete application from source.

Use the portable release

  1. Download DirectLStudio-1.0.0-win-x64.zip from GitHub Releases.
  2. Extract the complete DirectLStudio/ directory.
  3. Run DirectLStudio/DirectLStudio.exe.
  4. Press X to enter fullscreen on the selected light-field display.

The package includes the Lego SOG scene, nominal 2K Optical and Viewpoint reuse maps, runtime configuration, and the required libraries. Fullscreen presentation uses the physical monitor rectangle and a native-resolution backbuffer with Per-Monitor V2 DPI awareness.

Controls

Input Action
1 Switch to Multiview Raster
2 Switch to Ray Tracing
3 Switch to Optical Reuse
4 Switch to Viewpoint Reuse
G Show or hide the full interface
X Enter or leave fullscreen
R Reset the camera
W/A/S/D Move in first-person navigation mode
Mouse movement Look around in first-person navigation mode
Left mouse button Orbit the camera
Middle mouse button Pan the camera
Mouse wheel Zoom

The compact HUD displays the output resolution, FPS, frame time, and active mode. World axes are hidden by default. Use --no-review-hud when capturing an image without the overlay.

Download the demo scenes

The public DirectLStudio Demo Scenes dataset contains Lego, Garden, and Bicycle. Download one scene with the repository helper:

python .\tools\download_assets.py --scene lego --output .\assets\scenes
python .\tools\download_assets.py --scene garden --output .\assets\scenes
python .\tools\download_assets.py --scene bicycle --output .\assets\scenes

Use --scene all to download all three scenes:

python .\tools\download_assets.py --scene all --output .\assets\scenes

The same files are available through the Hugging Face CLI:

python -m pip install -U huggingface_hub
hf download Royalvice/DirectLStudio-Demo-Scenes `
  --repo-type dataset `
  --include "scenes/lego/*" `
  --local-dir .\assets

Lego follows the CC BY-NC terms of its source dataset. Garden and Bicycle are distributed under CC BY 4.0 with attribution to Mip-NeRF 360. See LICENSES.md and manifest.json in the dataset for file-level details.

Open a 3DGS scene

DirectLStudio supports trained scenes in these formats:

  • PLY (.ply)
  • SOG (.sog) or a SOG meta.json
  • SPZ (.spz)
  • SPZ4 (.spz4)

Open a scene by dragging it into the application, choosing Open in the interface, or passing its path on the command line:

.\DirectLStudio.exe --asset <path-to-scene.sog>

The scene is parsed into one SceneHandle. Raster and Ray Tracing create their GPU caches from that shared scene, so switching modes keeps the current scene and camera.

To define a preferred initial view for another scene, add a camera preset to configs/scene_presets.json. Relative path tokens make a preset portable across installations.

Build from source

Requirements

  • Windows 11 x64
  • An NVIDIA RTX GPU with a current driver
  • Visual Studio 2022 with Desktop development with C++ and the Windows 11 SDK
  • CMake 3.25 or newer
  • CUDA Toolkit 13.1
  • OptiX SDK 8.x headers
  • Python 3.10 or newer
  • Git

Set OPTIX_ROOT or OPTIX_HOME to the OptiX 8 SDK directory:

$env:OPTIX_ROOT = '<path-to-OptiX-8-SDK>'

Build with the helper script

git clone https://github.com/CoronaEngine/DirectLStudio.git
cd DirectLStudio
python -m pip install .
$BuildRoot = Join-Path $env:TEMP 'DirectLStudio-build'

.\tools\build.ps1 `
  -Configuration Release `
  -BuildDirectory $BuildRoot

The script configures an out-of-tree build, compiles the Release configuration, and runs CTest. The application is written to:

<build-directory>\bin\DirectLStudio.exe

Equivalent CMake commands are:

cmake -S . -B $BuildRoot -G Ninja `
  -DCMAKE_BUILD_TYPE=Release `
  -DDIRECTL_BUILD_TESTS=ON
cmake --build $BuildRoot --config Release
ctest --test-dir $BuildRoot -C Release --output-on-failure

During the first configure, CMake downloads pinned versions of Dear ImGui, nlohmann/json, and zstd when a suitable local zstd installation is unavailable.

Select a display and profile

The following command opens the Lego scene on monitor index 1, selects the nominal 2K profile, and starts in fullscreen Multiview Raster mode:

& (Join-Path $BuildRoot 'bin\DirectLStudio.exe') `
  --asset .\assets\scenes\lego\scene.sog `
  --profile 7.9_2k `
  --mode MVR `
  --monitor 1 `
  --fullscreen

The bundled 2K, 4K, and 8K profiles are nominal examples. For a physical display, replace line_count_lx, tilt_angle_deg, and offset_px with its calibration, then generate matching reuse maps as described in Subpixel Reuse.

Troubleshooting

  • The output is scaled or uses the wrong resolution. Select the profile that matches the panel's native resolution and enter fullscreen on that monitor.
  • The Ray Tracing backend does not load. Keep DirectLRayTracingBackend.dll and DirectLRayTracing.ptx beside the executable, install a compatible NVIDIA driver, and use OptiX 8.x when building from source.
  • A reuse mode remains on Loading. Check that the catalog and .dlmap files match the active width, height, and view_count. Artifact paths are resolved relative to catalog.json. Run directl-subpixel validate <map.dlmap> to inspect a map.
  • A screenshot contains changing FPS text. Start the application with --no-review-hud.
  • An imported reuse catalog is not written to the repository. User settings are stored in %LOCALAPPDATA%\DirectLStudio\settings.json.