FAQ

← Home

FAQ

Short answers to the questions that come up most often. Each entry is one short paragraph; the linked page carries the full detail. Ordered roughly by guessed frequency, hottest first.

• I ran solarxy-cli --paths "..." and the GUI launched. Why?
• My markers disappeared after re-exporting the model.
• Which solarxy.toml did Solarxy actually pick up?
• What is the difference between shading mode and inspection mode?
• How do I save preferences? I remember Shift+S used to work.
• Why does the menu bar say "Review" with an amber dot?
• Where do I find the keyboard shortcuts inside the app?
• Can I switch themes without restarting?
• Why is my Texel Density heatmap all red?
• Why are review markers invisible in the UV Map pane?
• Why doesn't the F4 Quad layout populate split panes with UV Map automatically?
• Why is there no CLI MSI on Windows?
• Does Solarxy ship a Linux aarch64 AppImage?
• Why are my annotations anonymous?

I ran solarxy-cli --paths "..." and the GUI launched. Why?

solarxy-cli defaults to view mode, which launches the GUI and ignores --paths. Batch validation requires the explicit --mode analyze, so any invocation that uses --paths must also include it. The combination is what flips dispatch from "open the GUI" to "run the batch validator." See CLI Reference → solarxy-cli: terminal companion.

My markers disappeared after re-exporting the model.

They are not gone - they moved. Solarxy compared the model's current per-mesh SHA-256 hashes against the hashes recorded in the sidecar; one or more changed. The affected markers moved to the Needs re-anchor section of the Review Panel and now render dimmed at their world-space fallback position. Click Re-place on the panel row, then click the corrected spot on the geometry. See Review System → Anchor stability.

Which solarxy.toml did Solarxy actually pick up?

Discovery walks four steps in order: explicit --config <PATH> if passed, then the $SOLARXY_CONFIG env var, then solarxy.toml in the start directory, then a parent walk up to a .git/ directory or the filesystem root (capped at 20 levels). For --paths runs the start directory is the current working directory, not each asset's directory - run CI from the repo root or pass --config explicitly. The resolved config path is recorded in the batch validation run report. See Configuration → Discovery order.

What is the difference between shading mode and inspection mode?

View mode (Shaded / ShadedWireframe / WireframeOnly / Ghosted, cycled with W and X) is the surface representation - shaded geometry, edges only, semi-transparent. Inspection mode (Shaded / Material ID / Texel Density / Depth / Overdraw / AO Preview, on keys 1, 2, 4, 5, 6, 7) is the shader output. They compose - you can run Texel Density in Wireframe view. See Inspection → View modes and inspection modes.

How do I save preferences? I remember Shift+S used to work.

Shift+S was retired in v0.6.0 RC2. The replacement is Edit → Save View Settings as Default for live display / rendering / lighting state, and the Preferences modal (Cmd/⌘+,) for startup-only fields like window size and MSAA. Plain S now resets the active pane to the default Shaded view mode. See Release Notes.

Why does the menu bar say "Review" with an amber dot?

Review mode is active. While review mode is on, the Review label gains an amber dot (● Review) and the Review Panel opens automatically. Click on the model to place a marker; press Shift+R again or Esc to leave review mode. See Review System → Entering review mode.

Where do I find the keyboard shortcuts inside the app?

Press ? while the GUI is focused to open the in-app shortcuts modal. It is a read-only reference grouped by category (File / Window & Layout / Navigation / Shading & Inspection / Show / Overlays / Mesh Visibility / Review / Lighting & Post-Processing). Dismiss with Esc. The full reference also lives at Keyboard Shortcuts.

Can I switch themes without restarting?

Yes. Open Edit → Preferences… → Appearance, switch between Ayu Mirage Dark and Ayu Mirage Light, click OK. The theme applies immediately - no restart. The pane toolbars, sidebar, dock, status bar, and review markers all reconfigure their palette in place. See Interface → Preferences.

Why is my Texel Density heatmap all red?

The heatmap colour reflects the asset's pixel density relative to [display].texel_density_target in config.toml (default 1.0). All red means the asset is densely textured compared to the target; raise the target value in config.toml to match your asset class. There is no GUI control for the target value - edit the config file from the Preferences modal's Startup tab. See Inspection → View modes and inspection modes.

Why are review markers invisible in the UV Map pane?

Review markers anchor in 3D space, not on UV islands - they have no meaningful position in a 2D UV-space view. Solarxy filters UV-Map panes out of the review-overlay slice by design. If you want to see markers, use a Scene3D pane (press 3 to switch back); for UV inspection, use a separate pane in split-view mode. See Review System → What the Review System does not do.

Why doesn't the F4 Quad layout populate split panes with UV Map automatically?

Split layouts (F2 SplitVertical, F3 SplitHorizontal, F4 Quad, F5 ThreeLeftBig) default every pane to Scene3D - they do not auto-populate a UV Map pane. To compare 3D and UV side by side, switch one pane to UV Map mode by clicking inside it and pressing 3 (or use its [ Scene 3D ] toolbar label and pick UV Map). Each pane carries its own pane-mode setting. See Interface → Viewport layouts.

Why is there no CLI MSI on Windows?

Deliberate. Rust CLI tools by convention distribute on Windows through the shell / PowerShell installer + a portable .zip + winget, not MSI - matching ripgrep, fd, zoxide, eza, bat, delta, and cargo-dist itself. The GUI binary (solarxy) does ship as an MSI for users who expect that on Windows; solarxy-cli follows the CLI convention. See Installation.

Does Solarxy ship a Linux aarch64 AppImage?

Not in v0.6.0. The native bundle pipeline ships x86_64 AppImages because the upstream appimagetool arm64 binary is not yet stable for the toolchain. aarch64 support is on the roadmap for v0.7.0+. For Linux arm64 today, build from source or use the Flathub package (which has its own arm64 path). See Installation.

Why are my annotations anonymous?

Author attribution is opt-in. Solarxy deliberately does not auto-derive the author from git config or your operating-system username - attaching an identity to a review is always an explicit choice. Set your display name in Edit → Preferences… → Interface → Reviewer name, or add [review].author = "Your Name" to your config.toml. See Review System → Author attribution.

See also: Troubleshooting · Keyboard Shortcuts · Quickstart · User Guide