User Guide

← Home

Solarxy User Guide

The canonical user manual for Solarxy v0.5.0. Quick references for individual topics live on standalone pages — this guide focuses on understanding the GUI viewer and analyze TUI end-to-end.

• Two binaries
• Supported file formats
• View mode
  • Menu bar
  • Sidebar
  • Viewport layouts (split view)
  • View modes vs inspection modes
  • Material overrides
  • Lighting
  • Post-processing
  • Display overlays
  • Camera and projection
  • Loading models and HDRIs
  • Console, FPS HUD, toasts, modals
• Analyze mode
• Preferences
• Validation checks
• Quick references

---

Two binaries

Since v0.5.0, Solarxy ships as two independent binaries:

Binary	What it does
solarxy	The GUI viewer — wgpu-rendered 3D window with PBR shading, sidebar controls, split viewport, inspection overlays
solarxy-cli	The terminal companion — model analyze (TUI report + JSON export), view mode (execs the GUI binary), and --update

Native install channels (Homebrew Cask, Flathub, MSI) install both side-by-side; CLI-only paths exist for headless servers and CI. See Installation for the full matrix.

solarxy-cli --mode view execs the sibling solarxy binary if it's in the same directory; on a CLI-only Homebrew install, it prints platform-specific GUI install hints instead.

---

Supported file formats

Format	Extensions	Meshes	Materials	Textures	UVs	Normals
Wavefront OBJ	.obj	Multi	Yes (.mtl)	Yes	Yes	Yes
STL	.stl	Single	No	No	No	Face-derived
PLY	.ply	Single	No	Auto-detected	Optional	Optional
glTF 2.0	.gltf, .glb	Multi	Full PBR	Embedded / external	Yes	Yes

HDRIs / environment maps: .hdr and .exr. Drop onto the viewer window or use Ctrl/⌘+Shift+O.

Format-specific notes:

• OBJ — .mtl resolves relative to the .obj. Texture paths inside the .mtl must resolve too. Multi-material objects are split into multiple draws automatically.
• STL — geometry only. Normals are computed per-face from triangle winding.
• PLY — flexible; companion textures with the same stem (e.g. bunny.ply + bunny.png) are auto-detected.
• glTF / GLB — full Cook-Torrance metallic-roughness workflow, normal maps, occlusion maps, emissive, alpha modes, scene hierarchy. .glb is preferred for portability since textures are embedded.

---

View mode

solarxy [-m model.obj] — opens the GUI viewer. Everything below applies to the GUI.

Screenshots in this guide were captured against an earlier UI revision; the v0.5.0 menu bar, Preferences modal, and Console panel are not yet pictured. Behaviour and shortcuts described in text are current.

Menu bar

The menu bar (toggle with F10) has five top-level entries:

