Performing a Calibration

In order to perform some measurements, or to improve the accuracy of others, instruments need to be calibrated. This guide describes the process required to perform an OSL calibration.

Overview

At a high level, an OSL calibration flow has four steps:

1. Configure a trace whose configuration result defines the required calibration.
2. Read the returned OslCalibration.
3. Configure that calibration with configureCalibration(calibration:).
4. Run the calibration and execute each enabled step.

The main APIs involved are configureCalibration(calibration:), runCalibration(), and runCalibrationStep(stepId:).

Start from a trace configuration

Applications do not always need to build an OslCalibration by hand. A trace configuration result can define the required calibration for the requested trace.

Read the required OSL calibration

Once the trace is configured, read the concrete trace configuration result and extract its calibration:

C#

var traceConfiguration = (CaaReturnLossFrequencyTraceConfigurationResult)
    testConfigurationResult.TraceConfigurationResults.First();
var calibration = (OslCalibration)traceConfiguration.Calibration;

Kotlin

val traceConfiguration = testConfigurationResult.traceConfigurationResults
    .filterIsInstance<CaaReturnLossFrequencyTraceConfigurationResult>()
    .first()
val calibration = traceConfiguration.calibration

Swift

let calibration = testConfigurationResult.traceConfigurationResults.first?
  .caaReturnLossFrequencyTraceConfigurationResult?
  .calibration?

This is the key step: the trace configuration result defines the OSL calibration required for the requested trace.

Configure the OSL calibration

Pass the returned calibration into configureCalibration(calibration:):

C#

var calibrationConfigurationResult = (OslCalibrationConfigurationResult)
    unify.ConfigureCalibration(calibration);

Kotlin

val calibrationConfigurationResult =
    unify.configureCalibration(calibration) as OslCalibrationConfigurationResult

Swift

let calibrationConfigurationResult = try unify.configureCalibration(
    calibration: .oslCalibration(calibration)
)

Run the calibration

Once configuration succeeds, start runCalibration() and observe the step list it emits:

C#

await foreach (var state in unify.RunCalibration())
{
    if (state is OslCalibrationState oslState)
    {
        foreach (var step in oslState.Steps)
        {
            Console.WriteLine($"{step.Name}: enabled={step.Enabled} complete={step.Complete}");
        }
    }
}

Kotlin

unify.runCalibration().collect { state ->
    val oslState = state as? OslCalibrationState
    if (oslState != null) {
        oslState.steps.forEach { step ->
            println("${step.name}: enabled=${step.enabled} complete=${step.complete}")
        }
    }
}

Swift

for try await state in unify.runCalibration() {
  if let oslState = state.oslCalibrationState {
    for step in oslState.steps {
        print("\(step.name): enabled=\(step.enabled) complete=\(step.complete)")
    }
  }
}

Each CalibrationStep includes:

• id, which you pass to runCalibrationStep(stepId:)
• name, which you can show in your UI
• instruction, which may contain Markdown
• enabled and complete, which tell you what the user can do next

Execute each calibration step

When a step becomes enabled, present its instruction to the user, wait until they are ready, and then run that step:

C#

var nextStep = oslState.Steps.FirstOrDefault(step => step.Enabled && !step.Complete);
if (nextStep is not null)
{
    Console.WriteLine(nextStep.Instruction);
    await foreach (var progress in unify.RunCalibrationStep(nextStep.Id))
    {
        if (progress < 0)
        {
            Console.WriteLine("Step progress: indeterminate");
        }
        else
        {
            Console.WriteLine($"Step progress: {(int)Math.Round(progress * 100)}%");
        }
    }
}

Kotlin

val nextStep = oslState.steps.firstOrNull { it.enabled && !it.complete }
if (nextStep != null) {
    println(nextStep.instruction)
    unify.runCalibrationStep(nextStep.id).collect { progress ->
        if (progress < 0) {
            println("Step progress: indeterminate")
        } else {
            println("Step progress: ${(progress * 100).toInt()}%")
        }
    }
}

Swift

if let nextStep = oslState.steps.first(where: { $0.enabled && !$0.complete }) {
    print(nextStep.instruction)
    for try await progress in unify.runCalibrationStep(stepId: nextStep.id) {
        print("Step progress: \(Int(progress * 100))%")
    }
}

Applications usually present the step instruction to the user, wait for them to place the correct calibration standard, then trigger the step run. After a step completes, keep listening to runCalibration() for the updated calibration state and the next enabled step.

Repeat this process until every step reports complete == true.