// Copyright 2019 The MediaPipe Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package mediapipe;

import "mediapipe/util/tracking/camera_motion.proto";
import "mediapipe/util/tracking/frame_selection_solution_evaluator.proto";
import "mediapipe/util/tracking/region_flow.proto";

// Stores selected timestamps and corresponding frame index.
message FrameSelectionTimestamp {
  optional int64 timestamp = 1;  // Timestamp of the selected frame.

  // Frame index of the selected frame in the initial video stream.  If this
  // timestamp was manufactured, this will be the index of the initial frame.
  optional int32 frame_idx = 2;

  // If this timestamp was manufactured, the timestamp of the original frame.
  optional int64 processed_from_timestamp = 3 [default = -1];
}

// Stores the result of the frame selection, with composited features.
// Next index: 6
message FrameSelectionResult {
  optional int64 timestamp = 1;  // Timestamp of the selected frame.

  // Frame index of the selected frame in the initial video stream.  If this
  // timestamp was manufactured, this will be the index of the initial frame.
  optional int32 frame_idx = 2;

  // CameraMotion from selected item to previous selected item.
  optional CameraMotion camera_motion = 3;

  // Features from selected item to previous selected item.
  optional RegionFlowFeatureList features = 4;

  // If this FrameSelectionResult was the result of processing a previous one,
  // the timestamp of the original frame.
  optional int64 processed_from_timestamp = 5 [default = -1];
}

// Next index: 7
message FrameSelectionCriterion {
  // Interval at which frames should be sampled; set to zero if sampling should
  // not be enforced (i.e. selection is performed w.r.t. other criteria).
  optional int32 sampling_rate = 1 [default = 0];

  // Bandwidth used during dynamic programming. The larger the bandwidth the
  // more accurate the result w.r.t. the specified sampling rate. Smaller
  // bandwidth's bias the solution suboptimally to center around the mean
  // frame numbers of the sampling rate.
  // If in (0, 1), assumed to specify fraction of total number of input frames,
  // otherwise must be an integer.
  optional float bandwidth_frames = 2 [default = 50];

  // Search radius for dynamic programming (how many frames you are allowed to
  // search around the previous frame).
  optional int32 search_radius_frames = 3 [default = 1];

  // Allows one to specify custom solution selection criteria (i.e. different
  // way to choose the best row of the computed cost matrix).
  optional FrameSelectionSolutionEvaluatorType solution_evaluator = 4;

  // Outputs a fixed number of frames and automatically sets the appropriate
  // sampling rate. Set to 0 by default (i.e. not enabled).
  optional int32 max_output_frames = 5 [default = 0];
}

// Options for computing frame selection.
// TODO: Support multiple criteria if required. Currently uses only the
// first one.
message FrameSelectionOptions {
  repeated FrameSelectionCriterion criterion = 1;

  // FrameSelection buffers incoming CameraMotions for specified chunk size
  // and creates cost matrices upon reaching the limit.
  // TODO: Implement if necessary (currently nothing is cleared upon
  // reaching the limit).
  optional int32 chunk_size = 2 [default = 100];
}