手写识别 API

1. 引言

• 本节为非规范性内容。*

手写输入是绘画。绘画捕获了能够数字化重现人类笔尖运动所需的信息。

本API旨在将操作系统的能力暴露给Web。我们预计手写识别能力会因操作系统而异，因此API旨在达成能够灵活集成操作系统特性的设计。

我们期望用户代理将Web API的数据结构（本规范中定义）转换为宿主操作系统可用的结构，并将Web API与操作系统API连接起来。

本API不试图定义在所有平台上行为一致的识别。

1.1. 术语定义

• 绘画（drawing）由多个笔画组成（如上图字母E包含三笔）。

• 笔画（stroke）表示一次在一段时间内连续的笔尖运动（例如从一次touchstart事件到对应的touchend事件）。其运动轨迹由一系列点（points）描述。

• 点（point）是时空中笔尖的观测记录。其记录了笔尖在书写表面上的时间戳和位置（例如touchmove事件）。

• 转写（transcription） 是表示绘画中书写文本的Unicode字符串（如字符串"WEB"）。

手写识别器（handwriting recognizer） 是一个接口（通常由外部应用或服务实现），它：

• 将绘画（drawing）作为输入

• 输出该绘画的若干转写（transcriptions）

• 可选地，输出每个转写的切分（segmentation）信息

是否为手写识别器由用户代理自行决定。

要转换（convert）与手写识别器适配的数据格式，用户代理应将本规范中的定义与手写识别器的等价概念对应。

手写识别器还可以输出额外信息帮助Web应用更好地处理手写内容（如删除手写中的某个字符）。

切分（Segmentation）用于将字素（用户感知的字符）与其组成的笔划和点进行映射。一个字素可能跨多个Unicode码点。

以手写文本 "int" 为例：

• 第1和第5笔组成字母"i"

• 第2笔组成字母"n"

• 第3和第4笔组成字母"t"

2. API惯用法

本规范中提及的任务源是手写识别任务源（handwriting recognition task source）。

当某个算法排入一个手写识别API任务 T时，用户代理必须使用全局对象的手写识别任务源将T排入当前realm记录的任务队列。

除非特别说明，通过算法步骤构造的JavaScript对象的realm应为当前realm记录。

3. 能力查询

能力查询接口允许Web应用查询实现相关的能力，从而决定是否使用该功能。

const modelConstraint = { languages: ['zh-CN', 'en'] };
const modelDesc = await navigator.queryHandwritingRecognizer(modelConstraint);

// \`modelDesc\` 描述了满足 \`modelConstraint\` 的手写识别器。
// 如果约束无法被满足，\`modelDesc\` 为null。
{
  textAlternatives: true,
  textSegmentation: true,
  hints: {
    alternatives: true,
    textContext: true,
    inputTypes: ['mouse', 'touch', 'stylus']
  }
}

[SecureContext]
partial interface Navigator {
  Promise<HandwritingRecognizerQueryResult?>
      queryHandwritingRecognizer(HandwritingModelConstraint constraint);
};

dictionary HandwritingModelConstraint {
  required sequence<DOMString> languages;
};

dictionary HandwritingRecognizerQueryResult {
  boolean textAlternatives;
  boolean textSegmentation;
  HandwritingHintsQueryResult hints;
};

dictionary HandwritingHintsQueryResult {
  sequence<HandwritingRecognitionType> recognitionType;
  sequence<HandwritingInputType> inputType;
  boolean textContext;
  boolean alternatives;
};

enum HandwritingRecognitionType{
  "text", "per-character"
};

enum HandwritingInputType {
  "mouse", "stylus", "touch"
};

3.1. queryHandwritingRecognizer(constraint)

该方法为Web应用提供了一种查询底层识别器能力并决定是否使用的方法：

• 如果约束可被满足，则返回满足约束的手写识别器描述，

• 如果约束无法被满足，则返回null

同一份HandwritingModelConstraint 可用于调用createHandwritingRecognizer(constraint) 去创建满足约束的HandwritingRecognizer。

3.2. HandwritingModelConstraint 属性

描述底层手写识别器（如后续要创建）的约束条件。

在createHandwritingRecognizer(constraint)中也用于创建手写识别器。

languages

用于描述识别器要识别的语言的一组[BCP47]语言标签。

如提供多个语言，识别器需支持全部才能满足约束。

用户代理应考虑每个语言标签所有可能的书写体系。例如，只能识别拉丁字母阿塞拜疆语（"az-Latn"）的识别器，不应用于"az"标签，因为阿塞拜疆语也可用西里尔字母（"az-Cyrl"）书写。

