Namespaces
namespace	HandEyeLowDOF

Classes
class	AccuracyEstimate
	A dimension accuracy estimate for a specific working volume. More...

class	CameraCorrection
	An in-field correction that may be written to a camera. More...

class	CameraVerification
	An assessment of the current dimension trueness of a camera at a specific location. More...

class	InfieldCorrectionInput
	Container for input-data needed by in-field verification and correction functions. More...

Enumerations
enum class	InfieldCorrectionDetectionStatus { ok , detectionFailed , insufficientDataQuality , invalidCaptureMethod , invalidAlignment }

Functions
ZIVID_CORE_EXPORT CameraIntrinsics	intrinsics (const Camera &camera)
	Intrinsic parameters of a given camera.

ZIVID_CORE_EXPORT CameraIntrinsics	intrinsics (const Camera &camera, const Settings &settings)
	Intrinsic parameters of a given camera and settings.

ZIVID_CORE_EXPORT CameraIntrinsics	intrinsics (const Camera &camera, const Settings2D &settings2d)
	Intrinsic parameters of a given camera and 2D settings.

ZIVID_CORE_EXPORT CameraIntrinsics	estimateIntrinsics (const Frame &frame)
	Estimate camera intrinsics for a given frame.

ZIVID_CORE_EXPORT PixelMapping	pixelMapping (const Camera &camera, const Settings &settings)
	Return pixel mapping information given camera and settings.

ZIVID_CORE_EXPORT HandEyeOutput	calibrateEyeInHandLowDOF (const std::vector< HandEyeInput > &inputs, const HandEyeLowDOF::FixedPlacementOfCalibrationObjects &fixedObjects)
	Performs eye-in-hand calibration for low degrees-of-freedom robots.

ZIVID_CORE_EXPORT HandEyeOutput	calibrateEyeToHandLowDOF (const std::vector< HandEyeInput > &inputs, const HandEyeLowDOF::FixedPlacementOfCalibrationObjects &fixedObjects)
	Performs eye-to-hand calibration for low degrees-of-freedom robots.

ZIVID_CORE_EXPORT Zivid::Calibration::DetectionResult	detectFeaturePoints (Zivid::Camera &camera)
	Detects feature points from a calibration object.

ZIVID_CORE_EXPORT Zivid::Calibration::DetectionResult	detectFeaturePoints (const Zivid::Frame &frame)
	Detects feature points in a captured Frame.

ZIVID_CORE_EXPORT Zivid::Frame	captureCalibrationBoard (Zivid::Camera &camera)
	Capture the calibration board.

ZIVID_CORE_EXPORT std::ostream &	operator<< (std::ostream &stream, const InfieldCorrectionInput &input)
	Serialize the value to a stream.

ZIVID_CORE_EXPORT std::ostream &	operator<< (std::ostream &stream, const CameraVerification &cameraVerification)
	Serialize the value to a stream.

ZIVID_CORE_EXPORT std::ostream &	operator<< (std::ostream &stream, const AccuracyEstimate &accuracyEstimate)
	Serialize the value to a stream.

ZIVID_CORE_EXPORT std::ostream &	operator<< (std::ostream &stream, const CameraCorrection &cameraCorrection)
	Serialize the value to a stream.

ZIVID_CORE_EXPORT CameraVerification	verifyCamera (const InfieldCorrectionInput &input)
	Verify the current camera trueness based on a single measurement.

ZIVID_CORE_EXPORT CameraCorrection	computeCameraCorrection (const std::vector< InfieldCorrectionInput > &dataset)
	Calculate new in-field camera correction.

ZIVID_CORE_EXPORT void	writeCameraCorrection (Zivid::Camera &camera, const CameraCorrection &cameraCorrection)
	Write the in-field correction on a camera.

ZIVID_CORE_EXPORT void	resetCameraCorrection (Zivid::Camera &camera)
	Reset the in-field correction on a camera to factory settings.

ZIVID_CORE_EXPORT bool	hasCameraCorrection (const Zivid::Camera &camera)
	Check if the camera has an in-field correction written to it.

ZIVID_CORE_EXPORT std::chrono::time_point< std::chrono::system_clock >	cameraCorrectionTimestamp (const Zivid::Camera &camera)
	Get the time at which the camera's in-field correction was created.

ZIVID_CORE_EXPORT std::string	toString (InfieldCorrectionDetectionStatus status)
	Get string representation of the status.

ZIVID_CORE_EXPORT std::ostream &	operator<< (std::ostream &stream, const InfieldCorrectionDetectionStatus &status)
	Serialize the value to a stream.

Enumeration Type Documentation

◆ InfieldCorrectionDetectionStatus

enum class Zivid::Experimental::Calibration::InfieldCorrectionDetectionStatus

strong

Enumerator
ok
detectionFailed
insufficientDataQuality
invalidCaptureMethod
invalidAlignment

Function Documentation

