Universal Ink Data Format

Universal Ink Model はProtocol Buffers v3 messageとしてシリアル化され、RIFF container.内でラッピングされます。 以下のセクションでは、このコンテナと protobuf のシリアル化スキームについて説明します。

RIFF Container

Universal Ink Model (UIM)は@@@内の RIFF container コンテナへとシリアル化されます。RIFF chunk UIM3. このチャンクには 2 つのサブチャンク、すなわち HEAD と DATA が含まれます。 HEAD チャンクには現在の仕様バージョンが含まれています。 このバージョンは 3 バイトを使用してエンコードされ、[major-version]-[minor-version]-[patch-version] のように定義されます。

インクモデルはセクション 8.2「Protocol Buffers のシリアル化スキーム」に記載されている Protocol Buffers メッセージとしてシリアル化され、DATA チャンクに格納されます。

図 1：RIFF のダイアグラム

インクツリ

インクツリーは汎用的なノード構造で構築されます。 ツリーを構築する場合、ツリー内部の深さはdepth属性によって示されます。 図 3に示すように、ツリー構造のシリアル化では、深さ優先の前順序ツリーシリアル化が適用されます。

それぞれのノードには、サブジェクトの識別子としてのセマンティックステートメントに関連のある一意の識別子idが付いています。 index属性はパスまたはセンサーデータインデックスに関連しています。 groupBoundingBoxはオプションで、視覚的デバッグを容易にしたり、クリック可能なオプションの関連領域をハイライト表示したりできます。 属性chunkFromIndexおよびchunkToIndexは、ノードのtypeがCHUNKである場合にのみ、サブインデックス化の対象となります。

図 2：赤で示した深さ優先のツリー順序：F、B、A、D、C、E、G、I、H

データ圧縮

エンコーディング

エンコードプロセスは次のように行われます。

ステップ 1. （オプション） 10 進数の精度を外部指定して、浮動小数点値を整数値に変換します。

integerValue = floatValue * (10 ^ decimalPrecision);

Note: ステップ 1 はデータタイプが整数データタイプ(など 以外の場合にのみ適用されます。UINT32, UINT64, INT32, or INT64).

ステップ 2. 変換された値にデルタエンコードを実施します。

encodedValues[0] = integerValues[0];
for(i = 1; i < n; i++)
{
    encodedValues[i] = integerValues[i] - integerValues[i - 1];
}

注意： 浮動小数点値と固定小数点（整数）値との変換では、精度がある程度失われる可能性があります。 アプリケーションの機能にとって精度が極めて重要な場合は、これに対する考慮が必要です。 考えられる 1 つの解決策は、IEEE 754:の利用です。この場合、変換されるすべての値に対して適切なdecimalPrecisionと、この変換時に変更されない近似値を使用する必要があります。

デコード

元の値に戻すには、エンコードプロセスを次のように入れ替えます。

ステップ 1. デルタ復号を実施して整数値を元に戻します。

integerValues[0] = encodedValues[0];
for(i = 1; i < n; i++)
{
    integerValues[i] = integerValues[i - 1] + encodedValues[i];
}

ステップ 2. （オプション） 外部で指定された小数点精度を使用して整数値を浮動小数点値に変換します。

floatValue = integerValue / (10 ^ decimalPrecision)

注意： ステップ 2 はデータタイプが整数データタイプ以外の場合にのみ適用されます。

Protobuf シリアル化スキーム

BrushPrototype

ブラシのポリゴンプロトタイプの定義。

フィールド	タイプ	ラベル	説明
coordX	float	repeated	ブラシプロトタイプの x 座標のリスト。
coordY	float	repeated	ブラシプロトタイプの y 座標のリスト。
coordZ	float	repeated	ブラシプロトタイプの z 座標のリスト [3D レンダリング用]。
indices	uint32	repeated	ブラシプロトタイプのインデックスのリスト [3D レンダリング用]。
shapeURI	string	optional	ポリゴンの形状を一意に識別する URI。
size	float	optional	パスポイントサイズごとのプロトタイプを定義します。