区分书写体系时，建议使用最具体的语言标签。例如，仅需支持拉丁字母阿塞拜疆语时用"az-Latn"。

部分识别器仅支持单语种。为提升互操作性，可为每种语言创建独立识别器。

3.3. HandwritingRecognizerQueryResult 属性

描述某手写识别器实现的固有特性。

textAlternatives

布尔型，表示实现是否返回多个备选转写候选而不是单一结果。

textSegmentation

布尔型，表示实现是否为每个转写返回分段信息。

hints

HandwritingHintsQueryResult 对象，描述在startDrawing()中可接受的提示。

3.3.1. HandwritingHintsQueryResult 属性

描述一组可选传入startDrawing()以提升准确率或性能的提示。

本处属性名称与startDrawing()方法中一致。

recognitionType

一组HandwritingRecognitionType 枚举，描述可能书写的文本类型。

提示不能保证转写结果符合指定类型。

"text"

普通书写语句中的自由文本，意味着图像为真实词语。例如用于日常语言句子的手写输入。

"per-character"

由独立且互无关联的字素组成的手写体（用户感知字符）。如序列号、注册码等。

inputType

一组HandwritingInputType 枚举，描述绘画是如何书写的。

"touch"

用手指绘制。

"stylus"

用手写笔绘制。

"mouse"

用鼠标光标绘画。

textContext

布尔值，表示是否接受textContext。textContext为展示给用户的文本或前置已识别文本的字符串。

alternatives

布尔值，表示是否允许设置返回备选转写的个数。用于限制getPrediction返回的最大备选数量。

4. 创建手写识别器

A HandwritingRecognizer 管理执行识别所需的资源。

const modelConstraint = { languages: ['en'] };

try {
  const recognizer = await navigator.createHandwritingRecognizer(modelConstraint);
  // Use \`recognizer\` to perform recognitions.
} catch (err) {
  // The provided model constraint can't be satisfied.
}

[SecureContext]
partial interface Navigator {
  Promise<HandwritingRecognizer>
      createHandwritingRecognizer(HandwritingModelConstraint constraint);
};

4.1. createHandwritingRecognizer(constraint) 方法

• 如果约束可被满足，且操作系统上有足够资源执行识别，则解析为一个 HandwritingRecognizer 对象。

• 否则，拒绝并返回错误。

用户代理可能会提示用户安装或下载手写模型。Web 应用不应假定此方法总是会很快返回。

5. 使用识别器

const drawingHints = { textContext: "Hello world." }
const drawing = recognizer.startDrawing(textContext)

// Do something with \`drawing\`.

// Frees resources associated with recognizer.
recognizer.finish()

5.1. HandwritingRecognizer 对象

[Exposed=Window, SecureContext]
interface HandwritingRecognizer {
  HandwritingDrawing startDrawing(optional HandwritingHints hints = {});

  undefined finish();
};

dictionary HandwritingHints {
  DOMString recognitionType = "text";
  DOMString inputType = "mouse";
  DOMString textContext;
  unsigned long alternatives = 3;
};

HandwritingRecognizer 有一个 active 标志，为布尔值。active 标志初始为 true， 在调用 finish() 方法时变为 false。

当识别器的 active 标志为 true 时，Web 应用可以为该识别器创建新的绘画并执行识别。

用户代理可以限制网站的active handwriting recognizer总数。

5.2. startDrawing(hints)

此方法创建一个 HandwritingDrawing 用于存储后续识别的绘画信息。

HandwritingDrawing 拥有一个 strokes，它是一个 list，包含若干 HandwritingStroke， 初始为空。

HandwritingDrawing 有一个 recognizer，用于存储创建此 HandwritingDrawing 的 HandwritingRecognizer 的引用。

5.3. finish()

此方法将 this 的 active 标志设为 false，释放已分配的handwriting recognizer资源，并使未来涉及 this 的相关操作失败。

用户代理应释放与handwriting recognizer相关的资源。

在调用 finish() 之后，对由 this 创建的 HandwritingDrawing 调用后续的 getPrediction() 将会失败。

6. 构建 HandwritingDrawing

HandwritingDrawing 管理关于绘画的上下文信息，并维护构成绘画的笔划和点。它代表一个 drawing。

用户代理可以将所有笔划和点存储在内存中，然后在调用 getPrediction() 时将它们转换为适合 handwriting recognizer 的格式。在这种情况下，HandwritingDrawing 和 HandwritingStroke 表现得像一个列表。

const handwritingStroke = new HandwritingStroke()

// Add points to a stroke.
handwritingStroke.addPoint({ x: 1, y: 2, t: 0});
handwritingStroke.addPoint({ x: 7, y: 6, t: 33});

