FlowPen User Documentation

Version 1.4.0

Drawing-based surface retopology for Blender. You draw on a high-resolution source mesh; FlowPen builds clean quad topology on a separate target mesh without modifying the source.

Table of contents

1. Requirements

2. Installation

3. Concepts

4. Quick start

5. The workflow (1.4)

6. Tools

7. Preview Edit mode

8. Snapping & welding

9. Symmetry

10. Settings (N-panel)

11. Keyboard & mouse reference

12. Tips & best practices

13. Troubleshooting

14. Known limitations

15. Architecture (for developers)

1. Requirements

2. Installation

Extension install (recommended)

1. Download flowpen-1.4.0.zip — do not unzip it.

2. In Blender:

   • Drag the zip onto the window, or

   • Edit → Preferences → Get Extensions → Install from Disk…

3. Enable FlowPen if it is not already enabled.

4. Open a 3D Viewport, press N, and open the FlowPen tab.

Legacy add-on install

1. Edit → Preferences → Add-ons → Install…

2. Select flowpen-1.4.0.zip.

3. Enable FlowPen.

After updating

If you had an older version installed:

1. Disable or remove the old FlowPen extension/add-on.

2. Install the new zip.

3. Restart Blender if the panel does not appear.

3. Concepts

Non-destructive rule: the source mesh is never written to. The target is only changed on successful Commit.

4. Quick start

1. Select your high-resolution source mesh.

2. Open the FlowPen sidebar tab (N-panel).

3. Click Start.

   • FlowPen creates an empty target mesh.

   • You enter Edit Mode on the target.

4. Click a tool, e.g. Draw or Edge Flow.

5. LMB-drag on the source surface.

6. Release — the cyan strip stays and enters Preview Edit.

7. Optionally move verts, relax, or cut loops.

8. Press Enter to commit, or Esc to discard.

Use Continue later to resume work on an existing FlowPen target.

5. The workflow (1.4)

From version 1.4.0, Draw and Edge Flow use this sequence:

DRAW
  ↓
CYAN PREVIEW          (live while dragging)
  ↓
EDIT PREVIEW          (after mouse release)
  ↓
REFINE                (move, slide, cut, relax, undo)
  ↓
COMMIT                (Enter)  or  DISCARD (Esc)

Not the old pattern of generate → commit → edit on the target.

Why this matters

• You shape topology while it is still temporary.

• Mistakes never touch the Target until you accept them.

• Esc always restores the Target exactly.

• Ctrl+Z after Commit undoes the whole operation as one step.

6. Tools

Precise Draw

Place vertices one by one on the surface.

Draw

Freehand stroke that becomes a cyan quad strip.

Edge Flow

Strip that follows flow direction; can continue an open boundary.

Circle Patch

Concentric quad patch from a radius drag.

Move

Move existing target vertices, projected onto the source.

Relax

Improve spacing on the target with surface projection. Can preserve boundaries and feature edges (see settings).

Loop Cut

Hover a strip of quads → continuous cut path → LMB applies. Works on open and closed loops.

7. Preview Edit mode

Available after releasing a Draw or Edge Flow stroke (cyan topology still visible).

What you can do

• Move preview vertices on the source surface

• Select and move multiple vertices

• Edge slide on interior edges

• Loop cut on the cyan mesh

• Relax selected or nearby vertices

• Undo/redo preview edits before commit

• Change width/density while keeping locked (user-edited) vertices when possible

What you cannot do (by design)

• Change the Target until Commit

• Change the Source at any time

• Leave orphan geometry after Esc

Selection modes

Move vertices

1. Hover a cyan vertex (it brightens).

2. LMB-drag.

3. The vertex follows the source surface under the cursor (ray → surface hit → reproject).

4. Connected edges and faces update locally (no full grid rebuild).

Multi-selection: selected vertices move together and stay surface-constrained.

Edge slide

1. Switch to Edge mode (2).

2. Select an interior edge.

3. LMB-drag to slide along neighbouring quads.

4. Vertices stay projected on the source.

Loop cut (preview)

1. Hover or select an edge (C).

2. A cut is inserted on the cyan topology only.

3. Nothing is added to the Target until Commit.

Relax (preview)

Press R. Selected vertices (or nearby region) are smoothed tangentially, then reprojected onto the source. Boundaries are preserved by default.

Undo / redo (preview only)

These steps are local to the cyan preview. They do not write Blender undo until you Commit.

Commit

Press Enter or Space.

1. Preview is validated (duplicates, zero-area faces, non-manifold, non-quads, etc.).

2. If issues exist → error report, stay in Preview Edit to fix.

3. If clean → convert to Target geometry, weld/snap as configured, one Blender undo step.

Discard

Press Esc or right-click.

