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:
Interactive Drawing: Configure and activate drawing tools for users to create annotations manually
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 theToolsController 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 thesetTool method to activate a particular tool.
Use thesetToolSettings method to configure the options for a specific tool.
Use theonToolChange andonToolSettingsChange to be notified of changes to the above, or read them instantaneously with thegetTool andgetToolSettings methods.
As the user creates annotations with the tools, you can be notified of them being created and updated using theonElementCreate andonElementChange listeners. SeeListening for annotation creation for more details.
Tool types
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
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 theElementsController.
To create annotations, use thecreateElement method.
To update annotations, use theupdateElement method.
To delete annotations, use thedeleteElement method.
When annotations are created programatically, they also trigger notifications about the corresponding changes to annotations, viaonElementCreate,onElementChange andonElementDelete.
Example
Retrieving Annotation geometry
Extract the geometric representation of annotations using thegetElementGeometry 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.
Listening for changes
Every change that is made to the annotations on a map results in a call to eitheronElementCreate,onElementDelete oronElementChange.
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 hasfinished creating the annotation (e.g. the polygon was closed or the marker stroke ended) then you should use theonElementCreateEnd listener.
When annotations are created programmatically, they do not trigger theonElementCreateEnd event.
Annotations created using ToolsorcreateElement will trigger theonElementCreate event, with an extra property stating whether the annotation is still being created.
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 inGetting started, and in your own UI you have added apolygon-tool button and areset-tool button, all you need is the following:
Last updated
Was this helpful?