// Retrieve points of this stroke.
// Returns a copy of all the points, modifying the returned points
// has no effect.
const points = handwritingStroke.getPoints();

[ { x: 1:, t:2, t: 0 }, { x: 7, y: 6, t: 33} ];

// Delete all points in a stroke.
handwritingStroke.clear();

// Add a stroke to the drawing.
drawing.addStroke(handwritingStroke);

// Get all strokes of the drawing.
// Returns a list of \`HandwritingStroke\` in the drawing. Web applications can
// modify the stroke. For example, calling HandwritingStroke.addPoint().
drawing.getStrokes();

[ HandwritingStroke, /* ... */ ]

// Delete a stroke from the drawing.
drawing.removeStroke(handwritingStroke);

// Delete all strokes from the drawing.
drawing.clear();

[Exposed=Window, SecureContext]
interface HandwritingDrawing {
  undefined addStroke(HandwritingStroke stroke);
  undefined removeStroke(HandwritingStroke stroke);
  undefined clear();
  sequence<HandwritingStroke> getStrokes();

  Promise<sequence<HandwritingPrediction>> getPrediction();
};

[SecureContext, Exposed=Window]
interface HandwritingStroke {
  constructor();
  undefined addPoint(HandwritingPoint point);
  sequence<HandwritingPoint> getPoints();
  undefined clear();
};

dictionary HandwritingPoint {
  required double x;
  required double y;

  // Optional. Number of milliseconds since a reference time point for a
  // drawing.
  DOMHighResTimeStamp t;
};

6.1. HandwritingStroke

HandwritingStroke 有一个 Points，它是一个 list，用于存储该笔划的 points。points 初始为空。

6.1.1. HandwritingStroke()

6.1.2. addPoint(point)

6.1.3. getPoints()

该方法返回该笔划的所有点。

深拷贝可以防止对内部点的修改，并支持变更跟踪。

对 getPoints() 返回值的修改不会影响此笔划本身。

6.1.4. clear()

该方法会移除当前笔划的所有点，使其变为空笔划。

6.2. HandwritingDrawing

6.2.1. addStroke(stroke)

6.2.2. removeStroke(stroke)

6.2.3. getStrokes()

该方法返回该绘画中的笔划列表。

6.2.4. clear()

7. 获取 HandwritingDrawing 的识别结果

// 获取该绘画笔划的识别结果。
const predictions = await drawing.getPrediction();

// \`predictions\` 是一个 \`HandwritingPrediction\` 列表，其属性
// 取决于手写识别器的能力，和 queryHandwritingRecognizer() 返回的模型描述保持一致。
//
// 例如，\`recognizer\` 支持 textSegmentation。
[
  {
    text: "hello",
    segmentationResult: [
      {
        grapheme: "h", beginIndex: "0", endIndex: "1",
        drawingSegments: [
          { strokeIndex: 1, beginPointIndex: 0, endPointIndex: 32 },
          { strokeIndex: 2 , beginPointIndex: 0, endPointIndex:: 40 },
        ]
      },
      {
        grapheme: "2", beginIndex: "1", endIndex: "2",
        drawingSegments: [
          { strokeIndex: 2 , beginPointIndex: 41, endPointIndex:: 130 },
        ]
      },
      // ...
    ]
  },
  {
    text: "he11o",
    segmentationResult: [ /* ... */ ]
  },
  // 最多返回 \`alternatives\` 个预测结果（如在 startDrawing() 里配置）。
];

7.1. getPrediction()

getPrediction() 方法返回 this 绘画的预测结果列表及其元数据。

预测结果按置信度高到低排序。如果不为空，第一个预测结果应为最有可能的结果。

如果手写识别器无法识别出任何内容，getPrediction() 应返回空列表。

用户代理可能会进行变更跟踪以及增量识别以提升性能。

7.2. HandwritingPrediction 属性

HandwritingPrediction 表示来自手写识别器的预测结果。

dictionary HandwritingPrediction {
  required DOMString text;
  sequence<HandwritingSegment> segmentationResult;
};

dictionary HandwritingSegment {
  required DOMString grapheme;
  required unsigned long beginIndex;
  required unsigned long endIndex;
  required sequence<HandwritingDrawingSegment> drawingSegments;
};

dictionary HandwritingDrawingSegment {
  required unsigned long strokeIndex;
  required unsigned long beginPointIndex;
  required unsigned long endPointIndex;
};

text

表示所绘内容转录的DOMString。

segmentationResult

一个HandwritingSegment列表， 将每个被识别的音位（用户感知的字符）映射到其组成的笔画与点。