Menu	Contents
File	Open Model… (Ctrl/⌘+O), Import HDRI… (Ctrl/⌘+Shift+O), Recent Files (last 10), Save Screenshot (C), Close Model, Quit
Edit	Preferences… (Ctrl/⌘+,)
View	Shading / Inspection / Material Override sub-menus, Show (Grid / Axes / Local Axes / Validation / Normals / UV Overlay / Bounds / Wireframe Weight), Background, Lighting (IBL Mode / Lock Lights), Post-Processing (Bloom / SSAO / Tone Mapping), Layout (F1 / F2 / F3), Projection (P / O), Link Cameras, Turntable, Keyboard Shortcuts (?)
Window	Menu Bar (F10) / Sidebar (Tab) / Console (`) / Model Stats / FPS HUD — single source of truth for panel visibility
Help	Solarxy Wiki (this page set), Check for Updates…, About Solarxy

Help → Solarxy Wiki opens this wiki in your browser — the GUI itself recognises this page set as canonical user docs.

Sidebar

Tab toggles the left-side sidebar. Six collapsible groups:

Group	Default	Controls
View	Open	Mode (W), Inspection (1–5), Material (M), Normals (N), UV (U), Wireframe Weight (Shift+W), Background (B), Bounds (Shift+B); Link cameras (Ctrl/⌘+L) when in split view; UV-Map sub-controls (background / weight / overlap) when the active pane is UV mode
Display	Open	Grid (G), Axis Gizmo (A), Local Axes (Shift+A), Lock Lights (Shift+L), Turntable (V) + RPM slider
Validation	Closed	"Highlight issues on mesh" (Shift+V), per-issue list with category color swatches — only present when a model with issues is loaded
Post-Processing	Open	Bloom (Shift+D), SSAO (Shift+O), Tone Map (Shift+T), Exposure (E / Shift+E) slider
Material	Closed	Roughness Scale + Metallic Scale sliders (only when no Material Override is active)
Lighting	Open	IBL mode (I / Shift+I)

Every sidebar control is bidirectionally synced with its keyboard shortcut — you can drive Solarxy entirely from either surface. Shift+S saves the current sidebar state to config.toml so it becomes the new launch default.

Viewport layouts (split view)

Key	Layout	Default panes
F1	Single	3D
F2	Vertical split	left: UV Map · right: 3D
F3	Horizontal split	top: UV Map · bottom: 3D

Each pane has its own camera, inspection mode, and display settings — the active pane follows the cursor. Ctrl/⌘+L toggles camera linking between panes (auto-disabled when one pane is in UV Map mode, since the cameras live in different spaces). Shift+L is lock lights — freezes the 3-light rig relative to the model rather than the camera.

View modes vs inspection modes

These compose: pick a view mode (the surface representation) and an inspection mode (the shader output) independently.

View modes (W cycles, S forces shaded, X toggles ghosted):

Mode	What renders
Shaded	Full PBR, no wireframe
Shaded + Wireframe	PBR with edge wireframe overlay
Wireframe	Edges only
Ghosted	Semi-transparent shaded with wireframe overlay (good for overlap inspection)

Inspection modes (1–5):

Key	Mode	Purpose
1	Shaded	Default PBR (Cook-Torrance metallic-roughness)
2	Material ID	Flat per-slot color — quickly see which material each face uses
3	UV Map	Switch the pane into 2D UV-space view; toggles back to 3D when pressed again
4	Texel Density	Heat map: blue (low) → green (target) → red (high). Adjust target via the sidebar slider when this mode is active
5	Depth	Linearized depth (white = near, black = far)

Inspection modes apply per pane in split view and compose with view modes.

Material overrides

Shift+M cycles, M toggles between Textured / Clay Light:

Override	What it does
Textured (default)	Apply loaded materials
Clay Light	Directionless ambient from IBL irradiance L0; suppresses Cook-Torrance specular
Clay Dark	Like Clay Light but darker
Chrome	IBL specular only — no direct lights
Silhouette	Flat black early-return

Overrides are stylized, not physical — useful for surface-only inspection without the visual noise of textures.

Lighting

Solarxy's lighting model is a 3-light rig (key / fill / rim) following the camera, plus image-based lighting (IBL) for environment-driven ambient and specular reflections.

Key	Action
I	Toggle IBL on/off
Shift+I	Cycle IBL mode: Off → Diffuse (irradiance probe only, fast) → Full (irradiance + specular reflection, full PBR)
Shift+L	Lock lights — freeze the 3-light rig in world space relative to the model (otherwise the rig follows the camera)
Ctrl/⌘+Shift+O	Import HDRI / EXR environment map

To use a custom environment, drag a .hdr or .exr file onto the viewer or use the import dialog.

Post-processing

Key	Effect
Shift+D	Bloom (HDR threshold + blur passes)
Shift+O	SSAO (screen-space ambient occlusion)
Shift+T	Cycle tone mapping: None (clip) → Linear → Reinhard → ACES Filmic (default)
E / Shift+E	Exposure ± / reset to default

Disabling bloom and SSAO is the easiest performance win on integrated GPUs — see Troubleshooting → Performance tips.

Display overlays

Key	Action
G	Grid
A	Axis gizmo (origin)
Shift+A	Local axes — per-mesh origin gizmos
N	Cycle normals (Off / Face / Vertex / Face+Vertex)
U	Cycle UV overlay (Off / Gradient / Checker)
B	Cycle background (White / Gradient / Dark / Black)
Shift+B	Cycle bounds (Off / Whole Model / Per Mesh)
Shift+W	Cycle wireframe weight (Light / Medium / Bold)
Shift+V	Validation overlay — color-coded issues directly on mesh

The validation overlay reads the same data shown in the analyze TUI's Validation tab. See Validation checks.

Camera and projection

Mouse-driven by default — left drag orbit, middle drag (or Shift+left drag) pan, scroll wheel zoom.

Key	Action
H	Frame model — reset view to the AABB
T / F / L / R	Top / Front / Left / Right preset views
P	Perspective projection
O	Orthographic projection (in 3D mode; toggles UV overlap in UV Map mode)
V	Toggle turntable rotation (auto-spin) — RPM slider in the sidebar
Arrow keys	Camera movement

The camera auto-frames the model on load using its AABB. Press H at any time to reset.

Loading models and HDRIs

Three ways to load:

1. Drag and drop onto the viewer window — model files (.obj, .stl, .ply, .gltf, .glb) and HDRIs (.hdr, .exr) both work.
2. File menu → Open Model… (Ctrl/⌘+O) or Import HDRI… (Ctrl/⌘+Shift+O) — native file picker via rfd.
3. Recent Files — File → Recent Files lists the last 10 (capped by ui.max_recent_files in preferences, default 20).
4. CLI flag — solarxy -m path/to/model.obj opens the file at launch.

Saving a screenshot with C writes a PNG capture of the current frame to the working directory; a toast confirms the path.

UV Map mode (press 3 or pick "UV Map" in the inspection menu) shows the texture-space layout with selectable backgrounds:

Console, FPS HUD, toasts, modals

` toggles the console panel — a tracing-backed log viewer. Filter by ERROR / WARN / INFO / DEBUG; substring search the message column; right-click → Copy message / Copy full line. Default capture is solarxy=trace. Dock or float via the panel's drag handle (or the default_console_docked preference).

The FPS HUD (Window → FPS HUD or default-on via preferences) shows frametime + frame count.

Toasts appear bottom-center for transient status (screenshot saved, HDRI loaded, validation summary). Queue caps at 5; oldest drops on overflow.

Modals are draggable and dismiss with Esc:

• Preferences (Ctrl/⌘+,) — see Preferences below.
• Update — appears when Help → Check for Updates… finds a newer release. Action button is platform-aware (brew upgrade, Flathub link, or self-update).
• Keyboard Shortcuts (?) — read-only reference, mirrors Keyboard Shortcuts.
• About Solarxy — version + project info.
• Model Stats — auto-opens on model load when ui.open_stats_on_model_load is true (default). Shows vertex / triangle / polygon counts, AABB, validation summary.

Esc no longer quits the app — it dismisses the topmost open modal. To exit, close the window or use File → Quit.

---

Analyze mode

Open a four-tab terminal report:

solarxy-cli --mode analyze -m model.glb

Tabs:

Tab	Contents
Overview	Model name, mesh / material counts, vertex / index / triangle totals, AABB (min / max / size / center / diagonal)
Meshes	Per-mesh breakdown: vertex / index / triangle counts, normal coverage, texcoord coverage, material assignment
Materials	Per-material details: ambient / diffuse / specular, shininess, dissolve, optical density, texture slots (with [MISSING] markers)
Validation	Errors and warnings with severity tags, scope, and message

Navigation:

Key	Action
Tab / Shift+Tab	Next / previous tab
1 / 2 / 3 / 4	Jump to tab
j / k, ↓ / ↑	Scroll one line
g / G	Top / bottom
PgDn / PgUp	Scroll 20 lines
e	Export text report (filename prompt)
J	Export JSON report (filename prompt)
q / Esc	Quit

Non-interactive export:

solarxy-cli --mode analyze -m model.glb -o report.txt              # text to file
solarxy-cli --mode analyze -m model.glb -f json                    # JSON to stdout
solarxy-cli --mode analyze -m model.glb -f json -o analysis.json   # JSON to file
solarxy-cli --mode analyze -m model.glb -f json | jq .meshes       # pipe to jq

Use the JSON output for CI pipelines — the schema is stable and roughly mirrors solarxy_core::report::AnalysisReport.

---

Preferences

Solarxy persists settings in a single TOML file. Three edit surfaces, each authoritative for a different slice:

1. Sidebar + Shift+S — live runtime tuning

Every display / rendering / lighting setting in the sidebar is wired bidirectionally to a keyboard shortcut. Tweak in real time; press Shift+S to write the current state to config.toml so it becomes the launch default. The sidebar is the canonical UI for runtime tuning — the Preferences modal deliberately doesn't duplicate it.

2. Preferences modal — Edit → Preferences… (Ctrl/⌘+,)

Three tabs, OK / Cancel / Reset semantics, Esc cancels:

Startup — settings that only take effect on next launch.

Setting	Range / values
Window width	640 – 7680 px
Window height	480 – 4320 px
MSAA	1× / 2× / 4× (4× default)
Config file path	Read-only display
Open config file	Button — opens the TOML in your default editor

Interface — UI defaults applied at launch.

Setting	Default
Sidebar visible at launch	true
FPS HUD visible at launch	false
Console docked at launch	true
Open Model Stats on model load	true
Recent files capacity	20 (cap 50)

Updater — release-channel behaviour.

Setting	Default
Check for updates on launch	false
Release channel	Stable (alternative: Prerelease — RCs and betas)

Reset to defaults only resets the active tab, not the whole file.

3. Direct TOML editing

The config file lives at:

OS	Path
macOS	~/Library/Application Support/solarxy/config.toml
Linux	~/.config/solarxy/config.toml
Windows	%APPDATA%\solarxy\config.toml

New fields default via #[serde(default)] so older config files upgrade cleanly without deletion. Unknown fields and unknown sections are ignored (forward-compatible).

TOML schema

Sections roughly map to solarxy_core::preferences::Preferences:

Section	Purpose
display	Background, view mode, normals mode, grid / axes / bloom / SSAO / IBL toggles, tone mode, exposure, turntable, inspection mode + texel-density target
rendering	Wireframe line weight, MSAA sample count, shadow map size
lighting	Lock state
window	Width, height (clamped to min/max on load)
history.recent_files	List of recent paths, capped by ui.max_recent_files
ui	Default panel visibility, recent-files cap, auto-open Model Stats
updater	Check on launch, channel (Stable / Prerelease)

Robustness notes:

• Invalid msaa_sample_count (anything other than 1 / 2 / 4) is rejected with a tracing::warn! and falls back to 4.
• Window dimensions are clamped to the supported range on load.
• Corrupt TOML triggers a tracing::warn! and falls back to defaults — the file is not overwritten until you save explicitly.

---

Validation checks

The analyzer (and the Shift+V overlay) runs the following checks:

• Normal count does not match vertex count
• UV count does not match vertex count
• Missing UVs (severity depends on format — fatal for glTF, warning for STL)
• Non-triangulated meshes (index count not divisible by 3)
• Empty index buffers
• Invalid material references
• Missing texture files
• Degenerate triangles (near-zero-area faces)

Issues are categorized for the overlay: degenerate triangles render in yellow, non-manifold edges in red, missing UVs in pink. The sidebar Validation group lists each issue with its category swatch, scope, and message.

---

Quick references

• Installation — install paths, first-launch caveats, system requirements
• CLI Reference — every flag for solarxy and solarxy-cli
• Keyboard Shortcuts — full reference (or press ? in the GUI)
• Troubleshooting — common errors, performance tips, config reset, diagnostic tools
• Release Notes — version history, breaking changes