Brushes

インクのラスタライゼーションに必要なブラシの説明。

フィールド	タイプ	ラベル	説明
vectorBrushes	VectorBrush	repeated	定義されたベクターブラシのリスト。
rasterBrushes	RasterBrush	repeated	定義されたラスターブラシのリスト。

ChannelData

データ項目のリスト。

フィールド	タイプ	ラベル	説明
sensorChannelID	string	optional	id を介して InkSensorChannel を参照します。
values	sint32	repeated	指定された精度でデルタ符号化されたサンプル値。

環境

環境は、入力環境に関するすべての詳細を定義します。

• オペレーティングシステム：名前、バージョンなど。
• アプリケーション：名前、バージョンなど。
• 地理情報：GPS 座標。

フィールド	タイプ	ラベル	説明
id	string	optional	MD5 ハッシュ。MD5 ハッシュベースの一意識別子生成スキームに従う。
properties	Property	repeated	オペレーティングシステム名、バージョンなどの環境プロパティ。

Float32

クロスプラットフォームのゼロ値の問題を回避するための浮動小数点値のラッパー。

フィールド	タイプ	ラベル	説明
value	float	optional	メッセージ内でラップされた浮動小数点値。

InkData

すべてのインクデータを含みます。

フィールド	タイプ	ラベル	説明
strokes	Stroke	repeated	ストロークのデータホルダー。

InkInputProvider

入力プロバイダータイプの定義。

フィールド	タイプ	ラベル	説明
id	string	optional	MD5 ハッシュ。MD5 ハッシュベースの一意識別子生成スキームに従う。
Type	InkInputProviderType	optional	使用されているハードウェアのタイプ - PEN、TOUCH、MOUSE、またはコントローラー。
properties	Property	repeated	PenID などの InkInputProvider プロパティ。

InkObject

すべての関連データをキャプチャするためのベース構造のインクオブジェクト。

• 入力センサーから記録されたセンサーデータ
• 使用される異なるブラシタイプを定義するブラシ構成
• インクストロークの視覚的ジオメトリを持つインクデータ
• インクデータを構造化するインクツリー
• 著者、ドキュメントなどを記述するメタデータ
• 意味論を持つ知識グラフ

フィールド	タイプ	ラベル	説明
inputData	InputData	optional	インク入力関連データのデータホルダー。
inkData	InkData	optional	インク関連のインクデータのデータホルダー。
brushes	Brushes	optional	ラスタライゼーションツール。
inkTree	Node	repeated	インクツリー：これはインク中心のデータモデルです。
views	View	repeated	ナレッジグラフに基づくインクツリーのビューのリスト。
knowledgeGraph	TripleStore	optional	ナレッジグラフ。
transform	Matrix4	optional	すべてのパスに適用されるアフィン変換行列。
properties	Property	repeated	DOCUMENT、AUTHOR、LAST_MODIFIED などのドキュメント関連のプロパティ。

InputContext

インクデバイスのコンテキストを環境と SensorContext への参照と共にキャプチャします。

フィールド	タイプ	ラベル	説明
id	string	optional	MD5 ハッシュ。MD5 ハッシュベースの一意識別子生成スキームに従う。
environmentID	string	optional	環境への参照。
sensorContextID	string	optional	SensorContext への参照。

InputContextData

コンテキストと入力定義のコンテナ構造。

フィールド	タイプ	ラベル	説明
inputContexts	InputContext	repeated	入力コンテキストのリスト。
inkInputProviders	InkInputProvider	repeated	入力プロバイダーのリスト。
inputDevices	InputDevice	repeated	入力デバイスのリスト。
environments	Environment	repeated	環境セットアップのリスト。
sensorContexts	SensorContext	repeated	センサーコンテキストのリスト。

InputData

InputData は入力をまとめます。

フィールド	タイプ	ラベル	説明
inputContextData	InputContextData	optional	入力コンテキストデータ。
sensorData	SensorData	repeated	センサーデータのデータホルダー。

InputDevice

入力デバイスとそのプロパティ。

プロパティには以下が含まれます:

