User Guide

← Home

Solarxy User Guide

The canonical user manual for Solarxy v0.6.0. This guide explains the GUI viewer and the analyze TUI end-to-end. Some topics have dedicated pages: Review System, Configuration, CI/CD Integration, and the Keyboard Shortcuts reference.

• Two binaries
• Supported file formats
• The viewer interface
  • Menu bar
  • Pane toolbars
  • Sidebar
  • Dockable layout
  • Status bar
• Viewport layouts (split view)
• View modes and inspection modes
• Material overrides
• Material Inspector
• Lighting
• Post-processing
• Display overlays
• Mesh visibility
• Camera and projection
• Loading models and HDRIs
• Console, toasts, and modals
• Preferences
• Review system
• Analyze mode
• Validation
• Quick references

---

Two binaries

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

Binary	What it does
solarxy	The GUI viewer - a wgpu-rendered 3D window with PBR shading, dockable panels, split viewport, and inspection overlays.
solarxy-cli	The terminal companion - model analyze (TUI report + JSON export), batch validation, view mode (which launches the GUI), and --update.

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

---

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 / GLB	.gltf, .glb	Multi	Full PBR	Embedded / external	Yes	Yes

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

Format-specific notes:

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

---

The viewer interface

solarxy [-m model.obj] opens the GUI. The window is built from a menu bar along the top, a dockable workspace of panels around a central viewport, pane toolbars floating on the viewport itself, and a status bar along the bottom.

Menu bar

The menu bar has eight top-level menus. Toggle the whole bar with F10.

