RC Batch GUI — Opéra Paris / Maquettes & Décors

Batch-processes photogrammetry objects through RealityScan 2.0.1. Pick one MAQ folder → the tool rebuilds every N* subfolder inside it into its own .fbx export, fully unattended, with the dark backdrop masked out so each object comes out floating in void.

---

Requirements

• Windows 10/11
• Python 3.10+ (tkinter is built-in)
• Pillow — for background-mask generation: pip install pillow
• RealityScan 2.0.1 installed

uv note: if you launch with uv run, install Pillow into that environment (uv run --with pillow rc_batch_gui.py). A uv-managed interpreter does not see a Pillow installed in your system Python.

---

Run

python rc_batch_gui.py

---

Alignment settings (important)

-align takes no arguments — alignment quality comes from RealityScan's global settings, not a file the tool can pass. Set them once in the RC GUI's Alignment Settings dialog (they persist); headless runs then inherit them. This is what makes the batch match a manual GUI reconstruction.

The optional Unwrap XML and Export XML fields do take exported RS settings files, but leaving them empty uses RC defaults, which is fine for most runs.

---

Folder structure

Input (you pick one MAQ folder):

H:\...\Images_Variants_JPG\Praticable\MAQ255_Wagner_LaWalkyrie\
    _test_output\   ← always ignored (leading underscore)
    N1\JPG\*.jpg    ← processed
    N2\JPG\*.jpg
    ...

Outputs (mirroring the MAQ/N structure):

02_Photogrammetry\
    RC_Projects\MAQ255_Wagner_LaWalkyrie\N1\MAQ255_Wagner_LaWalkyrie_N1.rsproj
    Deliverables\MAQ255_Wagner_LaWalkyrie\N1\MAQ255_Wagner_LaWalkyrie_N1.fbx
    RC_Components\...\N1\MAQ255_Wagner_LaWalkyrie_N1.rsalign  ← only if rsalign checkbox on

Browsing for a MAQ folder auto-fills the output roots if a sibling 02_Photogrammetry folder exists up the directory tree.

Prepped inputs (geometry copies + masks) are written per object to RC_Projects\...\N*\_prepped_jpg\ — originals are never modified.

---

Pre-processing (before RealityScan sees anything)

• Skip first shot — drops the first image in each N*/JPG (the beauty / colour-checker / ID frame), by position, since it has no consistent filename.
• Background masks (Pillow) — threshold the dark void, open/close morphology to remove speckle and hairs, written as per-file IMG.jpg.mask.png beside each photo. RealityScan auto-detects this mask layer on -addFolder and ignores the void during alignment and reconstruction, while the original pixels stay available for texturing. White = keep, black = ignore.
  • Threshold (% black) — pixels darker than this become void (~5%).
  • Open / despeckle (px) — eats bright speckle & hairs in the void.
  • Close / fill (px) — fills small holes inside the object.
• Overwrite prepped — off = reuse an existing _prepped_jpg folder for a fast retry (no re-copy / re-mask); on = regenerate.

---

Pipeline per object (lean — mirrors GUI input → Start → export)

-headless -newScene
-addFolder  <_prepped_jpg>
-align
-setReconstructionRegionAuto
-calculateNormalModel
[-simplify <tri count>]        ← only if Simplify > 0
-unwrap  [unwrap_xml]
-calculateTexture
-exportSelectedModel  <MAQ_N.fbx>  [export_xml]
[-exportSelectedComponentFile  <MAQ_N.rsalign>]
-save   <MAQ_N.rsproj>
-quit

Simplify: 0 = full mesh (like the GUI). Values between 1 and 999 are refused (they create a degenerate mesh that crashes RC). Use 0 or a real target like 150000.

---

Crash recovery

Progress is saved to rc_progress.json next to the script after every object.

Status	Behaviour on re-run
done	Skipped — only if the .fbx still exists. Delete the output and it re-runs. Overridden by the Force checkbox.
failed	Re-run (or Force) to retry.
processing	Re-run to retry (script/RC was killed mid-run).

• Old .fbx / .rsproj are deleted before each run, so "FBX exists afterwards" means RC wrote a genuinely fresh one — a crash yields an honest failure, never a stale file marked done.
• Timeouts do not retry (a timeout is a deterministic stall, not a flaky job). Only unexpected launch crashes retry, up to Max retries.
• RC exit codes are decoded in the log (e.g. 0xC0000374 heap corruption). RC often exits non-zero after writing the FBX — that's accepted as done.

---

Options

Option	Meaning
Simplify triangles	0 = full mesh; >0 = target count (<1000 refused)
Timeout (seconds)	Per-object kill timeout; set low (~300) while testing
Max retries	Crash retries only — timeouts never retry
Skip first shot	Drop the beauty / colour-checker / ID frame
Generate masks	Mask the dark void (needs Pillow)
Overwrite prepped	Off = reuse existing prepped folder (fast retry)
Export .rsalign	Also write the alignment component to RC_Components
Force	Reprocess objects already marked done
Clear RC temp before batch	Empty the RealityScan temp folder once at start (path is a GUI field; guarded against wiping non-temp paths)

---

Buttons

Button	Action
▶ Run	Process all valid N* folders
⏹ Stop	Kill the running RealityScan immediately (and its child processes)
🔬 Test 1 object	Force-process only the first N* — validates paths/settings before a full batch
Scan	List N* folders, image counts, and status without processing
Clear log	Clear the output panel

---

Notes

• Paths with spaces and UNC prefixes (\\server\...) are handled correctly — commands are passed as argument lists, never shell strings.
• Processing runs on a background thread; the whole UI scrolls (scrollbar + mouse wheel) so the log is readable on a small window.
• _-prefixed and non-N* subfolders are always skipped. An N* folder with no JPG subfolder or no images is skipped without failing the batch.
• Nothing is auto-published to Git; the tool only writes RC projects, deliverables, prepped images, and rc_progress.json.