• 通信プロトコル：USB、BTC、BLE、SPP、WIFI
• 通信 ID：VID、PID；MAC；UID；COM_PORT
• デバイス名：Wacom Intuos Pro M、Apple iPad 8、Samsung GalaxyTab 10
• シリアル番号
• ファームウェアバージョン（MCU）
• セカンダリファームウェアバージョン（BT、WIFI）- 異なるモジュールはそれぞれのバージョンを提供します
• 方向：PORTRAIT、LANDSCAPE、PORTRAIT_REVERSE、LANDSCAPE_REVERSE または 0、90、180、270
• センサーサイズ

フィールド	タイプ	ラベル	説明
id	string	optional	MD5 ハッシュ。MD5 ハッシュベースの一意識別子生成スキームに従う。
properties	Property	repeated	入力デバイスのプロパティ。

Matrix4

4x4 アフィン行列の表現

| m00 m01 m02 m03 | | m10 m11 m12 m13 | | m20 m21 m22 m23 | | m30 m31 m32 m33 |

フィールド	タイプ	ラベル	説明
m00	float	optional
m01	float	optional
m02	float	optional
m03	float	optional
m10	float	optional
m11	float	optional
m12	float	optional
m13	float	optional
m20	float	optional
m21	float	optional
m22	float	optional
m23	float	optional
m30	float	optional
m31	float	optional
m32	float	optional
m33	float	optional

Node

ツリー構造の定義に使用されるノードメッセージ。

フィールド	タイプ	ラベル	説明
id	string	optional	ノードのユニークな識別子
depth	uint32	optional	階層構造内の深さ
index	uint32	optional	InkData.paths または InkData.sensorData データホルダー内のインデックス
Type	NodeType	optional	(PATH & SENSOR_DATA ノードのみ) ノードタイプ
groupBoundingBox	Rectangle	optional	バウンディングボックス (Group ノードのみ)
chunkFromIndex	uint32	optional	チャンクの始まり (CHUNK ノードのみ)
chunkToIndex	uint32	optional	チャンクの終わり (CHUNK ノードのみ)

PathPointProperties

変化しないパイプラインプロパティ。 可変のものは Stroke メッセージを介してシリアル化されます。

フィールド	タイプ	ラベル	説明
size	Float32	optional	ブラシサイズ
red	Float32	optional	赤チャンネルの色値 [0, 1]
green	Float32	optional	緑チャンネルの色値 [0, 1]
blue	Float32	optional	青チャンネルの色値 [0, 1]
alpha	Float32	optional	アルファチャンネルの色値 [0, 1]
rotation	Float32	optional	ブラシの回転 z
scaleX	Float32	optional	ブラシのスケール x
scaleY	Float32	optional	ブラシのスケール y
scaleZ	Float32	optional	ブラシのスケール z [3D レンダリング用]
offsetX	Float32	optional	ブラシのオフセット x
offsetY	Float32	optional	ブラシのオフセット y
offsetZ	Float32	optional	ブラシのオフセット z [3D レンダリング用]

Property

単一のプロパティをエンコードします。

フィールド	タイプ	ラベル	説明
name	string	optional	プロパティの名前
value	string	optional	プロパティの値

RasterBrush

ラスタ画像で定義されたブラシ

フィールド	タイプ	ラベル	説明
name	string	optional	ブラシディスクリプター。
spacing	float	optional	隣接する粒子間の距離。
scattering	float	optional	カーブ法線に沿った散乱。
rotationMode	RotationMode	optional	ブラシの粒子回転モード。
shapeTexture	bytes	repeated	形状テクスチャを含む png 画像のリスト。
shapeTextureURI	string	repeated	形状テクスチャに関連付けられた URI のリスト。
fillTexture	bytes	optional	塗りつぶしテクスチャを含む png 画像のリスト。
fillTextureURI	string	optional	塗りつぶしテクスチャを識別する URI。
fillWidth	float	optional	塗りつぶしタイルの幅。
fillHeight	float	optional	塗りつぶしタイルの高さ。
randomizeFill	bool	optional	塗りつぶしテクスチャがランダムに変位するかどうかを指定します。
blendMode	BlendMode	optional	適用されるブレンドモード。