Menu	Contents
File	Open Model… (Ctrl/⌘+O), Import HDRI… (Ctrl/⌘+Shift+O), Recent Files, Close Model, Quit.
Edit	Preferences… (Ctrl/⌘+,), Save View Settings as Default - persists the current display / rendering / lighting state as the launch default.
Render	Shading, Inspection, and Material Override submenus; Tone Mapping; Bloom and SSAO toggles; a Lighting submenu (IBL Mode, Lock Lights); Background; Save Screenshot… (C).
Review	Review Mode (Shift+R), Show Markers, Save Review Notes (Ctrl/⌘+S). The menu label turns amber (● Review) while review mode is active. See Review System.
View	Projection, Turntable, Link Cameras (in split view); a Show submenu (Grid, Axis Gizmo, Local Axes, Validation Overlay, Normals, UV Overlay, Bounds, Wireframe Weight); Show All Meshes.
Layout	Single (F1), Split Vertical (F2), Split Horizontal (F3), Quad (F4), Three-Left-Big (F5); Save Layout, Restore Saved Layout, Reset Layout to Default.
Window	Panel-visibility toggles - Viewport (Ctrl/⌘+1), Sidebar (Tab), Outliner, Properties, Review Panel, Material Inspector, Console (`), Status Bar, Menu Bar (F10).
Help	Solarxy Wiki, Keyboard Shortcuts (?), Check for Updates…, About Solarxy.

Per-pane controls in the Render and View menus (Shading, Inspection, Material Override, Background, Projection) act on the active pane - the one the cursor last selected.

Pane toolbars

Each 3D pane carries a set of small bracketed text labels that float directly on the scene - a 3ds Max-style viewport menu. They are the fastest way to change just that pane:

• [ Scene 3D ] - switch the pane between the 3D scene and UV Map view.
• [ Shaded ] - the effective display mode. Its dropdown nests the Inspection modes and Material Override.
• [ Perspective ] - projection, with Overlays and Background as nested submenus.

A UV pane shows [ UV Map ] and [ Display ] labels instead. Labels are bare text until you hover them, when they pick up the amber accent.

Sidebar

Tab toggles the Sidebar. It is the canonical surface for scene-global display, post-processing, and material settings - three collapsible groups:

Group	Default	Controls
Display	Open	Lock Lights (Shift+L), Turntable (V) with an RPM slider when active.
Post-Processing	Open	Bloom (Shift+D), SSAO (Shift+O), Tone Map (Shift+T), Exposure slider (E / Shift+E).
Material	Closed	Roughness Scale and Metallic Scale sliders, plus Reset. Disabled while a material override is active.

Per-pane view controls live on the pane toolbars; validation and HDRI details live in the Properties panel. Every sidebar control is also bound to a keyboard shortcut - you can drive Solarxy from either surface.

Dockable layout

The viewport and every panel live as tabs in a single dockable workspace. Drag a tab by its title to dock it against a different edge, split a region, stack it with another tab, or tear it out into a floating window.

Seven tabs:

Tab	Contents
Viewport	The 3D scene. Special: it never floats and is transparent so the wgpu surface shows through. It can be closed and reopened from Window → Viewport (Ctrl/⌘+1).
Sidebar	The collapsible-groups panel described above.
Outliner	Mesh and Material lists - per-row hide toggles, right-click actions, click a row to frame it.
Properties	Model, HDRI, and Validation sections. Clicking a validation row flies the active camera to the affected mesh.
Review Panel	The annotation browser - see Review System.
Material Inspector	View-only per-material PBR introspection - see Material Inspector. Shows a placeholder until a model is loaded.
Console	The docked log viewer - see Console, toasts, and modals.

Every panel ships in the default layout, so discoverability is the layout - no panel pops open on model load. The live arrangement is auto-saved on quit and restored next launch.

Layout menu entry	What it does
Save Layout	Snapshot the current arrangement into a saved slot.
Restore Saved Layout	Replay that snapshot. Greyed out until you've saved one.
Reset Layout to Default	Rebuild the default arrangement without touching either saved or auto-saved blob - the escape hatch when a layout gets wedged.

If a persisted layout fails to load (for example after an upgrade adds a new tab), Solarxy logs a debug line and silently falls back to the default - your data is safe, only the arrangement resets.

Status bar

A single-line status bar runs along the bottom of the window (toggle it from Window → Status Bar). It shows the loaded file and format, validation counts, the review badge, the active-pane label, frame time / fps, and the GPU backend. It collapses gracefully on narrow windows.

---

Viewport layouts (split view)

Five viewport layouts, switchable from the Layout menu or F1-F5:

Key	Layout
F1	Single
F2	Split Vertical (two panes, side by side)
F3	Split Horizontal (two panes, stacked)
F4	Quad (2×2)
F5	Three-Left-Big (one large pane, three small)

Each pane has its own camera, inspection mode, display settings, and background. The active pane follows the cursor. Switch any pane between the 3D scene and UV Map view with 3 (or its [ Scene 3D ] toolbar label) - a common setup is one pane on the model and one on its UV layout.

Ctrl/⌘+L toggles camera linking so panes orbit together; Shift+L is Lock Lights, which freezes the 3-light rig relative to the model instead of the camera.

---

View modes and inspection modes

These two settings compose: pick a view mode (the surface representation) and an inspection mode (the shader output) independently, per pane.

View modes - W cycles Shaded → Shaded+Wire → Wireframe; S forces Shaded; X toggles Ghosted:

Mode	What renders
Shaded	Full PBR, no wireframe.
Shaded+Wire	PBR with an edge wireframe overlay.
Wireframe	Edges only.
Ghosted	Semi-transparent shaded - good for spotting overlapping geometry. (W toggles its wireframe while Ghosted is active.)

Inspection modes - number keys 1-7:

Key	Mode	Purpose
1	Shaded	Default PBR (Cook-Torrance metallic-roughness).
2	Material ID	A flat, deterministic per-material colour - see at a glance which material each face uses.
3	UV Map	Switches the pane into 2D UV-space view, and back. This is a pane mode, not a shader mode - it sits alongside the inspection set.
4	Texel Density	A heat map (blue = low, green = on-target, red = high) for spotting uneven texture resolution.
5	Depth	Linearized depth - white near, black far.
6	Overdraw	A per-pixel draw-count heat map - finds geometry layered on top of itself.
7	AO Preview	Shows the raw SSAO buffer directly, bypassing tone mapping.

Texel Density's "on-target" green point is the display.texel_density_target value in config.toml (default 1.0) - there is no in-app control for it.

---

Material overrides

A material override replaces every material on the model with one stylized look - useful for inspecting form without texture noise. Shift+M cycles the full set; M toggles between Textured and Clay Light.

Override	What it does
Textured (default)	The model's real materials.
Clay Light	Directionless ambient from the IBL irradiance; no specular highlight.
Clay Dark	Like Clay Light, darker.
Chrome	IBL specular reflection only - no direct lights.
Silhouette	Flat black.

Overrides are stylized, not physical. While one is active the sidebar's Material sliders are disabled.

---

Material Inspector

The Material Inspector (Window → Material Inspector) is a view-only panel for texture and PBR introspection. It has no keyboard shortcut by design - M and Shift+M are reserved for the override cycle - and selecting a material in it never changes what the viewport renders.

It is a master/detail panel. The master list shows each material with a base-colour swatch, name, and a texture-presence indicator; the detail pane shows:

• The base colour swatch and hex value (Base color factor: #RRGGBB × Albedo when an albedo texture is bound, otherwise just the factor).
• A scalar PBR grid - Metallic, Roughness, Alpha mode (Opaque / Mask with cutoff / Blend), and the Emissive factor when non-zero.
• A row per bound texture role - Albedo, Normal, Metallic / Roughness, Occlusion, Emissive - each with a 128×128 thumbnail, dimensions, and filename (or (embedded)).
• An Open externally button per texture, opening the source image in your OS's default viewer. Disabled for embedded glTF textures.

Thumbnails decode once per texture and cache until the model is swapped.

---

Lighting

Solarxy lights the scene with a 3-light rig (key / fill / rim) plus image-based lighting (IBL) for environment-driven ambient and specular.

Key	Action
I	Toggle IBL on / off (restores the last active mode).
Shift+I	Cycle the IBL mode - Diffuse (irradiance only, fast) ↔ Full (irradiance + specular reflection).
Shift+L	Lock lights - freeze the 3-light rig in world space relative to the model, rather than following the camera.
Ctrl/⌘+Shift+O	Import an HDRI / EXR environment map.

Drop a .hdr or .exr onto the window to use it as the environment. Once an HDRI is loaded it becomes the scene's light source, and the HDRI Sky background renders it as a visible backdrop.

The Properties panel's HDRI section also exposes the IBL mode, an HDRI rotation slider, and a Clear HDRI button.

---

Post-processing

Key	Effect
Shift+D	Bloom - an HDR threshold + blur pass.
Shift+O	SSAO - screen-space ambient occlusion.
Shift+T	Cycle tone mapping - None (clip) → Linear → Reinhard → ACES Filmic (the default).
E / Shift+E	Raise / lower exposure.

Bloom, SSAO, tone mapping, and exposure also live in the sidebar's Post-Processing group. 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 (world origin).
Shift+A	Local axes - a per-mesh origin gizmo.
N	Cycle normals display - Off / Face / Vertex / Face+Vertex.
U	Cycle the UV overlay - Off / Gradient / Checker.
B	Cycle the background - White, Gradient, Dark, Ayu Mirage, Black, plus HDRI Sky once an HDRI is loaded, and any custom backgrounds you've defined.
Shift+B	Cycle bounds display - Off / Whole Model / Per Mesh.
Shift+W	Cycle wireframe weight - Light / Medium / Bold.
Shift+V	Toggle the validation overlay - colour-coded issues drawn on the mesh.

Define your own background colours and gradients in the Preferences modal's View tab - they then appear in the B cycle and the Background menu.

---

Mesh visibility

Individual meshes can be hidden to cut through a dense or layered model:

Action	Effect
Shift+H	Hide the mesh under the cursor
Alt+H	Show all meshes again
/	Isolate the mesh under the cursor - hide every other mesh
Right-click a mesh	Context menu: Frame / Hide / Hide Others / Show All

The Outliner panel lists every mesh and material with per-row visibility toggles and the same right-click actions; View → Show All Meshes (Alt+H) restores everything at once.

---

Camera and projection

The camera is mouse-driven: left drag orbits, middle drag (or Shift+left drag) pans, and the scroll wheel zooms.

Key	Action
H	Frame the model - reset the view to its bounding box.
T / F / L / R	Top / Front / Left / Right preset view.
P	Perspective projection.
O	Orthographic projection (in a UV pane, O toggles UV-overlap detection instead).
V	Toggle turntable auto-rotation.
Arrow keys	Move the camera.

The camera auto-frames the model on load; press H any time to reset.

---

Loading models and HDRIs

Four ways to load:

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

UV Map view (press 3 or pick "UV Map") shows the texture-space layout with selectable backgrounds:

---

Console, toasts, and modals

Console - ` toggles the docked log viewer. It is backed by tracing: filter by ERROR / WARN / INFO / DEBUG, substring-search the message column, and right-click any line to copy it. Default capture is solarxy=trace.

Toasts - transient status messages (screenshot saved, HDRI loaded, validation summary) stack bottom-centre. The queue caps at five; the oldest drops on overflow.

Modals are draggable and dismiss with Esc:

• Preferences (Ctrl/⌘+,) - see Preferences.
• Update - appears when Help → Check for Updates… finds a newer release; its action button is platform-aware.
• Keyboard Shortcuts (?) - a read-only reference; see Keyboard Shortcuts.
• About Solarxy - version and project info.
• Screenshot review - opens when you press C. It shows a downscaled preview; nothing is written to disk until you choose a path with Save As….

Esc does not quit the app. It dismisses the topmost open modal. To exit, close the window or use File → Quit.

Live frame time and fps are shown in the status bar, not a floating overlay.

---

Preferences

Solarxy persists settings in a per-user config.toml. Three edit surfaces each own a different slice:

1. Sidebar + Edit → Save View Settings as Default

Tune display, post-processing, and material settings live in the sidebar (and via keyboard shortcuts), then choose Edit → Save View Settings as Default to persist the current state as the launch default.

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

A five-tab modal with OK / Cancel / Reset to defaults (the reset affects only the active tab); Esc cancels.

Tab	Settings
Startup	Window width (640-7680 px), window height (480-4320 px), MSAA (1× / 2× / 4×). Window size and MSAA take effect on next launch. Also shows the config file path with an Open config file button.
Appearance	Theme - Ayu Mirage Dark or Ayu Mirage Light. Applies immediately on OK.
View	The default background, plus a manager for your custom backgrounds (add / edit / delete solid or gradient backgrounds).
Interface	Status bar visible at launch, recent-files capacity (cap 50), and the Reviewer name written onto new review annotations.
Updater	Check for updates on launch, and the release channel (Stable or Prerelease).

3. Direct TOML editing

Open config.toml from the Startup tab's Open config file button and edit it in any text editor. The full file schema, every section, and its location on each OS are documented on the Configuration page.

---

Review system

Solarxy includes a built-in annotation system for asset feedback: press Shift+R, click any face on the model to drop a categorized marker, organize markers in the Review Panel, and save them to a .solarxy-review.json sidecar that travels with the asset.

The Review System has its own page - see Review System for the full workflow, the Review Panel, sidecar persistence, author attribution, and the anchor-stability contract for re-exports.

---

Analyze mode

solarxy-cli analyzes a model without opening the GUI. With a single model and an interactive terminal it opens a four-tab TUI:

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

Tab	Contents
Overview	Model name, mesh / material counts, vertex / index / triangle totals, and the bounding box.
Meshes	Per-mesh breakdown - vertex / index / triangle counts, normal and texcoord coverage, material assignment.
Materials	Per-material detail - ambient / diffuse / specular, shininess, dissolve, optical density, and texture slots (with [MISSING] markers).
Validation	Errors and warnings, each with a severity tag, scope, and message.

TUI navigation:

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

Non-interactive export - for scripts and CI:

solarxy-cli --mode analyze -m model.glb -o report.txt              # text to a 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 a file
solarxy-cli --mode analyze -m model.glb -f json | jq .meshes       # pipe to jq

To validate many models at once and feed the results into a CI pipeline, use batch validation (--paths) - see CI/CD Integration.

---

Validation

Solarxy validates every model it loads against a configurable set of nine geometry and material checks (degenerate triangles, flipped normals, non-manifold edges, triangle-budget overruns, missing UVs, bad material references, and more).

You see the results in three places:

• In the GUI - Shift+V paints colour-coded issue highlights directly on the mesh, and the Properties panel's Validation section lists each issue (click a row to fly the camera to it).
• In the analyze TUI - the Validation tab.
• In CI - batch validation reports; see CI/CD Integration.

Which checks run, their thresholds, and the per-category triangle budgets are all controlled by a project solarxy.toml. The full check list and schema are on the Configuration page.

---

Quick references

• Installation - install paths, first-launch caveats, system requirements
• CLI Reference - every flag for solarxy and solarxy-cli
• Keyboard Shortcuts - the full reference (or press ? in the GUI)
• Configuration - solarxy.toml and config.toml schemas
• Review System - annotation workflow and the anchor contract
• CI/CD Integration - batch validation and pipeline recipes
• Troubleshooting - common errors, performance tips, diagnostics
• Release Notes - version history and breaking changes