# BICMap-Mobile

**Repository Path**: open_x_humanoid/BICMap-Mobile

## Basic Information

- **Project Name**: BICMap-Mobile
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BICMap-Mobile

基于 **uni-app (Vue3 + Vite)** 的安卓应用项目，通过 **renderJS** 模式集成 [BICMap](https://github.com/Open-X-Humanoid/BICMap) 地图引擎（`bicMap.ext.min.js`），并实现 **SLAM 建图** 场景作为演示。

## 为什么用 renderJS

`bicMap.ext.min.js` 基于 MapLibre GL（WebGL）实现，依赖完整的浏览器 DOM / Canvas / WebGL 环境，无法直接运行在 uni-app 的逻辑层（JsCore / V8）中。

renderJS 是 uni-app 提供的、运行在 **视图层 WebView** 的脚本机制，可以直接操作 DOM、加载第三方 Web 库。因此：

- **逻辑层**（`<script>`）：负责 UI、交互、状态展示，不接触地图引擎。
- **renderJS 层**（`<script module="mapRenderer" lang="renderjs">`）：加载 `bicMap.ext.min.js`，创建地图、加载 SLAM 帧、驱动机器人动画。
- 两层通过 `prop` / `action`（逻辑层 → renderJS）与 `ownerInstance.callMethod`（renderJS → 逻辑层）双向通信。

## 关于 bicMap.ext.min.js

这是 bic-map 的 **单文件扩展版**，已内置 MapLibre GL 与 Turf，调用 `bicMap.init()`（无参）即可使用，**无需** 额外的 `bicMap.min.js` / `bicMap.css` / assets 资源，非常适合打包进 App。

引擎被放在 `src/lib/bicMap.ext.min.js`，文件尾部追加了一行 `export default bicMap;` 使其成为可被 import 的 ESM 模块，renderJS 中直接 `import bicMapEngine from '@/lib/bicMap.ext.min.js'` 使用。

> 为什么不放在 `public/` 用 `<script src>` 加载？因为 Vite **dev server 会拒绝服务 `/public` 下的 `.js`**（返回 500，强制其只能在 HTML 中引用）。改为 ESM 内联后，H5 dev / H5 build / App 三种环境共用同一套加载逻辑，无需平台条件编译。

## 目录结构

```
uniapp-bicmap/
├─ public/
│  └─ bicMap/
│     └─ map-data/                   # SLAM 逐帧扫图数据
│        ├─ scan_accum_stage_01..50.bmp
│        └─ preview_contact_sheet_50.png
├─ src/
│  ├─ lib/bicMap.ext.min.js          # 地图引擎（ESM 内联）
│  ├─ pages/
│  │  ├─ index/index.vue             # 首页（演示入口）
│  │  └─ slam/buildMap.vue           # SLAM 建图演示（renderJS）
│  ├─ static/slam/                   # 缩略图等静态资源
│  ├─ App.vue / main.js
│  ├─ manifest.json / pages.json / uni.scss
├─ index.html / vite.config.js / package.json
```

## 资源路径约定

- 地图引擎：`src/lib/bicMap.ext.min.js`，在 renderJS 中 `import` 内联，全平台一致。
- BMP 扫图帧：放在 `public/bicMap/map-data/`，renderJS 中按平台条件编译拼接 URL（`.bmp` 不是 JS，Vite dev 正常静态服务）：

| 平台 | BMP 帧 |
| --- | --- |
| H5 | `/bicMap/map-data/scan_accum_stage_XX.bmp` |
| App-Plus | `bicMap/map-data/scan_accum_stage_XX.bmp` |

## 运行

```bash
# 安装依赖（首次）
npm install

# H5 调试
npm run dev:h5      # 浏览器访问 http://localhost:8002

# App 调试 / 打包
npm run dev:app     # 生成 App 资源，配合 HBuilderX 真机运行
npm run build:app   # 构建 App 资源
```

> 推荐用 **HBuilderX** 打开本项目制作安卓自定义基座 / 云打包；CLI 方式生成的 App 资源需导入 HBuilderX 后再打包成 apk。

## 演示功能（SLAM 建图）

- 50 帧累积扫图 BMP 实时绘制到隐藏 canvas，由 bicMap `loadSlamMap` 渲染为地图图层。
- 机器人沿真实 GPS 路径平滑移动（独立 requestAnimationFrame，速度与帧率解耦）。
- 支持：开始 / 暂停 / 重置 / 适应地图 / 自动更新帧（按录制节奏）/ 手动下一帧。
- 实时状态：进度、当前帧、用时、已扫面积、上帧间隔。

> 注意：单帧 BMP 约 7MB，移动端为控制内存，renderJS 内做了缓存窗口（仅保留当前帧附近若干帧）。

## 相关资源

BICMap-Mobile 基于以下项目构建：

| 资源 | 链接 |
|------|------|
| **BICMap GL 主工程** | [GitHub](https://github.com/Open-X-Humanoid/BICMap) |
| **在线文档 & 示例门户** | [bicmap.x-humanoid-cloud.com](https://bicmap.x-humanoid-cloud.com/) |

## Contributors

感谢以下开发者对 BicMap 的贡献：

<table>
  <tr>
    <td align="center">
      <a href="https://github.com/HouserHao">
        <img src="https://github.com/HouserHao.png" width="80" height="80" style="border-radius:50%" alt="HouserHao"/>
        <br/>
        <sub><b>HouserHao</b></sub>
      </a>
    </td>
  </tr>
</table>

## License

[MIT](./LICENSE) © 2024-2026 北京人形机器人创新中心 (Beijing Innovation Center of Humanoid Robotics)