evaluateMetric

R2026b

Evaluate metric function

Since R2026b

collapse all in page

    Syntax

    score = evaluateMetric(metric,opsys)
    [score,rawMetricValue] = evaluateMetric(metric,opsys)

    Description

    Add-On Required: This feature requires the Optical Design and Simulation Library for Image Processing Toolbox add-on.

    score = evaluateMetric(metric,opsys) evaluates the metric metric for the optical system opsys, and returns the normalized residual score.

    [score,rawMetricValue] = evaluateMetric(metric,opsys) also returns the raw metric value. For a spot RMS metric, this is the weighted average spot RMS across the specified wavelengths and field points.

    example

    Examples

    collapse all

    This example uses:

    Open Live Script

    Import an optical system into the workspace.

    opsys = zmximport("PhotographicLens.zmx");

    Define a custom metric function that returns only the residual score. The custom function maxDistortionMetric is defined at the end of this example.

    metric = optics.metric.CustomMetric(@maxDistortionMetric,Target=2.0,Name="Max Distortion (%)")
    metric = 
  CustomMetric with properties:

    CustomFunction: @maxDistortionMetric
     CustomFcnArgs: {}
              Name: "Max Distortion (%)"
            Target: [2 2]

    Evaluate the metric for the optical system.

    [score,rawMetricValues] = evaluateMetric(metric,opsys)
    score = 
1.8706

    rawMetricValues = 
1.8706

    Custom Function

    The maxDistortionMetric custom function measures the strongest lens distortion across the field and computes how far it is from the desired target. If the target value is 0, the function returns the greatest distortion magnitude. Otherwise, it returns a normalized nonnegative score indicating how much that distortion exceeds the target.

    function score = maxDistortionMetric(opsys,target)
    distResult = lensDistortion(opsys);
    maxDist = max(abs(distResult.Distortion),[],"all");
    if target(1) == 0
        score = maxDist;
    else
        score = max(0,(maxDist-target(1))/target(1));
    end
end

    This example uses:

    Open Live Script

    Import an optical system into the workspace.

    opsys = zmximport("PhotographicLens.zmx");

    Define a custom metric function that returns the residual and raw scores. The custom function chromaticMetric is defined at the end of this example.

    metric = optics.metric.CustomMetric(@chromaticMetric,Target=[0.001 0.005],Name="Lateral Chromatic Aberration")
    metric = 
  CustomMetric with properties:

    CustomFunction: @chromaticMetric
     CustomFcnArgs: {}
              Name: "Lateral Chromatic Aberration"
            Target: [1.0000e-03 0.0050]

    Evaluate the metric for the optical system.

    [score,rawMetricValues] = evaluateMetric(metric,opsys)
    score = 
1.3402

    rawMetricValues = 
0.0117

    Custom Function

    The chromaticMetric custom function measures the strongest lateral chromatic aberration across the field, and penalizes deviations outside a desired limit or range. The function computes the maximum lateral chromatic aberration of the optical system as the raw metric value, and compares this value to a target range to compute the residual score. If the target is a single value, it returns a normalized score of how much the raw metric exceeds that value (0, if within the limit). If the target is a range, the score is 0 if the metric lies within the range. Otherwise, the function returns a normalized score of how far the metric is from the nearest boundary.

    function [residualScore, metricValue] = chromaticMetric(opsys,target)
    caResult = chromaticAberration(opsys);
    % metricValue: the physically meaningful quantity (lateral CA)
    metricValue = max(abs(caResult.Lateral.Aberration),[],"all");
    % residualScore: unitless penalty relative to target
    if target(1)==target(2)
        if target(1) == 0
            residualScore = metricValue;
        else
            residualScore = max(0,(metricValue-target(1))/target(1));
        end
    else
        if metricValue >= target(1) && metricValue <= target(2)
            residualScore = 0;
        else
            diffs = abs(target - metricValue);
            [~,idx] = min(diffs);
            residualScore = abs(metricValue-target(idx))/target(idx);
        end
    end
end

    Input Arguments

    collapse all

    Metric to evaluate, specified as one of these metric objects.

    Optical system for which to evaluate the metric, specified as an opticalSystem object.

    Output Arguments

    collapse all

    Normalized residual score, returned as a nonnegative scalar computed relative to the target value specified for the metric.

    Raw metric value, returned as a scalar. For a spot RMS metric, this is the weighted average RMS spot size across the specified wavelengths and field points.

    Version History

    Introduced in R2026b

    See Also

    |