Zivid::Experimental::Calibration Namespace Reference

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 , unknownCalibrationObject , invalidCalibrationObject , 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 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
unknownCalibrationObject
invalidCalibrationObject
detectionFailed
insufficientDataQuality
invalidCaptureMethod
invalidAlignment

Function Documentation

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 must 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 writeCameraCorrection.

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.

This method will throw an exception if the frame does not come from Zivid::Experimental::Calibration::captureCalibrationBoard(Zivid::Camera &camera).

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).

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.

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.

operator<<() [1/5]

ZIVID_CORE_EXPORT std::ostream & Zivid::Experimental::Calibration::operator<<	(	std::ostream &	stream,
		const AccuracyEstimate &	accuracyEstimate
	)

Serialize the value to a stream.

operator<<() [2/5]

ZIVID_CORE_EXPORT std::ostream & Zivid::Experimental::Calibration::operator<<	(	std::ostream &	stream,
		const CameraCorrection &	cameraCorrection
	)

Serialize the value to a stream.

operator<<() [3/5]

ZIVID_CORE_EXPORT std::ostream & Zivid::Experimental::Calibration::operator<<	(	std::ostream &	stream,
		const CameraVerification &	cameraVerification
	)

Serialize the value to a stream.

operator<<() [4/5]

ZIVID_CORE_EXPORT std::ostream & Zivid::Experimental::Calibration::operator<<	(	std::ostream &	stream,
		const InfieldCorrectionDetectionStatus &	status
	)

Serialize the value to a stream.

operator<<() [5/5]

ZIVID_CORE_EXPORT std::ostream & Zivid::Experimental::Calibration::operator<<	(	std::ostream &	stream,
		const InfieldCorrectionInput &	input
	)

Serialize the value to a stream.

pixelMapping()

ZIVID_CORE_EXPORT PixelMapping Zivid::Experimental::Calibration::pixelMapping	(	const Camera &	camera,
		const Settings &	settings
	)

Return pixel mapping information given camera and settings.

When mapping from a subsampled point cloud to a full resolution 2D image it is important to get the pixel mapping correct. This mapping depends on camera model and settings. This function provides the correct parameters to map the 2D coordinates in a point cloud captured using settings to the full resolution of the camera.

Parameters

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

Returns

A PixelMapping instance.

resetCameraCorrection()

ZIVID_CORE_EXPORT void Zivid::Experimental::Calibration::resetCameraCorrection

(

Zivid::Camera &

camera

)

Reset the in-field correction on a camera to factory settings.

Parameters

camera

The camera to reset

toString()

ZIVID_CORE_EXPORT std::string Zivid::Experimental::Calibration::toString

(

InfieldCorrectionDetectionStatus

status

)

Get string representation of the status.

verifyCamera()

ZIVID_CORE_EXPORT CameraVerification Zivid::Experimental::Calibration::verifyCamera

(

const InfieldCorrectionInput &

input

)

Verify the current camera trueness based on a single measurement.

The purpose of this function is to allow quick assessment of the quality of the in-field correction on a camera (or the need for one if none exists already). This function will throw an exception if the provided InfieldCorrectionInput has valid()==false.

The return value of this function will give an indication of the dimension trueness at the location where the input data was captured. If the returned assessment indicates a trueness error that is above threshold for your application, consider using computeCameraCorrection in order to get an updated correction for the camera.

Parameters

input

A single in-field correction measurement.

writeCameraCorrection()

ZIVID_CORE_EXPORT void Zivid::Experimental::Calibration::writeCameraCorrection	(	Zivid::Camera &	camera,
		const CameraCorrection &	cameraCorrection
	)

Write the in-field correction on a camera.

After calling this function, the given correction will automatically be used any time the capture function is called on this camera. The correction will be persisted on the camera even though the camera is power-cycled or connected to a different PC.

Beware that calling this will overwrite any existing correction present on the camera.

Parameters

camera	The camera to write the correction to
cameraCorrection	The camera correction to write