◆ calibrateEyeInHandLowDOF()

ZIVID_CORE_EXPORT HandEyeOutput Zivid::Experimental::Calibration::calibrateEyeInHandLowDOF	(	const std::vector< HandEyeInput > &	inputs,
		const HandEyeLowDOF::FixedPlacementOfCalibrationObjects &	fixedObjects )

Performs eye-in-hand calibration for low degrees-of-freedom robots.

For robots with low degrees-of-freedom (DOF), that is, less than 6 DOF, the robot pose and capture inputs are not alone sufficient to uniquely identify the solution to the hand-eye calibration. This procedure additionally takes knowledge about the fixed placement of the calibration objects in the scene to provide a unique solution. For 6 DOF robots, consider using the calibrateEyeInHand function instead.

The procedure requires all robot poses to be different. At least 2 poses are required when using a calibration board, or 6 poses when using fiducial markers. For fiducial markers, each marker must be detected across 2 poses at minimum. An exception will be thrown if the preceding requirements are not fulfilled.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection results. Zivid point clouds are, by default, in millimeters.

Parameters

inputs	Vector of HandEyeInput instances.
fixedObjects	Specifies the fixed placement of calibration objects in the robot's base frame.

Returns: Instance of HandEyeOutput.

◆ calibrateEyeToHandLowDOF()

ZIVID_CORE_EXPORT HandEyeOutput Zivid::Experimental::Calibration::calibrateEyeToHandLowDOF	(	const std::vector< HandEyeInput > &	inputs,
		const HandEyeLowDOF::FixedPlacementOfCalibrationObjects &	fixedObjects )

Performs eye-to-hand calibration for low degrees-of-freedom robots.

For robots with low degrees-of-freedom (DOF), that is, less than 6 DOF, the robot pose and capture inputs are not alone sufficient to uniquely identify the solution to the hand-eye calibration. This procedure additionally takes knowledge about the fixed placement of the calibration objects in the scene to provide a unique solution. For 6 DOF robots, consider using the calibrateEyeToHand function instead.

The procedure requires all robot poses to be different. At least 2 poses are required when using a calibration board, or 6 poses when using fiducial markers. For fiducial markers, each marker must be detected across 2 poses at minimum. An exception will be thrown if the preceding requirements are not fulfilled.

Note: the units of the input robot poses must be consistent with the units of the point clouds used to create the detection results. Zivid point clouds are, by default, in millimeters.

Parameters

inputs	Vector of HandEyeInput instances.
fixedObjects	Specifies the fixed placement of calibration objects in the robot's end-effector frame.

Returns: Instance of HandEyeOutput.

◆ cameraCorrectionTimestamp()

ZIVID_CORE_EXPORT std::chrono::time_point< std::chrono::system_clock > Zivid::Experimental::Calibration::cameraCorrectionTimestamp ( const Zivid::Camera & camera )

Get the time at which the camera's in-field correction was created.

If hasCameraCorrection is false, the returned timestamp will default to beginning of epoch (Jan 1st 1970 UTC).

Parameters

camera The camera to check

Returns: A timestamp indicating when the correction was created

◆ captureCalibrationBoard()

ZIVID_CORE_EXPORT Zivid::Frame Zivid::Experimental::Calibration::captureCalibrationBoard ( Zivid::Camera & camera )

Capture the calibration board.

This method is used to capture an official Zivid calibration board, using settings that are optimized for the board. This method may be used to capture the Frame that is given as input to Zivid::Experimental::Calibration::detectFeaturePoints(const Zivid::Frame &frame). You can also use the Zivid::Experimental::Calibration::detectFeaturePoints(Zivid::Camera &camera) function directly, which under the hood will invoke captureCalibrationBoard for you.

To verify if you successfully captured the calibration board and found the feature points, invoke Zivid::Experimental::Calibration::detectFeaturePoints(const Zivid::Frame &frame) with the frame returned from this function, then invoke Zivid::Calibration::DetectionResult::valid() on the returned DetectionResult object.

For more information please visit Zivid help page.

Parameters

camera Camera to be used to capture the calibration board

◆ computeCameraCorrection()

ZIVID_CORE_EXPORT CameraCorrection Zivid::Experimental::Calibration::computeCameraCorrection ( const std::vector< InfieldCorrectionInput > & dataset )

Calculate new in-field camera correction.

The purpose of this function is to calculate a new in-field correction for a camera based on a series of calibration object captures taken at varying distances. This function will throw an exception if any of the provided InfieldCorrectionInput have valid()==false.

The quantity and range of data is up to the user, but generally a larger dataset will yield a more accurate and reliable correction. If all measurements were taken at approximately the same distance, the resulting correction will mainly be valid at those distances. If several measurements were taken at significantly different distances, the resulting correction will likely be more suitable for extrapolation to distances beyond where the dataset was collected.

