Technical Reference

PivotBreeze adapts one action set to the 3D View and UV Editor. This reference covers the state it changes, the preferences that control that state, and the rules used by each supported context.

Supported contexts

• Object Mode: edits selected object origins, starting from the active object’s origin. With no selection, it edits only the 3D Cursor.
• Edit Mesh: starts from the 3D Cursor transform and applies the pivot frame while restoring the editable mesh selection.
• Edit Curve: uses the 3D Cursor transform for selected curve control points and restores the curve-editing context after apply.
• Edit Surface: follows the same cursor-based workflow for selected surface control points.
• Sculpt Mode: edits the active Mesh origin and Blender’s native Sculpt Pivot, then returns to the captured Sculpt context.
• UV Editor · Mesh Edit Mode: edits the current UV 2D Cursor. A regular pivot session never changes UV coordinates.

The 3D View requires Object, Edit Mesh, Edit Curve, Edit Surface, or Sculpt Mode. The UV workflow requires Mesh Edit Mode, an editable Mesh, and an active UV map. A single session can include multiple Object Mode objects, multiple objects in Mesh Edit Mode, or selected UVs across multiple edited meshes.

Session lifecycle

1. PivotBreeze validates the current editor, mode, data, object, and selection requirements.
2. It captures the mode, selection, active object, active tool, cursor, viewport, gizmo, pivot, and snap state it may change.
3. A 3D helper or the UV 2D Cursor becomes the active pivot target.
4. The user moves the target with Blender’s transform tools and may change snapping inside the session.
5. Applying transfers the 3D transform to the supported origins or keeps the edited UV cursor. Cancellation skips 3D origin transfer and restores the session-entry 3D Cursor position, rotation, and rotation mode; UV cancellation restores the starting 2D Cursor.
6. PivotBreeze removes session-owned state and restores the captured workspace according to the exit preferences.

Only one session can be active. Any activation action invoked during that session closes it; incomplete three-point input cancels instead of applying. Finish or cancel before starting another placement workflow.

Enter / Numpad Enter applies; Esc cancels the active pivot session. Cancellation restores the starting pivot/cursor even after completed helper moves and rotations. Native Blender transforms consume the first Enter/Esc to confirm/cancel that transform; a second press handles the pivot session. Incomplete three-point input is cancelled rather than applied by Enter. Previously committed zero-command geometry changes are not rolled back by cancelling a resumed session.

Actions by editor

• Activate Pivot: starts a regular move-and-rotate session in the 3D View, or a regular 2D Cursor move session in UV.
• Activate Bounding Box Pivot: choose one of 27 mesh anchors. R switches Global/Local; click applies and finishes.
• Pivot by 3 Points: pick position, first axis, then the plane. R cycles axes, Backspace revisits a point, and Esc cancels incomplete placement.
• Reset Pivot: resets 3D position and rotation together. In UV it resets the cursor position and can select the 2D Cursor pivot point.
• Reset Position: resets only location in 3D or the cursor location in UV.
• Reset Rotation: resets only 3D orientation and is unavailable in UV.
• Move to Zero: moves selected objects by their origins, editable geometry relative to the cursor, or the complete Sculpt object. In UV it moves selected corners, or centers each fully visible island when nothing is selected.
• Pivot to Zero: moves Object/Sculpt origins or the Edit 3D Cursor to world zero. In UV it moves only the 2D Cursor to (0, 0).

Use Blender’s native snapping in every supported workflow. The 3D View and UV Editor retain their native snap controls; there are no separate snap activation presets. Zero commands do not configure snapping. With an active session, they apply it, perform the zero action, and resume the same workflow.

Geometry placement and aiming

During regular 3D pivot editing, Left Click a visible vertex, edge midpoint, or face center to place and orient the pivot. The session stays active. Shift + Left Click aims the nearest local axis at a target while keeping pivot position fixed. Aim is not configurable and is unavailable in UV or Bounding Box sessions. Native transform handles take priority over picking.

The enabled Pivot Placement Vertex Limit defaults to 100,000 vertices:

1. The original selected objects must fit; otherwise geometry picking is disabled.
2. If the whole visible supported scope also fits, it becomes available.
3. Otherwise picking stays within the original selection.
4. With nothing selected, the complete visible scope must fit for cursor-only picking.

