Infield Verification and Correction

Assess and restore the dimension trueness of a camera in the field. Verify the current trueness from a single calibration-board measurement, and compute and write a new correction from a series of measurements. Mirrors {cpp,csharp}/source/Camera/Maintenance/.

        flowchart LR
  subgraph collection [Data collection]
    Camera
    captureBoardOp(["captureCalibrationBoard()"])
    detectBoardOp(["detectCalibrationBoard()"])
    Frame
    DetectionResult
    InfieldCorrectionInput
  end

  subgraph verification [Verification]
    verifyCameraOp(["verifyCamera()"])
    CameraVerification
  end

  subgraph correction [Correction]
    computeCorrectionOp(["computeCameraCorrection()"])
    CameraCorrection
    accuracyEstimateOp(["accuracyEstimate()"])
    AccuracyEstimate
    writeCorrectionOp(["writeCameraCorrection()"])
  end

  Camera --> captureBoardOp --> Frame
  Frame --> detectBoardOp --> DetectionResult
  DetectionResult -.-> InfieldCorrectionInput
  InfieldCorrectionInput -.-> verifyCameraOp --> CameraVerification
  InfieldCorrectionInput -.-> computeCorrectionOp --> CameraCorrection
  CameraCorrection --> accuracyEstimateOp --> AccuracyEstimate
  CameraCorrection -.-> writeCorrectionOp --> Camera

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  class Camera,Frame,DetectionResult,InfieldCorrectionInput,CameraVerification,CameraCorrection,AccuracyEstimate zividClass
  class captureBoardOp,detectBoardOp,verifyCameraOp,computeCorrectionOp,accuracyEstimateOp,writeCorrectionOp api

The captureCalibrationBoard and detectCalibrationBoard entry points that produce the DetectionResult are documented on Hand-Eye Calibration.

InfieldCorrectionInput

Wraps a single DetectionResult and reports whether it is of sufficient type and quality for verification and correction. Inspect valid() / statusDescription() before use.

class InfieldCorrectionInput

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

The constructor takes a Zivid::Calibration::DetectionResult. Such an object may or may not contain data of sufficient type and quality for in-field verification and correction. This will be reflected by the result of the status() or valid() functions, and if invalid a human-readable reason will be accessible with the statusDescription() function.

Public Functions

InfieldCorrectionInput(const DetectionResult &detectionResult)

Constructs an InfieldCorrectionInput instance.

Input data should be captured by calling detectFeaturePoints(Zivid::Camera &camera) with a Zivid::Camera argument.

Parameters:

detectionResult – A feature-point detection result

const DetectionResult &detectionResult() const

Get the stored feature-point detection result.

InfieldCorrectionDetectionStatus status() const

Get detection status/validity as an enum.

bool valid() const

Check if the data is valid for use with in-field verification and correction.

explicit operator bool() const

Check if the data is valid for use with in-field verification and correction.

This operator is merely a shorthand for the valid() function.

std::string statusDescription() const

Get human-readable description of the status.

Useful for feedback if valid() is false.

This returns a free-form string and should not be considered API stable.

std::string toString() const

Get string representation of the in-field correction input.

class InfieldCorrectionInput

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

The constructor takes a Zivid::NET::Calibration::DetectionResult. Such an object may or may not contain data of sufficient type and quality for in-field verification and correction. This will be reflected by the value of the Status or Valid properties, and if invalid a human-readable reason will be accessible with the StatusDescription() function.

Public Functions

InfieldCorrectionInput (Zivid::NET::Calibration::DetectionResult ^ detectionResult)

Constructs an InfieldCorrectionInput instance.

Input data should be captured by calling detectFeaturePoints(Zivid::Camera &camera) with a Zivid::Camera argument.

Parameters:

detectionResult – A feature-point detection result

Properties

Zivid::NET::Calibration::DetectionResult^ DetectionResult

Get the stored feature-point detection result.

DetectionStatus^ Status

Get detection status/validity as an enum.

bool Valid

