WILL ServiceDesk and the Developer Documentation site has been upgraded and is available for general use.

Page tree
Skip to end of metadata
Go to start of metadata

Introduction

WILL data format specification provides formal description of digital ink content. The specification is defined on conceptual level and thus can be used in various environments and use cases - ranging from message driven applications to design of file formats. The conceptual model is based on well established vector graphics vocabulary with small number of extensions designed to better accommodate the specifics of digital ink. The vector path model is based on Catmull-Rom spline with variable width. Catmull-Rom spline passes through its control points that in combination with the variable width makes the model intuitive for ink generated with pointing tool. 

Terminology & Basics

Digital ink (referred to in this document as ink) content comprises of strokes. These are usually, but not necessarily, created with a pointing device. Strokes have certain graphical characteristics and can be optionally associated with other data or metadata. You can digitally store and share ink content using various models – vector-based, pixel-based, or hybrid.

Google Protocol Buffers

Protocol buffers are Google's open standard for serializing structured data using an extensible mechanism which is both language and platform neutral.
For further details see Google Protocol Buffers.

SVG Format

WILL data is stored in a format based on the Scalable Vector Graphics (SVG) open standard with extensions applied to cater for WILL requirements. SVG is the language based on XML for describing two-dimensional vector and mixed vector/raster graphics. For further details see SVG Introduction

Catmull-Rom spline

Catmull-Rom splines are a family of cubic interpolating splines formulated such that the tangent at each point is calculated using the previous and next point on the spline.

Open Packaging Conventions

The Open Packaging Conventions (OPC) is a container-file technology initially created by Microsoft to store a combination of XML and non-XML files that together form a single entity.

Conceptual Model

will-data-format-er-diagram




Conceptual model used in WILL Data Format Specification is described using entity-relationship model based on a subset of SVG Path specification, enhanced with specific digital ink features and vocabulary. 

Path

Path entity is the fundamental building block in digital ink. Every stroke is represented by a Path instance. 

Path style attributes

  • Stroke Color - the color used to render the stroke
  • Stroke Widths - list of positive values used to calculate the width of the stroke at different points along the path. If the list contains a single value, then the path has constant stroke width. If the list contains less values that the number of the control points used to define the path, the last value is taken multiple time to match the number of control points.

Path geometry attributes


  • Start Parameter - Specifies the t-value of the first segment from which the path should start.
  • End Parameter - Specifies the t-value of the last segment in which the path should end.

Segment Catmul-Rom

The geometry of the path is defined by a collection of path segments represented by Catmull-Rom curve. 

Catmull-Rom curve is represented as a collection of two-dimensional positions P0, P1, P2, ... Pn , where each four points Pi-1, Pi, Pi+1, Pi+2 define one segment using Catmull-Rom interpolation method to define the curve between Pi and Pi+1.

Appendix A: Serialization

Protocol Buffers

The encoding algorithm

The encoding algorithm implemented in the WILL software library is based on the well-known delta encoding technique. This technique is applied over all control point coordinates within a stroke, as well as across the corresponding width values for strokes with variable width. To enable further optimizations, these values are represented in integer form (as fixed-point numbers) before the delta encoding procedure.

Encoding coordinate values

The encoding process works as follows:

Step 1. Convert floating-point values to integer values using externally-specified decimal precision:

integerValue = floatValue * (10 ^ decimalPrecision);

Step 2. Perform delta encoding on the converted values:

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

Note: In converting between floating-point values and fixed-point (integer) values, some precision can be lost. If precision is critical to application functionality, you must take this into consideration. A possible solution is to rely on IEEE 754: in this case, for every value to be converted, you should use the appropriate decimalPrecision and an approximation that remains unchanged during this conversion.

Decoding coordinate values

To restore the original values, the encoding process is reversed, as follows:

Step 1. Perform delta decoding to restore the integer values:

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

Step 2. Convert integer values to floating-point values using externally-specified decimal precision:

floatValue = integerValue / (10 ^ decimalPrecision)

The encoding schema

Coordinates, width values, and other properties for every stroke are encoded in a binary form using Google protocol buffers. This allows rapid encoding and decoding, and the resulting binary code is highly-portable and compact because the techniques used for representing repeated stroke values greatly improve the efficiency of the varint technique used.

Values are encoded according to the following schema:

package WacomInkFormat;

option optimize_for = LITE_RUNTIME;

message Path {
    optional float startParameter = 1 [default = 0];
    optional float endParameter = 2 [default = 1];
    optional uint32 decimalPrecision = 3 [default = 2];
    repeated sint32 points = 4 [packed = true];
    repeated sint32 strokeWidths = 5 [packed = true];
    repeated sint32 strokeColor = 6 [packed = true];
}

Path message properties

Every Path message in the schema represents a single stroke and its properties as described below:

  • A value in the interval [0, 1] that specifies the exact beginning of the path:
    optional float startParameter = 1 [default = 0];
  • A value in the interval [0, 1] that specifies the exact ending of the path:
    optional float endParameter = 2 [default = 1];
  • The number of digits after the radix point for values stored in data and strokeWidth properties:
    optional uint32 decimalPrecision = 3 [default = 2];
  • An encoded list of the x and y values of all control points for a particular stroke:
    repeated sint32 data = 4 [packed = true];
  • A delta encoded list of width values for all control points for a stroke with a variable stroke width:
    repeated sint32 strokeWidth = 5 [packed = true];

For a stroke of constant width, this list contains a single value:

  • A delta encoded list of color values in RGBA format:
    repeated sint32 strokeColor = 6 [packed = true];

