Precomp Switcher v1.0.0: initial public release

A Nuke plugin that creates a Write + SwitchPrecomp + backdrop with
one hotkey, with three colored states (Bypass / Rendering / Precomped)
and Node Graph hotkeys for build (Shift+W), render (F7), and
read-from-write toggle (Alt+R).

Ships with full User and Developer Guides as PDFs.

Author: CreativeLyons

.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# macOS
+.DS_Store
+
+# Nuke working files
+*.nk
+*.nk~
+*.nk.autosave
+
+# Markdown (only README.md is public)
+*.md
+!README.md
+
+# Editor / AI tooling
+.claude/
+.cursor/
+.codex/
+.code-review/
+.plan/
+
+# Local-only modules
+precomp_switcher/reload.py
+fake_pipeline/
+
+# Local-only project material
+docs/
+docs_pdf/
+output/
+images/
+marketing/
+
+# Release / media artifacts
+*.pdf
+*.zip
+*.mp4
+*.mov
+*.exr
+*.abc

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Lyons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,117 @@
+![Precomp Switcher in action](img/precomp_switcher_demo.gif)
+
+by [Tony Lyons](https://github.com/CreativeLyons) |  www.compositingmentor.com
+# Precomp Switcher
+
+The Precomp Switcher lets you define important settings of your Write node quickly and intuitively, and creates a **Write + Switch + Backdrop** setup.
+
+There are clear labels and colors, always letting you know the current **"State"** of the precomp.
+
+Toggle between **Precomped** and **Bypass** states, simply by disabling the switch node.  The **Rendering** state reminds you to swap out your precomp when it's done rendering.
+
+Stop manually reconnecting. Start Switching.
+
+## Why use it?
+
+- **Consistency.**  Every precomp in every script looks and behaves the same.
+- **Readability.**  Tile color and label tell you at a glance whether a precomp is live, mid-render, or rendered.
+- **Speed.**  One hotkey to build, one to render, one to read back and flip/toggle.
+- **Pipeline-friendly.**  If your studio has its own render command, custom Write Node, custom Read Node or read-from-write tool, a TD can configure this tool to use those hooks to their own pipeline commands, instead of native Nuke ones.
+
+## The 3 states at a glance
+
+![The three precomp states at a glance](img/precomp_switcher_different_states.jpeg)
+
+Every precomp sits in one of three states.  The Backdrop and Switch tile & colors all track the state together:
+
+| State         | Color | What it means                                         |
+|---------------|-------|-------------------------------------------------------|
+| **Bypass**    | White | Live. Switch disabled; downstream sees the live tree. |
+| **Rendering** | Blue  | The Write is being rendered. Visual-only marker.      |
+| **Precomped** | Red   | Reading the rendered output by the enabled Switch.    |
+
+## Quick Start
+
+![Precomp Settings dialog: name entered](img/Precomp_creation_panel_named.jpeg)
+
+1. Start with a saved `.nk` script.
+2. Head to the area of the comp tree you want to precomp and press **Shift+W**.
+3. Type a precomp name, click **OK**.
+4. You should see a new Precomp Switcher backdrop with a Write + Switch.
+5. With the precomp Write selected, press **F7** to render. Your Precomp Switcher should turn Blue and say **Rendering**.
+6. When the render is done, select only the precomp Write and press **Alt+R** to create and connect a Read.
+7. The Precomp Switcher should turn Red and say **Precomped**.
+8. Disable/enable the SwitchPrecomp at any time to toggle between Precomped and Bypass.  Pressing **Alt+R** with either the Read or the Switch selected will also toggle the Bypass/Precomped states.
+
+For the full walkthrough, see User Guide §4.
+
+## Node Graph Hotkeys
+
+| Key         | Action                                                       |
+|-------------|--------------------------------------------------------------|
+| **Shift+W** | Create Precomp Switcher.                                     |
+| **F7**      | Render selected Writes; each backdrop flips to **Rendering**. |
+| **Alt+R**   | Read from Write, or toggle between **Bypass** and **Precomped**. |
+
+Defaults can be overridden in [`precomp_config.py`](precomp_switcher/precomp_config.py).  See User Guide §7 for the full hotkey behavior, including the optional Linked Read variant.
+
+## Localization (Optional Feature)
+
+![Localization prompt on first Read from Write](img/Localization_Prompt.jpeg)
+
+If you're working with files over a network, there's an optional feature for Localizing your Precomp Reads automatically.  If enabled, there will be a prompt on your first Read from Write, where it will ask if you'd like to Localize your precomp.  Click **Remember my Choice** to always repeat for later Read from Write actions.  The choice is stored in the Write node under a Precomp Tab, so that you can always change later.
+
+This feature is disabled by default.
+
+Set `PRECOMP_LOCALIZATION_FEATURES_ENABLED = True` in the `precomp_config.py` to enable.
+
+## Installation
+
+**Requirements:** Nuke 13+.
+
+Precomp Switcher is a self-loading plugin.  Meaning it's designed to load everything it needs by just adding the folder to Nuke's plugin path.
+
+Here is a step by step guide:
+
+1. Simply download the latest Release `.zip`, or clone/download this repo anywhere on disk.
+2. Add the `precomp_switcher` folder (the one with all the .py files) to your Nuke plugin path.
+
+   **Option A**
+   - Drop the folder inside your `~/.nuke/` directory
+   - Open or create your `~/.nuke/init.py` file in a Text Editor
+   - Then add this line to your `init.py`:
+     ```python
+     nuke.pluginAddPath('./precomp_switcher')
+     ```
+   **Option B**
+   - Or use any other location on disk or over the network:
+     ```python
+     nuke.pluginAddPath('/path/to/precomp_switcher')
+     ```
+   - Above is just an example path, so be sure to replace `/path/to/` with the folder path where you placed the precomp_switcher.
+
+That's it! No `menu.py` entry needed.  
+If you want to remove, add, or change hotkeys of Precomp Switcher, open up the `precomp_config.py` in a Text Editor and there you can assign, change, or disable hotkeys.
+
+See **Developer Guide §2** for more info on customization via the config file.
+
+After Nuke launches, you should see **Edit → Node → Precomp Switcher → Create Precomp Switcher** with **Shift+W** as its hotkey.
+
+## Documentation
+
+- **User Guide (PDF)**: install, quick start, every feature, troubleshooting.
+- **Developer Guide (PDF)**: pipeline integration, configuration reference, architecture.
+- [**`precomp_config.py`**](precomp_switcher/precomp_config.py): every user setting in one file with inline comments for help.
+
+## License & Credits
+
+MIT License.  © 2026 [Tony Lyons](https://github.com/CreativeLyons).  See [LICENSE](LICENSE).
+
+www.CompositingMentor.com
+Contact: [creativelyons@gmail.com](mailto:creativelyons@gmail.com)
+
+### Special Thanks
+
+A very special thanks to **Alexey Kuchinski** for inspiring the idea, design, and functionality of the Precomp Switcher from his own tool.  Full credit for the inception of the idea goes to Alexey.  This is my best implementation of that idea, brought to the community.
+
+The User and Dev guides were inspired by three well-loved Nuke tool user guides: **KnobScripter v3.2** (Adrian Pueyo), **Stamps v1.1** (Adrian Pueyo & Alexey Kuchinski), and **W_hotbox v2.0** (Wouter Gilsing).  Thanks for showing me how it's done!

img/Localization_Prompt.jpeg

@@ -0,0 +1,6 @@
+"""precomp_switcher plugin bootstrap.
+
+Nuke runs ``init.py`` from each directory on ``NUKE_PATH``. The plugin root is
+already on the import path; this file exists so the folder is recognized as a
+plugin bundle alongside ``menu.py``.
+"""

img/Precomp_creation_panel_named.jpeg

@@ -0,0 +1,65 @@
+"""NUKE_PATH startup: Precomp Switcher menu and Node Graph hotkeys.
+
+Creates the Precomp Switcher menu entry and registers configurable Node Graph hotkeys.
+"""
+
+import nuke
+
+import precomp_switcher as ps
+
+
+def _ensure_precomp_menu():
+    """Return ``Edit → Node → Precomp Switcher`` from the first available menu root."""
+    for root_name in ("Nuke", "Nodes"):
+        try:
+            root = nuke.menu(root_name)
+            if root is None:
+                continue
+            return root.addMenu("Edit").addMenu("Node").addMenu("Precomp Switcher")
+        except Exception:
+            continue
+    # Final fallback for unusual hosts.
+    return nuke.menu("Nuke").addMenu("Edit").addMenu("Node").addMenu("Precomp Switcher")
+
+
+_create_precomp_switcher_hotkey = ps.cfg_get("CREATE_PRECOMP_SWITCHER_HOTKEY")
+
+if _create_precomp_switcher_hotkey:
+    _ensure_precomp_menu().addCommand(
+        "Create Precomp Switcher",
+        "import precomp_switcher as ps; ps.create_precomp_switcher()",
+        _create_precomp_switcher_hotkey,
+        shortcutContext=2,
+    )
+else:
+    _ensure_precomp_menu().addCommand(
+        "Create Precomp Switcher",
+        "import precomp_switcher as ps; ps.create_precomp_switcher()",
+        shortcutContext=2,
+    )
+
+ps.register_render_hotkey()
+ps.register_read_from_write_hotkey()
+ps.register_linked_read_from_write_hotkey()
+
+
+try:
+    from PySide6 import QtCore
+except ImportError:
+    from PySide2 import QtCore
+
+
+def _rereregister_hooks_after_startup():
+    """Other scripts can override hotkeys after menu.py; re-apply hooks."""
+    try:
+        ps._RENDER_HOTKEY_REGISTERED = False
+        ps._READ_FROM_WRITE_HOTKEY_REGISTERED = False
+        ps._LINKED_READ_FROM_WRITE_HOTKEY_REGISTERED = False
+        ps.register_render_hotkey()
+        ps.register_read_from_write_hotkey()
+        ps.register_linked_read_from_write_hotkey()
+    except Exception:
+        pass
+
+
+QtCore.QTimer.singleShot(0, _rereregister_hooks_after_startup)