How to Debug the Brush Application: Complete Guide for 3D Gaussian Splatting

Set the RUST_LOG environment variable to enable verbose logging, use cargo run for debug builds with extra assertions, or cargo run --release for performance testing while monitoring logs in the integrated UI panel.

Brush is a Rust-based 3D reconstruction engine for Gaussian splatting that runs on desktop, web, and Android. Knowing how to debug the Brush application effectively means leveraging its unified log crate integration, conditional compilation flags, and platform-specific logging adapters. The following guide covers the exact file locations and environment configurations you need to trace execution across training loops, dataset loading, and rendering pipelines.

Enable Verbose Logging with RUST_LOG

Brush uses the standard Rust log ecosystem, initialized differently depending on the target platform. Both the CLI and GUI respect the RUST_LOG environment variable to filter message severity.

Desktop CLI Logging

In apps/brush-cli/src/lib.rs, the CLI initializes an env_logger::builder() between lines 81-92. This logger writes to stdout and integrates with terminal progress bars, capturing messages from all downstream crates.

Run the CLI with increased verbosity using:

# Show info-level messages (default)

RUST_LOG=info cargo run --release

# Show debug-level messages (requires debug build)

RUST_LOG=debug cargo run

# Trace a specific crate only

RUST_LOG=brush_process=trace cargo run

Native GUI Log Panel

The brush-app uses a custom logger implemented in apps/brush-app/src/ui/log_panel.rs. This captures log records and streams them to the Log side panel in the bottom-right of the viewer window, allowing you to inspect messages without leaving the interactive interface.

Debug Builds versus Release Builds

The codebase leverages cfg!(debug_assertions) to emit extra diagnostics. In apps/brush-cli/src/lib.rs (lines 63-66), the application detects debug builds and prints a reminder that performance will be significantly slower than --release.

• Debug builds (cargo run): Enable debug_assertions, triggering additional runtime checks and verbose logging paths. Use this when tracing numerical issues or developing new features.
• Release builds (cargo run --release): Disable debug assertions for maximum training speed. Logging still functions based on your RUST_LOG setting.

Interactive Debugging with the Built-in Viewer

Pass the --with-viewer flag to spawn the WebGPU-based viewer alongside the training process. This forwards renderer-specific warnings to the UI console, letting you visualize errors like NaN outputs or failed splat projections in real time.

cargo run --release -- --source path/to/colmap_dataset --with-viewer

Inspect Specific Subsystems

Target your debugging by enabling crate-specific logs and features.

Training Loop Diagnostics

The main training pipeline in crates/brush-process/src/train_stream.rs (lines 46-204) contains extensive log::info! calls. These report seed initialization, LOD decimation progress, and evaluation step timings. Watch this output to verify that epochs are progressing and that learning rate schedules are updating.

Dataset Loading Verification

Dataset parsers emit startup confirmations via log::info!. In crates/brush-dataset/src/formats/colmap.rs (line 37), loading begins with a logged message indicating which loader was selected. Check these lines to confirm that all image files are discovered and that camera parameters parsed correctly.

Renderer Validation Checks

For numerical instability issues, enable the optional debug-validation feature. This compiles extra checks in crates/brush-render/src/validation.rs (line 49) that print warnings when NaN or Inf values appear in the rendering pipeline.

cargo run --features debug-validation

Platform-Specific Logging

WebAssembly builds: The Vite configuration in apps/brush-js/web/vite.config.ts orchestrates wasm-pack build steps. Run npm run dev and monitor the terminal for wasm-pack warnings regarding memory limits or missing exports.

Android builds: The Android entry point in apps/brush-app/src/android.rs (line 24) initializes android_logger to forward Rust logs to Logcat. Use adb logcat to capture logs while running on a physical device:

adb logcat | grep brush

Common Debugging Patterns

• Insert temporary log::debug!: Add inline debug logs in suspect functions, recompile with cargo run, and observe the output in your terminal or the UI log panel.
• Leverage debug_assert!: The training code already contains debug_assert! calls (e.g., in brush-train/src/adam_scaled.rs) that fire only in debug builds to highlight inconsistent tensor states.
• Monitor the UI log panel: In the native brush-app, expand the Log panel to see realtime messages without switching windows.
• Enable feature-gated validation: Remember that debug-validation only compiles in debug mode or when explicitly requested via --features.

Summary

• Set RUST_LOG=debug or RUST_LOG=crate_name=trace to control verbosity across all platforms.
• Use cargo run for development with extra assertions, or cargo run --release for speed-critical testing.
• Launch with --with-viewer to see training progress and renderer warnings in the integrated UI log panel.
• Target specific subsystems by watching logs from brush-process, brush-dataset, and brush-render crates.
• Enable debug-validation features and android_logger when debugging GPU outputs or mobile deployments.

Frequently Asked Questions

How do I enable debug logging in the Brush CLI?

Set the RUST_LOG environment variable to debug or trace before running the binary. The CLI initialization code in apps/brush-cli/src/lib.rs uses env_logger, which respects this variable to filter output sent to stdout.

What is the difference between debug and release builds in Brush?

Debug builds (cargo run) activate cfg!(debug_assertions), enabling extra runtime checks and pathways that warn about numerical instabilities, while release builds (cargo run --release) disable these for maximum throughput. The CLI explicitly warns you when running a debug binary, as noted in lib.rs lines 63-66.

How can I view logs when running Brush on Android?

The Android implementation in apps/brush-app/src/android.rs configures android_logger to forward Rust log messages to the Android system log. Use adb logcat from your development machine to capture these messages while the application runs on the device.

What is the purpose of the debug-validation feature?

The debug-validation feature enables additional NaN and infinity checks inside crates/brush-render/src/validation.rs. Activate it with cargo run --features debug-validation to catch numerical errors early in the rendering pipeline before they propagate through the training loop.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}