如果手写识别器不支持文本分段， 则为null。

Web应用可以通过textSegmentation 检查该属性是否为null。

7.2.1. HandwritingSegment 属性

HandwritingSegment 描述从绘图分段出的单个音位。

grapheme

表示音位的DOMString。

beginIndex

该音位在text 中的起始索引。

endIndex

该音位在text 中的结束索引（下一个音位的起始点）。

drawingSegments

一个HandwritingDrawingSegment列表， 描述组成该音位的绘图部分。

用beginIndex 与endIndex 对text 进行切片，应当得到grapheme。

// Web 应用可使用 \`beginIndex\` 和 \`endIndex\` 对 \`text\` 进行切片。
// 例如，“घोषित”的 \`HandwritingPrediction\`：

const prediction = {
  // UTF-16 code points: \u0918 \u094b \u0937 \u093f \u0924
  // Graphemes: घो, षि, त
  text: "घोषित",
  segmentationResult: [
    { grapheme: "घो", beginIndex: "0", endIndex: "2" },
    { grapheme: "षि", beginIndex: "2", endIndex: "4" },
    { grapheme: "त", beginIndex: "4", endIndex: "5" },
  ]
}

// 以下均成立：
prediction.text.slice(0, 1) === "घो";
prediction.text.slice(2, 4) === "षि";
prediction.text.slice(4, 5) === "त";

// Web 应用可以通过 splice 删除第2个音位（षि）。
const withoutSecondGrapheme = (
  [...prediction.text]
    .splice(
      prediction.segmentationResult[1].beginIndex,
      prediction.segmentationResult[1].endIndex
    )
    .join('')
);
// => "घोत"

7.2.2. HandwritingDrawingSegment 属性

HandwritingDrawingSegment 描述HandwritingStroke 的一个连续片段。

属性基于HandwritingStroke 在HandwritingDrawing 调用getPrediction()时的内容。

strokeIndex

HandwritingDrawing中 HandwritingStroke 的索引。参见strokes。

beginIndex

该绘图片段的起始索引。

endIndex

该绘图片段的结束索引（下一个绘图片段的起始点）。

8. 隐私注意事项

指纹向量来源于两部分：特性检测和识别器实现。

所暴露的信息量（熵）取决于用户代理的实现。我们认为没有一种方案可适用于所有场景，建议用户代理根据自身用户情况决定是否需要隐私保护措施（例如权限提示）。

特性检测可能会暴露以下信息：

• 用户的语言选择（或已安装的手写识别模型）。这同样可以通过navigator.languages获取。

• 所用识别器实现，通过汇总支持的特征集合。这可能会被用来推断操作系统及其版本。

可通过以下方式缓解指纹收集：

• 隐私预算：若网站查询过于频繁，用户代理将拒绝 Promise。

• 权限提示：用户代理请求用户授权开放手写识别功能。

• 硬编码值：如果可以在构建时确定语言和特性，用户代理可对查询操作返回硬编码值。

识别器实现可能暴露操作系统、设备或用户习惯的信息。这主要依赖于所用的识别器技术。

以下是一些识别器实现类型及其相关风险：

• 无识别器支持：没有指纹风险。

• 基于云的识别器：风险极低或没有风险。网站可能通过对比预测结果和调用云服务直接获得的结果，检测所用云服务。但不会额外暴露用户或其设备的信息。

• 无状态模型（最常见）：此类模型的输出仅取决于输入绘图和模型本身。

  • 仅能通过浏览器更新的模型（例如全部在浏览器内实现）：网站可获知浏览器版本，但这也可通过其他手段检测。

  • 可在浏览器外进行更新的模型（例如通过操作系统 API 实现），根据场景，网站可获知：

    • 如果模型随每次操作系统更新一起更新，则可得知操作系统版本。

    • 如果模型仅随部分操作系统更新一起更新，则可得知某一范围的操作系统版本。

    • 如果模型通过带外或按需方式单独更新，则可能获知特定补丁级别。

  • 如模型利用硬件加速器（如 GPU），则结果可能暴露特定硬件的信息。

• 有状态/在线学习模型（最极端假设情况）：这些模型可根据先前使用记录学习。例如，操作系统识别器根据用户输入法习惯调整输出。这类模型可能泄露大量用户信息，风险极高。

然而，目前我们尚未发现属于此类的识别器实现。但我们建议对这类模型采取隐私保护措施，或者为每次会话使用全新、干净的状态。

指纹收集成本：指纹收集方需精心设计并准备一系列手写绘图（对抗性样本）以利用模型差异。生成这些样本可能成本较高，但可以认为有动力的一方能够获得这些样本。