diff --git a/app_qt.py b/app_qt.py index d982661..57134d6 100644 --- a/app_qt.py +++ b/app_qt.py @@ -642,8 +642,13 @@ def _show_help_dialog(self, title: str, html: str) -> None: lay.addWidget(btns) dlg.exec() - def _on_help_anchor(self, url: QUrl, _dlg: QDialog) -> None: + def _on_help_anchor(self, url: QUrl, _dlg: QDialog, browser: QTextBrowser | None = None) -> None: spec = url.toString() + # In-page jump (the How-To index links): scroll this tab, don't leave it. + if spec.startswith("#"): + if browser is not None: + browser.scrollToAnchor(spec[1:]) + return if not spec.startswith("action:"): QDesktopServices.openUrl(url) # external link → system browser return @@ -705,7 +710,8 @@ def _show_user_guide(self) -> None: browser.setStyleSheet( f"QTextBrowser {{ border: none; background: {pal.surface}; padding: 20px 26px; }}") browser.setHtml(css + body) - browser.anchorClicked.connect(lambda url, d=dlg: self._on_help_anchor(url, d)) + browser.anchorClicked.connect( + lambda url, d=dlg, b=browser: self._on_help_anchor(url, d, b)) tabs.addTab(browser, title.replace("&", "&&")) # && → literal & (not a mnemonic) lay.addWidget(tabs) btns = QDialogButtonBox(QDialogButtonBox.StandardButton.Close) @@ -746,6 +752,176 @@ def _guide_sections() -> list[tuple[str, str]]: show/hide panels from View. Press ⌘K for the command palette, and switch light/dark in View. First, point the app at Blender (or let it fetch one) in Properties.

+ """), + ("How-To Guides", """ +

How-To Guides

+

Step-by-step recipes for the things you'll actually do. + Each is self-contained — jump to the one you need.

+ + + + + + + + + + +
AMap clips onto a scene and render (the basics)
BSet up a watch folder that renders drops automatically
CAuto-assemble previz from a filename convention
DRoute different setups to different scene files
EBatch-render one mapping across many clips
FDeliver finished renders to a review folder automatically
GRender on a Deadline farm
HSave a look as a preset and reuse it
IFix “my clips aren’t being picked up”
+ +

A · Map clips onto a scene and render

+ + + + + + +
1Drag your 3D file (.blend, + .c4d, .glb) onto the Scene box and click + Scan Scene. Its materials appear in the list.
2Drag your videos into the Videos list and + choose a Camera.
3Click Auto-match to pair clips to materials + by name — or drag a clip onto a material to link them by hand.
4Check resolution, frame range, format and quality + in the Render panel (see the Render Settings tab).
5Press Render (⌘R). Watch progress + and the Live Preview; the finished file can open, reveal, or copy + itself somewhere when done.
+ +

B · Set up a watch folder (auto-render drops)

+

Hands-off: point the app at a folder and every clip dropped + there imports, maps onto your scene, and renders — great for “drop a new cut, + get a new preview” loops.

+

+ + + + + + +
1Load the scene and clips once, and + mark which screens matter: right-click a material → Mark as Render + Target (or click the coloured stripe on its left edge).
2Open View → Watch & Auto-render. In + ① Source, click Choose… and pick the folder to watch.
3In ② Mode, leave it on Auto-map onto the + current scene.
4In ④ Output, turn on Start renders + automatically (off = jobs just queue for you to start). Set the output + folder, or leave it blank for a PREVIZ subfolder.
5Press Start. Drop a clip named like a + material and it maps + renders on its own. A newer _v2 next to + _v1 takes over automatically — latest wins.
+

Tips: raise Wait if very large files are still + copying when grabbed; tick Include subfolders to watch per-day/per-setup + folders too; the ⑤ Activity feed logs every ingest (and survives a + restart).

+ +

C · Auto-assemble previz from a filename convention

+

If your footage is named by a convention, the watch folder can + build one multi-screen render per asset instead of mapping onto one + scene — drop 10 clips, get 5 assembled previz renders.

+

