evaluate

R2026b

Evaluate merit function

Since R2026b

collapse all in page

    Syntax

    score = evaluate(meritFcn,opsys)
    [score,rawMetricValues] = evaluate(meritFcn,opsys)

    Description

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

    score = evaluate(meritFcn,opsys) evaluates the merit function meritFcn for the optical system opsys, and returns the combined weighted RMS score.

    [score,rawMetricValues] = evaluate(meritFcn,opsys) also returns the raw metric values for each individual metric in the merit function.

    example

    Examples

    collapse all

    This example uses:

    Open Live Script

    Import an optical system into the workspace.

    opsys = zmximport("PhotographicLens.zmx");

    Create an empty optical merit function.

    meritFcn = opticalMeritFunction;

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

    meritFcn = addCustomMetric(meritFcn,@maxDistortionMetric,Target=2.0,Name="Max Distortion (%)")
    meritFcn = 
  opticalMeritFunction with properties:

         Metrics: [1×1 optics.metric.CustomMetric]
         Weights: 1
    MetricsTable: [1×3 table]

    Evaluate the merit function for the optical system.

    [score,rawMetricValues] = evaluate(meritFcn,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");

    Create an empty optical merit function.

    meritFcn = opticalMeritFunction;

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

    meritFcn = addCustomMetric(meritFcn,@chromaticMetric,Target=[0.001 0.005],Name="Lateral Chromatic Aberration")
    meritFcn = 
  opticalMeritFunction with properties:

         Metrics: [1×1 optics.metric.CustomMetric]
         Weights: 1
    MetricsTable: [1×3 table]

    Evaluate the merit function for the optical system.

    [score,rawMetricValues] = evaluate(meritFcn,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 chromatic aberration)
    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

    Merit function to evaluate, specified as an opticalMeritFunction object.

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

    Output Arguments

    collapse all

    Combined merit score, returned as a nonnegative scalar. The function computes the residual scores relative to the target values specified for each metric. The combined merit score is the mean of the absolute residual scores weighted by the square roots of the weights.

    Raw metric values, returned as a 1-by-n numeric vector, where n is the number of metrics in the merit function. Each element contains the raw evaluation result for the corresponding metric.

    Version History

    Introduced in R2026b

    See Also

    |