align_cursor_to_object.py

"""
Align Cursor to Object - Snaps the 3D cursor to the active object's transform.

In Object Mode, sets the cursor's location AND rotation to exactly match
the active object, making it a one-click inverse of "Align Object to Cursor".
Ideal for quickly setting up the cursor as a reference point before further
pivot or alignment operations.
"""

import bpy
from typing import Optional


def align_cursor_to_active(context) -> Optional[str]:
    """Set cursor location and rotation to match the active object.

    Args:
        context: Current Blender context

    Returns:
        Error message if the operation cannot proceed, None on success.
    """
    active = context.active_object
    if not active:
        return "No active object"

    cursor = context.scene.cursor
    cursor.location = active.location.copy()
    cursor.rotation_euler = active.rotation_euler.copy()
    return None


class VIEW3D_OT_align_cursor_to_active(bpy.types.Operator):
    """Snap the 3D cursor to the active object's location and rotation"""
    bl_idname = "view3d.align_cursor_to_active"
    bl_label  = "Cursor to Active Object"
    bl_description = (
        "Snap the 3D cursor to the active object's exact location and rotation. "
        "One-click setup for further pivot or alignment operations"
    )
    bl_options = {'REGISTER', 'UNDO'}

    @classmethod
    def poll(cls, context):
        return context.mode == 'OBJECT' and context.active_object is not None

    def execute(self, context):
        error = align_cursor_to_active(context)
        if error:
            self.report({'ERROR'}, error)
            return {'CANCELLED'}
        return {'FINISHED'}


# ─── Registration ─────────────────────────────────────────────────────────────

classes = (
    VIEW3D_OT_align_cursor_to_active,
)


def register():
    for cls in classes:
        bpy.utils.register_class(cls)


def unregister():
    for cls in reversed(classes):
        bpy.utils.unregister_class(cls)