addSpot

R2026b

Add spot RMS metric to merit function

Since R2026b

collapse all in page

    Syntax

    meritFcn = addSpot(meritFcn)
    meritFcn = addSpot(meritFcn,Name=Value)

    Description

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

    meritFcn = addSpot(meritFcn) adds a spot RMS metric to the merit function meritFcn with default settings. The metric evaluates the weighted average RMS spot size across all wavelengths and field points.

    example

    meritFcn = addSpot(meritFcn,Name=Value) specifies additional options using one or more name-value arguments. For example, Target=0.01 sets an upper bound on the acceptable spot RMS.

    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 spot RMS metric to the merit function.

    meritFcn = addSpot(meritFcn);

    Add a peak‑to‑valley wavefront error metric to the merit function.

    meritFcn = addWavefrontPeakToValley(meritFcn);

    Add an RMS wavefront error metric with a target RMS wavefront range of 0 to 0.2 waves to the merit function.

    meritFcn = addWavefrontRMS(meritFcn,Target=[0 0.1]);

    Specify weights for the metrics in the merit function.

    meritFcn.Weights = [3 7 5];

    Inspect the merit function.

    meritFcn
    meritFcn = 
  opticalMeritFunction with properties:

         Metrics: [1×3 optics.metric.Metric]
         Weights: [3 7 5]
    MetricsTable: [3×3 table]


    meritFcn.Metrics
    ans = 1×3 heterogeneous Metric (SpotRMS, WavefrontPeakToValley, WavefrontRMS) array with properties:
    Name
    Target


    meritFcn.Weights
    ans = 1×3

     3     7     5


    meritFcn.MetricsTable
    ans = 3×3 table
                    Name                Target     Weight
         __________________________    ________    ______

    1    "Spot"                        0      0      3   
    2    "Wavefront Peak To Valley"    0      0      7   
    3    "Wavefront RMS"               0    0.1      5

    Evaluate the merit function for the optical system.

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

    rawMetricValues = 1×3

    0.0076    0.7206    0.1410

    Input Arguments

    collapse all

    Merit function to which to add the spot RMS metric, specified as an opticalMeritFunction object.

    Name-Value Arguments

    collapse all

    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: addSpot(meritFcn,Target=0.01,Weight=2) specifies an upper bound of 0.01 for the metric value and a weight of 2 for the metric in the overall merit function.

    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 upper bound. If you specify this argument as a 1-by-2 vector, the object considers the first element the lower bound and the second element the upper bound. When the target metric value is [0 0], the residual score and the raw metric value are the same.

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

    Metric weight in the overall merit function, specified as a positive scalar. The opticalMeritFunction object normalizes all weights to sum to 1 when computing the combined merit score.

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

    Metric name, specified as a string scalar or character vector.

    Data Types: char | string

    Indices of the wavelengths to evaluate, specified as a vector of positive integers. By default, the metric evaluates all wavelengths defined in the optical system.

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

    Indices of the field points to evaluate, specified as a vector of positive integers. By default, the metric evaluates all field points defined in the optical system.

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

    Ray sampling grid, specified as a samplingGrid object.

    Output Arguments

    collapse all

    Updated merit function, returned as an opticalMeritFunction object with the spot RMS metric appended.

    Version History

    Introduced in R2026b

    See Also

    | |