// Copyright 2020 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Datatypes and interfaces of handwriting recognition API.

// NOTE: This mojom exists in two places and must be kept in sync:
//       Chromium:  //chromeos/services/machine_learning/public/mojom/
//       Chrome OS: src/platform2/ml/mojom/
// Example: A backwards-compatible mojom change (and corresponding
// implementation change) can be made in Chrome OS first, then replicated to the
// client (Chromium) later.

module chromeos.machine_learning.mojom;

import "ml/mojom/time.mojom";

// A single point in an ink stroke.
struct InkPoint {
  // (x, y) coordinates of the point. The upper-left corner of the writing area
  // is (0, 0). The positive x-axis points to the right. The positive y-axis
  // points down.
  float x;
  float y;
  // Optional TimeDelta from the point was captured relative to the beginning of
  // the ink. So first point of a request should have t=0.
  mojo_base.mojom.TimeDelta? t;
};

// A single ink stroke.
struct InkStroke {
  // The set of points representing the stroke.
  array<InkPoint> points;
};

// The writing guide shown to the user during input.
struct WritingGuide {
   // Size of the writing area. The writing area must have (0, 0) at the top
   // left.
   // width is the max value of x-axis (to the right) and height is the max
   // value of y-axis (to the bottom).
   float width;
   float height;
};

// Options that will influence the recognition output.
struct RecognitionContext {
  // The writing guide shown to the user when the ink was captured.
  WritingGuide? writing_guide;
  // The context before the written text.
  string? pre_context;
};

// Defines a handwriting recognition query.
struct HandwritingRecognitionQuery {
  // The set of ink strokes to be recognized.
  array<InkStroke> ink;
  // The optional context in which the ink was generated.
  RecognitionContext? context;
  // Maximum number of results to be returned.
  uint32 max_num_results;
  // If true, returns the segmentation results. This will make the response
  // struct much larger.
  bool return_segmentation;
};

// Represents a contiguous range of ink. Start and end strokes / points are
// inclusive.
struct HandwritingRecognizerInkRange {
  // Zero-based start- and end-stroke indices in the ink strokes.
  uint32 start_stroke;
  uint32 end_stroke;
  // Zero-based start- and end-point indices with the start / end strokes.
  uint32 start_point;
  uint32 end_point;
};

// A segment defines the substrokes that are associated with a substring of the
// recognized text.
struct HandwritingRecognizerSegment {
  // The substring of the recognized text represented by this segment.
  string sublabel;
  // The ink ranges represented by this segment.
  array<HandwritingRecognizerInkRange> ink_ranges;
};

// The ink segmentation information.
struct HandwritingRecognizerSegmentation {
  // The grouping of the cut strokes into characters.
  array<HandwritingRecognizerSegment> segments;
};

// One possible candidate from the handwriting recognition.
struct HandwritingRecognizerCandidate {
  // The recognized text.
  string text;
  // Scores will most often correspond to -log(p(c)) or a scaling thereof, so
  // lower scores represent higher confidence.
  float score;
  // The stroke segmentation that was used to generate the result.
  HandwritingRecognizerSegmentation? segmentation;
};

// The handwriting recognition response.
struct HandwritingRecognizerResult {
  // Status of the recognition response.
  enum Status {
    OK = 0,
    ERROR = 1,
  };
  Status status;

  // The recognition candidates with additional alternatives, sorted by lower
  // score first (lower score present higher confidence).
  array<HandwritingRecognizerCandidate> candidates;
};

// The mojom interface for performing the recognition of handwritten text.
interface HandwritingRecognizer {
  // Performs handwriting recognition on a set of ink strokes, and returns a set
  // of alternative recognition results.
  Recognize(HandwritingRecognitionQuery query) =>
      (HandwritingRecognizerResult result);
};