User Guide

← Home

Solarxy User Guide

A short orientation hub for the Solarxy GUI viewer. The detail lives on two dedicated pages: Interface covers the chrome (menu bar, panels, dock, layouts, preferences); Inspection covers what you do to look at the model (shading, UV, lighting, post-processing, mesh visibility, camera). For the analyze TUI and every CLI flag, see CLI Reference.

• Two binaries
• Supported file formats
• Where to go next

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.

Where to go next

Topic	Page
Five-minute walkthrough from install to first review marker	Quickstart
The GUI chrome - menus, panels, dock, layouts, preferences	Interface
Looking at the model - shading, UV, lighting, post-processing, camera	Inspection
Annotation system and the sidecar anchor contract	Review System
The nine validation checks - what trips them and how to fix	Validation Reference
Batch validation, GitHub Actions / GitLab / Jenkins / Perforce recipes	CI/CD Integration
Every keyboard binding	Keyboard Shortcuts
solarxy.toml and config.toml schemas	Configuration
Every flag of solarxy and solarxy-cli	CLI Reference

Tutorials

• Tutorial: First review session
• Tutorial: Inspect a glTF for delivery
• Tutorial: Validate in CI
• Tutorial: Build a custom validation policy

See also: Quickstart · Installation · Troubleshooting · FAQ