Check if the data is valid for use with in-field verification and correction.

zivid.calibration.InfieldCorrectionInput — see Infield Correction.

verifyCamera

Verifies the current dimension trueness from a single measurement. Throws if the input is not valid.

CameraVerification Zivid::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(conststd::vector<InfieldCorrectionInput> &dataset) in order to get an updated correction for the camera.

Parameters:

input – A single in-field correction measurement.

class Calibrator

Public Static Functions

static CameraVerification ^ VerifyCamera (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(

System::Collections::Generic::IEnumerable<InfieldCorrectionInput> &dataset) in order to get an updated correction for the camera.

Parameters:

input – A single in-field correction measurement.

zivid.calibration.verify_camera(input) — see Infield Correction.

CameraVerification

The result of a verification: the local dimension trueness error and the position at which it was measured.

class CameraVerification

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

The given dimension trueness includes the effects of any in-field correction stored on the camera at the time of capture. In other words, a camera with sub-optimal factory-settings trueness but a good in-field correction will show good results here.

Public Functions

float localDimensionTrueness() const

Get the estimated local dimension trueness error.

The dimension trueness represents the relative deviation between the measured size of the calibration object and the true size of the calibration object, including the effects of any in-field correction stored on the camera at the time of capture. Note that this estimate is local, i.e. only valid for the region of space very close to the calibration object.

The returned value is a fraction (relative trueness error). Multiply by 100 to get trueness error in percent.

Returns:

Estimated local dimension trueness error

PointXYZ position() const

Get the location at which the measurement was made.

Returns:

Location (XYZ) in the camera reference frame

std::string toString() const

Get string representation of the camera assessment.

Returns:

Assessment as string

class CameraVerification

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

The given dimension trueness includes the effects of any in-field correction stored on the camera at the time of capture. In other words, a camera with sub-optimal factory-settings trueness but a good in-field correction will show good results here.

Properties

float LocalDimensionTrueness

Get the estimated local dimension trueness error.

The dimension trueness represents the relative deviation between the measured size of the calibration object and the true size of the calibration object, including the effects of any in-field correction stored on the camera at the time of capture. Note that this estimate is local, i.e. only valid for the region of space very close to the calibration object.

The returned value is a fraction (relative trueness error). Multiply by 100 to get trueness error in percent.

Return:

Estimated local dimension trueness error

PointXYZ Position

Get the location at which the measurement was made.

Return:

Location (XYZ) in the camera reference frame

zivid.calibration.CameraVerification — see Infield Correction.

computeCameraCorrection

Computes a new correction from a dataset of measurements taken at varying distances. A larger, more varied dataset yields a more reliable correction.

CameraCorrection Zivid::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.

class Calibrator

Public Static Functions

static CameraCorrection ^ ComputeCameraCorrection (System::Collections::Generic::IEnumerable< 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::NET::Camera ^camera, 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.

zivid.calibration.compute_camera_correction(dataset) — see Infield Correction.

CameraCorrection

A computed correction that may be written to a camera. Exposes the expected accuracy through accuracyEstimate().

class CameraCorrection

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

Public Functions

AccuracyEstimate accuracyEstimate() const

Get an estimate for expected dimension accuracy if the correction is applied to the camera.

The suggested working volume is chosen based on the properties of the input data in order to achieve a reasonable tradeoff between accuracy and extrapolation.

Returns:

An accuracy estimate

std::string toString() const

Get string representation of the camera correction.

Returns:

Correction info as a string

class CameraCorrection

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

Properties

Zivid::NET::Calibration::AccuracyEstimate^ AccuracyEstimate

Get an estimate for expected dimension accuracy if the correction is applied to the camera.

The suggested working volume is chosen based on the properties of the input data in order to achieve a reasonable tradeoff between accuracy and extrapolation.

Return:

An accuracy estimate

zivid.calibration.CameraCorrection — see Infield Correction.

AccuracyEstimate

The dimension accuracy expected across a working volume (zMin() to zMax()) if the correction is written to the camera.

class AccuracyEstimate

A dimension accuracy estimate for a specific working volume.

Public Functions

float dimensionAccuracy() const

The estimated dimension accuracy error obtained if the correction is applied.

This number represents a 1-sigma (68% confidence) upper bound for dimension trueness error in the working volume (z=zMin() to z=zMax(), across the entire field of view). In other words, it represents the expected distribution of local dimension trueness measurements (see CameraVerification) that can be expected if measuring throughout the working volume.

The returned value is a fraction (relative trueness error). Multiply by 100 to get trueness in percent.

Note that the accuracy close to where the original data was captured is likely much better than what is implied by this number. This number is rather an accuracy estimate for the entire extrapolated working volume.

Returns:

A 1-sigma (68% confidence) upper bound for trueness error in the working volume

float zMin() const

The range of validity of the accuracy estimate (lower end)

Returns:

Minimum z-value of working volume in millimeters

float zMax() const

The range of validity of the accuracy estimate (upper end)

Returns:

Maximum z-value of working volume in millimeters

std::string toString() const

Get string representation of the accuracy estimate.

Returns:

Accuracy estimate as string

class AccuracyEstimate

A dimension accuracy estimate for a specific working volume.

Properties

float DimensionAccuracy

The estimated dimension accuracy error obtained if the correction is applied.

This number represents a 1-sigma (68% confidence) upper bound for dimension trueness error in the working volume (z=ZMin to z=ZMax, across the entire field of view). In other words, it represents the expected distribution of local dimension trueness measurements (see CameraVerification) that can be expected if measuring throughout the working volume.

The returned value is a fraction (relative trueness error). Multiply by 100 to get trueness in percent.

Note that the accuracy close to where the original data was captured is likely much better than what is implied by this number. This number is rather an accuracy estimate for the entire extrapolated working volume.

Return:

A 1-sigma (68% confidence) upper bound for trueness error in the working volume

float ZMin

The range of validity of the accuracy estimate (lower end)

Return:

Minimum z-value of working volume in millimeters

float ZMax

The range of validity of the accuracy estimate (upper end)

Return:

Maximum z-value of working volume in millimeters

zivid.calibration.AccuracyEstimate — see Infield Correction.

writeCameraCorrection / resetCameraCorrection / hasCameraCorrection / cameraCorrectionTimestamp

Manage the correction persisted on a camera: write a new correction, reset to factory settings, check whether one exists, and read when it was created. A written correction is applied automatically on every capture and survives power-cycling.

void Zivid::Calibration::writeCameraCorrection(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

void Zivid::Calibration::resetCameraCorrection(Camera &camera)

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

Parameters:

camera – The camera to reset

bool Zivid::Calibration::hasCameraCorrection(const 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

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

Get the UTC 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 UTC timestamp indicating when the correction was created

class Calibrator

Public Static Functions

static void WriteCameraCorrection (Camera ^ camera, 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

static void ResetCameraCorrection (Camera ^ camera)

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

Parameters:

camera – The camera to reset

static bool HasCameraCorrection (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

static System::DateTime CameraCorrectionTimestamp (Camera ^ camera)

Get the UTC 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 UTC timestamp indicating when the correction was created

zivid.calibration.write_camera_correction(camera, correction), zivid.calibration.reset_camera_correction(camera), zivid.calibration.has_camera_correction(camera), and zivid.calibration.camera_correction_timestamp(camera) — see Infield Correction.

InfieldCorrectionDetectionStatus

Enum describing the validity of an InfieldCorrectionInput (e.g. ok, detectionFailed, invalidAlignment).

enum class Zivid::Calibration::InfieldCorrectionDetectionStatus

Values:

enumerator ok
enumerator detectionFailed
enumerator invalidAlignment

See Zivid::NET::Calibration::InfieldCorrectionDetectionStatus in the C# API reference.

zivid.calibration.InfieldCorrectionInput.status_description() reports the status — see Infield Correction.

See also