Markers and Annotations

The Nextbillion Android Maps SDK provides a rich set of annotations that allow developers to add customized information and interactive elements to their maps. Annotations in the SDK can be used to represent various types of geographic features, such as points, lines, polygon shapes, and circles. Each annotation type has its own set of data-driven and constant properties, which developers can use to control its appearance, behavior, and interaction. By using annotations, developers can create interactive and visually appealing maps that engage their users and enhance their applications.

There are two approaches to adding annotations to the MapView, the first is to use NextbillionMap, and the second is to use AnnotationManager and Style. These approaches provide different levels of customization and control, allowing developers to choose the best fit for their specific needs.

NextbillionMap

NextbillionMap is the interface between developers and the Maps SDK, it provides many useful interface methods to allow developers to make changes to the MapView, the interface methods we are going to cover in this section are part of the class NextbillionMap.

Marker

The NextbillionMap Marker is a feature in the Android Maps SDK provided by Nextbillion that allows developers to add custom markers to a MapView. These markers can represent a variety of information such as location, points of interest, or custom graphics and can be added to the map as annotations. The NextbillionMap Marker is a convenient tool for mapping and visualizing data, making it easier for users to understand and interact with the information being presented.

Interface

The NextbillionMap interface provides methods to add markers on the map. There are three methods to add a single marker, one that takes a LatLng position, another that takes a MarkerOptions object and a third that takes a BaseMarkerOptions object. There is also a method to add multiple markers at once by passing a list of BaseMarkerOptions objects. Finally, the interface provides a way to set an OnMarkerClickListener, which is a listener that listens for click events on markers on the map.

1
public Marker addMarker(@NonNull LatLng position)
2

3
public Marker addMarker(@NonNull MarkerOptions markerOptions)
4

5
public Marker addMarker(@NonNull BaseMarkerOptions markerOptions)
6

7
public List<Marker> addMarkers(@NonNull List<? extends BaseMarkerOptions> markerOptionsList)
8

9
public void setOnMarkerClickListener(@Nullable OnMarkerClickListener listener);

Example

1
nextbillionMap.addMarker(new LatLng(12.97551913,77.58917229));

This code adds a marker to the NextbillionMap at the given latitude and longitude (12.97551913, 77.58917229).

Event

1
The NextbillionMap can also set one MakerClickListener to every MapView’s NextbillionMap instance(each NextbillionMap can only have one MakerClickListener).
2
nextbillionMap.setOnMarkerClickListener(new NextbillionMap.OnMarkerClickListener() {
3
   @Override
4
   public boolean onMarkerClick(@NonNull Marker marker) {
5
       if("Title".equals(marker.getSnippet())){
6
           //your logic
7
       }
8
       return false;
9
   }
10
});

This code sets a listener for when a user clicks on a marker on a NextbillionMap instance. If the marker's snippet equals "Title", a custom logic block is executed. The method returns a boolean value indicating whether the event has been consumed.

Update a Marker

According to what we have mentioned earlier, each method to add a marker(s) will return the added marker(s), which will be a handle to modify the newly created marker.

1
Marker marker = nextbillionMap.addMarker(new LatLng(12.97551913,77.58917229));

with this instance, you can update it’s properties dynamically.

Custom Marker Icon

1
Bitmap iconBitmap = your bitmap logic;
2
marker.setIcon(IconFactory.getInstance(MarkerActivity.this).fromBitmap(iconBitmap));

This code sets a custom marker icon for a marker. The custom icon is created by using the "iconBitmap" variable which is the result of the custom logic implemented to generate the bitmap. Then, the method "setIcon()" is called on the marker instance, which takes the custom bitmap as input and sets it as the marker icon using the "IconFactory.getInstance()" method. The IconFactory is used to create an Icon object from a Bitmap.

Remove a Marker

You can remove a marker by calling removeMarker method of NextbillionMap

1
nextbillionMap.removeMarker(marker);

Info Window

