CustomMetric

R2026b

Custom metric function

Since R2026b

Description

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

A CustomMetric object defines a custom metric using a custom function for use in tolerance and sensitivity analysis.

Creation

Syntax

metric = optics.metric.CustomMetric(fcnHandle)

metric = optics.metric.CustomMetric(fcnHandle,arg1,...,argN,Name=Value)

metric = optics.metric.CustomMetric(___,Name=Value)

Description

metric = optics.metric.CustomMetric(fcnHandle) creates a custom metric defined by the function handle fcnHandle.

metric = optics.metric.CustomMetric(fcnHandle,arg1,...,argN,Name=Value) passes the additional input arguments arg1,...,argN to the custom metric function.

metric = optics.metric.CustomMetric(___,Name=Value) specifies additional options using name-value arguments.

Input Arguments

fcnHandle — Custom metric function handle

function handle

Custom metric function, specified as a function handle. The function must accept at least two input arguments: an opticalSystem object and a target value. The function can return one or two outputs. With one output, the value serves as both the residual score and raw metric. With two outputs, the first is the residual score and the second is the raw metric value.

Data Types: function_handle

arg1,...,argN — Additional input arguments for custom metric function

depends on function

Additional input arguments for the custom metric function, specified as a comma-separated list. The types of the inputs depend on the function fcnHandle. These arguments are inputs to fcnHandle after the optical system and target arguments.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: optics.metric.CustomMetric(@myMetric,Target=0.5) specifies a target metric value of 0.5.

Target — Target metric value

[0 0] (default) | nonnegative scalar | 1-by-2 nonnegative vector

Target metric value, specified as a nonnegative scalar or a 1-by-2 nonnegative vector. If you specify this argument as a scalar, the object considers the target metric as the lower or upper bound, depending on the function. If you specify this argument as a 1-by-2 vector, the object considers the target values as the lower and upper bounds.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Name — Metric name

"Custom" (default) | string scalar | character vector

Metric name, specified as a string scalar or character vector. This argument sets the Name property.

Properties

CustomFunction — Custom metric function

Read-only: function handle

This property is read-only.

Custom metric function, represented as a function handle.

CustomFcnArgs — Custom function arguments

Read-only: cell array

This property is read-only.

Custom function arguments, represented as a cell array containing the additional arguments specified during object creation.

Name — Metric name

"Custom" (default) | string scalar

Metric name, represented as a string scalar.

Target — Target metric value

[0 0] (default) | 1-by-2 nonnegative vector

Target metric value, represented as a 1-by-2 nonnegative vector. If the target metric value is only a single bound b, the object represents this property as [b b]. If the target metric value is a range with lower bound lb and upper bound ub, the object represents this property as [lb ub].

Object Functions

evaluateMetric

Evaluate metric function

Examples

Evaluate Custom Metric with Residual Score

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

Evaluate Custom Metric with Residual and Raw Scores

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

Version History

Introduced in R2026b