Encoding

The InkModel is serialized as Protocol Buffers v3 message and wrapped within a RIFF container. The sections below describe the container and the protobuf serialization scheme.

RIFF Container

The InkModel is serialized into a RIFF Container, within the RIFF chunk UINK. It contains a HEAD sub-chunk, holding information about the logical parts the RIFF container and variable-length list of data sub-chunks holding separate logical parts of the ink model in the context of the RIFF container.

HEAD Chunk

The HEAD chunk contains the format version of the InkModel specification, which the serialized model complies to, and a list of chunk descriptors, containing information about the data chunks following the HEAD chunk.

The format version is encoded using 4 bytes as follows:

Byte 0	Byte 1	Byte 2	Byte 3
Version Major	Version Minor	Version Patch	Reserved

The format version is followed by a list of data chunk descriptors. Each chunk descriptor occupies 8 bytes and is defined as follows:

Byte 0	Byte 1	Byte 2	Byte 3	Byte 4	Byte 5	Byte 6	Byte 7
Version Major	Version Minor	Version Patch	Content Type	Compression Type	Reserved	Reserved	Reserved

The data chunk's content type must be of the following:

Value	Type	Mime-Type	Description
0	BINARY	binary/octet-stream	Some binary content.
1	PROTOBUF	application/protobuf	The content is a Protocol Buffers v3 message.
2	JSON	application/json	The content is a JSON message.
3	TEXT	text/plain	The content is some plain text.

The data chunk's compression type indicates the compression algorithm used to compress the corresponding data chunk. It must be one of the following:

Value	Type	Description
0	NONE	Uncompressed
1	ZIP	ZIP compression
2	LZMA	LZMA compression

Data Chunks

This reference document defines a list of pre-defined data chunks, intended for ink model logical data parts separation. This section contains a list of chunks, which are specific to the Universal Ink Model - the order of the chunks within the RIFF container is important and is specified in the table below using the column index.

Index	Chunk Name	FourCC	Description	Data Specification	Mandatory
0	Properties	PRPS	Data chunk used for storing ink model meta data.	Protobuf message Properties.	no
1	InputData	INPT	Data chunk used for storing raw input & biometric data.	Protobuf message InputData.	no
2	Brushes	BRSH	Data chunk holding a list of brush definitions.	Protobuf message Brushes.	no
3	InkData	INKD	Data chunk holding a stroke repository and additional information about how the strokes should be transformed and rendered by the implementations.	Protobuf message InkData.	yes
4	Knowledge Graph	KNWG	Data chunk holding a knowledge graph in form of a list of semantic triples.	Protobuf message TripleStore.	no
5	Ink Structure	INKS	Data chunk holding a list of logical trees (the main ink tree and, optionally, one or more ink views).	Protobuf message InkStructure.	yes

Protobuf Structures

BrushPrototype

Definition of polygon prototype for brush.

Field	Type	Label	Description
coordX	float	repeated	List of x coordinates of brush prototype.
coordY	float	repeated	List of y coordinates of brush prototype.
coordZ	float	repeated	List of z coordinates of brush prototype [for 3D rendering].
indices	uint32	repeated	List of indices of brush prototype [for 3D rendering].
shapeURI	string		URI uniquely identifing shape's polygon
size	float		Defines prototype per path point size

Brushes

Brush descriptions, needed for ink rasterization.

Field	Type	Label	Description
vectorBrushes	VectorBrush	repeated	List of defined vector brushes.
rasterBrushes	RasterBrush	repeated	List of defined raster brushes.

ChannelData

List of data items.

Field	Type	Label	Description
sensorChannelID	string		Referencing InkSensorChannel via id.
values	sint32	repeated	Sample values delta encoded with provided precision.

Environment

Environment defines the all details regarding the input environment:

• Operating System: name, version, ...
• Application: name, version, ...
• Geographic information: GPS coordinates.

Field	Type	Label	Description
id	string		MD5 hash according to the MD5 hash-based Unique Identifier Generation Scheme
properties	Properties		Properties are encoded as properties.

Float32

Float value wrapper to avoid cross-platform zero value issues.

Field	Type	Label	Description
value	float		Float value wrapped within the message.

InkData

Contains all ink data.

Field	Type	Label	Description
paths	Path	repeated	Data holder for paths.

InkInputProvider

Definition of input provider types.

Field	Type	Label	Description
id	string		MD5 hash according to the MD5 hash-based Unique Identifier Generation Scheme
type	InkInputProviderType		Type of used hardware - PEN, TOUCH, MOUSE, or controller.
properties	Properties		Properties are encoded as properties.

InkObject