• Preview is destroyed.

• Target is identical to the state before the operation.

• No hidden verts, orphan edges, or selection side effects.

Visual feedback

HUD example while editing:

FLOWPEN — PREVIEW EDIT
Mode [VERTEX]  Verts 48  Faces 35
LMB Select/Move  Shift=Extend  1/2/3=Mode
R=Relax  C=LoopCut  Ctrl+Z=Undo  Enter=Commit  Esc=Discard

8. Snapping & welding

Snap types

Snap / weld radius is shared in settings. Active snap type is shown as a coloured marker in the viewport.

Weld (Connect)

On commit (and via Connect tools), vertices closer than the radius are merged when safe:

• World-space distance (correct with non-uniform scale)

• Normal compatibility (avoids welding through thin layers)

• Spacing guard (avoids collapsing short edges)

• Optional boundary-only mode

Live Connect previews welds as you adjust the radius; Cancel restores the baseline topology.

9. Symmetry

• Axes: X / Y / Z (local) or None

• During Preview Edit, moving a vertex can update its mirror pair when pairs are set up

• On Commit, mirrored geometry is created and the seam is welded according to Seam Distance

Enable symmetry in the FlowPen N-panel before drawing if you want mirrored strips.

10. Settings (N-panel)

Open N → FlowPen.

Typical controls:

Exact labels may vary slightly by panel layout; tooltips describe each property.

11. Keyboard & mouse reference

Global (most tools)

Preview Edit (Draw / Edge Flow after release)

Pie menu

Shift + Q (when registered) opens the FlowPen tool pie for fast tool switching.

12. Tips & best practices

1. Start coarse, refine in Preview Edit
   Draw a clean strip, release, then move corners and cut loops before committing.

2. Use Esc freely
   Discarding is safe. The Target never changes until Enter.

3. Match density to the form
   Increase density for curved areas; keep it lower on flat panels. Changing density after edits tries to keep locked verts.

4. Boundary continuation
   Start Edge Flow near an open Target boundary so the strip continues with matching vertex count.

5. Symmetry first
   Turn on the symmetry axis before the stroke if you need mirrored results.

6. Validate before commit
   If Commit reports topology issues, stay in Preview Edit, fix the highlighted region, then try again.

7. One logical undo
   After Commit, a single Ctrl+Z in Blender removes the whole FlowPen operation.

13. Troubleshooting

14. Known limitations

• Loop Cut on highly irregular non-quad regions may not find a full loop; the tool reports failure rather than applying a partial cut.

• Circle Patch uses a small inner ring (no single pole) so faces stay quads; very small radii relative to Quad Size may produce fewer rings than requested.

• Preview density rebuild preserves locked vertices where possible, but extreme density jumps can still shift unedited regions.

• Live Connect baseline is per-target and is discarded when another tool edits the mesh (keeps Blender’s undo stack coherent).

• Proportional editing radius for multi-vert falloff in Preview Edit is limited compared to full Blender proportional edit.

15. Architecture (for developers)

flowpen/
├── __init__.py              # register / unregister
├── properties.py            # Scene + Object settings
├── session.py               # Source / Target session
├── operators/               # Start, Continue, tool switch, Connect
├── tools/                   # Draw, Edge Flow, Precise Draw, …
├── core/
│   ├── preview_mesh.py      # Editable cyan topology (1.4)
│   ├── controller.py        # Single active tool, viewport capture
│   ├── transaction.py       # begin / preview / commit / cancel
│   ├── surface_query.py     # BVH, continuity-aware projection
│   ├── snap.py              # Unified snap
│   ├── commit.py            # Grid → BMesh + validation
│   ├── quad_grid.py         # Strip grids
│   ├── stroke_engine.py     # Stroke sampling → grid
│   ├── validator.py         # Topology checks
│   └── …
├── viewport/                # GPU draw, preview, HUD
└── ui/                      # N-panel, pie menu

PreviewMesh responsibilities

• Own vertices, edges, faces, adjacency, selection, hover

• Surface binding (source_face, normal, locked flags)

• Local dirty updates on vertex move (no full regenerate)

• Preview-local undo stack

• validate() before commit

• Export to commit path without writing Target until Commit

Design guarantees

1. Source is never modified.

2. Target is unchanged until Commit succeeds.

3. Esc restores Target exactly (snapshot-based where transactions are used).

4. Moving one preview vertex updates only local topology.

5. Commit is one Blender undo step.

Version history (summary)

Support

• See INSTALL.md for install variants (including Superhive).

• See README.md for a short overview and changelog.

• Report bugs with Blender version, FlowPen version, and steps to reproduce.

FlowPen 1.4.0 — DRAW → CYAN PREVIEW → EDIT PREVIEW → COMMIT