Zero or an unchecked limit disables enumeration, picking, aiming, bounds, and three-point placement while preserving manual gizmos and UV editing. Unchecking preserves the stored number. Changes take effect during an active session. Bounding boxes always stay selected-only.

Picking supports Mesh, Curve, Surface, Text, and Metaball geometry. Edit Mesh sources use editable base topology; other supported sources use evaluated geometry. Collection instances, Grease Pencil, Volume, and Point Cloud are not geometry-picking targets. Occlusion is evaluated within the admitted scope.

Objects admitted for picking temporarily show Viewport Display > Wireframe. Each object’s original value is restored on close, cancellation, failed start, and Undo suspension; exceeding the budget does not enable extra wireframes.

Bounding boxes and three-point frames

Both tools require Mesh in Object, Edit Mesh, or Sculpt; neither supports UV, Edit Curve, or Edit Surface.

Workflow	Bounding Box	Pivot by 3 Points
Object	Each selected mesh uses its own box and corresponding anchor	All selected origins receive the same position and orientation
Edit Mesh	One combined box of selected components; changes the 3D Cursor	One shared 3D Cursor frame; origins and component selections remain unchanged
Sculpt	Active mesh’s box, origin, and Sculpt pivot	Active mesh’s origin and Sculpt pivot only

Bounding boxes offer 8 corners, 12 edge midpoints, 6 face centers, and the center. Each new session starts Global. R toggles Local, using each object’s rotation in Object/Sculpt and the active object’s rotation for combined Edit bounds. Accepting an anchor applies the chosen frame without moving base geometry.

Three-point placement builds a right-handed frame from position, an axis direction, and a plane. The default first axis is X; R cycles X/Y/Z. Coincident or collinear picks are rejected. The third valid click applies and finishes; Backspace removes a prior pick, and Esc or toggling incomplete input off cancels. Native Undo/Redo restores the supported placement state.

Snap memory

Remember Snap Settings is enabled by default. Object, Edit, and Sculpt share one 3D configuration; UV-specific fields are retained separately. The same option controls persistence between Blender sessions—there is no separate persistence checkbox. Disabling it forgets stored memory.

A session loads remembered settings, records its in-session settings on close, and restores the outside snapping configuration captured at entry. Remembering a configuration does not force the magnet on.

Preferences reference

• Activate Pie Menu — enabled, Ctrl + D: opens the context-aware eight-direction Pie Menu.
• Eight direct action shortcuts — disabled: enable only individually configured actions. Displayed keys 1–8 are storage placeholders. Each row uses Blender’s native mapping-type and full-event controls for keyboard, mouse, NDOF, tweak, text-input, timer, and modifier input.
• Show Sidebar Panel — enabled: show the 3D View and UV Editor panels.
• Remember Snap Settings — enabled: remember shared 3D and separate UV-specific snapping, including persistence across Blender restarts.
• Pivot Placement Vertex Limit — enabled, 100,000: control admitted geometry for placement, aiming, bounds, and three-point input.
• Customize Color for Center Handle — enabled: uses the selected color instead of Blender’s Gizmo View Align theme color.
• Use Empty Hierarchies for Reset Actions — enabled: uses recursive non-Empty descendant bounds for selected Empty reset targets.
• Four On exit settings — enabled: leave each workflow’s transform or UV pivot setting active after an applied session.
• Four On reset settings — enabled: apply each workflow’s transform or UV pivot setting after reset.

Changing an enabled hotkey rebuilds PivotBreeze’s owned keymap items. Conflict reporting is informational and includes matching active, user, and add-on bindings in the supported keymaps. PivotBreeze does not disable or delete the matching item.

Exit and reset settings

On exit

Identifier and context	Result when enabled
OBJECT · Object Mode	Leave Local orientation and Bounding Box Center pivot
EDIT · Edit Mesh, Curve, Surface	Leave Cursor orientation and 3D Cursor pivot
UV · UV Editor	Leave the 2D Cursor pivot point
SCULPT · Sculpt Mode	Leave Local orientation and Bounding Box Center pivot

On reset

Identifier and context	Result when enabled
OBJECT · Object Mode	Set Local orientation and Bounding Box Center pivot
EDIT · Edit Mesh, Curve, Surface	Set Cursor orientation and 3D Cursor pivot
UV · UV Editor	Reset Pivot selects the 2D Cursor pivot point
SCULPT · Sculpt Mode	Set Local orientation and Bounding Box Center pivot

