Surfaces

Blender add-on v0.4.0

Review notes for the people building the scene, right inside Blender. A Red Pen tab in the 3D Viewport sidebar lets you leave typed, status-tracked notes that live in a sidecar file next to the .blend - never inside it - and push to the Red Pen Hub so they land on the same board as your WordPress, Express, and static notes.

User manual (PDF)

What it is

Red Pen for Blender is a Blender 4.2+ extension (the fifth surface in the family). It adds a Red Pen tab to the 3D Viewport's N-panel where you create and work through review notes. It is the 3D-tool sibling of the static drop-in and the Express middleware: the same overlay idea and the same note fields, with a file-based backend that the Hub already understands.

One thing it deliberately does not do: it never creates objects in your scene and never writes notes into the .blend. The on-screen list is a runtime mirror; the real notes live in a separate sidecar file. Open the .blend without the add-on and the file is clean - no stray note objects, nothing in your renders.

Install

The add-on is a versioned extension zip. Take it from the project's GitHub Releases, or build one locally with ./build.sh - new zips are no longer committed to the repository, so releases/ holds only the older builds that predate that rule.

1. In Blender, open Edit > Preferences > Get Extensions > Install from Disk.
2. Pick the zip, for example red_pen-0.4.0.zip.
3. Enable Red Pen for Blender.

To roll between versions, Install-from-Disk a different zip - Blender replaces the installed copy with that build.

Using it

Press N in the 3D Viewport to open the sidebar, then click the Red Pen tab. From there you can:

• Add a note. Type the note text, choose a type - Note, Bug, To-do, or Question - and click Add. See Core concepts for what the fields mean.
• Work the list. Every note for the open file shows with a status icon and a type icon. Select one and use Resolve, Reopen, or delete.
• Capture in one keystroke. Ctrl+Shift+N raycasts what is under the cursor, takes a viewport snapshot, remembers the camera angle, and opens a small dialog carrying type and priority - so a note filed at speed still arrives triageable instead of landing as note/normal. The hotkey is registered in Blender's keymap, so you can remap it there.
• See the note in the viewport. Pins draw at the point you clicked, stored in the object's local space, so a note about a ceiling tile keeps tracking that tile when the object is moved, rotated or scaled. High-priority notes render red.
• Bookmark and restore a view. Locate selects the object or sets the frame, then puts the viewport back where you were standing when you wrote the note.
• Refresh. Re-read the notes from disk - handy after a resolve was pushed back from the Hub, or after editing the sidecar by hand.

The panel's status box tells you where notes are being saved: the project sidecar when the .blend is saved, or a scratch file with a warning when it is not.

Snapshots

Every note can carry a viewport snapshot, saved beside the .blend in thumbs/ and shown on the note in the sidebar. It is the single most useful artefact this surface produces - "the shading is wrong here" is a sentence; the frame it was wrong in is the note - and the Hub renders it on the board's Location cell, which those notes otherwise leave empty. Saving a previously-unsaved .blend moves the notes and their images together.

When the scene moves under a note

• A renamed or deleted pinned object is detected and the note is flagged. There is no re-link - you unpin and pin again.
• Notes stranded by a renamed or deleted .blend used to be unreachable from any session. The panel now counts them and offers to move them onto the open file. Nothing is deleted and nothing is re-keyed on its own: two .blend files can share a folder, so a missing file and a merely-closed one look identical from here.
• Save As asks what happens to the notes. Save As is how people version a .blend, so a new name would otherwise mean an empty list. A prompt offers to copy the previous file's notes across with fresh ids, or leave them with the original.

Where notes are stored

Notes are written to a JSON sidecar - the same .redpen/notes.json store the Hub folder-scans for the Express and static surfaces - so the Blender surface drops straight into the existing pipeline.

The sidecar is the single source of truth. The list you see in the panel is a runtime copy held on Blender's Window Manager, which is never saved into the .blend - that is how the notes stay out of your scene file.

The sidecar stays one flat notes.json, because that is what the Hub folder-scans, but each note carries a blend key and the panel shows only the open file's notes. Two .blend files can sit in one folder without sharing a note list, and writing one file's notes leaves its siblings alone. Notes from 0.3.0 and earlier are routed by the .blend name they already recorded, so an upgrade does not shuffle them. Timestamps are stamped in UTC, which is the shape the Hub's conflict resolver expects; a sidecar written in the older local-offset shape is converted as it is read.

Connect to the Hub

The add-on can push its notes to the Red Pen Hub so they appear on the combined board next to every other project, tagged with the blender surface. To set it up:

1. Start the Hub (it serves http://localhost:3900).
2. Get the Hub's connect token: open http://localhost:3900/api/connect-info in a browser.
3. In Blender, open Edit > Preferences > Add-ons > Red Pen for Blender and paste the Hub URL and Connect Token. Optionally set a Project name (it defaults to the .blend filename).
4. Back in the N-panel, click Push. The project self-registers as a connected source - there is no separate "add source" step.

Turn on Auto-push on change in preferences if you want every add, resolve, or delete to push automatically. The push is a localhost call, so it works whether or not Blender's Online Access toggle is on. See the Hub page for how connected sources and the URL and token work.

The round-trip: resolving from the Hub

Push sends notes up; Pull brings changes back down. A connected push store is one-way by design - resolving a note on the board updates the Hub's own copy, not the file in Blender - so the Pull button is what closes the loop. Click it and any note you resolved or reopened on the board is applied to this file's notes (matched by id).

A simple rule keeps the two directions from fighting: pull before you push if you have resolved notes on the board. Otherwise a push of stale local state could overwrite a Hub-side resolve. (A single merge-aware Sync button is planned; for now the two buttons keep the behaviour explicit.)

Current status

Version 0.4.0 ships the Red Pen N-panel tab, typed notes (Note / Bug / To-do / Question) with priorities and the full three-state status (open / in progress / resolved), a per-file list with resolve / reopen / delete, pinning a note to an object at the exact point you clicked or to a render frame, anchor-loss detection for a deleted or renamed object, quick capture on Ctrl+Shift+N carrying type and priority, viewport snapshots per note, Bookmark View and Locate, the .redpen/notes.json sidecar with the unsaved-file scratch fallback, and Push / Pull with the Hub (the pull completes the round-trip so board-side resolves reflect in Blender). It creates no scene objects and writes nothing into the .blend.

0.4.0 in particular was a data-integrity pass: notes scoped to one .blend rather than the whole folder, stranded notes made reachable again, UTC timestamps so the Hub stops overriding newer changes, snapshots that survive the first save, and a Save As prompt. Everything in it is backward compatible - notes written by 0.1.x to 0.3.0 keep working and are upgraded in place as they are touched.

Not here yet: threaded replies, custom note types, an author name, and an export operator. Planned next: mesh-face and shader-node pinning, plus replies. Progress is tracked on the Roadmap, and the Surface matrix has the per-feature grid.