Infield Verification and Correction

评估并恢复现场相机的尺寸正确度。通过单次标定板测量验证当前的正确度，并根据一系列测量结果计算并写入新的校正值。对应 {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

生成 DetectionResult 的 captureCalibrationBoard 和 detectCalibrationBoard 入口点记录在 手眼标定 中。

InfieldCorrectionInput

封装单个 DetectionResult，并报告其类型和质量是否足以用于验证和校正。使用前请检查 valid() / statusDescription()。

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.

参数:

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.

参数:

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.

class InfieldCorrectionInput(detection_result: DetectionResult)

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

detection_result() → DetectionResult

Get the contained DetectionResult.

返回:

A DetectionResult instance

status() → str

Get a the status of this input object.

Mostly used to figure out why valid() is False.

返回:

A enum describing the status.

status_description() → str

Get a string describing the status of this input object.

Mostly used to figure out why valid() is False.

返回:

A human-readable string describing the status.

valid() → bool

Check if this object is valid for use with in-field correction.

返回:

True if InfieldCorrectionInput is valid

verifyCamera

根据单次测量验证当前的尺寸正确度。如果输入无效，则抛出异常。

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

参数:

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.

参数:

input -- A single in-field correction measurement.

verify_camera(
infield_correction_input: InfieldCorrectionInput,
) → CameraVerification

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 any of the provided InfieldCorrectionInput have 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 compute_camera_correction in order to get an updated correction for the camera.

参数:

infield_correction_input -- An InfieldCorrectionInput instance.

返回:

A CameraVerification instance.

CameraVerification

验证结果：局部尺寸正确度误差以及测量时的位置。

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.

返回:

Estimated local dimension trueness error

PointXYZ position() const

Get the location at which the measurement was made.

返回:

Location (XYZ) in the camera reference frame

std::string toString() const

Get string representation of the camera assessment.

返回:

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

class CameraVerification(impl)

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

local_dimension_trueness() → float

Get the estimated local dimension trueness.

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 in percent.

返回:

Estimated local dimension trueness.

position() → ndarray

Get the location at which the measurement was made.

返回:

Location (XYZ) in the camera reference frame.

computeCameraCorrection

根据在不同距离处采集的一组测量数据计算新的校正值。数据集越大、越多样，得到的校正值越可靠。

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

参数:

dataset -- A sequence of in-field correction measurements.

返回:

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.

参数:

dataset -- A sequence of in-field correction measurements.

返回:

A new correction that may be written to the camera.

compute_camera_correction(
dataset: list[InfieldCorrectionInput],
) → CameraCorrection

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.

参数:

dataset -- A list of InfieldCorrectionInput instances.

返回:

A CameraCorrection instance.

CameraCorrection

可写入相机的计算校正值。通过 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 trueness 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.

返回:

An accuracy estimate

std::string toString() const

Get string representation of the camera correction.

返回:

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

class CameraCorrection(impl)

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

accuracy_estimate() → AccuracyEstimate

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

返回:

An AccuracyEstimate instance.

AccuracyEstimate

若将该校正值写入相机，在整个工作范围（zMin() 到 zMax()）内预期可达到的尺寸正确度。

class AccuracyEstimate

A dimension trueness estimate for a specific working volume.

Public Functions

float dimensionAccuracy() const

The estimated dimension trueness 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 trueness close to where the original data was captured is likely much better than what is implied by this number. This number is rather a trueness estimate for the entire extrapolated working volume.

返回:

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)

返回:

Minimum z-value of working volume in millimeters

float zMax() const

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

返回:

Maximum z-value of working volume in millimeters

std::string toString() const

Get string representation of the accuracy estimate.

返回:

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

class AccuracyEstimate(impl)

A dimension accuracy estimate for a specific working volume.

dimension_accuracy() → float

Get the estimated dimension accuracy 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.

返回:

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

z_max() → float

Get the range of validity of the accuracy estimate (upper end).

返回:

Maximum z-value of working volume in millimeters.

z_min() → float

Get the range of validity of the accuracy estimate (lower end).

返回:

Minimum z-value of working volume in millimeters.

writeCameraCorrection / resetCameraCorrection / hasCameraCorrection / cameraCorrectionTimestamp

管理保存在相机上的校正值：写入新的校正值、重置为出厂设置、检查是否存在校正值，以及读取其创建时间。写入的校正值会在每次捕获时自动应用，并在重新上电后依然保留。

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

参数:

  • camera -- The camera to write the correction to

  • cameraCorrection -- The camera correction to write

void resetCameraCorrection(Camera &camera)

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

参数:

camera -- The camera to reset

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

参数:

camera -- The camera to check

返回:

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

std::chrono::time_point<std::chrono::system_clock> 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).

参数:

camera -- The camera to check

返回:

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.

参数:

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

参数:

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.

参数:

camera -- The camera to check

返回:

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

参数:

camera -- The camera to check

返回:

A UTC timestamp indicating when the correction was created

write_camera_correction(
camera: Camera,
camera_correction: CameraCorrection,
) → None

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.

参数:

  • camera -- The Camera to write the correction to.

  • camera_correction -- The CameraCorrection instance to write to the camera.

reset_camera_correction(camera: Camera) → None

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

参数:

camera -- The Camera to reset.

has_camera_correction(camera: Camera) → bool

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

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

参数:

camera -- The Camera to check.

返回:

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

camera_correction_timestamp(camera: Camera)

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

参数:

camera -- The Camera to check.

返回:

A UTC timestamp indicating when the correction was created.

InfieldCorrectionDetectionStatus

描述 InfieldCorrectionInput 有效性的枚举（例如 ok、detectionFailed、invalidAlignment）。

enum class InfieldCorrectionDetectionStatus

Values:

enumerator ok
enumerator detectionFailed
enumerator invalidAlignment

请参见 C# API 参考 中的 Zivid::NET::Calibration::InfieldCorrectionDetectionStatus。

zivid.calibration.InfieldCorrectionInput.status_description() 会报告状态——参见 Infield Correction（现场标定）。

另请参见