For a stroke of constant color, this list contains a single value. Most commonly, any variation in stroke color is in the opacity (the alpha channel of the RGBA format). In other words, the same RGB values apply throughout, but the A value changes.

The list of Path messages that define all of the encoded strokes is represented as a length-delimited list as follows:

DescriptionBytes sequence
128 bit varintPath 1 message length
BytesPath 1 message bytes
128 bit varintPath 2 message length
BytesPath 2 message bytes
......
128 bit varintPath N message length
BytesPath N message bytes

Appendix B: Store in File Format

WILL file format is using OPC formatted ZIP archive as a container. The diagram on the left illustrates the different parts and their relationship within a WILL file. The diagram is using the following notation:

  • The blue parts and relationships are part of OPC specification. 
  • The green parts and relationships are specific to WILL file format.


will-open-packaging-conventions

Below you can find brief descriptions of all parts (entities) in the OPC package. Parts that are in relationship with "something-to-many" cardinality will have IRIs containing an integer number. (ex. /sections/section1.svg)

Part IRIDescription
/props/core.xmlThis part contains general information and meta-data about the file.

/props/app.xml

This part contains information about the application that originally created the file.
/sections/section.svgThis part contains the multi-media content encoded using SVG.
/sections/media/paths.protobufThis part contains all strokes (paths) encoded using WILL encoding scheme (based on Google Protocol Buffers).


Sample OPC file structure looks like this:

_rels



.rels
<?xml version="1.0" encoding="UTF-8"?>
<Relationships 
    xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
    <Relationship Id="core-properties" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="/props/core.xml"/>
    <Relationship Id="extended-properties" Type="http://schemas.willfileformat.org/2015/relationships/extended-properties" Target="/props/app.xml"/>
    <Relationship Id="section0" Type="http://schemas.willfileformat.org/2015/relationships/section" Target="/sections/section0.svg"/>
</Relationships>
props



app.xml
<?xml version="1.0" encoding="UTF-8"?>
<Properties 
    xmlns="http://schemas.willfileformat.org/2015/relationships/extended-properties">
    <Application>Bamboo Spark</Application>
    <AppVersion>1.0</AppVersion>
</Properties>

core.xml
<?xml version="1.0" encoding="UTF-8"?>
<coreProperties 
    xmlns="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" 
    xmlns:dc="http://purl.org/dc/elements/1.1/" 
    xmlns:dcterms="http://purl.org/dc/terms/" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <dcterms:created xsi:type="dcterms:W3CDTF">2016-05-12T16:46:34Z</dcterms:created>
    <dc:title>WCM0074</dc:title>
</coreProperties>
sections



_rels



section0.svg.rels
<?xml version="1.0" encoding="UTF-8"?>
<Relationships 
    xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
    <Relationship Id="image0" Type="http://schemas.willfileformat.org/2015/relationships/section/paths" Target="/sections/media/image-453127858.protobuf"/>
</Relationships>

media



path-453127858.protobufBinary data encoded using the schema described in Appendix A.

section0.svg
<?xml version="1.0" encoding="UTF-8"?>
<svg 
    xmlns="http://www.w3.org/2000/svg" 
    xmlns:r="http://schemas.willfileformat.org/2015/relationships" width="592.0" height="840.0">
    <rect fill="#FFFFFF" fill-opacity="1.0" width="592.0" height="840.0"/>
    <g transform="matrix(1.0 0.0 -0.0 1.0 0.0 0.0)">
        <g r:id="image0"/></g>
</svg>
[Content_Types].xml

<?xml version="1.0" encoding="UTF-8"?>
<Types 
    xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
    <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
    <Default Extension="svg" ContentType="image/svg+xml"/>
    <Default Extension="jpg" ContentType="image/jpeg"/>
    <Default Extension="jpeg" ContentType="image/jpeg"/>
    <Default Extension="png" ContentType="image/png"/>
    <Default Extension="protobuf" ContentType="application/vnd.willfileformat.path+protobuf"/>
    <Override PartName="/props/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>
    <Override PartName="/props/app.xml" ContentType="application/vnd.willfileformat.extended-properties+xml"/>
    <Override PartName="/style/paints.protobuf" ContentType="application/vnd.willfileformat.paint+protobuf"/>
</Types>


According to OPC the actual linking inside the content of the parts is specific to the content type of the parts. For example /sections/section.svg uses r:id attribute:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:r="http://schemas.willfileformat.org/2015/relationships">
	<image r:id="rId1" x="0" y="0" width="1500" height="1500" /> <!-- Relationship that points to /sections/media/image.jpg -->
	<g r:id="rId2" transform="matrix(1 0 0 1 0 400)"/> <!-- Relationship that points to /sections/media/paths.protobuf -->
</svg> 


According to OPC the extensions to /props/core.xml should be implemented as a separate part. In WILL file format this is implemented via /props/app.xml part:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Properties xmlns="http://schemas.willfileformat.org/2015/extended-properties">
	<Template>Artistic(Green,Lines)</Template>
	<Application>Bamboo Paper</Application>
	<AppVersion>3.0.0</AppVersion>
</Properties> 

Remarks

  1. The vendor specific content types are preferred over the generic ones, because of the enhanced semantics. These content types are not intended to be used outside of the container.
  2. The URLs used for schemas and types have the following characteristics (or differences from Microsoft's ones):
    1. WILL file format is explicitly defined on the top of OPC and therefore there is no need for "package" segment in the URLs.
    2. The URLs have semantic meaning, so we don't expect frequent changes. Just in case, we have included the current year (2015) as a first segment in the URLs. 


  • No labels