Ink Object as base structure to capture all relevant data.

• Sensor data recorded from the input sensor,
• Brush configurations defining the different brush types used,
• Ink tree structuring the ink data,
• Meta-data describing the author, document, and so forth,
• Knowledge graph with semantics.

Field	Type	Label	Description
inputData	InputData		Data holder for ink input related data.
inkData	InkData		Data holder for ink related ink data.
brushes	Brushes		Rasterization tools.
inkTree	Node	repeated	The ink-tree: this is the ink-centric data model.
views	View	repeated	A list of views of the ink-tree based on the knowledge graph.
knowledgeGraph	TripleStore		The Knowledge Graph.
transform	Matrix4		transform is an affine transformation matrix which is applied to all paths.
properties	Properties		Document related data, such as DOCUMENT, AUTHOR, LAST_MODIFIED etc.

InputContext

Capturing context of the ink device with reference to the Environment and the SensorContext.

Field	Type	Label	Description
id	string		MD5 hash according to the MD5 hash-based Unique Identifier Generation Scheme
environmentID	string		Reference to the Environment.
sensorContextID	string		Reference to the SensorContext.

InputContextData

Container structure for context and input defines.

Field	Type	Label	Description
inputContexts	InputContext	repeated	List of input contexts
inkInputProviders	InkInputProvider	repeated	List of input providers
inputDevices	InputDevice	repeated	List of input devices
environments	Environment	repeated	List of environment setups
sensorContexts	SensorContext	repeated	List of sensor contexts

InputData

Input Data bundles the input.

Field	Type	Label	Description
inputContextData	InputContextData		Input context data.
sensorData	SensorData	repeated	Data holder for sensor data.

InputDevice

InputDevice with properties defined as triple store. The properties can contain:

• Communication Protocol: USB, BTC, BLE, SPP, WIFI,
• Communication ID: VID, PID; MAC; UID; COM_PORT,
• Device Name: Wacom Intuos Pro M, Apple iPad 8, Samsung GalaxyTab 10,
• PenID,
• Serial number,
• Firmware Version (MCU),
• Secondary Firmware Version (BT, WIFI) - different modules provide versions for itself,
• Orientation: PORTRAIT, LANDSCAPE, PORTRAIT_REVERSE, LANDSCAPE_REVERSE or 0, 90, 180, 270,
• Sensor size.

Field	Type	Label	Description
id	string		MD5 hash according to the MD5 hash-based Unique Identifier Generation Scheme
properties	Properties		Properties are encoded as properties.

Matrix4

Representation of a 4x4 affine matrix

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

Field	Type	Label	Description
m00	float
m01	float
m02	float
m03	float
m10	float
m11	float
m12	float
m13	float
m20	float
m21	float
m22	float
m23	float
m30	float
m31	float
m32	float
m33	float

Node

Node - the node message. Used for the definition of tree-structures.

Field	Type	Label	Description
id	string		Node unique identifier
depth	uint32		Depth in hierarchy structure
index	uint32		Index in InkData.paths or in InkData.sensorData data holder
type	NodeType		(PATH & SENSOR_DATA nodes only)

Node type | | groupBoundingBox | Rectangle | | Bounding box (Group nodes only) | | chunkFromIndex | uint32 | | Chunk beginning (CHUNK node only) | | chunkToIndex | uint32 | | Chunk ending (CHUNK node only) |

Path

Visual path structure. Path in its simplest form contains one or more Segments (Catmull-Rom), which include a series of positional points, Positions. In addition to those properties, digital ink in WILL Data Format includes Start Parameter and End Parameter as Path entity's properties.

Field	Type	Label	Description
id	string		Internal id.
startParameter	float		Spline start parameter [0, 1].
endParameter	float		Spline end parameter [0, 1].
splineX	float	repeated	Spline values for x.
splineY	float	repeated	Spline values for y.
splineZ	float	repeated	Spline values for z [for 3D rendering].
red	float	repeated	Color values [0, 1] for red channel.
green	float	repeated	Color values [0, 1] for green channel.
blue	float	repeated	Color values [0, 1] for blue channel.
alpha	float	repeated	Color values [0, 1] for alpha channel.
size	float	repeated	Brush size.
rotation	float	repeated	Brush rotation z.
scaleX	float	repeated	Brush scale x.
scaleY	float	repeated	Brush scale y.
scaleZ	float	repeated	Brush scale z [for 3D rendering].
offsetX	float	repeated	Brush offset x.
offsetY	float	repeated	Brush offset y.
offsetZ	float	repeated	Brush offset z [for 3D rendering].
sensorDataOffset	uint32		Index of points mapping between raw and processed paths.
sensorDataID	string		Reference sensor data.
sensorDataMapping	uint32	repeated	Explicit mapping between indices of Path and SensorData, used when the input rate is very high and provides unwanted points.
style	Style		Style that is applied to the path.

