Syntool JSON Shapes format

syntool_json_shapes_format.md

Syntool JSON Shapes format

Table of Contents

• Introduction
• JSON Shapes file
• Types
  • Shape
  • ShapeType
  • ShapeArrow

Introduction

Shapes (aka User shapes) are special datasets. They may have an author and a label (which can hold any text value). They are filtered based on their label not their ID.

Shapes can be created by the user. The user created ones are always in the product of type "USER_SHAPES". A shape is a geometry (e.g. point, line, polygon, ...) or a text label positioned geographically. A shape can be imported and exported. The exported shapes are in the same format accepted in the config (see Shape).

JSON Shapes file

A JSON Shapes file can be imported into Syntool and consists of a single Shape object or a JSON array of Shapes.

Examples

Single WKT shape

{
  "type": "WKT",
  "text": "text",
  "start": 1149163200000,
  "end": 1149163200000,
  "author": "anonymous",
  "wkt": "POLYGON((77.51953122494571 59.26588064106204,40.95703122494571 44.339565266015946,64.68749997494598 21.453068656405353,111.26953122494571 45.21300357364395,94.04296872494179 56.46249049773187,77.51953122494571 59.26588064106204))"
}

Multilple shapes

[
  {
    "type": "TEXT",
    "text": "Text goes here",
    "start": 1459814400000,
    "end": 1459900800000,
    "location": [133.23063184654524, -21.083556353366014]
  },
  {
    "type": "ARROW",
    "text": "",
    "start": 1459814400000,
    "end": 1459900800000,
    "points": [[28.762538978264597,-33.09396148741701],[27.872646400139594,-33.745014639370424]]
  }
]

Types

Shape

Type: object

Field	Type	Default	Description
General
id	string	Optional	The ID of the shape used to generate the corresponding dataset's ID. If not given, the index of the shape in it's product's shapes array will be used.
type	ShapeType	Required	The type of the shape. For more info see ShapeType.
text	string	Optional	The label displayed with the shape. Also used for filtering.
start	Date or number	Optional	If provided, the shape will be hidden before that date. A number is considered as milliseconds since 1 January 1970 00:00:00 UTC.
end	Date or number	Optional	If provided, the shape will be hidden starting from that date. A number is considered as milliseconds since 1 January 1970 00:00:00 UTC.
color	Color	Optional	If provided, will be used to color the shape.
Arrow Shape			Applies to "ARROW" shapes only
points	number[2][2]	Required	A couple of coordinates pairs defined as [lon, lat] both in EPSG:4326. The first pair marks the start (the tail) of the arrow. The second marks the end (the head) of the arrow.
arrowSize	number > 0	15000	The size in meters of the arrow head.
Text Shape			Applies to "TEXT" shapes only
location	number[2]	Required	The coordinates of the shape defined as [lon, lat] both in EPSG:4326.
Line Shape			Applies to "LINE" shapes only
points	number[2][]	Required	A list of at least two coordinate pairs defined as [lon, lat] both in EPSG:4326.
arrow	ShapeArrow	Optional	The description of an optional arrow head to rendered on the line. For more info see ShapeArrow.
Ellipse Shape			Applies to "ELLIPSE" shapes only
center	number[2]	Required	The coordinates of the center of the ellipse defined as [lon, lat] both in EPSG:4326.
rx	number > 0	Required	The radius of the ellipse on the x-axis in meters.
ry	number > 0	rx	The radius of the ellipse on the y-axis in meters.
angle	number ∈ [-180, 180]	0	The amount of rotation applied to the ellipse in degrees (counter-clockwise).
arrow	ShapeArrow	Optional	The description of an optional arrow head to rendered on the line. For more info see ShapeArrow.
Mushroom Shape			Applies to "MUSHROOM" shapes only
baseWidth	number >= 0	Required	The distance between the two vertical edges of the base of the mushroom in meters.
baseHeight	number >= 0	Required	The length of base of the mushroom in meters.
baseAngle	number ∈ [-45, 45]	0	The amount of rotation applied to the base of the mushroom in degrees (counter-clockwise).
leftLobeCenter	number[2]	Required	The coordinates of the center of the left lobe defined as [lon, lat] both in EPSG:4326.
leftLobeRx	number >= 0	Required	The radius of the left lobe ellipse on the x-axis in meters.
leftLobeRy	number >= 0	Required	The radius of the left lobe ellipse on the y-axis in meters.
rightLobeCenter	number[2]	Required	The coordinates of the center of the right lobe defined as [lon, lat] both in EPSG:4326.
rightLobeRx	number >= 0	Required	The radius of the right lobe ellipse on the x-axis in meters.
rightLobeRy	number >= 0	Required	The radius of the right lobe ellipse on the y-axis in meters.
Generic Shape			Applies to "WKT" shapes only
author	string	Optional	The author associated to the shape.
wkt	string	Required	The geometry of the shape formatted as WKT in EPSG:4326.

