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

> Debug the brush application efficiently. Use RUST_LOG for verbose logs, cargo run for debug builds, or cargo run release for performance tests. Monitor logs in the UI.

- Repository: [Arthur Brussee/brush](https://github.com/ArthurBrussee/brush)
- Tags: how-to-guide
- Published: 2026-05-14

---

**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`](https://github.com/ArthurBrussee/brush/blob/main/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:

```sh

# 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`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/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.

```sh
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`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/crates/brush-render/src/validation.rs) (line 49) that print warnings when NaN or Inf values appear in the rendering pipeline.

```sh
cargo run --features debug-validation

```

### Platform-Specific Logging

**WebAssembly builds**: The Vite configuration in [`apps/brush-js/web/vite.config.ts`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/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:

```sh
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`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/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`](https://github.com/ArthurBrussee/brush/blob/main/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.