// These protos contain the calibration parameters necessary for transforming
// a model's original detection scores or logits. The parameters result from
// fitting a calibration function on the model's outputs.

syntax = "proto2";

package object_detection.protos;

// Message wrapper for various calibration configurations.
message CalibrationConfig {
  oneof calibrator {
    // Class-agnostic calibration via linear interpolation (usually output from
    // isotonic regression).
    FunctionApproximation function_approximation = 1;

    // Per-class calibration via linear interpolation.
    ClassIdFunctionApproximations class_id_function_approximations = 2;

    // Class-agnostic sigmoid calibration.
    SigmoidCalibration sigmoid_calibration = 3;

    // Per-class sigmoid calibration.
    ClassIdSigmoidCalibrations class_id_sigmoid_calibrations = 4;

    // Temperature scaling calibration.
    TemperatureScalingCalibration temperature_scaling_calibration = 5;
  }
}

// Message for class-agnostic domain/range mapping for function
// approximations.
message FunctionApproximation {
  // Message mapping class labels to indices
  optional XYPairs x_y_pairs = 1;
}

// Message for class-specific domain/range mapping for function
// approximations.
message ClassIdFunctionApproximations {
  // Message mapping class ids to indices.
  map<int32, XYPairs> class_id_xy_pairs_map = 1;
}

// Message for class-agnostic Sigmoid Calibration.
message SigmoidCalibration {
  // Message mapping class index to Sigmoid Parameters
  optional SigmoidParameters sigmoid_parameters = 1;
}

// Message for class-specific Sigmoid Calibration.
message ClassIdSigmoidCalibrations {
  // Message mapping class index to Sigmoid Parameters.
  map<int32, SigmoidParameters> class_id_sigmoid_parameters_map = 1;
}

// Message for Temperature Scaling Calibration.
message TemperatureScalingCalibration {
  optional float scaler = 1;
}

// Description of data used to fit the calibration model. CLASS_SPECIFIC
// indicates that the calibration parameters are derived from detections
// pertaining to a single class. ALL_CLASSES indicates that parameters were
// obtained by fitting a model on detections from all classes (including the
// background class).
enum TrainingDataType {
  DATA_TYPE_UNKNOWN = 0;
  ALL_CLASSES = 1;
  CLASS_SPECIFIC = 2;
}

// Message to store a domain/range pair for function to be approximated.
message XYPairs {
  message XYPair {
    optional float x = 1;
    optional float y = 2;
  }

  // Sequence of x/y pairs for function approximation.
  repeated XYPair x_y_pair = 1;

  // Description of data used to fit the calibration model.
  optional TrainingDataType training_data_type = 2;
}

// Message defining parameters for sigmoid calibration.
message SigmoidParameters {
  optional float a = 1 [default = -1.0];
  optional float b = 2 [default = 0.0];
}