The Marker has a built-in InfoWindow, you can show InfoWindow by clicking on the Marker if you have assigned a title or snippet to your MarkerOptions.

1
nextbillionMap.addMarker(new MarkerOptions().position(new LatLng(12.97780156,77.59656748)).title("Title"));
2
nextbillionMap.addMarker(new MarkerOptions().position(new LatLng(12.98208919,77.60329262)).snippet("Snippet"));

Customize InfoWindow

1
nextbillionMap.setInfoWindowAdapter(new NextbillionMap.InfoWindowAdapter() {
2
   @Nullable
3
   @Override
4
   public View getInfoWindow(@NonNull Marker marker) {
5
      //Logic of customizing infoWindow's View
6
       return your view;
7
   }
8
});

This is a code block for customizing the InfoWindow for a marker on a NextbillionMap. The method setInfoWindowAdapter sets a custom adapter for the InfoWindow, allowing the user to define their own layout for the InfoWindow. The getInfoWindow method is called to get the custom view that should be displayed as the InfoWindow. The logic for customizing the InfoWindow view is included in this method and the resulting view is returned.

Polyline

Polyline in Android Maps SDK refers to a series of connected line segments on a map. It is used to represent a route, path, or boundary on a map. In the Android Maps SDK, Polyline is a class that can be used to draw polylines on a MapView. The polylines can be customized with various styles, such as width, color, and opacity. Additionally, Polyline objects can also be used to interact with the map, for example, to listen for clicks on a specific polyline.

Interface

1
public Polyline addPolyline(@NonNull LatLng origin, @NonNull LatLng dest, int color)
2

3
public Polyline addPolyline(@NonNull LatLng origin, @NonNull LatLng dest, String color)
4

5
public Polyline addPolyline(@NonNull List<LatLng> points, int color)
6

7
public Polyline addPolyline(@NonNull List<LatLng> points, String color)
8

9
public Polyline addPolyline(@NonNull PolylineOptions polylineOptions)
10

11
public List<Polyline> addPolylines(@NonNull List<PolylineOptions> polylineOptionsList)
12
  
13
public void setOnPolylineClickListener(@Nullable OnPolylineClickListener    listener)

The above code is an interface for adding Polylines to the Android Maps SDK. The interface provides several methods to add Polylines to the map, including adding a Polyline between two points, adding multiple Polylines to the map, and adding a Polyline using PolylineOptions. Additionally, the interface includes a method to set an OnPolylineClickListener, which can be used to listen for clicks on the Polylines.

Example

1
nextbillionMap.addPolyline(origin, dest, 0xff00ffff);

This example shows how to add a polyline to a NextbillionMap. The addPolyline() method is called with origin and dest LatLng coordinates, and an integer representing the color of the line in ARGB format (0xff00ffff represents a bright green color). The method returns a Polyline instance that can be used to further customize the line.

Event

Similar to markers, we can set one OnPolylineClickListener to every MapView’s NextbillionMap instance.

1
nextbillionMap.setOnPolylineClickListener(new NextbillionMap.OnPolylineClickListener() {
2
    @Override
3
    public void onPolylineClick(@NonNull Polyline polyline) {
4

5
    }
6
});

If the SDK detects that a polyline has been clicked, the onPolylineClick method will be called with a non-null instance of Polyline as its argument. Otherwise, the method will not be called. Developers can use this listener to perform actions in response to polyline clicks, such as displaying information about the polyline or navigating to a different location on the map.

Polygon

Polygon is a feature in the Android Maps SDK that allows the representation of shapes on the map. It can be used to display geographical areas, such as a park, lake or building, by connecting multiple points on the map. The Android Maps SDK provides a simple and convenient way to add Polygons to the map, making it easy to visualize and display specific regions of interest. With the Polygon feature, you can create custom shapes with different colors and widths, and also define listeners to handle events such as clicking on the Polygon.

Interface