+ + + + + + +
1Open View → Watch & + Auto-render and in ② Mode choose Previz assembly — one render + per asset. The ③ Naming card appears.
2Build the filename pattern from chips — no + regex. {Field} = text, {Field#} = number, + add ? for optional. Hyphens are fine + (TC-MASTER).
3Paste a real filename into the sample box. + The live preview shows exactly what parses — or where it stopped and + what it expected.
4Fill Screen → Material (which material each + screen code drives) and, if you have multiple scenes, + Setup # → Scene (see guide D).
5Click Preview (dry run) to see exactly what + WOULD assemble — per asset: screen → material → clip → version — plus every + skipped clip and why. Then press Start.
+

+

Example pattern for a touring show: + {ID#}_D{Day#}_{Section}_{Cue}_{Screen}_v{Version#} parses + 80230_D2_War-Treaty_MusicH_TC-MASTER_v001.mp4 into its fields + automatically.

+ +

D · Route setups to different scene files

+

A show with several stage layouts (D1, D2, …) can send each + setup’s clips to its own scene.

+ + + + +
1Add a Setup field to your naming + pattern, e.g. …_S{Setup#}_… (or use the Day field if + that’s what distinguishes them).
2In the ③ Naming card’s Setup # → Scene + table, click + Add and map each setup number to its scene file — + 1 → /…/D1.c4d, 2 → /…/D2.c4d.
3Unmapped setups fall back to the currently loaded + scene. Use Preview (dry run) to confirm each asset shows the right + scene before rendering.
+ +

E · Batch-render one mapping across many clips

+ + + + + +
1Set up the scene + mapping once + (guide A).
2Add all the clips you want rendered with that + mapping to the Videos list.
3Use Queue current mapping — one job per clip + is added, each with its own resolved output name. Reorder, rename, set + priority, or remove any of them in the Queue.
4Press Render All. Jobs run in order; each + reports duration and per-frame metrics when done.
+ +

F · Deliver finished renders automatically

+ + + + +
1Open View → Watch & + Auto-render (or the render settings) and find ④ Output → Delivery.
2Set a Copy to folder — a synced review + folder, a hand-off share, anything.
3Every finished render is now also copied there + automatically. Combine with a watch folder + auto-start for a fully + hands-off “clip lands → assembled preview appears in the review folder” + pipeline.
+ +

G · Render on a Deadline farm

+ + + + +
1Open + Properties → Deadline and point the + app at your Deadline repository (and deadlinecommand if + it isn’t auto-found). Click Test.
2Build your jobs in the Queue as usual (Blender + and C4D both submit).
3Choose Submit to Deadline instead of a local + render. Frames spread across your nodes; the app hands off and the farm + takes it from there.
+ +

H · Save a look as a preset

+ + + + +
1Dial in resolution, format, quality, + tone-mapping and the other render settings you like.
2Save Preset… and name it (e.g. “Client + Review 1080p”).
3Later, Load Preset… — or apply it to queued + jobs — to reproduce that look in one click. Presets live in the + Presets browser.
+ +

I · Fix “my clips aren’t being picked up”

+

+ + + + + + +
Skipped badgeIf ⑤ Activity shows + “N clip(s) skipped — why?”, click it — the dry run names every + skipped file and the reason (name doesn’t match, screen not mapped, older + version).
In a subfolder?Turn on Include subfolders + in ① Source if clips land in nested folders.
Cloud placeholderDropbox/OneDrive “online-only” + files are skipped until their contents actually download — right-click → + Always keep on this device.
Still copyingA file must hold its size for the + Wait window before import; raise it for slow copies of huge + files.
Pattern mismatchUse the live preview in ③ Naming + with a real filename — it pinpoints the first character where it + diverged.
"""), ("Scene & Clips", """

Scene & Clips

diff --git a/app_version.py b/app_version.py index 5485b34..899eaa9 100644 --- a/app_version.py +++ b/app_version.py @@ -4,5 +4,5 @@ CI, so the version lives in exactly one place. CI fails a ``v`` release tag whose value doesn't match this string. """ -__version__ = "1.8.33" +__version__ = "1.8.34" APP_NAME = "Render Mapper Pro" # display name; single source shared by the app + mixins diff --git a/docs/user-guide.md b/docs/user-guide.md index 8405111..70d1962 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -20,11 +20,16 @@ screenshots and clickable links into the relevant settings). - [③ Naming](#-naming--teach-it-your-convention) - [④ Output & delivery](#-output--delivery) - [⑤ Activity](#-activity--trust-but-verify) -3. [Filename pattern reference](#filename-pattern-reference) -4. [The queue](#the-queue) -5. [Render engines](#render-engines) -6. [Crash reports](#crash-reports) -7. [Troubleshooting & FAQ](#troubleshooting--faq) +3. [How-to recipes](#how-to-recipes) +4. [Filename pattern reference](#filename-pattern-reference) +5. [The queue](#the-queue) +6. [Render engines](#render-engines) +7. [Crash reports](#crash-reports) +8. [Troubleshooting & FAQ](#troubleshooting--faq) + +> The same guidance is built into the app under **Help → User Guide** — the +> **How-To Guides** tab has these recipes with screenshots and clickable links +> into the relevant settings. --- @@ -44,6 +49,82 @@ screenshots and clickable links into the relevant settings). --- +## How-to recipes + +Task-oriented walkthroughs for the things you'll actually do. The [Watch & +Auto-render](#watch--auto-render) deep dive below covers the panel field by +field; these are the "just tell me the steps" versions. + +### A · Map clips onto a scene and render + +1. Drag your 3D file (`.blend`, `.c4d`, `.glb`) onto the **Scene** box → **Scan Scene**. +2. Drag your videos into the **Videos** list, choose a **Camera**. +3. **Auto-match** to pair clips to materials by name, or drag a clip onto a material. +4. Set resolution / range / format / quality in the **Render** panel. +5. **Render** (`⌘R`). Watch the Live Preview; the output can open/reveal/copy itself when done. + +### B · Set up a watch folder (auto-render drops) + +1. Load the scene + clips once, then **right-click a material → Mark as Render Target** for each screen that matters. +2. **View → Watch & Auto-render → ① Source → Choose…** the folder. +3. **② Mode** = *Auto-map onto the current scene*. +4. **④ Output** → turn on **Start renders automatically** (off = jobs just queue). Set an output folder or leave blank for a `PREVIZ` subfolder. +5. Press **Start**. Drops import, map and render; a newer `_v2` supersedes `_v1` automatically. + +### C · Auto-assemble previz from a filename convention + +1. **② Mode** = *Previz assembly — one render per asset*. The **③ Naming** card appears. +2. Build the **pattern** from chips (no regex): `{Field}` text, `{Field#}` number, add `?` for optional. Hyphens are fine. +3. Paste a real filename into the **sample** box — the live preview shows what parses (or where it stopped). +4. Fill **Screen → Material** and, for multiple scenes, **Setup # → Scene** (recipe D). +5. **Preview (dry run)** to confirm what would assemble + what's skipped, then **Start**. + +Example: `{ID#}_D{Day#}_{Section}_{Cue}_{Screen}_v{Version#}` parses +`80230_D2_War-Treaty_MusicH_TC-MASTER_v001.mp4` into its fields automatically. + +### D · Route setups to different scene files + +1. Include a `{Setup#}` (or `{Day#}`) field in the pattern. +2. In **Setup # → Scene**, **+ Add** each setup number → its scene (`1 → D1.c4d`, `2 → D2.c4d`). +3. Unmapped setups use the loaded scene. **Preview (dry run)** confirms each asset's scene. + +### E · Batch-render one mapping across many clips + +1. Set up the scene + mapping once (recipe A). +2. Add every clip you want rendered with it to the **Videos** list. +3. **Queue current mapping** → one job per clip, each with its own output name. +4. **Render All**. Jobs run in order and report metrics when done. + +### F · Deliver finished renders automatically + +1. Find **④ Output → Delivery** (or the render settings). +2. Set a **Copy to** folder (a synced review/hand-off folder). +3. Every finished render is also copied there. Combine with B for a fully hands-off pipeline. + +### G · Render on a Deadline farm + +1. **Properties → Deadline** → point at your repository (and `deadlinecommand` if not auto-found) → **Test**. +2. Build jobs in the Queue as usual (Blender *and* C4D both submit). +3. Choose **Submit to Deadline** instead of a local render — frames spread across your nodes. + +### H · Save a look as a preset + +1. Dial in resolution, format, quality, tone-mapping, etc. +2. **Save Preset…** and name it. +3. **Load Preset…** later (or apply to queued jobs) to reproduce it in one click. + +### I · Fix "my clips aren't being picked up" + +| Check | Fix | +|---|---| +| **Skipped badge** in ⑤ Activity | Click **"N clip(s) skipped — why?"** — the dry run names every file and reason. | +| Clip in a subfolder | Turn on **Include subfolders** in ① Source. | +| Cloud placeholder | Right-click → *Always keep on this device* (online-only files are skipped until downloaded). | +| Still copying | Raise the **Wait** window for slow copies of huge files. | +| Pattern mismatch | Use the live preview in ③ Naming — it pinpoints the first divergence. | + +--- + ## Watch & Auto-render The Watch panel is a single automation rule that reads top to bottom: