Skip to content

Tutorial First Review Session

Jump to bottom
Marko Koljancic edited this page May 28, 2026 · 5 revisions

← Home

Tutorial: First review session

You're an art director reviewing a model from a contractor. You need to leave a few targeted notes, the artist will revise and re-export, and you'll come back to verify the revisions and close out outstanding markers. This tutorial walks the full loop end-to-end - including the moment when a re-export shifts the geometry and you have to re-anchor a stale marker.

By the end you'll understand the Review System's anchor-stability contract - the practical rule for when markers survive a re-export and when they need a deliberate human re-placement.

Goal

Run one complete review cycle, including a re-export, and finish with every marker either Complete or freshly re-anchored to Open.

Setup

You need:

  • Solarxy installed (the Quickstart walks through it).
  • A model with at least two distinct meshes. The Khronos FlightHelmet asset works well - it has visor, lens, leather, and shell as separate meshes, so we can practice re-anchoring across multiple meshes.

Grab the asset (its textures sit alongside the .gltf so use the directory form):

curl -LO https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/FlightHelmet/glTF/FlightHelmet.gltf
# Plus its textures - cloning the repo is easier than wgetting each file.

Or, for a single-file alternative, use the DamagedHelmet.glb from the Quickstart. Then open it:

solarxy -m FlightHelmet.gltf

Step 1: Enter review mode and place your first marker

Press Shift+R. Three things happen:

  • The Review label in the menu bar gains an amber dot: ● Review.
  • The Review Panel opens (docked at right by default).
  • Your next click on the model surface will create an annotation.

Click on the visor. The annotation popup opens at the cursor:

  1. Leave the category as Question - this is the default; review conversations are usually questions first.
  2. Type: "Should this glass be more reflective?"
  3. Press Cmd/⌘+Enter to save.

The marker stays at the exact triangle you clicked, even as you orbit.

Step 2: Use the four categories deliberately

Each annotation category communicates intent. The glyph and colour are consistent between the in-viewport marker and the row in the Review Panel:

Category Glyph Meaning
Info i A neutral observation. Use it for "good to know" notes.
Warning ! A concern that may or may not need action.
Question ? An open question for the artist. Default.
Change ✎ A requested modification - the action item.

Place one of each category on different parts of the helmet:

  • A Change on the strap: "Tighten this stitch row by ~20%."
  • A Warning on the lens edge: "This edge is sharper than the silhouette needs - watch for shading artefacts at glancing angles."
  • An Info on the inner shell: "Inner shell matches reference well."

The Review Panel groups markers under Open and Complete. Category filter chips at the top of the panel let you hide categories you don't want to think about right now.

Review Panel showing all four categories

Step 3: Reply to a marker, resolve one

Click the Info marker on the inner shell to select it. A cyan ring surrounds the marker; the inline editor appears at the bottom of the Review Panel.

  • Click Reply to add a threaded follow-up: "Approved - lock this surface before final bake." The reply renders indented under the parent in the panel; it has no 3D marker of its own (threading is one level deep by design).
  • Click Complete on the Info marker. It moves into the Complete section of the panel. Completed markers stay visible in the viewport but render dimmed.

"Complete" is a display label. On disk the field is resolved: true. The panel and editor read "Complete" because that reads better for an asset-review workflow.

Step 4: Save the sidecar

Press Cmd/⌘+S while review mode is active. Solarxy writes FlightHelmet.solarxy-review.json next to the model.

In-session saving is manual on purpose - you control when you commit a checkpoint. As a safety net, Solarxy also flushes unsaved annotations to the sidecar when you quit the app, so closing the window mid-review never silently drops work.

You can stop the review here, hand the sidecar to the artist, and resume later. Real reviews often span several sessions.

Step 5: Re-export the model and re-open

For this tutorial, simulate the artist's revision by re-saving the model with a small tweak that doesn't change the mesh topology. The easiest way is to open the source asset in your DCC tool, nudge a non-mesh value (scene transform, light, material parameter), and re-export.

If you don't have a DCC tool handy and just want to exercise the sidecar reload, skip the re-export and re-open the model in Solarxy as-is - all markers should stay in Open, demonstrating the anchor-stability contract.

