Annotations

Annotations (aka Shapes, or 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.

Annotations can be created by the user. The user created ones are always in the User Shapes product.

An annotation is a geometry (e.g. point, line, polygon, ...) or a text label positioned geographically.

An annotation can be imported/exported in a custom Annotations JSON, GeoJSON, or KML formats.

Note: The KML format is partially supported.

DrawableShape

Type: object

Field Type Default Description
title string Required The tooltip of the toolbar button that allows the user to draw that annotation.
cssClassNames string Optional The CSS class names added to the toolbar button that allows the user to draw that annotation. Useful for customizing the icon.
wkt string Required The geometry of the drawable annotation formatted as WKT in the projection projection.

For each DrawableShape a button is added in the user annotations toolbar. For more info see Annotations.

Example
{
  title: 'Right Arrow',
  cssClassNames: '-RightArrow',
  wkt: 'MULTILINESTRING((0 0, 100 0),(90 10, 100 0, 90 -10, 90 10))',
}

Shape

Type: object

Field Type Default Description
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 its product's shapes array will be used.
type string Required The type of the shape. For more info see Shape Types.
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.

Shape Types

Text Shape

Type: 'TEXT'

Field Type Default Description
... ... ... The fields described in Shape.
location number[2] Required The coordinates of the shape defined as [lon, lat] both in EPSG:4326.

Note: Text shapes require the text field to contain a none-empty string.

Example
{
  type: 'TEXT',
  text: 'Text goes here',
  start: 1459814400000,
  end: 1459900800000,
  location: [133, -21]
}

Arrow Shape

Type: 'ARROW'

Field Type Default Description
... ... ... The fields described in Shape.
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.

Note: Arrow shapes require the points field to contain exactly 2 points.

Example
{
  type: 'ARROW',
  text: '',
  start: 1459814400000,
  end: 1459900800000,
  points: [
    [28, -33],
    [27, -33]
  ]
}

Line Shape

Type: 'LINE'

Field Type Default Description
... ... ... The fields described in Shape.
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.
Example
{
  type: 'LINE',
  text: '',
  start: 1459814400000,
  end: 1459900800000,
  points: [
    [132, -26],
    [136, -26]
  ],
  arrow: {
    directionFlipped: false,
    sideFlipped: false,
    ratio: 0.5,
    density: 0.5,
    offset: 0.5
  }
}

Ellipse Shape

Type: 'ELLIPSE'

Field Type Default Description
... ... ... The fields described in Shape.
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.
Example
{
  type: 'ELLIPSE',
  text: 'C',
  start: 1459814400000,
  end: 1459900800000,
  center: [134, -23],
  rx: 244598,
  ry: 244598,
  angle: 0,
  arrow: {
    directionFlipped: false,
    sideFlipped: false,
    ratio: 0.5,
    density: 0.2,
    offset: 0.125
  }
}

Mushroom Shape

Type: 'MUSHROOM'

Field Type Default Description
... ... ... The fields described in Shape.
baseAnchor number[2] ∈ [-1, 1] [0, 1] The relative position of the inner extremity of the base as [x, y] each between -1 and 1, where [-1, -1] indicates a position half-lobe-centers-distance above the left lobe's center, and [1, 1] half-lobe-centers-distance below the right lobe's center.
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.
Example
{
  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
}

Generic Shape

Type: 'WKT'

Field Type Default Description
... ... ... The fields described in Shape.
author string Optional The author associated to the shape.
wkt string Required The geometry of the shape formatted as WKT in EPSG:4326.
Example
{
  type: 'WKT',
  text: 'text',
  start: 1149163200000,
  end: 1149163200000,
  author: 'anonymous',
  wkt: 'POLYGON((77. 59,40 44,64 21,111 45,94 56,77 59))',
}

ShapeArrow

Type: object

Field Type Default Description
directionFlipped boolean false If true the arrow will point from the end of the line segment to its start, instead of start to end. In the case of an ellipse false means counter-clockwise and true means clockwise.
sideFlipped boolean or 'none' false If true the colors of the arrow head are swapped. If 'none' the arrow head as an outline with the same color as the shape.
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
}

ShapeStyleMap

Type: object

Field Type Default Description
ALL ShapeStyle Optional The style applied to all shapes.
TEXT ShapeStyle Optional The style applied to Text shapes. Overrides the "ALL" style.
ARROW ShapeStyle Optional The style applied to Arrow shapes. Overrides the "ALL" style.
LINE ShapeStyle Optional The style applied to Line shapes. Overrides the "ALL" style.
ELLIPSE ShapeStyle Optional The style applied to Ellipse shapes. Overrides the "ALL" style.
MUSHROOM ShapeStyle Optional The style applied to Mushroom shapes. Overrides the "ALL" style.
WKT ShapeStyle Optional The style applied to Generic shapes. Overrides the "ALL" style.
Example
{
  ALL: {
    strokeColor: '#00EE00',
    fillOpacity: 0,
    fontColor: '#00EE00',
    fontSize : 16,
  },
  WKT: {
    strokeColor: '#AAAAEE',
    fillOpacity: 0.4,
    strokeDashstyle: 'dash',
    fontColor: '#AAAAEE',
    fontSize : 12,
  },
}

ShapeStyle

Type: object

Field Type Default Description
pointRadius number > 0 10 The radius in pixels of the point disk marker when rendered on the screen.
fillColor SVGPaint '#AAAAAA' The color of the shape's inside.
fillOpacity number ∈ [0, 1] 0.4 The opacity of the fill color. 0.0 (fully transparent) to 1.0 (fully opaque).
strokeColor SVGPaint '#AAAAEE' The color of the shape's outline.
strokeOpacity number ∈ [0, 1] 1 The opacity of the stroke color. 0.0 (fully transparent) to 1.0 (fully opaque).
strokeWidth number >= 0 2 The width of the outline on the polygon. If a value of 0 is used the outline will never be drawn.
strokeDashstyle string 'solid' Controls the pattern of dashes and gaps used to stroke the polygon. Can be one of ('dot', 'dash', 'dashdot', 'longdash', 'longdashdot', 'solid') or a list of white space separated <length>s and <percentage>s that specify the lengths of alternating dashes and gaps. If an odd number of values is provided, then the list of values is repeated to yield an even number of values. Thus, '5 3 2' is equivalent to '5 3 2 5 3 2'.
fontColor SVGPaint '#AAAAAA' The color used to render the text.
fontSize number >= 0 12 The text size in pixels when rendered on the screen.
Example
{
  strokeColor: '#00EE00',
  fillOpacity: 0,
}

Annotations JSON file

A custom JSON based format for saving annotations to a file. It consists of a single Shape object or an array of Shapes.

Examples

Single generic shape

{
  "type": "WKT",
  "text": "text",
  "start": 1149163200000,
  "end": 1149163200000,
  "author": "anonymous",
  "wkt": "POLYGON((77 59,40 44,64 21,111 45,94 56,77 59))"
}

Multiple shapes

[
  {
    "type": "TEXT",
    "text": "Text goes here",
    "start": 1459814400000,
    "end": 1459900800000,
    "location": [133, -21]
  },
  {
    "type": "ARROW",
    "text": "",
    "start": 1459814400000,
    "end": 1459900800000,
    "points": [[28,-33],[27,-33]]
  }
]