Rectangle

長方形の表現

フィールド	タイプ	ラベル	説明
x	float	optional	長方形の左下 x 座標。
y	float	optional	長方形の左下 y 座標。
width	float	optional	長方形の幅。
height	float	optional	長方形の高さ。

SemanticTriple

意味トリプル、または単にトリプルは、主語-述語-対象の三つ組で、意味データについての文を表現します。

フィールド	タイプ	ラベル	説明
subject	string	optional
predicate	string	optional
object	string	optional

SensorChannel

センサーチャネルに関する情報。

サポートされるチャネルタイプ:

• will:///input/3.0/channel/X
• will:///input/3.0/channel/Y
• will:///input/3.0/channel/Z
• will:///input/3.0/channel/Timestamp
• will:///input/3.0/channel/Pressure
• will:///input/3.0/channel/RadiusX
• will:///input/3.0/channel/RadiusY
• will:///input/3.0/channel/Altitude
• will:///input/3.0/channel/Azimuth
• will:///input/3.0/channel/Rotation

フィールド	タイプ	ラベル	説明
id	string	optional	MD5 ハッシュ。MD5 ハッシュベースの一意識別子生成スキームに従う。
Type	string	optional	このチャネルを一意に識別する URI。サポートされるタイプは次のとおりです：
metric	InkSensorMetricType	optional	ユーザー定義のチャネルはユーザー側から提供されるべきです。データ項目の解像度を計算する際に使用されるメトリックを示します。
resolution	double	optional	データ項目の増分数を示す 10 進数。
min	float	optional	物理単位ごと。たとえば、物理単位が m であり、デバイスの単位が 100000 である場合、値 150 は 0.0015 m になります。チャネルの最小値。
max	float	optional	チャネルの最大値
precision	uint32	optional	エンコードされた浮動小数点値に必要な整数エンコーディングの精度

SensorChannelsContext

SensorChannelsContext は、同じサンプリングレートでデータを生成するセンサーチャネルをグループ化します。

フィールド	タイプ	ラベル	説明
id	string	optional	MD5 ハッシュ。MD5 ハッシュベースの一意識別子生成スキームに従う。
channels	SensorChannel	repeated	このグループのチャネルは、同じ時間に整列した値を提供します。
samplingRateHint	Uint32	optional	チャネルの意図されたサンプリングレートのヒント [オプション]。
latency	Uint32	optional	ミリ秒単位のレイテンシ測定 [オプション]。
inkInputProviderID	string	optional	InkInputProvider への参照。
inputDeviceID	string	optional	InputDevice への参照。

SensorContext

各入力デバイスには、デバイスの利用可能なセンサーを記述する SensorContext があります。 同じタイプのデバイスからの 2 つのデバイスの Ink データが共有コンテキストを持つファイルに含まれる可能性があります。

フィールド	タイプ	ラベル	説明
id	string	optional	MD5 ハッシュ。MD5 ハッシュベースの一意識別子生成スキームに従う。
sensorChannelsContext	SensorChannelsContext	repeated	デバイスセンサーチャネルのグループ化コンテキスト。

SensorData

SensorData は、インクセンサーからの生データを保存するための中心的なデータ構造です。

フィールド	タイプ	ラベル	説明
id	string	optional
inputContextID	string	optional	id を介して InputContext を参照します。
state	InkState	optional	インクの状態。
timestamp	uint64	optional	ストロークの最初のサンプルのタイムスタンプ、ミリ秒単位で計測されます。
dataChannels	ChannelData	repeated	(最初の X および Y が報告された時刻)。データチャネルはデータリストをエンコードします。

Stroke

視覚的なパスの構造。 Stroke は、最も単純な形式では、1 つ以上のセグメント（Catmull-Rom）を含み、 Positions としての一連の位置点を含みます。 これらのプロパティに加えて、デジタルインクストロークには、開始パラメーターと終了パラメーターが Stroke エンティティのプロパティとして含まれます。

