Tutorial Inspect A Gltf

← Home

Tutorial: Inspect a glTF for delivery

You're an artist who just received a glTF asset from a vendor and you need to QA it before passing it down your real-time pipeline. This tutorial walks you through the full inspection toolkit - every shading and inspection mode, the wireframe overlay, mesh isolation from the Outliner, and the Analyze TUI for the structural validation report.

By the end you'll know which inspection mode to reach for given a specific concern (Material ID for "did the vendor's material assignment survive export?", Texel Density for "is the UV layout efficient?", Overdraw for "is anything layered that shouldn't be?").

• Goal
• Setup
• Step 1: Open the asset and frame it
• Step 2: Cycle the inspection modes
• Step 3: Pull a wireframe pass
• Step 4: Isolate meshes from the Outliner
• Step 5: Run Analyze for the structural report
• Verify
• What you learned
• Where to go next

---

Goal

Confirm a glTF asset is delivery-clean across geometry, materials, UVs, and validation in one inspection pass.

---

Setup

You need:

• Solarxy installed.
• A glTF or GLB to inspect. This tutorial uses Khronos DamagedHelmet.glb (the same asset as the Quickstart):

curl -LO https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb
solarxy -m DamagedHelmet.glb

For a multi-mesh asset (more interesting for the Outliner step), substitute FlightHelmet from the same repo.

---

Step 1: Open the asset and frame it

The model auto-frames on load. If you ever lose the camera, press H to re-frame. The status bar at the bottom shows the format, mesh count, and any validation issues Solarxy raised at load time - glance at it before going deeper.

---

Step 2: Cycle the inspection modes

flowchart TD
    classDef key fill:#33415E,stroke:#FFC44C,color:#FFC44C
    classDef q fill:#1F2430,stroke:#5C6773,color:#CCCAC2

    Q[What do you want to inspect?]:::q
    Q --> A{Material<br/>assignments?}
    A -->|yes| A1[2: Material ID]:::key
    A -->|no| B{UV layout or<br/>texel density?}
    B -->|layout| B1[3: UV Map]:::key
    B -->|density| B2[4: Texel Density]:::key
    B -->|neither| C{Hidden layers<br/>or overlap?}
    C -->|depth issue| C1[5: Depth]:::key
    C -->|overdraw| C2[6: Overdraw]:::key
    C -->|neither| D{Lighting<br/>or AO?}
    D -->|yes| D1[7: AO Preview]:::key
    D -->|no| D2[1: Shaded<br/>default PBR]:::key

Loading

A quick decision tree: pick a mode by the question you are trying to answer.

Use the number keys to step through every inspection mode. Each one answers a different question:

Key	Mode	The question it answers
1	Shaded	What does the asset look like with real materials?
2	Material ID	How many materials, and which faces use each?
3	UV Map	Is the UV layout sensible, with no overlaps or wasted space?
4	Texel Density	Is texture pixel density even across the surface?
5	Depth	Are there hidden geometry layers or unexpected scale jumps?
6	Overdraw	How much geometry is stacked on top of itself?
7	AO Preview	What does the raw SSAO buffer look like before tone mapping?

The texel density target lives in config.toml under [display].texel_density_target (default 1.0). If your asset class needs a different density, set it there before you trust the heatmap colours. There is no GUI control for the target - see Inspection → View modes and inspection modes.

For UV Map mode, press U to cycle the UV background (Off / Gradient / Checker). The Checker is the standard for spotting stretching at a glance.

---

Step 3: Pull a wireframe pass

The wireframe overlay surfaces the actual triangle topology - vendors sometimes ship geometry with hidden subdivisions or odd quad / triangle mixes that only show up as wireframe.

• Press W to enter Shaded+Wire view mode: PBR with the wireframe drawn on top.
• Press Shift+W to cycle the line weight: Light (1 px) → Medium (2 px) → Bold (3 px). Bold is best for catching very-small triangles; Light is cleanest for evaluating silhouette.
• Press W again to step to Wireframe only (no shading) for topology-only review.

Press S to snap back to plain Shaded view mode.

---

Step 4: Isolate meshes from the Outliner

Complex assets carry many meshes. The Outliner dock tab (Window → Outliner) lists every mesh and material. To verify a single mesh in isolation:

• Right-click a row → Hide Others. Or use / over the mesh in the viewport to isolate the one under the cursor.
• Right-click → Frame to fly the camera to its bounding box.
• The eye icon toggles per-mesh visibility one at a time.

When you're done, Alt+H (or View → Show All Meshes) restores everything.

Mesh visibility is per-mesh and global across panes and passes - the validation overlay, the wireframe, shadows, and the camera framing all respect it.

---

Step 5: Run Analyze for the structural report

The GUI surfaces validation findings in the Properties panel's Validation section and as the in-viewport overlay (Shift+V). For a structured text / JSON report, drop to solarxy-cli:

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

This opens a four-tab TUI: Overview, Meshes, Materials, Validation. Tab and Shift+Tab step between tabs; 1-4 jumps directly. Press e to export a text report, J for JSON, q to quit.

For a non-interactive run (CI or piping to jq):

solarxy-cli --mode analyze -m DamagedHelmet.glb -f json | jq .meshes

See CLI Reference → solarxy-cli: terminal companion for every flag.

If any check needs interpretation, the per-check detail (what trips it, common causes, how to fix) lives on Validation Reference.

---

Verify

By the end of the inspection pass you should have:

• Confirmed materials map cleanly (Material ID).
• Confirmed UVs are unique and texel density is even (UV Map + Texel Density).
• Confirmed no unexpected overdraw or hidden layers (Overdraw + Depth).
• Zero or accounted-for validation findings in the Analyze TUI's Validation tab.

If any finding turned up, fix it in your DCC and re-export. If the asset deliberately uses open meshes (e.g. card-based foliage), set allow_open_mesh = true in your project solarxy.toml - see Tutorial: Build a custom validation policy.

---

What you learned

• Inspection modes compose, view modes layer. Inspection mode picks the shader output (1-7); view mode picks the surface representation (W cycles Shaded → Shaded+Wire → Wireframe; X toggles Ghosted; S snaps back to Shaded). You can run Texel Density (4) in Wireframe view (W).
• UV Map is a pane mode. 3 flips the active pane into 2D UV space; it isn't an overlay on the 3D view. Use split-view (F2) to see both at once.
• Mesh visibility is global. Hiding a mesh in the Outliner hides it everywhere - shadows, wireframe, validation overlay, framing.
• The TUI is the canonical structural report. The GUI overlay shows you where issues are; the TUI tells you what they are and lets you export the finding list as text or JSON.

---

Where to go next

• Tutorial: First review session - leave feedback on what you found here.
• Tutorial: Validate in CI - make these checks block bad assets at PR time.
• Inspection - the full reference for every mode and overlay.

---

See also: Inspection · Quickstart · Validation Reference · Tutorial: Validate in CI