To force the stale-anchor path so we can practice re-anchoring, deliberately re-topologize one mesh (a decimate pass, a remesh, or "optimize / weld vertices" in your DCC). Save over the original file.

Close and re-open the model in Solarxy. When the sidecar loads, Solarxy re-hashes each mesh and compares against the hashes recorded in the sidecar.

If a mesh's hash changed, every marker on that mesh moves to the Needs re-anchor section of the Review Panel. The markers render dimmed at their world-space fallback position, so you can still see roughly what they referred to. A stale marker is never deleted.

If the re-export preserved mesh order, face indexing, and vertex order within each face - the common "fix material, re-export" loop - all markers stay Open. The contract is documented in Review System → Anchor stability.

Step 6: Re-anchor a stale marker

flowchart TD
    classDef ok fill:#1F2430,stroke:#7FD962,color:#7FD962
    classDef stale fill:#1F2430,stroke:#FFC44C,color:#FFC44C
    classDef action fill:#33415E,stroke:#FFC44C,color:#FFC44C
    classDef neutral fill:#1F2430,stroke:#5C6773,color:#CCCAC2

    Load[Open model + sidecar]:::neutral
    Load --> Cmp{Per-mesh hash<br/>matches recorded?}
    Cmp -->|yes| Open[Open<br/>marker visible]:::ok
    Cmp -->|no| Stale[Needs re-anchor<br/>marker dimmed at fallback]:::stale
    Stale --> ReplaceBtn[User clicks Re-place]:::action
    ReplaceBtn --> Sub[Re-anchor sub-mode<br/>amber pulse on row]:::action
    Sub -->|click geometry| Open
    Sub -->|Esc| Stale
    Open -->|user marks Complete| Complete[Complete<br/>dimmed but visible]:::ok
Loading

The stale-anchor flow. Solarxy never auto-re-anchors - re-placement is always a deliberate human click.

For any marker that landed in Needs re-anchor:

  1. Click Re-place on its row in the Review Panel. The row pulses amber - Solarxy is in the re-anchor sub-mode for that marker.
  2. Click the geometry on the model where the marker should now sit. Solarxy commits a fresh anchor against the current mesh, clears the stale flag, and the marker returns to Open.

To cancel the re-anchor sub-mode without committing, press Esc.

Solarxy never auto-re-anchors. The nearest face on a re-topologized mesh isn't necessarily what you meant; re-placement is always a deliberate human action.

Verify

By the end of the cycle your Review Panel should show:

  • All markers in either Open or Complete.
  • Zero markers in Needs re-anchor.
  • The sidecar file checked into Git alongside the model so the next reviewer picks up where you left off.

The sidecar's JSON shape (open it in any text editor):

{
  "format_version": 1,
  "model_hash": "...",
  "mesh_hashes": ["...", "...", "..."],
  "annotations": [
    {
      "id": "01HF7Z3N9K...",
      "category": "question",
      "text": "Should this glass be more reflective?",
      "anchor": {
        "mesh_index": 0,
        "face_index": 1234,
        "barycentric": [0.5, 0.3, 0.2],
        "world_pos_fallback": [1.2, 0.8, -0.3]
      },
      "author": null,
      "resolved": false,
      "reply_to": null
    }
  ]
}

What you learned

  • The click ladder. A left-click in review mode walks a priority chain: re-anchor pending wins, then marker hit-test (within ~20 px), then new- annotation popup.
  • The anchor. Each marker stores (mesh_index, face_index, barycentric) plus a world-space fallback. A re-export is anchor-safe when mesh order, face indexing, and vertex order within each face are preserved.
  • Stale never deletes. A stale marker is always recoverable from its fallback position; Solarxy demands a human re-placement rather than guess.
  • Threading is one level deep. Replies have no 3D marker of their own; they live indented under their parent in the panel.

For the full contract, see Review System.

Where to go next

See also: Review System · Quickstart · Keyboard Shortcuts · Tutorial: Inspect a glTF for delivery

Solarxy - A lightweight, cross-platform 3D model viewer and validator built with Rust and wgpu.

GitHub Repository · Releases & Downloads

© 2026 Marko Koljancic · MIT License

Solarxy Wiki

Getting Started

Tutorials

Using Solarxy

Reference

Help

Project

Clone this wiki locally