フィールド	タイプ	ラベル	説明
id	string	optional	内部 ID。
startParameter	float	optional	スプラインの開始パラメーター [0, 1]。
endParameter	float	optional	スプラインの終了パラメーター [0, 1]。
splineX	float	repeated	x のスプライン値。
splineY	float	repeated	y のスプライン値。
splineZ	float	repeated	z のスプライン値 [3D レンダリング用]。
red	float	repeated	赤チャンネルの色値 [0, 1]。
green	float	repeated	緑チャンネルの色値 [0, 1]。
blue	float	repeated	青チャンネルの色値 [0, 1]。
alpha	float	repeated	アルファチャンネルの色値 [0, 1]。
size	float	repeated	ブラシのサイズ。
rotation	float	repeated	ブラシの回転 z。
scaleX	float	repeated	ブラシのスケール x。
scaleY	float	repeated	ブラシのスケール y。
scaleZ	float	repeated	ブラシのスケール z [3D レンダリング用]。
offsetX	float	repeated	ブラシのオフセット x。
offsetY	float	repeated	ブラシのオフセット y。
offsetZ	float	repeated	ブラシのオフセット z [3D レンダリング用]。
sensorDataOffset	uint32	optional	生データと処理済みパスの間のポイントのマッピングのインデックス。
sensorDataID	string	optional	参照センサーデータ。
sensorDataMapping	uint32	repeated	Stroke と SensorData のインデックス間の明示的なマッピング。入力レートが非常に高く、不要なポイントが提供される場合に使用されます。
style	Style	optional	パスに適用されるスタイル。

Style

Stroke のカスタマイズに使用されるスタイルメッセージ。

フィールド	タイプ	ラベル	説明
properties	PathPointProperties	optional	パスポイントごとに存在しない静的なプロパティの値
brushURI	string	optional	ストロークラスタリゼーションに使用されるブラシへの参照
particlesRandomSeed	uint32	optional	パーティクルランダムシード、パーティクルストロークに必要
renderModeURI	string	optional	ストロークの視覚化に関する追加情報の定義、消しゴムなど。

TripleStore

TripleGroup のリストをカプセル化します。

フィールド	タイプ	ラベル	説明
statements	SemanticTriple	repeated	セマンティックトリプルのリスト。

Uint32

整数のゼロ値の問題を回避するための符号なし整数値のラッパー。

フィールド	タイプ	ラベル	説明
value	uint32	optional	メッセージ内にラップされた符号なし整数値。

VectorBrush

多角形（3D の場合はポリエドロン）で定義されたブラシ。

フィールド	タイプ	ラベル	説明
name	string	optional	ブラシの記述子。
prototype	BrushPrototype	repeated	ブラシのための多角形プロトタイプ。
spacing	float	optional	間隔値。

View

インクツリーのビューを表すメッセージで、別のツリー形式でシリアル化されます。

フィールド	タイプ	ラベル	説明
name	string	optional	ビュー記述子 URI（モデルスコープで一意）。
tree	Node	repeated	現在のビューのツリー構造。

BlendMode

ブレンドモードの列挙型は、ラスターブラシに適用できる異なるブレンドモードを示します。

名前	番号	説明
SOURCE_OVER	0	これがデフォルト設定で、新しい形状を既存のキャンバスコンテンツの上に描画します。NORMAL とも呼ばれます。
DESTINATION_OVER	1	新しい形状が既存のキャンバスコンテンツの背後に描画されます。NORMAL_REVERSE とも呼ばれます。
DESTINATION_OUT	2	新しい形状が重ならない部分では既存のコンテンツが維持されます。ERASE とも呼ばれます。
LIGHTER	3	両方の形状が重なる部分の色は、色の値を加算することで決定されます。ADD とも呼ばれます。
COPY	4	新しい形状のみが表示されます。NONE とも呼ばれます。
MIN	5	結果は両方の色の最小値です。結果はより暗い色です。
MAX	6	結果は両方の色の最大値です。結果はより明るい色です。

