Introduction to amapro

2023-05-11

Welcoming JavaScript library AMap into the world of R.
AMap is an advanced mapping library made in China and widely used there. It features 2D/3D animation, supports a multitude of layers and markers, data import, flyover playback, etc.
Library amapro let you control AMap from R and Shiny. It uses AMap’s native commands/parameters wrapped in just a few commands.

Translation

AMap’s documentation is in Chinese and most links here make reference to it. If you happen not to know Chinese, it is convenient to set your browser to auto-translate. This will help a little or a lot depending on the website/page structure. One can also copy/paste text to Google translate.

Installation

Install amapro from Github with
remotes::install_github("helgasoft/amapro")
CRAN version also available but usually outdated.

Run with the following commands
library(amapro); am.init()
A pop-up dialog will ask for an API key (shows once, will not be repeated).
API key is obtained through registration, expecting you to provide a Chinese phone number for SMS verification.
How to get an API key if you reside out of China?

Shiny Demo

Interactive, hands-on showcase of many library features. Activate with the following command:
library(amapro); demo(am.shiny)

Commands

Controlling map and elements is done by sending AMap commands to them. Commands can be chained with the pipe operator |> or %>% and are executed sequentially in the order received.
Example: am.cmd('setAngle', 'carIcon', -90)
amapro uses native AMap commands and introduces these additional:

AMap commands starting with get return data from the map or related objects.
Put the data in a Shiny input variable by setting its name in parameter r.
Example: am.cmd('getCenter', 'map', r='inShiny1')
Above command will update input$inShiny1 with the Lng/Lat coordinates of the map center.

Events

Events could be defined for map and elements. All types of instances use on/off methods to bind and remove events.
Events are set in attribute on(or off) as a list of lists. Each event is a separate list with event name in e, a JS function f and optionally a query q.
Example:

am.init(center= c(116.475, 39.997), zoom= 17,
        on= list(list(e= 'complete', 
                      f= "function() {alert('loaded!');}")) )

on/off events without name are ignored, except for the map itself (as above example).
JavaScript function Shiny.setInputValue() can be used to send data back to Shiny.

Limitations

Tips