chromium/chromeos/services/machine_learning/public/mojom/heatmap_palm_rejection.mojom

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

// Next MinVersion: 4

// Datatypes and interfaces of heatmap palm rejection 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 "mojo/public/mojom/base/time.mojom";

// Enum indicates the result of LoadHeatmapPalmRejection in mlservice.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
// Keep this enum in sync with
// MachineLearningServiceLoadHeatmapPalmRejectionResult in
// tools/metrics/histograms/metadata/cros_ml/enums.xml.
[Stable, Extensible]
enum LoadHeatmapPalmRejectionResult {
  // The service was loaded successfully.
  OK = 0,
  // Failed with unknown reason.
  [Default] UNKNOWN_ERROR = 1,
  // Failed to load the TF model.
  LOAD_MODEL_ERROR = 2,
  // Failed to create the graph executor.
  CREATE_GRAPH_EXECUTOR_ERROR = 3,
  // Failed to open the hidraw device.
  OPEN_DEVICE_ERROR = 4,
  // Failed to create a watcher for the hidraw device.
  [MinVersion=2] WATCH_DEVICE_ERROR = 5,
  // The device does not support heatmap.
  [MinVersion=2] FEATURE_NOT_SUPPORTED_ERROR = 6,
};

// Configs to set up heatmap palm rejection service.
[Stable]
struct HeatmapPalmRejectionConfig {
  // The path to the heatmap palm rejection TF model on device.
  string tf_model_path;
  // The path to the touchscreen hidraw device.
  string heatmap_hidraw_device;
  // The index of the input node in TF model.
  uint32 input_node;
  // The index of the output node in TF model.
  uint32 output_node;
  // The threshold to decide whether the TF model result indicates a palm.
  [MinVersion=1]
  double palm_threshold;
  // Optional crop that should be applied to the heatmap when provided.
  [MinVersion=3]
  CropHeatmap? crop_heatmap;
};

// The result of processing a frame of heatmap data.
[Stable]
struct HeatmapProcessedEvent {
  // The timestamp of the heatmap event.
  mojo_base.mojom.Time timestamp;
  // Whether there is a palm on the screen according to the TF model prediction.
  bool is_palm;
};

// The client of heatmap palm rejection service, which will receive the palm
// rejection results.
[Stable]
interface HeatmapPalmRejectionClient {
  // This is how the client receives heatmap palm rejection results;
  OnHeatmapProcessedEvent@0(HeatmapProcessedEvent event);
};

// Crop configuration to be applied to the heatmap. Accepts any valid values
// however a value of zero is obviously a no-op. Additionally, values that crop
// beyond the width or height of the heatmap will be treated as no-op. These
// values are human provided configuration values based on observed heatmap
// dimensions and the expected input shape to the ML model.
[Stable]
struct CropHeatmap {
  // Number of rows of data to crop from the bottom.
  uint8 bottom_crop;
  // Number of columns of data to crop from the left.
  uint8 left_crop;
  // Number of columns of data to crop from the right.
  uint8 right_crop;
  // Number of rows of data to crop from the top.
  uint8 top_crop;
};