InkInputProviderType

入力の異なるタイプを定義します。

名前	番号	説明
PEN	0	スタイラス、スマートペン、ペンディスプレイ、署名キャプチャデバイスなど。
TOUCH	1	タッチコントローラー入力：指または受動ペン。
MOUSE	2	マウスデバイス。
CONTROLLER	3	3-DOFまたは6-DOF入力デバイス。

InkSensorMetricType

サポートされているメトリックのタイプ

名前	番号	説明
LENGTH	0	基本のSI単位はメートルです。
TIME	1	基本のSI単位は秒です。
FORCE	2	基本のSI単位はニュートンです。
ANGLE	3	基本のSI単位はラジアンです。
NORMALIZED	4	パーセンテージ。最大値と最小値に対する分数（1.0 = 100％）として表されます。
LOGICAL	5	論理値、true / false 値。
DIMENSIONLESS	6	センサーに対して定義されたメトリックはありません。

InkState

インクデバイスの状態は、インクデバイスの状態を定義します。WILL 3.0 は、さまざまなモードをサポートしています:

• 平面に書く

• 表面の上をホバリングする

• 空中で移動する（VR/AR/MR）相互作用

• 空中でのみホバリングする

  名前	番号	説明
  PLANE	0	インクデバイスが表面に書き込んでいます。
  HOVERING	1	表面の上をホバリングしています。
  IN_VOLUME	2	インクデバイスを空中で使用し、アクティブなインキングを行っています。
  VOLUME_HOVERING	3	インキングが無効になっている状態でペンを空中で移動しています。

NodeType

ノードのタイプを定義します。

名前	番号	説明
PATH_GROUP	0	PATH_GROUP は階層的にストロークノードを組み合わせます。
SENSOR_DATA_GROUP	1	SENSOR_DATA_GROUP は階層的にセンサーデータノードを組み合わせます。
PATH	2	PATH は、ノードが直接ストロークを指すノードタイプです。
SENSOR_DATA	3	SENSOR_DATA は、ノードが直接センサーデータサンプルシーケンスを指すノードタイプです。

RotationMode

回転モードは、パーティクルの回転を指定します。

名前	番号	説明
NONE	0	図形が回転しないことを示します。
RANDOM	1	描画前に図形がランダムに回転することを示します。
TRAJECTORY	2	図形がパスの軌跡に一致するように回転することを示します。

スカラー値のタイプ

.proto Type	説明	C++ タイプ	Java タイプ	Python タイプ
double		double	double	float
float		float	float	float
int32	可変長エンコーディングを使用します。負の数をエンコードするのに効率が悪いです - フィールドが負の値を持つ可能性が高い場合は、代わりに sint32 を使用してください。	int32	int	int
int64	可変長エンコーディングを使用します。負の数をエンコードするのに効率が悪いです - フィールドが負の値を持つ可能性が高い場合は、代わりに sint64 を使用してください。	int64	long	int/long
uint32	可変長エンコーディングを使用します。	uint32	int	int/long
uint64	可変長エンコーディングを使用します。	uint64	long	int/long
sint32	可変長エンコーディングを使用します。符号付き整数値。これらは、通常の int32 よりも効率的に負の数をエンコードします。	int32	int	int
sint64	可変長エンコーディングを使用します。符号付き整数値。これらは、通常の int64 よりも効率的に負の数をエンコードします。	int64	long	int/long
fixed32	常に 4 バイトです。値が 2^28 よりも大きい場合は、uint32 よりも効率的です。	uint32	int	int
fixed64	常に 8 バイトです。値が 2^56 よりも大きい場合は、uint64 よりも効率的です。	uint64	long	int/long
sfixed32	常に 4 バイトです。	int32	int	int
sfixed64	常に 8 バイトです。	int64	long	int/long
bool		bool	boolean	boolean
string	文字列は常に UTF-8 エンコードされたテキストまたは 7 ビット ASCII テキストを含んでいる必要があります。	string	String	str/unicode
bytes	任意のバイト列を含むことができます。	string	ByteString	str