JIIX format reference

Reference of the JSON Interactive Ink eXchange format (JIIX) version 3.

Content

JIIX is an exchange format to export, share and re-import the internal semantics of the Interactive Ink model.

As such, it is designed to host information about:

• Content - strokes, glyphs and graphical primitives
• Semantic interpretation of the content, including lists
• Style information - decorations, color, width, font, etc.

When exporting JIIX from iink SDK, depending on the use case, you may sometimes want to only retrieve part of this information. This is managed at configuration level, via the following keys:

• export.jiix.bounding-box - Export item bounding boxes
• export.jiix.strokes - Export ink strokes
• export.jiix.glyphs - Export converted glyphs
• export.jiix.primitives - Export shape primitives (lines, circles, etc.)
• export.jiix.style - Export detailed styling information (color, width, font, etc.)
• export.jiix.text.chars - Export detailed information about the characters in the text interpretation
• export.jiix.text.words - Export detailed information about the words in the text interpretation
• export.jiix.ids - Export items ids.
• export.jiix.deprecated.text.linebreaks - Export detailed information about the line breaks within a text.
• export.jiix.text.structure - Export detailed information about the text layout structure for Text blocks.
• export.jiix.shape.candidates - Export shape candidates when using a Shape Recognizer.

For more information about these parameters, including default values, refer to the configuration reference.

Versioning

The version of the format that the current document conforms to is given by the version property of the root of the JSON document (as the root of the document corresponds to the root block of the exposed content block hierarchy, the version property belongs to this root block).

For example, if the root block is a "Text" block, we will have something like:

{
 "version": "3",
 "type": "Text",
 "bounding-box": { ... },
 "label": "Hello world!",
 "words": [ ... ],
 "id": "MainBlock"
}

Unit system

Units are not explicitly provided in a JIIX document.

For system coordinates, they shall be understood as model units, that is to say millimeters. The actual rendering of a JIIX document on the screen will then depend on the dpi and any other parameter (zoom, offset) used to configure the renderer.

The angles are specified in radians.

Structure

Block hierarchy

JIIX documents are organized as a hierarchy of JSON objects (called "Blocks" in this page) that mirrors the block hierarchy of a content part. Each object has a specific type string property identifying it as a text block, a diagram block, a math node, etc. and defining the block semantics.

For example, a simple diagram may aggregate a text label and a rectangular node:

{
 "type": "Diagram",
 "elements": [ {
   "type": "Text",
   ...
  }, {
   "type": "Node",
   "kind": "rectangle",
   ...
  } ],
 ...
}

This semantics, in turn defines how sub-blocks are aggregated. For example :

• A Diagram block will host an array of "Diagram Item" blocks under its elements property.
• A Math block will host an array of "Math Node" blocks under its expressions property.
• A generic Container block will host its sub-blocks under a children property.
• ...

Properties common to blocks

Whatever their types, all blocks share the following common properties:

For example, a simple drawing block can be represented as:

{
 "type": "Drawing",
 "id": "MainBlock",
 "bounding-box": {
  "x": 20.43125,
  "y": 31.272942,
  "width": 9.9375,
  "height": 8.9725456
 },
 ...
}

Other potential properties depend on the type of the block. Refer to the "blocks" section for more details.

Block content description

Block content is described using items, which represent what is actually visible when rendering the model.

Items

Items are used to describe the content of blocks in terms of ink, glyphs or shape primitives.

Like blocks, items share common properties:

Stroke item

A stroke item represents a standalone portion of ink, that is to say the trajectory of a writing tool between a pointer down and the corresponding pointer up.

It has the following specific properties:

Example:

{
  "timestamp": "2021-08-31 15:14:39.652000",
  "X": [ 58.5874977, 58.7666626, 58.7666626, 58.7666626, 58.7666626, 58.7666626, 58.9458313, 58.9458313,
  59.1249962, 59.4833298, 59.8416634, 60.0208321, 60.0208321, 60.0208321, 60.0208321, 60.0208321,
  60.1999969, 60.1999969, 60.3791618, 60.5583305, 60.5583305 ],
  "Y": [ 33.0518494, 33.0518494, 33.5907364, 34.1296272, 34.8481445, 35.5666618, 36.6444397, 37.5425873,
  39.159256, 40.7759209, 42.433329, 43.4703674, 44.7277718, 46.3444405, 47.4222183, 48.6796265,
  49.9370308, 50.4759216, 51.0148087, 51.0148087, 51.0148087 ],
  "F": [ 0, 0, 0, 0, 0, 0, 0, 0,
  0, 0, 0, 0, 0, 0, 0, 0,
  0, 0, 0, 0, 0 ],
  "T": [ 0, 14, 30, 38, 46, 54, 62, 70,
  78, 86, 94, 102, 110, 118, 126, 134,
  142, 150, 158, 166, 206 ],
  "type": "stroke",
  "id": "0000010001002900ff00"
}

Line item

A line item represents a converted line primitive, for instance the edge of a polygon.

It has the following specific properties:

Example:

