// 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.autoflip;

// Focus point location (normalized w.r.t. frame_width and frame_height, i.e.
// specified in the domain [0, 1] x [0, 1]).

// For TYPE_INCLUDE:
// During retargeting and stabilization focus points introduce constraints
// that will try to keep the normalized location in the rectangle
// frame_size - normalized bounds.
// For this soft constraints are used, therefore the weight specifies
// how "important" the focus point is (higher is better).
// In particular for each point p the retargeter introduces two pairs of
// constraints of the form:
//           x - slack < width - right
//    and    x + slack > 0 + left,        with slack > 0
//  where the weight specifies the importance of the slack.
//
// For TYPE_EXCLUDE_*:
// Similar to above, but constraints are introduced to keep
// the point to the left of the left bound OR the right of the right bound.
// In particular:
//          x - slack < left OR
//          x + slack >= right
//  Similar to above, the weight specifies the importance of the slack.
//
// Note: Choosing a too high weight can lead to
// jerkiness as the stabilization essentially starts tracking the focus point.
message FocusPoint {
  // Normalized location of the point (within domain [0, 1] x [0, 1].
  optional float norm_point_x = 1 [default = 0.0];
  optional float norm_point_y = 2 [default = 0.0];

  enum FocusPointType {
    TYPE_INCLUDE = 1;
    TYPE_EXCLUDE_LEFT = 2;
    TYPE_EXCLUDE_RIGHT = 3;
  }

  // Focus point type. By default we try to frame the focus point within
  // the bounding box specified by left, bottom, right, top. Alternatively, one
  // can choose to exclude the point. For details, see discussion above.
  optional FocusPointType type = 11 [default = TYPE_INCLUDE];

  // Bounds are specified in normalized coordinates [0, 1], FROM the specified
  // border. Opposing bounds (e.g. left and right) may not add to values
  // larger than 1.
  // Default bounds center focus point within centering third of the frame.
  optional float left = 3 [default = 0.3];
  optional float bottom = 4 [default = 0.3];
  optional float right = 9 [default = 0.3];
  optional float top = 10 [default = 0.3];

  optional float weight = 5 [default = 15];

  extensions 20000 to max;
}

// Aggregates FocusPoint's for a frame.
message FocusPointFrame {
  repeated FocusPoint point = 1;

  extensions 20000 to max;
}