This is a list of methods available in Android Maps SDK for creating and adding polygon shapes to a map. The method addPolygon can be used to add a polygon shape to the map, with either a list of LatLng points, a color code, or a PolygonOptions object. The method addPolygons can be used to add multiple polygon shapes at once. The setOnPolygonClickListener method allows to set a listener that will be triggered when a polygon shape is clicked on the map.

1
public Polygon addPolygon(@NonNull List<LatLng> points, int color)
2

3
public Polygon addPolygon(@NonNull List<LatLng> points, String color)
4

5
public Polygon addPolygon(@NonNull PolygonOptions polygonOptions)
6

7
public List<Polygon> addPolygons(@NonNull List<PolygonOptions> polygonOptionsList)
8

9
public void setOnPolygonClickListener(@Nullable OnPolygonClickListener listener);

Example

1
nextbillionMap.addPolygon(points, 0xffff0000);

The above code shows an example of adding a Polygon to a NextbillionMap with a color specified in the hexadecimal format of 0xffff0000.

Event

Similar to markers and polylines, we can set one OnPolygonClickListener to every MapView’s NextbillionMap instance.

1
nextbillionMap.setOnPolygonClickListener(new NextbillionMap.OnPolygonClickListener() {
2
    @Override
3
    public void onPolygonClick(@NonNull Polygon polygon) {
4

5
    }
6
});
7

An non-null instance of Polygon will be returned once the SDK has detected a Polygon get clicked, otherwise the method onPolygonClick will not be called.

AnnotationManager and Style

According to previous guide: We can add source-layers to Style

https://geojson.org/

Essentially, every AnnotationManager will create and add a GeoJSONSource to Style, and ultimately, all annotations(Symbols, Lines, Fills and Circles) will be converted to GeoJSON features and updated to the GeoJSONSource it maintains.

Each Annotation has a major Annotation class, an options class, and a manager class. The relationship between the major annotation class and the options class is one-to-one, The relationship between the manager and the major annotation class is one-to-many.

Normally an annotation has two groups of properties,

Data-driven properties: the properties can be dynamically changed based on data attributes. This provides developers with a high level of customization and flexibility to tailor the map to their specific use case.
Constant properties: control the position and orientation of the map elements, further enhancing the customization options available to developers. The options class is used to configure the data-driven properties, and the manager class is for constant properties, other than properties, the manager class also exposes interfaces to add and remove relevant event listeners, such as
dragListener
clickListener
longClickListener

The step to plot an annotation is:

Create a manager
Create an option
Pass the options to the create() method of the manager to create an annotation

For example Symbol, SymbolOptions, and SymbolManager.

Symbol

The Android Maps SDK allows the addition of symbols as annotations to the map. These symbols serve as a visual representation of a specific location or feature and can be customized in terms of shape, color, and size.

Data-driven properties

This is a list of data-driven properties that can be set for a feature in a map using Android Maps SDK. The properties include the feature's draggability, data associated with it, its geometry, sorting key, icon details like size, image, rotation, and offset, text field, font, size, letter spacing, justification, radial offset, anchor, and transform, opacity and color details for both icon and text, and halo details like color, width, and blur for both icon and text.

1
  private boolean isDraggable;
2
  private JsonElement data;
3
  private Point geometry;
4
  private Float symbolSortKey;
5
  private Float iconSize;
6
  private String iconImage;
7
  private Float iconRotate;
8
  private Float[] iconOffset;
9
  private String iconAnchor;
10
  private String textField;
11
  private String[] textFont;
12
  private Float textSize;
13
  private Float textMaxWidth;
14
  private Float textLetterSpacing;
15
  private String textJustify;
16
  private Float textRadialOffset;
17
  private String textAnchor;
18
  private Float textRotate;
19
  private String textTransform;
20
  private Float[] textOffset;
21
  private Float iconOpacity;
22
  private String iconColor;
23
  private String iconHaloColor;
24
  private Float iconHaloWidth;
25
  private Float iconHaloBlur;
26
  private Float textOpacity;
