Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,10 +199,11 @@ from the camera can be used.
- **multi_camera**
- [multi_camera_calibration] - Use captures of a calibration
object to generate transformation matrices to a single
coordinate frame, from connected cameras.
coordinate frame, from multiple connected cameras.
- [multi_camera_calibration_from_zdf] - Use captures of a
calibration object to generate transformation matrices to a
single coordinate frame, from ZDF files.
single coordinate frame, from ZDF files captured with multiple
cameras.
- [stitch_by_transformation] - Use transformation matrices from
Multi-Camera calibration to transform point clouds into a single
coordinate frame, from connected cameras.
Expand Down
3 changes: 3 additions & 0 deletions source/applications/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Applications

> **Tutorials:** Read the [Applications](https://support.zivid.com/en/latest/camera/academy/applications.html) tutorials on Zivid Knowledge Base.
3 changes: 3 additions & 0 deletions source/applications/advanced/auto_2d_settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@
first. If you want to use your own white reference (white wall, piece of paper, etc.) instead of using the calibration
board, you can provide your own mask in _main(). Then you will have to specify the lower limit for f-number yourself.

For more information about camera settings, check out this article:
https://support.zivid.com/en/latest/camera/reference-articles/camera-settings.html

"""

import argparse
Expand Down
3 changes: 3 additions & 0 deletions source/applications/advanced/barcode/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Barcode Detection

> **Tutorial:** Read the full [Barcode Detection](https://support.zivid.com/en/latest/camera/academy/applications/barcode-detection.html) tutorial on Zivid Knowledge Base.
3 changes: 3 additions & 0 deletions source/applications/advanced/barcode/barcode_detector.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
"""
Detect and decode linear and matrix barcodes from a 2D capture.

For more information on how to use the Zivid Barcode Detector, check out the Barcode Detection tutorial:
https://support.zivid.com/en/latest/camera/academy/applications/barcode-detection.html

"""

import zivid
Expand Down
3 changes: 3 additions & 0 deletions source/applications/advanced/color_balance.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@
If you want to use your own white reference (white wall, piece of paper, etc.) instead of using the calibration board,
you can provide your own mask in _main().

For more information on color balance, check out this article:
https://support.zivid.com/en/latest/reference-articles/settings/2d-settings/color-balance.html

"""

import argparse
Expand Down
4 changes: 4 additions & 0 deletions source/applications/advanced/downsample.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

The ZDF files for this sample can be found under the main instructions for Zivid samples.

For more information on downsampling point clouds, check out this tutorial:
https://support.zivid.com/en/latest/camera/academy/applications/downsampling.html

"""

import argparse
Expand Down Expand Up @@ -58,6 +61,7 @@ def _main() -> None:

point_cloud = frame.point_cloud()


print(f"Before downsampling: {point_cloud.width * point_cloud.height} point cloud")

visualize_point_cloud(point_cloud)
Expand Down
3 changes: 3 additions & 0 deletions source/applications/advanced/gamma_correction.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
"""
Capture 2D image with gamma correction.

For more information about gamma correction, check out this article:
https://support.zivid.com/en/latest/camera/reference-articles/settings/2d-settings/gamma.html

"""

import argparse
Expand Down
233 changes: 1 addition & 232 deletions source/applications/advanced/hand_eye_calibration/README.md
Original file line number Diff line number Diff line change
@@ -1,234 +1,3 @@
# Hand-Eye Calibration

This page provides an overview of how to **perform**, **verify**, and **use Hand–Eye Calibration** with Zivid cameras.

If you are new to Hand–Eye Calibration, start with the [Hand–Eye Calibration – Concept & Theory][HandEyeTutorial-url], explaining:

- What Hand–Eye Calibration is
- The difference between **eye-in-hand** and **eye-to-hand**
- Best practices for dataset (point clouds and robot poses) acquisition

If you already know what you’re doing and just want to run calibration or check out our Hand-Eye calibration code, continue reading.

<!-- Use "Markdown All in One plugin in VS code to automatically generate and update TOC". -->

- [Quick Start: Just Calibrate](#quick-start-just-calibrate)
- [Programmatic Hand–Eye Calibration](#programmatic-handeye-calibration)
- [Dataset Acquisition Samples](#dataset-acquisition-samples)
- [After Hand–Eye Calibration](#after-handeye-calibration)
- [Verifying Calibration Accuracy](#verifying-calibration-accuracy)
- [Summary: Which Tool Should I Use?](#summary-which-tool-should-i-use)

---

## Quick Start: Just Calibrate

If your goal is **only to compute the Hand–Eye Transformation Matrix**, use one of the tools below and follow Zivid’s [best-practice guide for capture poses][ZividHandEyeCalibration-url].

### Hand–Eye Calibration GUI (Recommended)

- Tutorial: [Hand–Eye GUI Tutorial][HandEyeCalibrationGUITutorial-url]
- Application: [HandEyeCalibration GUI][HandEyeCalibrationGUI-url]

Best choice if you:

- Want a guided, no-code workflow

---

## Programmatic Hand–Eye Calibration

The following applications produce a Hand–Eye Transformation Matrix from robot poses and calibration captures.

### Minimal Hand-Eye Calibration Code Example

- Sample: [HandEyeCalibration][HandEyeCalibration-url]
- Tutorial: [Integrating Zivid Hand-Eye Calibration][hand-eye-procedure-url]

Workflow:

1. User inputs robot pose in the form of a 4x4 transformation matrix (manual entry)
2. Camera captures the calibration object
3. User moves the robot to a new capture pose and enters the command to add a new pose
4. First three steps are repeated (typically 10–20 pose pairs)
5. User enters the command to perform calibration and the application returns a Hand-Eye Transformation Matrix

Use this if you:

- Want the simplest integration example
- Are building your own calibration pipeline

---

### Hand Eye Calibration CLI Tool

- Tutorial: [Zivid CLI Tool for Hand–Eye Calibration][CLI application-url]
- Installed with:
- Windows Zivid installer
- `tools` deb package on Ubuntu

Use this if you:

- Already have a dataset (robot poses + point clouds)
- Want a command-line, batch-style workflow

---

## Dataset Acquisition Samples

The samples below show how to acquire robot poses and point clouds, then compute the Hand–Eye Transformation Matrix.

### RoboDK-Based (Robot-Agnostic)

- Sample: [RoboDKHandEyeCalibration][RobodkHandEyeCalibration-url]
- Tutorial: [Any Robot + RoboDK + Python Hand–Eye Tutorial][RoboDKHandEyeTutorial-url]
- Supported robots: [RoboDK robot library][robodk-robot-library-url]

Features:

- Works with any RoboDK-supported robot
- Capture poses are manually defined in the `.rdk` file
- Fully automated robot control

---

### Universal Robots (e.g. UR5e)

- Sample: [UniversalRobotsPerformHandEyeCalibration][URhandeyecalibration-url]
- Tutorial: [UR5e + Python Hand–Eye Tutorial][URHandEyeTutorial-url]

Features:

- Designed specifically for UR robots
- Fully automated robot control

---

## After Hand–Eye Calibration

The following applications assume that a **Hand–Eye Transformation Matrix already exists**.

### Utilize Hand-Eye Calibration

- Sample: [UtilizeHandEyeCalibration][UtilizeHandEyeCalibration-url]
- Tutorial: [How To Use The Result Of Hand-Eye Calibration][UtilizeHandEyeCalibrationTutorial-url]

Demonstrates how to:

- Transform poses from camera coordinates to robot coordinates
- Use the transform in real applications (e.g., bin picking)

Example workflow:

1. Capture a point cloud with a Zivid camera
2. Find an object pick pose in camera coordinate system
3. Transform the pose into robot coordinate system
4. Plan and execute the robot motion

---

### Pose Conversions

- Sample: [PoseConversions][PoseConversions-url]
- Application: [PoseConversions GUI][PoseConversionsGUI-url]
- Theory: [Conversions Between Common Orientation Representations][PoseConversionsTheory-url]

Zivid primarily operates with a (4x4) Transformation Matrix (Rotation Matrix + Translation Vector). This example shows how to convert to and from:

- Axis–Angle
- Rotation Vector
- Roll–Pitch–Yaw
- Quaternion

Useful for integrating with robot controllers.

---

## Verifying Calibration Accuracy

### Verify Hand-Eye With Visualization

- Sample: [VerifyHandEyeWithVisualization][VerifyHandEyeWithVisualization-url]

Application validation approach:

- Loads the hand-eye dataset and output (transformation matrix)
- For each dataset pair:
- Transforms the point cloud to common coordinate system
- Finds the checkerboard centroid cartesian coordinates
- Removes the points outside the the checkerboard ROI
- Overlaps transformed point clouds
- Visualizes alignment accuracy

Best for:

- Visual verification
- Detecting systematic rotation/translation errors

---

### RoboDK Touch Test Verification

- Script: [RobodkHandEyeVerification][RobodkHandEyeVerification-url]
- Tutorial: [Verify Hand-Eye Calibration Result Via Touch Test][RobodkHandEyeVerificationTutorial-url]

Verification steps:

1. Robot moves to a predefined capture pose
2. User places the calibration object in the FOV
3. Camera estimates a touch point
4. Robot physically touches the calibration object
5. User repeats the test at multiple locations

Best for:

- Physical validation
- High-accuracy requirement applications

---

## Summary: Which Tool Should I Use?

| Goal | Recommended Tool |
|------|------------------|
| Conceptual understanding | [Knowledge Base article][HandEyeTutorial-url] |
| Guided calibration | [Hand–Eye GUI][HandEyeCalibrationGUITutorial-url] |
| Minimal integration example | [HandEyeCalibration][HandEyeCalibration-url] |
| Existing dataset | [Hand–Eye GUI][HandEyeCalibrationGUITutorial-url]|
| UR robots | [Hand–Eye GUI][HandEyeCalibrationGUITutorial-url] or [UR Hand–Eye sample][URHandEyeTutorial-url] |
| Any robot | [Hand–Eye GUI][HandEyeCalibrationGUITutorial-url] or [RoboDK Hand–Eye sample][RoboDKHandEyeTutorial-url] |
| Use calibration result | [UtilizeHandEyeCalibration][UtilizeHandEyeCalibrationTutorial-url] |
| Verify visually | [Hand–Eye GUI][HandEyeCalibrationGUITutorial-url] or [VerifyHandEyeWithVisualization][VerifyHandEyeWithVisualization-url] |
| Verify physically | [Hand–Eye GUI][HandEyeCalibrationGUITutorial-url] or [RoboDK Touch Test][RobodkHandEyeVerification-url] |


[HandEyeTutorial-url]: https://support.zivid.com/latest/academy/applications/hand-eye.html

[HandEyeCalibration-url]: hand_eye_calibration.py

[HandEyeCalibrationGUI-url]: hand_eye_gui.py
[HandEyeCalibrationGUITutorial-url]: https://support.zivid.com/en/latest/academy/applications/hand-eye/hand-eye-gui.html

[UtilizeHandEyeCalibration-url]: utilize_hand_eye_calibration.py
[UtilizeHandEyeCalibrationTutorial-url]: https://support.zivid.com/en/latest/academy/applications/hand-eye/how-to-use-the-result-of-hand-eye-calibration.html

[VerifyHandEyeWithVisualization-url]: verify_hand_eye_with_visualization.py
[ZividHandEyeCalibration-url]: https://support.zivid.com/latest/academy/applications/hand-eye/hand-eye-calibration-process.html
[hand-eye-procedure-url]: https://support.zivid.com/en/latest/academy/applications/hand-eye/hand-eye-calibration-process.html#custom-integration

[PoseConversions-url]: pose_conversions.py
[PoseConversionsGUI-url]: pose_conversion_gui.py
[PoseConversionsTheory-url]: https://support.zivid.com/en/latest/reference-articles/pose-conversions.html

[CLI application-url]: https://support.zivid.com/latest/academy/applications/hand-eye/zivid_CLI_tool_for_hand_eye_calibration.html

[URhandeyecalibration-url]: ur_hand_eye_calibration/universal_robots_perform_hand_eye_calibration.py
[URHandEyeTutorial-url]: https://support.zivid.com/en/latest/academy/applications/hand-eye/ur5-robot-%2B-python-generate-dataset-and-perform-hand-eye-calibration.html

[RobodkHandEyeCalibration-url]: robodk_hand_eye_calibration/robodk_hand_eye_calibration.py
[RoboDKHandEyeTutorial-url]: https://support.zivid.com/en/latest/academy/applications/hand-eye/robodk-%2B-python-generate-dataset-and-perform-hand-eye-calibration.html

[RobodkHandEyeVerification-url]: robodk_hand_eye_calibration/robodk_verify_hand_eye_calibration.py
[RobodkHandEyeVerificationTutorial-url]: https://support.zivid.com/en/latest/academy/applications/hand-eye/hand-eye-calibration-verification-via-touch-test.html

[robodk-robot-library-url]: https://robodk.com/supported-robots
> **Tutorial:** Read the full [Hand-Eye Calibration](https://support.zivid.com/en/latest/camera/academy/applications/hand-eye.html) tutorial on Zivid Knowledge Base.
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
"""
Perform Hand-Eye calibration.

For more information on Hand-Eye calibration, check out this tutorial:
https://support.zivid.com/en/latest/camera/academy/applications/hand-eye.html

"""

import argparse
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@
The `zividsamples` package is available in the /modules folder in the
`zivid-python-samples` repository. `pip install /path/to/zivid-python-samples/modules`

For more information on Hand-Eye GUI, check out this tutorial:
https://support.zivid.com/en/latest/camera/academy/applications/hand-eye/hand-eye-gui.html

"""

import sys
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
- Roll-Pitch-Yaw (Euler angles)
- Quaternion

For more information on pose conversions, check out this article:
https://support.zivid.com/en/latest/camera/reference-articles/pose-conversions.html

"""

from PyQt5.QtWidgets import QAction, QHBoxLayout, QMainWindow, QVBoxLayout, QWidget
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@
The convenience functions from this example can be reused in applicable applications. The YAML files for this sample
can be found under the main instructions for Zivid samples.

For more information on pose conversions, check out this article:
https://support.zivid.com/en/latest/camera/reference-articles/pose-conversions.html

"""

import enum
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,6 @@

You must modify each robot pose to your scene using the RoboDK GUI interface.

More information about RoboDK:
https://robodk.com/doc/en/Getting-Started.html

The sample comes with a .rdk sample environment file using a Universal Robots UR5e robot.

To use the sample with your robot an rdk file needs to be created using a model of your robot.
Expand All @@ -14,6 +11,11 @@
https://support.zivid.com/latest/academy/applications/hand-eye/hand-eye-calibration-process.html
Make sure to launch your RDK file and connect to robot through Robodk before running this script.

You can find the complete tutorial with a detailed explanation at:
https://support.zivid.com/en/latest/camera/academy/applications/hand-eye/robodk-%2B-python-generate-dataset-and-perform-hand-eye-calibration.html

More information about RoboDK is available at: https://robodk.com/doc/en/Getting-Started.html

"""

import argparse
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@

The YAML files for this sample can be found under the main instructions for Zivid samples.

For more information on how to utilize Hand-Eye calibration results, check out this tutorial:
https://support.zivid.com/en/latest/camera/academy/applications/hand-eye/how-to-use-the-result-of-hand-eye-calibration.html

"""

import numpy as np
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@
directory where this sample is stored. You can open the PLY point clouds
in MeshLab for visual inspection.

For more information on verifying Hand-Eye calibration, check out this tutorial:
https://support.zivid.com/en/latest/camera/academy/applications/hand-eye/hand-eye-calibration-verification.html

"""

import argparse
Expand Down
Loading
Loading