Drawing annotations

Note: Annotations were previously referred to as Elements.

References have been updated in the app and documentation, while naming in the REST API and JS SDK remains unchanged.

The Felt SDK provides two main approaches for creating annotations on your maps:

1. Interactive Drawing: Configure and activate drawing tools for users to create annotations manually

2. Programmatic Creation: Create and modify annotations directly through code

Annotations created via the SDK are session-specific - they're not persisted to the map and won't be visible to other users.

Interactive Drawing with Tools

The methods on the ToolsController enable you to programmatically activate drawing tools for your users, as well as setting various options for the tools, such as color, line width, etc.

Use the setTool method to activate a particular tool.

Use the setToolSettings method to configure the options for a specific tool.

Use the onToolChange and onToolSettingsChange to be notified of changes to the above, or read them instantaneously with the getTool and getToolSettings methods.

As the user creates annotations with the tools, you can be notified of them being created and updated using the onElementCreate and onElementChange listeners. See Listening for annotation creation for more details.

Tool types

Tool name	Annotation Type	Description
pin	Place	Creates a single point on a map, with a symbol and optional label
line	Line	Creates a sequence of straight lines through the points that the user clicks
route	Line	Creates a line that follows the routing logic depending on the mode of transport selected. For instance, walking, driving and cycling routes follow applicable roads and pathways to reach the waypoints the user provides. Flying routes follow great circle paths.
polygon	Polygon	Creates an enclosed area with straight edges
circle	Circle	A circle is defined by its center and radius.
marker	Marker	Freeform drawing with a pen-like rendering. Different sizes can be set for the pen. The geometry produced is in world-space, so as you zoom the map, the pen strokes remain in place.
highlighter	Highlighter	Represents an area of interest, created by drawing with a thick pen. By default, drawing an enclosed shape fills the interior.
text	Text	A label placed on the map with no background color.
note	Note	A label placed on the map with a rectangular background color and either white or black text.

Example

// Configure the line tool
felt.setToolSettings({
  tool: "line",
  strokeWidth: 8,
  color: "#448C2A"
});

// Activate the line tool
felt.setTool("line");

// Later, deactivate the tool
felt.setTool(null);

Programmatic Annotation Creation

If you want to create annotations programmatically instead of letting your users draw them interactively on the map, use the methods in the ElementsController.

To create annotations, use the createElement method.

To update annotations, use the updateElement method.

To delete annotations, use the deleteElement method.

When annotations are created programatically, they also trigger notifications about the corresponding changes to annotations, via onElementCreate, onElementChange and onElementDelete.

Example

// Create a polygon
const polygonElement = await felt.createElement({
  type: "Polygon",
  coordinates: [
    [
      [-122.42, 37.78],
      [-122.41, 37.78],
      [-122.41, 37.77],
      [-122.42, 37.77],
      [-122.42, 37.78]
    ]
  ],
  color: "#FF5733",
  fillOpacity: 0.5
});
​

// Update its properties
await felt.updateElement({
  id: polygonElement.id,
  
  // note that we pass the type here, too in order to get correct
  // TypeScript type-checking and autocompletion.
  type: "Polygon",
  
  color: "#ABC123",
  fillOpacity: 0.5,
  strokeWidth: 2
});

// Finally delete the element
await felt.deleteElement(polygonElement.id)

Retrieving Annotation geometry

Extract the geometric representation of annotations using the getElementGeometry method.

The geometry is returned in GeoJSON geometry format, which can be quite different to the way the annotation is specified in Felt. For example, Circle annotations in Felt have their geometry converted into a polygon, representing the area covered by the circle.

Note: Text, Note, and Image annotations do not return geometry as they are considered to annotations rather than true "geospatial" annotations.

// Get an element's geometry in GeoJSON format
const geometry = await felt.getElementGeometry("element-1");
console.log(geometry?.type, geometry?.coordinates);

Listening for changes

Every change that is made to the annotations on a map results in a call to either onElementCreate, onElementDelete or onElementChange.

// Set up a listener for changes to a polygon
const unsubscribeChange = felt.onElementChange({
  options: { id: polygon.id },
  handler: ({element}) => {
    console.log("Polygon was updated:", element);
  }
});
​
// Set up a listener for deletion
const unsubscribeDelete = felt.onElementDelete({
  options: { id: polygon.id },
  handler: () => {
    console.log("Polygon was deleted");
  }
});
​
// Later, clean up listeners
unsubscribeChange();
unsubscribeDelete();

Listening for annotation creation

There are two different ways for listening to annotations being created, and the one you use depends on how the annotation is being created, and at what point you want to know about an annotation's creation.

When the user is creating annotations with tools, they are often created in a number of steps, such as drawing a marker stroke or creating a polygon with many vertices.

When you want to know when the user has finished creating the annotation (e.g. the polygon was closed or the marker stroke ended) then you should use the onElementCreateEnd listener.

When annotations are created programmatically, they do not trigger the onElementCreateEnd event.

Annotations created using Tools or createElement will trigger the onElementCreate event, with an extra property stating whether the annotation is still being created.

// Listen for any element creation
const unsubscribe = felt.onElementCreate({
  handler: (element) => {
    console.log(`New element created with ID: ${element.id}`);
    
    // Check if the element is still being drawn
    if (element.isBeingCreated) {
      console.log("User is still creating this element");
    }
  }
});

// Or listen for when element creation is completed with a tool
const unsubscribeEnd = felt.onElementCreateEnd({
  handler: ({element}) => {
    console.log(`Element ${element.id} creation finished`);
  }
});

// Later, clean up listeners
unsubscribe();
unsubscribeEnd();

Sample application: sending annotations drawn by users to your backend

Here is an example showing the power of the Felt SDK, where in just a few lines of code you can allow your users to draw annotations and have them sent to your own backend systems for persistence or analysis.

Assuming you have embedded your Felt map as described in Getting started, and in your own UI you have added a polygon-tool button and a reset-tool button, all you need is the following:

// Set your initial tool settings in a style that suits your application
felt.setToolSettings({
  tool: "polygon",
  strokeWidth: 2,
  color: "#FF5733",
  fillOpacity: 0.3,
});
  
// Activate the tool when the user clicks a button in your UI
​document.getElementById("polygon-tool").addEventListener("click", () => {
  felt.setTool("polygon");
});
​
// Disable the tool when the user clicks a button in your UI
document.getElementById("reset-tool").addEventListener("click", () => {
  felt.setTool(null);
});
​
// Listen for completed polygons
felt.onElementCreateEnd({
  handler: async ({element}) => {
    // get the polygon geometry that the user just drew
    const geometry = await felt.getElementGeometry(element.id);
    
    // send the polygon to your own backend system
    sendToServer(geometry);
  }
});