The result of this process is a CameraCorrection object, which will contain information regarding the proposed working range and the accuracy that can be expected within the working range, if the correction is written to the camera. The correction may be written to the camera using void writeCameraCorrection(Zivid::Camera &camera, const CameraCorrection &cameraCorrection).

This function will throw an exception if the input data is extremely inconsistent/noisy.

Parameters

dataset A sequence of in-field correction measurements.

Returns: A new correction that may be written to the camera.

◆ detectFeaturePoints() [1/2]

ZIVID_CORE_EXPORT Zivid::Calibration::DetectionResult Zivid::Experimental::Calibration::detectFeaturePoints ( const Zivid::Frame & frame )

Detects feature points in a captured Frame.

If this function is being used for in-field verification or correction, the frame should come from Zivid::Experimental::Calibration::captureCalibrationBoard(Zivid::Camera &camera) in order to ensure good data quality.

Parameters

frame Frame to be used to detect the feature points

◆ detectFeaturePoints() [2/2]

ZIVID_CORE_EXPORT Zivid::Calibration::DetectionResult Zivid::Experimental::Calibration::detectFeaturePoints ( Zivid::Camera & camera )

Detects feature points from a calibration object.

Using this version of the detectFeaturePoints function is necessary to ensure that the data quality is sufficient for use in in-field verification and correction.

The functionality is to be exclusively used in combination with Zivid verified checkerboards. For further information please visit Zivid help page.

Parameters

camera Camera to be used to capture the calibration object

◆ estimateIntrinsics()

ZIVID_CORE_EXPORT CameraIntrinsics Zivid::Experimental::Calibration::estimateIntrinsics ( const Frame & frame )

Estimate camera intrinsics for a given frame.

The estimated parameters may be used to project 3D point cloud onto the corresponding 2D image. This function is for advanced use cases. Otherwise, use intrinsics(const Camera &camera) or intrinsics(const Camera &camera, const Settings &settings).

For a 2D+3D capture, the 2D color image and 3D point cloud may have different resolutions, depending on the pixel sampling and resampling settings used in the Settings and in the Settings::Color. This function returns intrinsics applicable for the 3D point cloud resolution.

Parameters

frame Reference to frame instance.

Returns: A CameraIntrinsics instance.

◆ hasCameraCorrection()

ZIVID_CORE_EXPORT bool Zivid::Experimental::Calibration::hasCameraCorrection ( const Zivid::Camera & camera )

Check if the camera has an in-field correction written to it.

This is false if writeCameraCorrection has never been called using this camera. It will also be false after calling resetCameraCorrection.

Parameters

camera The camera to check

Returns: Boolean indicating whether or not the camera has an in-field correction

◆ intrinsics() [1/3]

ZIVID_CORE_EXPORT CameraIntrinsics Zivid::Experimental::Calibration::intrinsics ( const Camera & camera )

Intrinsic parameters of a given camera.

These intrinsic parameters are only appropriate for the resolution that the default 3D settings for the given camera provides. If planning to capture with settings other than the default 3D then use intrinsics(const Camera &camera, const Settings &settings) or intrinsics(const Camera &camera, const Settings2D &settings2d), or one can estimate the intrinsics from the frame after capture with estimateIntrinsics. Note! If there is a mismatch between 2D and 3D resolution then use intrinsics(const Camera &camera, const Settings2D &settings2d).

Parameters

camera Reference to camera instance.

Returns: A CameraIntrinsics instance.

◆ intrinsics() [2/3]

ZIVID_CORE_EXPORT CameraIntrinsics Zivid::Experimental::Calibration::intrinsics	(	const Camera &	camera,
		const Settings &	settings )

Intrinsic parameters of a given camera and settings.

These intrinsic parameters take into account the expected resolution of the point clouds captured with these settings.

Note: This function returns intrinsics for a fixed temperature and aperture value. The only part of Settings currently used by this function is Settings::Sampling::Pixel and Settings::Processing::Resampling::Mode.

For a 2D+3D capture, the 2D color image and 3D point cloud may have different resolutions, depending on the pixel sampling and resampling settings used in the Settings and in the Settings::Color. This function returns intrinsics applicable for the 3D point cloud resolution. You can use intrinsics(const Camera &camera, const Settings2D &settings2d) with Settings::Color for 2D intrinsics.

Parameters

camera	Reference to camera instance.
settings	Reference to settings instance.

Returns: A CameraIntrinsics instance.

◆ intrinsics() [3/3]

ZIVID_CORE_EXPORT CameraIntrinsics Zivid::Experimental::Calibration::intrinsics	(	const Camera &	camera,
		const Settings2D &	settings2d )

Intrinsic parameters of a given camera and 2D settings.

These intrinsics will match the resolution of a 2D capture done using this camera with the provided Settings2D.

Parameters

camera	Reference to camera instance.
settings2d	Reference to a 2D settings instance.

Returns: A CameraIntrinsics instance.