Zivid C++ API 2.13.1+18e79e79-1
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

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 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
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 void writeCameraCorrection(Zivid::Camera &camera, const CameraCorrection &cameraCorrection).

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.

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
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(const Camera &camera) or intrinsics(const Camera &camera, const Settings &settings).

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() [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
cameraReference 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
cameraReference to camera instance.
settingsReference 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
cameraReference to camera instance.
settings2dReference 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
cameraReference to camera instance.
settingsReference 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
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(const std::vector<InfieldCorrectionInput> &dataset) 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