27
  private String textColor;
28
  private String textHaloColor;
29
  private Float textHaloWidth;
30
  private Float textHaloBlur;

Constant properties

1
 public void setSymbolPlacement(@Property.SYMBOL_PLACEMENT String value)
2
 public void setSymbolSpacing( Float value)
3
 public void setSymbolAvoidEdges( Boolean value)
4
 public void setIconAllowOverlap( Boolean value)
5
 public void setIconIgnorePlacement( Boolean value)
6
 public void setIconOptional( Boolean value)
7
 public void setIconRotationAlignment(@Property.ICON_ROTATION_ALIGNMENT String value)
8
 public void setIconTextFit(@Property.ICON_TEXT_FIT String value)
9
 public void setIconTextFitPadding( Float[] value)
10
 public void setIconPadding( Float value)
11
 public void setIconKeepUpright( Boolean value)
12
 public void setIconPitchAlignment(@Property.ICON_PITCH_ALIGNMENT String value)
13
 public void setTextPitchAlignment(@Property.TEXT_PITCH_ALIGNMENT String value)
14
 public void setTextRotationAlignment(@Property.TEXT_ROTATION_ALIGNMENT String value)
15
 public void setTextLineHeight( Float value)
16
 public void setTextVariableAnchor( String[] value)
17
 public void setTextMaxAngle( Float value)
18
 public void setTextPadding( Float value)
19
 public void setTextKeepUpright( Boolean value)
20
 public void setTextAllowOverlap( Boolean value)
21
 public void setTextIgnorePlacement( Boolean value)
22
 public void setTextOptional( Boolean value)
23
 public void setIconTranslate( Float[] value)
24
 public void setIconTranslateAnchor(@Property.ICON_TRANSLATE_ANCHOR String value)
25
 public void setTextTranslate( Float[] value)
26
 public void setTextTranslateAnchor(@Property.TEXT_TRANSLATE_ANCHOR String value)

The above code lists the constant properties of a symbol layer in the Android Maps SDK. The properties define the behavior and appearance of the symbols on a map layer. For example, the setSymbolPlacement method sets the placement of the symbols in relation to the geometry they represent. The setIconAllowOverlap method determines whether or not icons can overlap with each other. Similarly, setTextPitchAlignment sets the vertical alignment of the text in relation to its anchor. These properties help to customize the look and feel of the symbols in a map layer.

Line

Line annotations in Nextbillion.ai’s Android Maps SDK allow developers to display lines or paths on the map. With this feature, it is possible to represent linear features such as roads, rivers, and borders, with custom styles and attributes. The SDK provides data-driven and constant properties to control the appearance of lines, such as line width, color, join, opacity, and more. The line annotations are drawn over the base map tiles and can be updated dynamically as the map view changes, making them a powerful tool for visualizing linear features in a map-based application.

Data-driven properties

1
  private boolean isDraggable;
2
  private JsonElement data;
3
  private LineString geometry;
4
  private String lineJoin;
5
  private Float lineOpacity;
6
  private String lineColor;
7
  private Float lineWidth;
8
  private Float lineGapWidth;
9
  private Float lineOffset;
10
  private Float lineBlur;
11
  private String linePattern;

These are Data-driven properties of the Line class in the Android Maps SDK.

isDraggable: determines if the line can be moved by the user.
data: can be used to store custom data for the line, in the form of a JsonElement.
geometry: defines the shape of the line, represented by a LineString object.
lineJoin: specifies the behavior of corners on the line. The options are round, miter, and bevel.
lineOpacity: defines the transparency of the line, where 1 is fully opaque and 0 is fully transparent.
lineColor: sets the color of the line.
lineWidth: sets the width of the line.
lineGapWidth: sets the size of the gap between the segments of a dashed or dotted line.
lineOffset: sets the distance the line is offset from its origin.
lineBlur: adds a blur effect to the line, where the higher the value, the greater the blur.
linePattern: sets a repeated pattern for the line, represented as a string of "tl" and "dr" characters, which represent diagonal lines going up and to the left, and diagonal lines going down and to the right, respectively.