PathPointContext

Field	Type	Label	Description
statics	PathPointProperties
dynamics	PathPointSettings

PathPointProperties

Pipeline properties that do not vary. Variable ones are serialized via Path message.

Field	Type	Label	Description
size	Float32		Brush size.
red	Float32		Color value [0, 1] for red channel.
green	Float32		Color value [0, 1] for green channel.
blue	Float32		Color value [0, 1] for blue channel.
alpha	Float32		Color value [0, 1] for alpha channel.
rotation	Float32		Brush rotation z.
scaleX	Float32		Brush scale x.
scaleY	Float32		Brush scale y.
scaleZ	Float32		Brush scale z [for 3D rendering].
offsetX	Float32		Brush offset x.
offsetY	Float32		Brush offset y.
offsetZ	Float32		Brush offset z [for 3D rendering].

PathPointSettings

Field	Type	Label	Description
size	PropertySettings
red	PropertySettings
green	PropertySettings
blue	PropertySettings
alpha	PropertySettings
rotation	PropertySettings
scaleX	PropertySettings
scaleY	PropertySettings
scaleZ	PropertySettings
offsetX	PropertySettings
offsetY	PropertySettings
offsetZ	PropertySettings

Properties

Definition of properties.

Field	Type	Label	Description
props	Property	repeated	List of properties

Property

Encodes a single property

Field	Type	Label	Description
name	string		Name of the property
value	string		Value of property

PropertySettings

Field	Type	Label	Description
value	Range
velocity	Range
pressure	Range
altitude	Range
radiusX	Range
radiusY	Range
dependencies	InputPropertyType	repeated

Range

Field	Type	Label	Description
min	float
max	float
remapURI	string

RasterBrush

A brush defined with raster images

Field	Type	Label	Description
name	string		Brush descriptor
spacing	float		Distance between neighbour particles.
scattering	float		The scattering along the curve normal.
rotationMode	RotationMode		The particle rotation mode of the brush.
shapeTexture	bytes	repeated	List of png images that contains the shape texture.
shapeTextureURI	string	repeated	List of URIs associated to the shape texture.
fillTexture	bytes		List of png image that contains the fill texture.
fillTextureURI	string		URI identifying the fillTexture.
fillWidth	float		Width of the fill tile.
fillHeight	float		Height of the fill tile.
randomizeFill	bool		Specifies whether the fill texture is randomly displaced.
blendMode	BlendMode		The applied blend mode.

Rectangle

Representation of rectangle

Field	Type	Label	Description
x	float		Lower-left x-coordinate point of rectangle.
y	float		Lower-left y-coordinate point of rectangle.
width	float		Width of rectangle.
height	float		Height of rectangle.

SemanticTriple

A semantic triple, or simply triple, is the atomic data entity data model. As its name indicates, a triple is a set of three entities that codifies a statement about semantic data in the form of subject-predicate-object expressions.

Field	Type	Label	Description
subject	string
predicate	string
object	string

SensorChannel

Information about the sensor channel.

Field	Type	Label	Description
id	string		MD5 hash according to the MD5 hash-based Unique Identifier Generation Scheme
type	string		URI which describes uniquely this channel. Supported types are:
metric	InkSensorMetricType		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

User-defined channels that introduce custom meaning should be provided from the user's side.

Indicates metric used in calculating the resolution for the data item. | | resolution | float | | Is a decimal number giving the number of data item increments. | | min | float | | Per physical unit., e.g. if the physical unit is in m and device units. Resolution is 100000, then the value 150 would be 0.0015 m.

Minimal value of the channel | | max | float | | Maximal value of the channel | | precision | uint32 | | Precision of integer encoding, needed for encoded float values |

SensorChannelsContext

The SensorChannelsContext groups sensor channels that are producing data with the same sampling rate.

Field	Type	Label	Description
id	string		MD5 hash according to the MD5 hash-based Unique Identifier Generation Scheme
channels	SensorChannel	repeated	Channels in this group provides aligned values in the same time.
samplingRateHint	Uint32		Hint for the intended sampling rate of the channel [Optional].
latency	Uint32		Latency measure in milliseconds [Optional].
inkInputProviderID	string		Reference to the InkInputProvider.
inputDeviceID	string		Reference to the InputDevice.

SensorContext

Each input device has a SensorContext describing the available sensors of a device. One file can contain Ink data from two devices of the same type with a shared context.

