// Copyright 2021 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 document scanner 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/
//       Note: Other repos downstream of Chromium might also use this mojom.
// Example: A backwards-compatible mojom change (and corresponding
// implementation change) can be made in Chrome OS first, then replicated to the
// clients (Chromium, other downstream repos) later.
// Use //chromeos/services/machine_learning/public/mojom/roll_mojoms.sh to help
// replicate Chrome OS-side changes over to Chromium.

module chromeos.machine_learning.mojom;

import "ml/mojom/geometry.mojom";
import "ml/mojom/shared_memory.mojom";

// Status of the document scanner response.
[Stable, Extensible]
enum DocumentScannerResultStatus {
  OK = 0,
  ERROR = 1,
};

// The corner detection response.
// Next min field ID: 2
[Stable]
struct DetectCornersResult {
  // Status of the result. Even when there is no corners detected, the detection
  // can still be considered successful if there is no error occurs.
  DocumentScannerResultStatus status@0;

  // Detected document corners.
  array<gfx.mojom.PointF> corners@1;
};

// The post processing response.
// Next min field ID: 2
[Stable]
struct DoPostProcessingResult {
  // Status of the result.
  DocumentScannerResultStatus status@0;

  // Image data after processing. Will be in JPG format.
  array<uint8> processed_jpeg_image@1;
};

// The mojom interface for performing document scanning.
// Next ordinal: 3
[Stable]
interface DocumentScanner {
  // Detect document corners for given `nv12_image` which is in 256x256 size.
  DetectCornersFromNV12Image@0(
      mojo_base.mojom.ReadOnlySharedMemoryRegion nv12_image)
      => (DetectCornersResult result);

  // Detect document corners for given `jpeg_image`.
  DetectCornersFromJPEGImage@1(
      mojo_base.mojom.ReadOnlySharedMemoryRegion jpeg_image)
      => (DetectCornersResult result);

  // Do post processing such as rectification for the document region, contrast
  // enhancement on the given `jpeg_image` according to document `corners`.
  DoPostProcessing@2(mojo_base.mojom.ReadOnlySharedMemoryRegion jpeg_image,
                     array<gfx.mojom.PointF> corners)
      => (DoPostProcessingResult result);
};