Calibrating XY Tool Offsets with Camera Alignment

Overview

This procedure explains how to calibrate XY offsets between tools and the machine's z-probe using a USB microscope for visual alignment. Correct tool offsets are essential for consistent multi-tool operations.

Pre-Conditions

• Jubilee machine is powered on and homed.
• No XY offsets are currently active for the tool.
• USB microscope installed on the bed, facing upward.
• A suitable video capture setup (e.g., cv2.VideoCapture(0)).

Steps

1. Connect to the Machine

Establish communication with Jubilee.

from science_jubilee.machine import Machine
from science_jubilee.tools import Tool

# Connect to machine (edit address as needed)
m = Machine(address="jubilee.local")

2. Prepare the Tool

Ensure no previous XY offset is active:

• Manually clear XY offsets for the tool using Duet Web Control:

  G10 P<your_tool_number> X0 Y0

Then load and pick up the tool:

tool_number = 4
tool_name = "Test Tool"

tool = Tool(tool_number, tool_name)
m.load_tool(tool)
m.pickup_tool(tool)

3. Move to Reference Position

Move tool to a rough central reference point on the bed.

# Move close to bed center
m.move_to(x=150, y=150)

Lower the bed for camera installation:

# Make room to install camera
m.move_to(z=150)

4. Install Camera and Launch Video Feed

Mount USB microscope and check live feed.

import cv2 as cv2

# Open camera feed
cap = cv2.VideoCapture(0)

# Start simple centered view
def camera_stream(cap):
    center = None
    while center is None:
        ret, frame = cap.read()
        h, w = frame.shape[0:2]
        center = (int(w/2), int(h/2))

    while True:
        ret, frame = cap.read()
        target = cv2.circle(frame, center, 5, (0,255,0), -1)
        cv2.imshow('Input', frame)
        c = cv2.waitKey(1)
        if c == 27:  # Press ESC to close
            break

    cap.release()
    cv2.destroyAllWindows()

camera_stream(cap)

5. Center the Z-Probe

• Jog the machine until the z-probe is centered in the camera feed.
• When aligned, record the machine’s X/Y position.

pos = m.get_position()
zprobe_x = float(pos['X'])
zprobe_y = float(pos['Y'])

print(zprobe_x, zprobe_y)

6. Center the Tool Tip

• Open the camera feed again.
• Jog until the equipped tool tip is centered.

cap = cv2.VideoCapture(0)
camera_stream(cap)

Record the tool’s X/Y coordinates:

pos = m.get_position()
tool_x = float(pos['X'])
tool_y = float(pos['Y'])

print(tool_x, tool_y)

7. Calculate the XY Offset

Compute the difference between z-probe and tool tip positions.

xoff = zprobe_x - tool_x
yoff = zprobe_y - tool_y

print(f"G10 P{tool_number} X{xoff:.2f} Y{yoff:.2f}")

8. Update Toffsets.g

Add the generated G10 command into your Toffsets.g configuration file on Duet Web Control:

G10 P<tool_number> X<xoff> Y<yoff>

This ensures the tool offsets are applied automatically during tool changes.

Important Notes

• ESC key will close the camera streaming window.
• Clear existing tool offsets before starting.
• Double-check camera index if no image appears (0, 1, 2, etc.).
• Precise alignment is critical — even 0.1 mm error will cause issues with multi-tool workflows.
• Always rehome the machine after setting tool offsets.

Related Concepts

• Tool
• Machine
• Setting Tool Parking Positions