{
  "type": "line",
  "timestamp": "2021-09-07 09:04:39.162000",
  "x1": 24.8770332,
  "y1": 19.7303886,
  "x2": 66.5452576,
  "y2": 19.7303886,
  "startDecoration": "none",
  "endDecoration": "none",
  "id": "0000010001000300ff00"
  }

Arc item

An arc item represents a converted arc primitive, for instance a curved connector in a diagram or a portion of an ellipse.

It has the following specific properties:

Example:

{
  "type": "arc",
  "timestamp": "2021-09-06 13:56:41.110000",
  "cx": 167.432373,
  "cy": 105.229813,
  "rx": 30.8068428,
  "ry": 7.45266199,
  "phi": 0,
  "startAngle": 0,
  "sweepAngle": 6.28318548,
  "startDecoration": "none",
  "endDecoration": "none",
  "id": "0000300001008900ff00"
  }

Glyph item

A glyph item represents a converted typeset character.

It has the following specific properties:

Example:

{
  "type": "glyph",
  "timestamp": "2021-09-06 13:55:37.298000",
  "label": "2",
  "bounding-box": {
  "x": 39.1022644,
  "y": 27.6022339,
  "width": 1.92954254,
  "height": 3.19965172
  }

Text interpretation

Text interpreted by iink SDK is represented by word and character objects as part of a Text block.

Word object

A word object represents the recognition of a word made by the MyScript engine. Note that to get such interpretation in JIIX export, your need to set the export.jiix.text.words configuration option to true.

It has the following properties:

Examples:

• Example corresponding to the word hello:

{
  "label": "hello",
  "candidates": [ "hello", "hells", "hellor", "helle", "kello" ],
  "first-char": 0,
  "last-char": 4,
  "bounding-box": {... },
  "items": [ ... ]
}

• Linefeed example, corresponding to the word \n:

{
   "label": "\n",
   "reflow-label": " "
}

Character object

A character object represents the recognition of a character made by the MyScript engine. Note that to get such interpretation in JIIX export, your need to set the export.jiix.text.chars configuration option to true.

It has the following properties:

Example:

{
  "label": "h",
  "candidates": [ "h", "k", "b", "H" ],
  "word": 0,
  "grid": [ {
    "x": 18.875834,
    "y": 31.736748
   }, {
    "x": 25.118258,
    "y": 31.736748
   }, {
    "x": 25.118258,
    "y": 44.957951
   }, {
    "x": 18.875834,
    "y": 44.957951
   } ],
  "bounding-box": { ... },
  "items": [ ... ]
 }

Style

The JIIX format can contain styling information. These encompass:

• CSS properties that you explicitly assign to the pen (dynamic styles)
• Style classes that you assign to the pen (pen style classes)
• Classes and styles automatically set by iink SDK when decorations are detected.

If you are exporting content, you need to set the export.jiix.style configuration key to true to get style information.

Item span styling

Blocks like Drawing and text/non-text raw content items can be seen as an ordered collection of strokes. Such a collection can be styled via the definition of "item spans", each span associating a specific style to a range of items.

Item spans have the following properties:

For example, if we write 2 strokes with pen style class set to "greenThickPen" then 2 more strokes with no pen style class but pen style set to "color : #FF324233", we obtain something like:

{
  "first-item": 0,
  "last-item": 1,
  "class": "greenThickPen"
}

and

{
 "first-item": 2,
 "last-item": 3,
 "style": "color: #FF324233"
}

Note that an item may be contain both class and style indications, or none of them if default styling applies.

Text span styling

Text blocks can be seen as an ordered collection of characters. Such a collection can be styled via the definition of "character spans", each span associating a specific style to a range of characters.

Item spans have the following properties:

For example, text underlined by a gesture may get the following style:

{
 "first-char": 0,
 "last-char": 12,
 "class": "text-emphasis1",
 "style": "color: #000000FF; -myscript-text-decoration-color: #000000FF; -myscript-text-decoration-background-color: #FFED2666"
}

Nodes styling

Blocks like math and diagram nodes, as well as diagram connectors are independently styled.

They can directly have the following properties:

For example, a math node can be styled as follows:

{
 "type": "number",
 "id": "math/170",
 "label": "3",
 "value": 3,
 "items": [ ... ],
 "bounding-box": { ... },
 "class": "greenThickPen"
}

Blocks

This section lists all available blocks of the hierarchy, their properties and particularities, if any.

Container block

A block of type Container groups children blocks together.

It has the following specific property:

For example, in the JIIX export of a "Text Document" part composed of two paragraphs of text, each paragraph will correspond to a text block and both will be grouped as the children of a same container block:

{
 "type": "Container",
 "id": "MainBlock",
 "bounding-box": { ... },
 "children": [ {
   "type": "Text",
   ...
  }, {
   "type": "Text",
   ...
  } ],
 ...
}

Diagram block

A block of type Diagram groups together the different internal blocks of an individual diagram.

It has the following specific property:

For example, a diagram may be composed of a Text label and of a diagram Node corresponding to a rectangle:

{
 "type": "Diagram",
 "id": "4",
 "bounding-box": { ... },
 "elements": [ {
   "type": "Text",
   ...
  }, {
   "type": "Node",
   "kind": "rectangle",
   ...
  } ],
 ...
}

Diagram item blocks

Diagram item blocks collectively form a family of blocks of different types describing the semantic structure of a diagram: connectors, text blocks, geometric shapes, etc. There is no actual "Diagram Item" type.

These blocks share the following common properties:

Diagram nodes and connectors (i.e. with type node, edge or polyedge) will get the following styling properties:

Style is only present in then JIIX export when export.jiix.style is configured to true.

Example:

{
 "id": "diagram/3/242",
 "type": "Node",
 "parent": 12,
 "bounding-box": { ... },
 "items": [ ... ],
 ... specific properties ...
}

➤ Diagram Node block

A diagram item of type Node is associated with a particular shape, an optional label, and may host child items. This is modeled by the following properties:

Depending on its "kind", the item will have specific properties:

• If "kind": "rectangle"
  • x - X coordinate of the upper-left corner of the rectangle.
  • y - X coordinate of the upper-left corner of the rectangle.
  • width - Width of the rectangle.
  • height - Height of the rectangle.
  • orientation - x-axis rotation angle of the selection box of the rectangle (when shape rotation is active).
• If "kind": "rhombus"
  • points - Array containing the 4 {x, y} points describing the rhombus.
  • orientation - x-axis rotation angle of the selection box of the rhombus (when shape rotation is active).
• If "kind": "polygon"
  • points - Array of {x, y} points describing the polygon.
  • orientation - x-axis rotation angle of the selection box of the polygon (when shape rotation is active).
• If "kind": "circle"
  • cx - X coordinate of the circle center.
  • cy - Y coordinate of the circle center.
  • r - Radius of the circle.
  • orientation - x-axis rotation angle of the selection box of the circle (when shape rotation is active).
• If "kind": "ellipse" : an axis aligned ellipse.
  • cx - X coordinate of the ellipse center.
  • cy - Y coordinate of the ellipse center.
  • rx - X radius of the ellipse.
  • ry - Y radius of the ellipse.
  • orientation - x-axis rotation angle of the selection box of the ellipse (when shape rotation is active).
• If "kind": "doodle"
  • No specific property describes a doodle.
  • Note: As doodles are not converted, items will never contain shape primitives.

For example, the following node represents a rectangle in a diagram, associated with a text label:

   "type": "Node",
   "kind": "rectangle",
   "orientation": -0.0148907145,
   "label-element": "diagram/22",
   "children": [ "diagram/22" ],
   "id": "diagram/13",
   "bounding-box": {
    "x": 61.7742119,
    "y": 51.8420029,
    "width": 82.0821991,
    "height": 36.4551468
   }

➤ Diagram Edge block

A diagram item of type Edge connects other diagram items.

Example of a "straight" edge:

{
  "type": "Edge",
  "kind": "line",
  "connected": [ "diagram/12", "diagram/47" ],
  "ports": [ 0, 0.521515965 ],
  "id": "diagram/85",
  "bounding-box": {... },
  "x1": 81.9797897,
  "y1": 49.3274384,
  "x2": 146.199982,
  "y2": 55.2804871,
  "p2Decoration": "arrow-head"
}

Note that as a "line" connector, the edge includes x1, y1, x2 and y2 properties, defined the exact same way than in the case of line items.

Example of a "curved" edge:

{
  "type": "Edge",
  "kind": "arc",
  "connected": [ "diagram/10", "diagram/53" ],
  "ports": [ 0, 1 ],
  "id": "diagram/105",
  "bounding-box": { ... },
  "items": [ ...  ],
  "cx": 120.779442,
  "cy": 74.4197159,
  "rx": 32.6964035,
  "ry": 32.6964035,
  "phi": 0.00504867753,
  "startAngle": -1.82163024,
  "sweepAngle": 3.53351736,
  "endDecoration": "arrow-head"
  }

Note that as an "arc" connector, the edge includes cx, cy, rx, ry, phi, startAngle and sweepAngle properties, defined the exact same way than in the case of arc items.

➤ Diagram Polyedge block

A diagram item of type Polyedge connects other diagram items via several other edges. It is associated with the following properties:

Example of a polyedge gathering three edges together:

{
 "type": "Edge",
 "kind": "polyedge",
 "id": "diagram/65",
 "connected": [ "diagram/37" ],
 "edges": [ {
   "type": "Edge",
   "kind": "line",
   ...
  }, {
   "type": "Edge",
   "kind": "line",
   ...
  }, {
   "type": "Edge",
   "kind": "line",
   ...
  } ]
}

➤ Diagram Text block

A diagram item of type Text combines the properties of a diagram item and those of a Text Block. It is styled using text spans.

Drawing block

A drawing block gathers raw digital ink.

It can have the following specific properties:

Example:

{
 "type": "Drawing",
 "id": "7",
 "bounding-box": { ... },
 "items": [ ... ],
 "spans": [ ... ],
 "image": { ... }
}

➤Drawing image object

   "image": {
    "url": "1630419125093723_20160701_212430.jpg",
    "mime-type": "image/jpeg",
    "x": 14.0750961,
    "y": 52.8047333,
    "width": 195.449829,
    "height": 109.940521
   }