Notes

• All "TEXT" shapes require the text field to contain a none-empty string.
• All "ARROW" shapes require the points field to contain exactly 2 points.

Examples

{
  "type": "TEXT",
  "text": "Text goes here",
  "start": 1459814400000,
  "end": 1459900800000,
  "location": [133.23063184654524, -21.083556353366014]
}

{
  "type": "ARROW",
  "text": "",
  "start": 1459814400000,
  "end": 1459900800000,
  "points": [[28.762538978264597,-33.09396148741701],[27.872646400139594,-33.745014639370424]]
}

{
  "type": "LINE",
  "text": "",
  "start": 1459814400000,
  "end": 1459900800000,
  "points": [[132.48356160920454,-26.78394450491424],[136.1749678592054,-26.469667679940457]],
  "arrow": {
    "directionFlipped": false,
    "sideFlipped": false,
    "ratio": 0.5,
    "density": 0.5,
    "offset": 0.5
  }
}

{
  "type": "ELLIPSE",
  "text": "C",
  "start": 1459814400000,
  "end": 1459900800000,
  "center": [134.02164747155183,-23.945171626522214],
  "rx": 244598.49047851562,
  "ry": 244598.49047851562,
  "angle": 0,
  "arrow": {
    "directionFlipped": false,
    "sideFlipped": false,
    "ratio": 0.5,
    "density": 0.2,
    "offset": 0.125
  }
}

{
  "type": "MUSHROOM",
  "text": "",
  "start": 1486944000000,
  "end": 1487203200000,
  "baseWidth": 955.4628534317018,
  "baseHeight": 1997.5447529548906,
  "baseAngle": 0.6778513460412228,
  "leftLobeCenter": [-4.814060593358906, 48.0702570920605],
  "leftLobeRx": 761.6419180129138,
  "leftLobeRy": 645.4213335569948,
  "rightLobeCenter": [-4.8014029583976665, 48.07037335406251],
  "rightLobeRx": 739.6453667184011,
  "rightLobeRy": 664.7914310097694
}

{
  "type": "WKT",
  "text": "text",
  "start": 1149163200000,
  "end": 1149163200000,
  "author": "anonymous",
  "wkt": "POLYGON((77.51953122494571 59.26588064106204,40.95703122494571 44.339565266015946,64.68749997494598 21.453068656405353,111.26953122494571 45.21300357364395,94.04296872494179 56.46249049773187,77.51953122494571 59.26588064106204))"
}

ShapeType

Type: string Possible values:

• 'TEXT'
• 'ARROW'
• 'LINE'
• 'ELLIPSE'
• 'MUSHROOM'
• 'WKT'

Notes

• All "TEXT" shapes require the text field to contain a none-empty string.
• All "ARROW" shapes require the points field to contain exactly 2 points.

ShapeArrow

Type: object

Field	Type	Default	Description
directionFlipped	boolean	false	If true the arrow will point from the end of the line segment to it's start, instead of start to end. In the case of an ellipse false means counter-clockwise and true means clockwise.
sideFlipped	boolean	false	If true the colors of the arrow head are swapped.
ratio	number ∈ [0, 1]	0.5	The ratio of the proportion of the left triangle and the right.
density	number ∈ [0, 1]	see below	The density of arrow heads on the shape. 0 means one arrow head, and 1 means arrow head on each line segment.
offset	number ∈ [0, 1]	see below	The offset of the first arrow head. 0 means on the first line segment, and 1 means on the last.
size	number > 0	15000	The size in meters of the arrow head.

Default values by type

Type	density	offset
'LINE'	0.5	0.5
'ELLIPSE'	0.2	0.125

Example

{
  "directionFlipped": false,
  "sideFlipped": false,
  "ratio": 0.5,
  "density": 0.2,
  "offset": 0.125
}