# JSAPI Three

JSAPI Three 是由百度地图开放平台推出的基于 WebGL 的下一代二三维一体化地图引擎，帮助开发者快速搭建自己的二三维地图场景。JSAPI Three 采用`mapvthree`作为命名空间，基于 Three.js 版本开发，采用 Three.js 作为底层渲染引擎。

官网：https://lbsyun.baidu.com/faq/api?title=jsapithree

## 文档示例

示例中心：https://lbsyun.baidu.com/jsapithree/tutorial

类参考：https://lbsyun.baidu.com/jsapithree/docs/modules/mapvthree.html

## 开始使用

### 1. 安装依赖
mapvthree 基于 Three.js 版本开发，采用 Three.js 作为底层渲染引擎。请执行以下命令安装必要的依赖：
```shell static
npm i -S @baidumap/mapv-three three
```

### 2. 静态资源配置
mapvthree 在初始化时需要加载必要的静态资源。如果在未完成配置的情况下运行 `npm run dev`，您可能会遇到以下错误提示：
```jsx noeditor
<p style={{color: '#f00'}}>"Unable to determine base URL automatically, try defining a global variable called MAPV_BASE_URL."</p>
```

此错误表明引擎无法正确访问所需的静态资源。您需要配置构建工具，将 mapvthree 的静态资源复制到项目的打包目录中。

#### Webpack 配置
如果您使用 Webpack 作为构建工具，请参考以下配置：
```js static
// webpack.config.js
const CopyWebpackPlugin = require('copy-webpack-plugin');

const webpackConfig = {
    ...
    plugins: [
        new CopyWebpackPlugin({ 
            patterns: [
                {from: 'node_modules/@baidumap/mapv-three/dist/assets', to: 'mapvthree/assets'},
            ],
        }),
        ...otherPlugins,
    ]
    ...
};
```

#### Vite/Rollup 配置
如果您使用 Vite 或 Rollup 作为构建工具，请参考以下配置：
```js static
// vite.config.js
import copy from 'rollup-plugin-copy';

const viteConfig = {
    ...
    plugins: [
        copy({
            targets: [
                {src: 'node_modules/@baidumap/mapv-three/dist/assets', dest: 'public/mapvthree'},
            ],
            // vite需要加下面这两这个参数，rollup可忽略
            verbose: true,
            hook: 'buildStart',
        }),
        ...otherPlugins,
    ]
    ...
};
```

完成构建工具配置后，请在项目的 `index.html` 模板中声明 `MAPV_BASE_URL` 全局变量，指向静态资源目录：
```html static
<!-- index.html -->
<script>
    window.MAPV_BASE_URL = 'mapvthree/';   // 配置为mapv-three包路径的dist目录
</script> 
```

### 3. 配置百度地图AK

mapvthree 默认展示百度地图矢量数据，使用前需要配置百度地图开发者密钥（AK）。请按照以下步骤操作：

1. 访问[百度地图开放平台](https://lbsyun.baidu.com/apiconsole/key)，登录您的百度账号
2. 在控制台页面点击"创建应用"
3. 填写应用名称，选择应用类型为"浏览器端"
4. 创建完成后，您将获得一个 AK 密钥

获取 AK 后，您需要在项目的入口处进行配置，以下配置全局执行一次即可：

```js static
// 在项目入口文件中配置
import * as mapvthree from '@baidumap/mapv-three';

// 配置百度地图 AK
mapvthree.BaiduMapConfig.ak = '您的AK密钥';
```

### 4. 安装完成
完成上述配置后，您即可开始使用 mapvthree 进行开发。