Field	Type	Label	Description
id	string		MD5 hash according to the MD5 hash-based Unique Identifier Generation Scheme
sensorChannelsContext	SensorChannelsContext	repeated	Properties are encoded as semantic triples.

SensorData

SensorData is the central data structure for storing raw data from the ink sensor.

Field	Type	Label	Description
id	string
inputContextID	string		Referencing the InputContext via id.
state	InkState		State of the ink.
timestamp	uint64		Timestamp for first sample of the stroke, measured in milliseconds
dataChannels	ChannelData	repeated	(time when first X & Y are reported). Data channels encode the data list.

Style

A style message, used for Path customization.

Field	Type	Label	Description
properties	PathPointProperties		Static values of properties which do not exist per per path point
brushURI	string		Reference to Brush used for stroke rasterization
particlesRandomSeed	uint32		Particles random seed, required for particle strokes
renderModeURI	string		Defines additional information about stroke visualisation, such as ERASER

Tool

Field	Type	Label	Description
vectorBrush	VectorBrush
rasterBrush	RasterBrush
blendMode	BlendMode
context	PathPointContext

TripleStore

TripleStore - encapsulates a list of TripleGroups

Field	Type	Label	Description
statements	SemanticTriple	repeated	List of semantic triples.

Uint32

Unsigned integer value wrapper to avoid cross-platform zero value issues.

Field	Type	Label	Description
value	uint32		Unsigned integer value wrapped within the message.

VectorBrush

A brush defined with a polygon (polyhedron for 3D)

Field	Type	Label	Description
name	string		Brush descriptor
prototype	BrushPrototype	repeated	Polygon prototype for the brush.
spacing	float		Spacing value.

View

View - a message representing a view of the ink-tree, which is serialized in the form of another tree.

Field	Type	Label	Description
name	string		View descriptor URI (unique in the model scope)
tree	Node	repeated	The tree structure of the current view

BlendMode

The blend mode enum lists the different blend modes that can be applied to raster brushes.

Name	Number	Description
BLEND_NORMAL	0
BLEND_NORMAL_REVERSE	1
BLEND_NONE	2
BLEND_ERASE	3
BLEND_MIN	4
BLEND_MAX	5
BLEND_ADD	6
BLEND_SUBTRACT	7
BLEND_SUBTRACT_REVERSE	8
BLEND_MULTIPLY_NO_ALPHA	9
BLEND_MULTIPLY_NO_ALPHA_INVERT	10

InkInputProviderType

Defining the different types of input.

Name	Number	Description
PEN	0	Stylus, smart pens, pen displays, signature capturing device, ...
TOUCH	1	Touch controller input: Finger or passive stylus.
MOUSE	2	Mouse device.
CONTROLLER	3	3-DOF or 6-DOF input devices.

InkSensorMetricType

Supported metric types

Name	Number	Description
LENGTH	0	Underling si unit is meter.
TIME	1	Underling si unit is second.
FORCE	2	Underling si unit is newton.
ANGLE	3	Underling si unit is radian.
NORMALIZED	4	Percentage, expressed as a fraction (1.0 = 100%) relative to max-min.
LOGICAL	5	Logical value, true / false values.
DIMENSIONLESS	6	No metric defined for sensor.

InkState

The ink device state defines the state of the Ink device. WILL 3.0 supports different modes:

• Writing on a plane,
• Hovering above a surface,
• Moving in the air (VR/AR/MR) interaction,
• Only hovering in the air.

Name	Number	Description
PLANE	0	Ink device is writing on a surface.
HOVERING	1	Hovering over a surface.
IN_VOLUME	2	Using the ink device in the air, with active inking.
VOLUME_HOVERING	3	Moving the pen in the air with disabled inking.

InputPropertyType

Name	Number	Description
PRESSURE	0	Pressure value.
RADIUS_X	1	Touch radius by X.
RADIUS_Y	2	Touch radius by Y.
AZIMUTH	3	Azimuth angle of the pen (yaw).
ALTITUDE	4	Elevation angle of the pen (pitch).
ROTATION	5	Rotation (counter-clockwise rotation about pen axis).

NodeType

Defines the node type.

Name	Number	Description
PATH_GROUP	0
SENSOR_DATA_GROUP	1
PATH	2
SENSOR_DATA	3

RotationMode

The rotation parameter specifies the rotation of the particle.

Name	Number	Description
NONE	0	Indicates that the shape will not be rotated.
RANDOM	1	Indicates that the shape will be rotated randomly before it renders.
TRAJECTORY	2	Indicates that the shape will be rotated to match the path trajectory.

Scalar Value Types

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str