Constant properties

1
 public void setLineCap(@Property.LINE_CAP String value)
2
 public void setLineMiterLimit( Float value)
3
 public void setLineRoundLimit( Float value)
4
 public void setLineTranslate( Float[] value)
5
 public void setLineTranslateAnchor(@Property.LINE_TRANSLATE_ANCHOR String value)
6
 public void setLineDasharray( Float[] value)

The above code sets properties for a Line class in a map. The constant properties include:

setLineCap: Set the display of the endpoints of the line. The values for this property can be "butt", "round", or "square".
setLineMiterLimit: Set the limit of the ratio of the miter length to the line width.
setLineRoundLimit: Set the limit of how rounded the line join can be.
setLineTranslate: Set the translation of the line in pixels as an array of two numbers.
setLineTranslateAnchor: Set the origin of the translation of the line. The values can be "map" or "viewport".
setLineDasharray: Set the length and spacing of dashes and gaps as an array of numbers.

Fill

The Fill properties define the appearance and behavior of a filled area on a map. The properties can be either data-driven or constant.

Data-driven properties

The data-driven properties of the Fill class include:

isDraggable: a boolean indicating whether the fill can be moved.
data: a JsonElement representing any additional data associated with the fill.
geometry: a Polygon defining the shape of the fill.
fillOpacity: a float representing the opacity of the fill.
fillColor: a string representing the color of the fill.
fillOutlineColor: a string representing the color of the outline of the fill.
fillPattern: a string representing the pattern used to fill the shape.

1
  private boolean isDraggable;
2
  private JsonElement data;
3
  private Polygon geometry;
4
  private Float fillOpacity;
5
  private String fillColor;
6
  private String fillOutlineColor;
7
  private String fillPattern;

Constant properties

The constant properties of the Fill class include:

setFillAntialias: a boolean indicating whether the fill should use antialiasing.
setFillTranslate: a float array representing the translate property of the fill.
setFillTranslateAnchor: a string representing the translate anchor property of the fill.

1
 public void setFillAntialias(Boolean value)
2
 public void setFillTranslate(Float[] value)
3
 public void setFillTranslateAnchor(@Property.FILL_TRANSLATE_ANCHOR String value)

Circle

Circle annotations in Nextbillion Android Maps SDK allow developers to display circular shapes on a map, with customizable radius, color, opacity, and stroke properties. These annotations can be used to represent areas of interest, show proximity or coverage of a location, or to highlight geographic features.

Data-driven properties

The data-driven properties are variables such as "isDraggable", "data", "geometry", "circleRadius", "circleColor", "circleBlur", "circleOpacity", "circleStrokeWidth", "circleStrokeColor", and "circleStrokeOpacity". These properties are dynamic and can change based on the data provided.

1
  private boolean isDraggable;
2
  private JsonElement data;
3
  private Point geometry;
4
  private Float circleRadius;
5
  private String circleColor;
6
  private Float circleBlur;
7
  private Float circleOpacity;
8
  private Float circleStrokeWidth;
9
  private String circleStrokeColor;
10
  private Float circleStrokeOpacity;

Constant properties

The constant properties are methods such as "setCircleTranslate", "setCircleTranslateAnchor", "setCirclePitchScale", and "setCirclePitchAlignment". These properties are set to a fixed value and cannot be changed dynamically. These methods are used to set values for properties such as the circle's translation, its translation anchor, its pitch scale, and its pitch alignment.

1
 public void setCircleTranslate( Float[] value)
2
 public void setCircleTranslateAnchor(@Property.CIRCLE_TRANSLATE_ANCHOR String value)
3
 public void setCirclePitchScale(@Property.CIRCLE_PITCH_SCALE String value)
4
 public void setCirclePitchAlignment(@Property.CIRCLE_PITCH_ALIGNMENT String value)