导航服务
导航服务用于提供机器人从当前位置移动到目的地的能力，NavigationManager 提供了地图管理、定位、移动等能力的相应 API 。
可通过RobotContext 对象获取到NavigationManager。
NavigationManager navigationManager = robotContext.getSystemService(NavigationManager.SERVICE);
地图库
地图数据文件是由特定的地图扫描机器生成，其中指定了地图的初始方向、地图原点、距离单位、标记点、游览路线等数据（这些数据在生成地图时设定，无法修改），在获取到地图数据文件后需要将其导入到地图库中。
- 创建地图
地图由标记点、图层、轨迹和地图数据组成，创建地图时根据需要添加。
//创建标记点 Marker marker/* [1] */=new Marker.Builder(point/* [2] */).build(); //创建图层 GroundOverlay groundOverlay /* [3] */= new GroundOverlay.Builder(width, height).build(); //创建路线 Polyline polyline /* [4] */= new Polyline.Builder(id).build(); //创建地图 NavMap navMap /* [5] */= new NavMap.Builder(scale).build();
[1] Marker地图标记，用于描述各个坐标点，通过 Marker.Builder 构建，使用说明如下：
| 方法 | 说明 |
|---|---|
| Builder.constructor(point) | 构造方法，设置标记点坐标 |
| Builder.setId(id) | 设置标记ID,唯一标志 |
| Builder.setTitle(title) | 设置标题 |
| Builder.addTag(tag) | 添加标签 |
| Builder.addTag(index,tag) | 在指定位置添加标签 |
| Builder.addTagList(taglist) | 添加标签列表 |
| Builder.removeTag(index) | 移除指定位置的标签 |
| Builder.setDescription(description) | 设置描述 |
| Builder.setExtension(extension) | 设置扩展数据，内容自定义 |
`[2]` `Ponit`坐标点，坐标为相对于地图原点的位置（单位与地图距离单位一致），原点为扫图起始点。
| 类型 | 属性 | 说明 |
|---|---|---|
| float | x | x轴坐标 |
| float | y | y轴坐标 |
`[3]` `GroundOverlay` 地图图层，显示时覆盖到地图上，通过 `GroundOverlay.Builder` 构建，使用说明如下：
| 方法 | 说明 |
|---|---|
| Builder.constructor(width, height) | 构造方法，宽度和高度 |
| Builder.setName(name) | 设置图层名称 |
| Builder.setType(type) | 设置图层类型 |
| Builder.setOriginInImage(originInImage) | 设置图层起点坐标 |
| Builder.setImage(image) | 设置本地图片URI |
| Builder.setImageUrl(imageUrl) | 设置在线图片URL |
`[4]` `Polyline` 地图上的路线，由多个 [Location](#Location) 组成，通过 `Polyline.Builder` 构建，使用说明如下：
| 方法 | 说明 |
|---|---|
| Builder.constructor(id) | 构造方法，添加路线id,唯一标志 |
| Builder.setName(name) | 设置名称 |
| Builder.setDescription(description) | 设置描述 |
| Builder.addLocation(location) | 添加路线包含的坐标点列表 |
| Builder.addLocation(index,location) | 在指定位置添加坐标 |
| Builder.addLocationList(locationList) | 添加坐标列表 |
| Builder.removeLocation(index) | 移除指定位置的坐标 |
| Builder.setExtension(extension) | 设置扩展数据，内容自定义 |
`[5]` `NavMap`地图，通过 `NavMap.Builder` 构建，使用说明如下：
| 方法 | 说明 |
|---|---|
| Builder.constructor(scale) | 构造时可指定地图缩放 |
| Builder.setId(id) | 设置地图ID |
| Builder.setName(name) | 设置地图名称 |
| Builder.setNavFile(navFileUri) | 设置地图数据文件路径 |
| Builder.addGroundOverlay(groundOverlay) | 添加图层 |
| Builder.addGroundOverlay(index, groundOverlay) | 在列表的指定位置添加图层 |
| Builder.addGroundOverlayList(groundOverlayList) | 添加图层列表 |
| Builder.removeGroundOverlay(index) | 移除列表指定位置的图层 |
| Builder.addMarker(marker) | 添加标记 |
| Builder.addMarker(index, marker) | 在列表的指定位置标记 |
| Builder.addMarkerList(markerList) | 添加标记列表 |
| Builder.removeMarker(index) | 移除列表的指定位置的标记 |
| Builder.addPolyline(polyline) | 添加导航线路 |
| Builder.addPolyline(index, polyline) | 在列表的指定位置添加导航线路 |
| Builder.addPolylineList(polylineList) | 添加导航线路列表 |
| Builder.removePolyline(index) | 移除列表的指定位置的导航线路 |
- 添加地图
Promise<NavMap, NavMapException> addNavMapPromise /* [1] */= navigationManager.addNavMap(navMap); /* [2] */
[1] 返回结果为Promise的方法为异步方法，可通过注册回调获取执行结果，也可执行get()方法转换成同步方法，具体请参考 async 。
[2] 添加地图操作可能耗时较长，使用同步方法时需要注意。
- 获取地图
Promise<NavMap, NavMapException> getNavMapPromise = navigationManager.getNavMap(navMapId); Promise<List<NavMap>, NavMapException> getNavMapListPromise = navigationManager.getNavMapList();
- 修改地图
Promise<NavMap, NavMapException> modifyNavMapPromise = navigationManager.modifyNavMap(navMap);
- 移除地图
Promise<NavMap, NavMapException> removeNavMapPromise = navigationManager.removeNavMap(navMapId);
当前地图
在定位和导航之前需要先设置一张地图
- 获取当前地图
Promise<NavMap, NavMapException> currentNavMapPromise = navigationManager.getCurrentNavMap();
- 设置当前地图
Promise<NavMap, NavMapException> setCurrentNavMapPromise = navigationManager.setCurrentNavMap(navMapId);
- 移除当前地图
Promise<NavMap, NavMapException> unsetCurrentNavMapPromise = navigationManager.unsetCurrentNavMap();
定位
机器人在导航开始之前需要确定自己在地图中的位置。
- 查询定位状态
//是否正在定位 boolean locatingSelf = navigationManager.isLocatingSelf(); //是否已经定位成功 boolean selfLocated = navigationManager.isSelfLocated();
- 定位
//默认定位 ProgressivePromise<Location /* [1] */, LocatingException, LocatingProgress> locateSelfPromise = navigationManager.locateSelf(); //使用参数定位 LocatingOption locatingOption /* [2] */= new LocatingOption.Builder() .setNearby(location) .setTimeout(timeout) .build(); ProgressivePromise<Location, LocatingException, LocatingProgress> locateSelfPromise = navigationManager.locateSelf(locatingOption); //取消定位 locateSelfPromise.cancel();
[1] Location 位置数据
| 属性 getter | 说明 |
|---|---|
| position | x轴,y轴坐标，坐标为相对于地图原点 |
| z | z轴坐标 |
| rotation | 朝向角度，范围为（0~360）， 角度为相对于地图初始角度 |
[2] LocationOption 定位选项，通过 LocationOption.Builder 构建，使用说明如下： |
| 方法 | 说明 | 默认值 |
|---|---|---|
| Buidler.setTimeout(timeout) | 超时时间 单位：ms | -1 |
| Buidler.setNearby(useNearby) | 在指定坐标附近定位 | 默认不使用 |
- 获取当前位置
Location currentLocation = navigationManager.getCurrentLocation();
导航
- 查询导航状态
boolean navigating = navigationManager.isNavigating();
- 开始导航
NavigationOption navigationOption /* [1] */= new NavigationOption.Builder(location).build(); ProgressivePromise<Void, NavigationException, NavigationProgress/* [2] */> navigatePromise = navigationManager.navigate(navigationOption);
[1] NavigationOption导航选项，通过 NavigationOption.Builder 构建，使用说明如下：
| 属性 | 描述 |
|---|---|
| Builder.constructor(location) | 构造方法，设置导航目的地 |
| Builder.setMaxSpeed(maxSpeed) | 设置最大速度，m/s |
| Builder.setRetryCount(retryCount) | 设置重试次数 |
| Builder.setRetryInterval(retryInterval) | 设置重试间隔，ms |
| Builder.setTrackMode(trackMode) | 设置是否沿着轨迹导航（地图中附带轨道信息） |
[2] NavigationProgress导航进度,通过getLocation()获取当前位置
- 停止导航
navigatePromise.cancel();
监听位置
- 设置位置监听
LocationListener locationListener = new LocationListener() { @Override public void onLocationChanged(Location location) { //位置改变 } }; navigationManager.registerListener(locationListener);
- 取消位置监听
navigationManager.unregisterListener(locationListener);