Zivid C++ API 2.9.0+4dbba385-1
Defining the Future of 3D Machine Vision
Classes | Enumerations | Functions
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. More...
 
ZIVID_CORE_EXPORT CameraIntrinsics estimateIntrinsics (const Frame &frame)
 Estimate camera intrinsics for a given frame. More...
 
ZIVID_CORE_EXPORT Zivid::Calibration::DetectionResult detectFeaturePoints (Zivid::Camera &camera)
 Detects feature points from a calibration object More...
 
ZIVID_CORE_EXPORT Zivid::Calibration::DetectionResult detectFeaturePoints (const Zivid::Frame &frame)
 Detects feature points in a captured Frame More...
 
ZIVID_CORE_EXPORT Zivid::Frame captureCalibrationBoard (Zivid::Camera &camera)
 Capture the calibration board More...
 
ZIVID_CORE_EXPORT std::ostream & operator<< (std::ostream &stream, const InfieldCorrectionInput &input)
 Serialize the value to a stream More...
 
ZIVID_CORE_EXPORT std::ostream & operator<< (std::ostream &stream, const CameraVerification &cameraVerification)
 Serialize the value to a stream More...
 
ZIVID_CORE_EXPORT std::ostream & operator<< (std::ostream &stream, const AccuracyEstimate &accuracyEstimate)
 Serialize the value to a stream More...
 
ZIVID_CORE_EXPORT std::ostream & operator<< (std::ostream &stream, const CameraCorrection &cameraCorrection)
 Serialize the value to a stream More...
 
ZIVID_CORE_EXPORT CameraVerification verifyCamera (const InfieldCorrectionInput &input)
 Verify the current camera trueness based on a single measurement More...
 
ZIVID_CORE_EXPORT CameraCorrection computeCameraCorrection (const std::vector< InfieldCorrectionInput > &dataset)
 Calculate new in-field camera correction More...
 
ZIVID_CORE_EXPORT void writeCameraCorrection (Zivid::Camera &camera, const CameraCorrection &cameraCorrection)
 Write the in-field correction on a camera More...
 
ZIVID_CORE_EXPORT void resetCameraCorrection (Zivid::Camera &camera)
 Reset the in-field correction on a camera to factory settings More...
 
ZIVID_CORE_EXPORT bool hasCameraCorrection (const Zivid::Camera &camera)
 Check if the camera has an in-field correction written to it More...
 
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 More...
 
ZIVID_CORE_EXPORT std::string toString (InfieldCorrectionDetectionStatus status)
 Get string representation of the status. More...
 
ZIVID_CORE_EXPORT std::ostream & operator<< (std::ostream &stream, const InfieldCorrectionDetectionStatus &status)
 Serialize the value to a stream More...
 

Enumeration Type Documentation

◆ InfieldCorrectionDetectionStatus

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
cameraThe 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
cameraCamera 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
datasetA 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
frameFrame 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
cameraCamera 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.

Parameters
frameReference 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
cameraThe camera to check
Returns
Boolean indicating whether or not the camera has an in-field correction

◆ intrinsics()

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

Intrinsic parameters of a given camera.

Parameters
cameraReference to camera 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

◆ resetCameraCorrection()

ZIVID_CORE_EXPORT void Zivid::Experimental::Calibration::resetCameraCorrection ( Zivid::Camera camera)

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

Parameters
cameraThe 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
inputA 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
cameraThe camera to write the correction to
cameraCorrectionThe camera correction to write