An On exit setting applies after a successful interactive session. Disable it to restore the setting captured at session start. A Python API cancellation also restores the starting context-specific setting.

An On reset setting controls the transform or pivot-point change that accompanies reset actions outside a session. In UV, it applies to Reset Pivot; Reset Position changes only the cursor location.

Reset rules

Object Mode Reset Position uses the combined world-space bounding box of the selected regular objects. With Empty hierarchy handling enabled, each selected Empty uses all recursive non-Empty descendants as its own bounds source. A selected regular object in the same operation still uses the regular selection’s combined target. Position, rotation, geometry placement, and child world transforms remain independent as required by the chosen reset action.

Edit Mesh Reset Position uses selected vertices across all unique meshes in Edit Mode. Curve and Surface use selected editable control points. An empty editable selection falls back to world origin. Sculpt uses the active object’s world-space bounding box and synchronizes the native Sculpt Pivot.

UV Reset Position uses the visible selected UV bounds center or (0, 0) when nothing is selected. During an active UV session, the reset target is the selection center captured for that session. UV reset uses Blender’s cursor transform path so the cursor-only change participates in Undo without changing UV coordinates.

State restoration and Undo

PivotBreeze restores the captured selection, active object, mode, tool, viewport presentation, gizmo visibility, and outside snap settings after a normal close. The 3D Cursor follows the last valid 3D helper transform. The UV 2D Cursor keeps its applied location and is synchronized across compatible UV Editor spaces.

Changing the mode, tool, active object, or selection can close a session and apply its current target. Hiding or deleting the 3D helper closes without applying the origin transform. Disabling runtime services also cancels the active session before unregistering hotkeys and monitoring.

PivotBreeze creates and restores the Undo boundaries needed by its 3D and UV workflows. UV cursor moves are recorded independently from UV geometry changes, and undoing before activation temporarily suspends the session UI until Redo returns to its activation boundary.

Move to Zero and Pivot to Zero use a data-changing operator with Blender’s native Undo support. If a session is active, applying it, performing the action, and resuming pivot editing belong to that command rather than requiring a second activation command. Add-on Undo/Redo handlers reconcile the temporary session and cursor state with Blender’s restored geometry; this is not a separate geometry history.

Validation failures leave the session open and targets unchanged. An unexpected error after mutation can still leave an undoable change: inspect the error and use Undo instead of assuming nothing happened. Cancelling a resumed session does not roll back the preceding zero action.

The initial release verification passed 112 fast checks. The source-linked runtime suites passed 334 tests with three expected skips in Blender 4.2.0 and 336 tests with one expected skip in Blender 5.2.2. Both reached 83% coverage; native-window checks passed in both versions, all 87 persistent preferences and snap memory survived process restart, and GPU overlay checks passed in 5.2.2. These are upstream results, not Blender tests run by the website build. macOS, ARM, and arbitrary third-party add-on combinations are not verified.

Data safety and limitations

• Object-origin editing validates the complete selection before mutating any object.
• Linked objects and linked object data are rejected because their origins are read-only.
• Normal pivot sessions can copy shared editable data before applying an origin transform. Zero commands instead require single-user data when changing geometry or origins.
• Child world matrices are restored after a parent origin changes.
• UV sessions create no helper Object or Mesh and do not rotate the 2D Cursor.
• Starting Object Mode with no selection edits only the 3D Cursor.
• A missing active helper, invalid context, or failed poll cancels the requested operation without leaving a partial session.

Zero commands reject linked objects, linked data that would be modified, and singular transforms where matrix inversion is required. A plain object translation can use shared data or zero scale. Object/Sculpt commands also reject location locks, active constraints, animation actions, drivers, and NLA tracks. Origin edits reject linked, constrained, or animated descendants; Sculpt origin edits, including an active session’s apply, require Dyntopo off.

Origin changes compensate base geometry and supported shape keys, but may change the evaluated result of origin-dependent modifiers. The command warns when modifiers are present. Save the Blender file before changing production data, inspect the result, and verify Undo and Redo. These safeguards do not silently unlock transforms, remove constraints, duplicate shared data, or disable Dyntopo.

For symptom-based fixes, report preparation, and support links, continue to the Troubleshooting guide.