Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Syntool JSON Shapes format

Syntool JSON Shapes format

Table of Contents

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
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment