Technical Reference
Pivots and session behavior
Section titled “Pivots and session behavior”An object origin, the 3D Cursor, and the UV Editor’s 2D Cursor are different things. Object origins belong to objects. The 3D Cursor belongs to the scene. UV cursors belong to editor spaces. Their restoration requirements differ.
In the 3D View, PivotBreeze creates a temporary Empty representing the editable pivot. While editing a mesh, curve, surface, or sculpt pivot, the extension can temporarily switch to Object Mode to manipulate that helper. The session still remembers its original workflow and restores it on exit.
UV sessions operate on the 2D Cursor using a native Move tool and cursor gizmo; they do not create a helper object. Rotation controls are intentionally absent.
Only one PivotBreeze session is active at a time. An activation command invoked during a session finishes that session, with incomplete three-point placement cancelling instead. To change placement modes, finish first and start again.
Confirmed exits apply the pivot and restore supported tool, selection, gizmo, and snapping state. Changing the mode, tool, active object, or selection can trigger an exit. A deleted or hidden helper causes cancellation rather than applying an unusable transform. Exit preferences can intentionally leave a different transform orientation or pivot-point setting; restoration is not unconditional.
The helper is runtime data. File loading, disabling the extension, and undo reconciliation have explicit cleanup paths. External scripts must not rename, duplicate, delete, or retain direct references to helper datablocks as an API. After Undo/Redo, query the current session again.
Supported workflows
Section titled “Supported workflows”| Editor and mode | What the pivot controls | Selection requirements |
|---|---|---|
| 3D View / Object | Origin position and orientation of selected supported objects | No selection permits a cursor-only pivot session |
| 3D View / Edit Mesh | 3D Cursor used as the component transform pivot | Selected mesh elements to start a session |
| 3D View / Edit Curve or Surface | 3D Cursor used for selected editable spline elements | Selected editable points or handles to start a session |
| 3D View / Sculpt | Active mesh origin and Blender’s native Sculpt Pivot | Active editable mesh |
| UV Editor / Edit Mesh | 2D Cursor | Valid Mesh Edit context; UV operations require usable UV data |
Unsupported modes include Vertex Paint, Weight Paint, Texture Paint, Pose, and Grease Pencil editing. PivotBreeze shortcuts and the Pie Menu do not run in these modes. An Image Editor displaying an image outside UV mode is not a UV Editor context.
Object origin edits compensate base geometry and child world transforms. Some datablock types do not expose the required transform operation; for example, camera origin editing is rejected. Moving an object and independently editing its origin are not interchangeable capabilities.
Normal origin-edit sessions can copy shared object data before changing it. The zero commands deliberately use stricter validation, described below. Origin-dependent modifiers may evaluate differently after an origin change even when the base geometry stays at exactly the same world coordinates.
Geometry picking
Section titled “Geometry picking”During any 3D View pivot session, hover over supported visible geometry and click to place the pivot. Pivot Placement Vertex Limit under Settings > Additional defaults to 100,000 vertices and replaces the experimental all-visible checkbox. One budget governs placement, Shift aiming, three-point placement, and Bounding Box Pivot:
Its checkbox is on by default. The numeric field uses the same column width as Customize Color. Unchecking it disables geometry enumeration, counting, picking, aiming, three-point placement, and bounds placement while preserving the saved number. The numeric field is dimmed until re-enabled. Manual pivot transforms and UV editing remain available.
- If the original selected objects exceed the limit, geometry picking is disabled.
- If they fit but the complete visible scope does not, only the original selection is used.
- If the complete visible scope fits, all visible supported objects are used.
- With no selection, the whole visible scope must fit. Zero disables geometry picking.
- Bounding Box Pivot always uses only its original selected mesh objects and never expands to other scene objects, even when they would fit.
Mesh, Curve, Surface, Text, and Metaball objects are supported. The status bar shows the current scope or Vertex Limit Exceeded. Manual gizmo transforms and UV editing remain available. Changes take effect during an active session. Excluded objects are neither prepared nor used as occluders. The source selection is captured before the pivot helper is selected. The original selection is retained, and the session stays active, including after an empty click. Native transform handles take priority. Multiple originally selected objects share the session pivot; clicks do not accumulate a second selection. UV sessions do not use this picking behavior.
PivotBreeze temporarily enables Viewport Display > Wireframe on every object in the current picking scope so its geometry remains readable while the helper is active. With the vertex budget exceeded, no additional wireframes are enabled. Otherwise, this affects only objects admitted by the budget. Each object’s original Wireframe value is captured independently and restored on every session exit, cancellation, failed activation, and Undo suspend path.
Geometry picking prioritizes vertices within a UI-scaled 10-pixel radius, then edges, then the visible face. Geometry hidden behind another supported object in the picking scope is not picked through. Loose edges, isolated vertices, perspective views, and points just outside the object silhouette are supported. Objects other than Edit Mesh sources use evaluated mesh geometry. Edit Mesh source objects use their editable base topology so saved component indices remain meaningful; generated modifier faces are not edit-cage selection targets. Collection instances, Grease Pencil, Volume, and Point Cloud objects are not supported as picking targets or occluders.
| Target | Position | Trial orientation |
|---|---|---|
| Vertex | Vertex coordinate | Z follows the vertex normal; the previous X direction seeds the tangent |
| Edge | Endpoint midpoint | X follows the edge; Z follows the projected average adjacent-face normal |
| Face | Mean of polygon vertices | Z follows the face normal; the longest boundary edge seeds X |
An isolated vertex preserves orientation. A loose edge uses the previous frame to resolve rotation around its direction.
For sessions started in Edit Mesh, selected vertices, edges, face fills, face centers, and active elements are drawn from the saved selection. Colors and element sizes are read from the current Blender theme on each draw. Turning off Customize Color uses the theme’s Gizmo View Align RGB for hover and the center handle; enabling it uses Center Handle Color for both without changing saved-selection colors. The overlay respects Show Overlays and uses depth testing or X-Ray display. It approximates native Edit Mesh rendering; it is not Blender’s edit overlay engine. Selection history and the active face are restored on exit.
Aim Pivot at Point
Section titled “Aim Pivot at Point”During ordinary mesh pivot editing, Shift + Left Click aims the nearest local axis direction at the hovered vertex, edge midpoint, or face center. The pivot position stays fixed and the session stays active. Each click chooses among +X, -X, +Y, -Y, +Z and -Z for the smallest rotation from the current orientation. Exact ties use X, then Y, then Z. Coincident target and pivot positions leave the transform unchanged. Ordinary left click still places the pivot using the existing picking rules. Selection and geometry are preserved.
Aim has a fixed Shift + Left Click binding, with no Ctrl, Alt or OS-key modifier. There are no Aim hotkey controls in Preferences. Legacy saved bindings and the old enable checkbox do not affect aiming. The placement checkbox and vertex budget still control geometry access. The status bar shows the fixed shortcut.
The action uses the existing geometry hit cache and performs no extra geometry preparation. It follows the shared vertex budget in supported 3D pivot sessions, including Sculpt and Curve/Surface, but is unavailable in UV and Bounding Box Pivot.
Bounding Box Pivot
Section titled “Bounding Box Pivot”Activate Bounding Box Pivot replaces the former Position/UV Vertex Snap activation. It supports Mesh objects in the 3D View: Object Mode, Edit Mesh Mode, and Sculpt Mode. Curve and Surface are unavailable. It has no UV command or UV hotkey.
The active object displays 27 anchors: eight corners, twelve edge midpoints, six face centers, and the box center. Click an anchor to move the pivot and align its orientation to the current box axes, apply the result, and finish the session. The center ring and dot draw through geometry; other rings and box edges use viewport depth with a small drawing offset. Visible anchor rings remain complete on the surface; occluded anchors are neither drawn nor clickable. Markers and box lines use Customize Color, or the current theme’s Gizmo View Align color when disabled.
In Object Mode, the selected anchor is applied independently to every originally selected object’s own box when the session finishes. Geometry stays in place. In Sculpt Mode, the active object’s origin and native sculpt pivot are updated. In Edit Mode, one combined box contains the selected mesh components across all edited objects. Only the shared 3D Cursor moves; object origins stay unchanged. Starting requires selected components.
Press R to switch Global / Local; each new session starts in Global. Global uses world axes and identity pivot rotation. Local uses each object’s own rotation in Object/Sculpt Mode, and the active object’s rotation for the combined Edit Mode box. Rotation is orthonormal: scale and shear affect the enclosed geometry, not the axis frame. Switching changes only the preview until an anchor is accepted. Undo/Redo restores the mode. The status bar displays the current orientation. Object and Sculpt bounds read evaluated vertices for an exact fit; Edit bounds use selected editable vertices transformed to world coordinates. Source geometry and overlay batches are cached until their relevant inputs change.
Pivot by 3 Points
Section titled “Pivot by 3 Points”Pivot by 3 Points replaces 3D Aligned Snap activation, with no additional settings. It supports Mesh objects in Object, Edit Mesh, and Sculpt modes. Pick a vertex, edge midpoint, or face center for each step:
- The first point is the pivot position.
- The second point sets positive X from the first toward the second.
- The third sets the XY plane; positive Y points toward its projection perpendicular to X. Positive Z follows the right-hand rule.
The last click applies and exits. All selected objects receive the same origin position and orientation while world geometry stays fixed. In Edit Mesh, only the shared 3D Cursor changes; component selection and object origins are preserved. In Sculpt, the active mesh origin and Blender’s native Sculpt Pivot are updated; cancellation and native Undo/Redo preserve the session’s Sculpt workflow. Coincident or collinear points are rejected without advancing the step.
Press R at any step to cycle which axis the second point controls: X, Y, then Z. The third point controls the next axis in that cycle, and the remaining axis is derived automatically. The status bar shows the axis controlled at the current step. Existing accepted points stay in place when the assignment changes, and the preview updates immediately.
Hovered geometry and the pivot-position point use Customize Color (or the theme fallback).
With the default assignment, after the first point the live positive X direction is red and
its automatically aligned positive Z direction is blue. After X is accepted, the live third
point controls positive Y; Y is projected perpendicular to X and Z follows the right-hand
rule. Cycling the assignment applies the same behavior to the corresponding theme-colored
axes. All displayed axes have filled arrowheads and share the length of the axis currently
being placed, measured to the perpendicular projection at the third point. Arrowheads use
the same native Blender shape as the main pivot. Their screen size follows Blender’s
Gizmo Size and UI scale settings, independently of guide length; axis colors follow the
current Blender theme. The arrow tip stays at the guide endpoint. The overlay
therefore matches the orthonormal frame that Blender can apply
instead of drawing separate raw-point and final-direction guides. Preview drawing does not
modify origins, geometry, or the cursor.
Backspace removes the last accepted point; Esc, an incomplete second toggle,
or an interrupted session cancels without applying. Native Undo/Redo restores
accepted points and the axis assignment selected with R. The internal
view3d.ih_pivot_breeze_three_points_back operator
performs the same Backspace action. Three-point placement is unavailable in UV.
The status bar groups keys with their actions, following Blender’s Knife presentation.
The first step shows Place Pivot (1/3); later steps show Set Axis, the current
axis, and the step number. Backspace — Remove Last Point appears only after accepting
a point. R — Cycle Axes shows the currently controlled axis, and Esc — Cancel
remains available throughout. Key names and X/Y/Z stay unchanged in every Blender language.
Bounding Box Pivot shows Place Pivot for the left mouse button and Enter — Apply Changes and Esc — Cancel. Ordinary 3D pivot and UV cursor sessions keep Blender’s native transform hints and add the same apply/cancel hints. Aim Pivot uses fixed Shift in a separate key/action group and is omitted when disabled or unavailable. Native modal transform hints are not replaced. The session hints are limited to the owning window and removed when the tool exits.
Snapping and cursor tracking
Section titled “Snapping and cursor tracking”Pivot by 3 Points does not change snap settings. Three-point and Bounding Box placement have no UV activation operators. The complete configured pie menu keeps its slot positions in every mode, with unavailable commands disabled. In the 3D View, Move to Zero and Pivot to Zero are disabled without selected objects.
Remember Snap Settings uses one shared configuration for Object, Edit and Sculpt, matching Blender’s 3D ToolSettings. UV keeps its own magnet, elements and 2D angle increments. Properties that Blender itself shares between UV and 3D (such as snap target and transform toggles) remain shared rather than gaining conflicting copies. On exit, the pre-session snap configuration is restored. Disabling memory clears stored configurations. Blender’s normal preference saving persists the add-on settings.
Older mode-specific memories migrate once: the current 3D mode wins when available, otherwise Object, Edit, then Sculpt is used. The old format has no last-used timestamps. UV-specific settings are retained. Subsequent 3D sessions all use the same memory.
Realtime tracking follows supported completed transforms and selection changes. In UV editing, a new selected set places the cursor at its bounds center; a completed translation carries the cursor with the selection. A pivot session starts at the current cursor, not automatically at a newly calculated center. The lightweight timers avoid inspecting geometry during modal transforms.
Reset actions
Section titled “Reset actions”Reset means returning a pivot to the workflow’s reference placement. It does not mean moving geometry to world zero.
| Action | Position | Orientation | Geometry |
|---|---|---|---|
| Reset Pivot Position | Reference bounds center, or the workflow’s empty-selection fallback | Preserved | Not translated |
| Reset Pivot Rotation | Preserved | World identity in 3D | Not translated |
| Reset Pivot | Position and rotation reset together | World identity in 3D | Not translated |
During a 3D session, resets update the helper and keep the session active. Outside a session, Object Mode uses selected-object bounds; Edit modes use selected editable geometry; Sculpt uses the active object’s bounds. Bounds are axis-aligned in world space. Edit position resets with no selected points fall back to world zero. A rotation reset is unavailable in UV editing.
In the UV Editor, Reset Pivot and Reset Pivot Position place the cursor at the
selected UV bounds center, or (0, 0) when nothing is selected. They do not
translate UV islands. The optional reset preference switches the UV pivot point
to 2D Cursor.
With Use Empty Hierarchies for Reset Actions, each selected Empty uses the recursive bounds of its non-Empty descendants. An Empty without usable descendants retains its current position. Ordinary selected objects use their combined bounds. Mixed Empty/child selections retain these separate targets; their base geometry remains fixed. This option affects resets, not Move to Zero.
Move to Zero and Pivot to Zero
Section titled “Move to Zero and Pivot to Zero”These are separate public actions, available through the Pie Menu, optional hotkeys, contextual operators, and the scripting API.
| Context | Move to Zero | Pivot to Zero |
|---|---|---|
| Object | Move each selected object’s origin to world (0, 0, 0) by translating the object |
Put each origin at world zero while compensating base geometry and child transforms |
| Edit Mesh / Curve / Surface, selected elements | Translate selected elements by the negative current 3D Cursor position | Put the 3D Cursor at world zero without moving geometry |
| Edit Mesh / Curve / Surface, no selection | Center each edited object’s complete geometry independently by its world bounds; keep origins fixed | Put the 3D Cursor at world zero |
| Sculpt | Move the entire active object by its origin to world zero | Move its origin to world zero while preserving base geometry; update the native Sculpt Pivot |
| UV, selected elements | Translate selected UV corners by the negative current UV cursor position | Put the UV cursor at (0, 0) without moving UVs |
| UV, no selection | Center each fully visible UV island independently by its bounds at (0, 0) |
Put the UV cursor at (0, 0) |
Coordinate details
Section titled “Coordinate details”For an Edit selection and cursor C, a selected world-space point P becomes
P - C. For example, with C = (2, 3, 4), the point (5, 7, 9) becomes
(3, 4, 5). This preserves the selection’s offset from the cursor; it does not
force the selected bounds center to zero. The cursor also becomes zero.
The same rule applies in UV space with two coordinates. UV zero is the UV origin, not the center of the unit tile. Independently centered islands may overlap and extend into negative coordinates. This command does not pack islands or move them to separate tiles.
Object Mode leaves the 3D Cursor unchanged when no pivot session is active. Object rotation and scale are retained. Selected parent and child objects each receive their own world-zero target. Unselected children normally follow an object translation; an origin-only change instead compensates child transforms.
Empty Edit selection includes hidden geometry when centering the whole object, so hidden parts do not remain behind. Curve and Surface bounds use control points. A selected Edit operation respects visible selected elements. In UV, partially hidden islands are skipped as a whole rather than deformed. No UV map is created automatically.
Sculpt masks and Face Sets are not treated as a component selection by these commands. Move to Zero moves the complete active sculpt object.
Data safety and limitations
Section titled “Data safety and limitations”If a session is active, the command applies it, closes it, performs the zero action, and restores session activity. Snap settings and the original session’s exit bookkeeping are retained. In Edit Mode, geometry moves without moving the object origin. In Object/Sculpt modes, the preceding apply can first change the origin and orientation according to the edited pivot.
The commands validate before closing a session. Important restrictions are:
- A UV action and a 3D action cannot operate across an incompatible active session.
- Linked object data cannot be modified. Shared data must be made single-user before geometry/origin edits; a plain object translation can use shared data.
- Singular object transforms are rejected when matrix inversion is required. A plain object translation can still work with zero scale.
- Object/Sculpt location locks, active constraints, animation actions, drivers, and NLA tracks prevent these transform operations.
- Origin changes also reject linked, constrained, or animated descendants when their positions cannot safely be preserved.
- Dyntopo must be disabled before a sculpt origin edit or before applying an active sculpt pivot as part of a zero command.
- Origin edits preserve supported shape-key coordinates in world space, but do not promise unchanged results from origin-dependent modifiers.
These guards do not silently unlock objects, remove constraints, make data single-user, or disable Dyntopo. Normal reset/session commands have their own validation rules; do not assume all actions share the zero commands’ restrictions.
Preferences and shortcuts
Section titled “Preferences and shortcuts”Preferences contain Pie Menu, Hotkeys, Settings, and Python API.
Localization policy
Section titled “Localization policy”The add-on interface is English-only. It does not ship translated catalogs or locale aliases. Every interface string uses the private add-on translation context, so changing Blender’s language cannot translate matching words inside IH PivotBreeze.
Default shortcuts
Section titled “Default shortcuts”| Hotkey API identifier | Binding | Enabled |
|---|---|---|
ACTIVATE_PIVOT |
1 | No |
ACTIVATE_PIVOT_BOUNDS |
2 | No |
ACTIVATE_PIVOT_THREE_POINTS |
3 | No |
RESET_PIVOT |
4 | No |
RESET_PIVOT_POSITION |
5 | No |
RESET_PIVOT_ROTATION |
6 | No |
MOVE_TO_ZERO |
7 | No |
PIVOT_TO_ZERO |
8 | No |
PIVOT_PIE_MENU |
Ctrl+D | Yes |
The number keys are placeholders, not recommended Blender keymap replacements. Rebinding does not enable a disabled shortcut. Conflict inspection is read-only. Priority registration adds PivotBreeze-owned entries; it must not disable or rewrite another add-on’s or Blender’s keymap items.
Each shortcut row uses Blender’s native compact keymap controls. Choose Keyboard, Mouse, NDOF, Tweak, Timer, or another available mapping type in the first field, then use the adjacent native event field. Keyboard, mouse, and NDOF fields capture the complete event, including Ctrl, Shift, Alt, and the platform OS modifier. The click that activates the field is not assigned as the shortcut.
Default Pie Menu slots
Section titled “Default Pie Menu slots”| Slot | Direction | Action identifier |
|---|---|---|
| 0 | Left | MOVE_TO_ZERO |
| 1 | Right | PIVOT_TO_ZERO |
| 2 | Bottom | RESET_PIVOT |
| 3 | Top | ACTIVATE_PIVOT |
| 4 | Top Left | ACTIVATE_BOUNDS |
| 5 | Top Right | ACTIVATE_THREE_POINTS |
| 6 | Bottom Left | RESET_POSITION |
| 7 | Bottom Right | RESET_ROTATION |
NONE leaves a slot empty. Pie action identifiers differ from some hotkey
identifiers: for example, RESET_POSITION versus RESET_PIVOT_POSITION.
Preferences display directions in a visual order; the API always uses the slot
numbers above. Every editor keeps the complete layout; unavailable actions are disabled.
Since API version 3, the session argument and result field are named placement_mode.
Its values are NONE, BOUNDS, and THREE_POINTS; capability metadata uses
placement_modes. The former snapping-preset fields have no compatibility
aliases. UV supports only NONE. Removed pie actions do not reuse stored enum
values; obsolete explicit assignments resolve to empty slots and can be reassigned.
Settings
Section titled “Settings”| Setting | Default | Effect |
|---|---|---|
| Show Sidebar Panel | On | Show the IH PivotBreeze action panel in the 3D Viewport and UV Editor sidebars |
| Remember Snap Settings | On | Share Object/Edit/Sculpt memory; retain separate native UV settings between Blender sessions |
| Pivot Placement Vertex Limit — Additional | 100,000 | Automatically allow selected objects or all visible geometry within the vertex budget; zero disables geometry picking |
| Customize Color | On | Use the configured color for the center handle and geometry hover instead of the theme’s Gizmo View Align color |
| Center Handle Color | RGB (63/255, 150/255, 1) |
Center handle appearance in 3D and UV, and geometry hover in 3D |
| Use Empty Hierarchies for Reset Actions | On | Use descendant bounds for selected Empty resets |
| Object/Sculpt exit and reset settings | On | Leave Local orientation and Bounding Box Center pivot point |
| Edit exit and reset settings | On | Leave Cursor orientation and 3D Cursor pivot point |
| UV exit and reset settings | On | Leave 2D Cursor pivot point |
Exit and reset preferences are separate. Turning off an exit preference restores the captured setting; turning off a reset preference avoids forcing the reset setting. These preferences do not select the target of Move to Zero.
The sidebar panel uses the same operators, labels, and icons as the Pie Menu. It shows all eight actions in supported 3D modes and only the five supported UV actions in the UV Editor. The panel is hidden in Vertex Paint, Weight Paint, Texture Paint, and every other unsupported context. Changing Show Sidebar Panel redraws all open 3D View and Image Editor areas immediately.
Apply, cancel, and Undo
Section titled “Apply, cancel, and Undo”Enter or Numpad Enter applies and closes the session. Esc cancels and restores the session-entry 3D or UV cursor, including completed helper moves and rotations. During a native transform, these keys first confirm or cancel that transform; press again to finish the pivot session. Cancelling does not undo a zero action already committed before the session resumed.
Blender owns geometry Undo; PivotBreeze reconciles helper, selection and cursor state. After an unexpected error, inspect the result and use Undo when appropriate. Re-query the active session after Undo/Redo in scripts.
Compatibility
Section titled “Compatibility”The extension requires Blender 4.2 or newer and currently uses Python API 4. The add-on release verification records source-linked checks on Windows with Blender 4.2.0 and 5.2.0, including native window tests. These results do not establish every operating system or third-party add-on combination.
For symptom-based help, see Troubleshooting.