1. 快速入门

让用户快速入门，了解如何获取和使用BOSGeo提供的API，通过JSAPI快速搭建自定义的二三维一体化应用程序。

1.1. 初始化

BosGeo 提供了Script和NPM两种使用方式。

1.1.1. Script方式

如果仅需要调用基本的三维地图接口、不需要预定义的界面工具组件，只需要引用引擎库文件（BOSGeo.js）即可；如果需要使用同BOSGeo Viewer同样的工具界面，需要同时引用BOSGeo.js和BOSGeoUI.js这两个文件。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>BOSGeo Viewer</title>
    <link rel="icon" href="https://bos.boswinner.com/favicon.ico">    
    <script src="https://bosgeo.boswinner.com/BOSGeo.js"></script>
    <script src="https://bosgeo.boswinner.com/BOSGeoUI.js"></script></body>
    <style></style>
  </head>
  <body style=" overflow: hidden">
    <div id="bosgeoContainer"></div>
  <script type="text/javascript" defer="defer">
    //初始化三维引擎
    const geomap = new BOSGeo.GeoMap("bosgeoContainer");
    //初始化UI界面
    new BOSGeoUI({
      geomap: geomap //三维地图引擎
    });
  </script>
</html>

其中，bosgeoContainer为地图容器，可以根据实际情况改成其他id名称。BOSGeo.js为三维地图引擎库，BOSGeoUI.js为UI组件库。上述域名 https://bosgeo.boswinner.com 为BOSGeo的生产环境域名地址，实际使用时可根据所处的环境修改域名地址。在实际项目开发过程中建议使用固定版本的BOSGeo.js进行开发 ，避免由于不同版本之间API兼容性造成的问题（具体请参考第7小节“访问指定版本”）。从BOSGeo-V2.4.0版本开始兼容https和http，之前版本只能通过http访问。

1.1.2. NPM方式

从BOSGeo-V2.5.0开始，在NPM上，BOS提供了bosgeo和bosgeo-ui两个NPM安装包。如果仅需要调用基本的三维地图接口、不需要预定义的界面工具组件，只需要安装引擎库（bosgeo），里面包含BOSGeo对象；如果需要使用同BOSGeo Viewer同样的工具界面，也只需安装UI库（bosgeo-ui），里面包含BOSGeo和BOSGeoUI对象。最新版本请访问 https://www.npmjs.com/package/bosgeo-ui 或者 https://www.npmjs.com/package/bosgeo 获取，安装和使用方法可参考对应网页的Readme文档。下面是使用NPM方式的简单介绍：

（1）安装 BOSGeo 引擎库或UI库 npm 包

安装引擎库： npm install bosgeo

安装UI库： npm install bosgeo-ui

（2）使用

webpack.config.js配置(若使用的是UI库的NPM包，需将包名替换为bosgeo-ui)

const CopyWebpackPlugin = require("copy-webpack-plugin");
// ...
{
  plugins: [
    new CopyWebpackPlugin([
      {
        from: path.join("node_modules/bosgeo/build", "/Assets"), 
        to: "Assets"
      },
      {
        from: path.join("node_modules/bosgeo/build", "/ThirdParty"),
        to: "ThirdParty",
      },
      {
        from: path.join("node_modules/bosgeo/build", "/Widgets"),
        to: "Widgets",
      },
      {
        from: path.join("node_modules/bosgeo/build", "/Workers"),
        to: "Workers",
      }
    ])
    // ...
  ];
}

index.js使用

//import * as BOSGeo from "bosgeo"; //引入BOSGeo引擎库
import {BOSGeo, BOSGeoUI} from "bosgeo-ui"; //引入BOSGeoViewer的两个核心对象

//用于本地化部署时设置静态资源文件的根路径，作用相当于CESIUM_BASE_URL
BOSGeo.setBOSGeoBaseUrl("http://localhost:8000/"); 
let geomap = new BOSGeo.GeoMap("bosgeoContainer"); //实例化GeoMap对象
//UI界面初始化
let geoUI = new BOSGeoUI({
    geomap: geoMap
});

1.2. 自定义界面工具

视图控制工具条（basicTool）、底部工具栏（toolBox）和底部工具栏设置按钮（toolBoxControl）在上一小节的初始化UI界面的代码中默认是全部显示的，二次开发者可通过相关参数配置默认显示的工具条。默认true（显示），当对其设置为true或false时则分别进行显示与隐藏控制，具体代码如下。

//自定义初始化UI界面 
new BOSGeoUI({
    geomap: geomap, //三维地图引擎
    layerConfigUrl:'https://yourWebsite/layersSetting.json',//初始化图层配置文件
    toolBoxControl: true,        //底部工具栏设置按钮
    toolBox: {                   //底部工具栏
        analysis: true,          //空间分析
        layerManage: true,       //图层管理
        snapshot: true,          //快照管理
        roam: true,              //漫游
        measure: true,           //测量
        draw: true,              //绘制
    },
    basicTool: {                 //视图控制工具
        home: true,              //主页
        full: true,              //全屏
        zoomin: true,            //放大
        zoomout: true,           //缩小
        north: true,             //指北针
    }
});

layersSetting.json文件中包含一个图层配置对象数组，图层配置对象由图层类型type，图层名称name，图层是否显示show，与数据data构成构成。其中data是一个数据对象数组，每个数据对象中包含的参数可参考对应图层对象中add函数的参数，示例如下（为了避免出现文件格式和编码问题，建议直接下载 http://bosgeo.boswinner.com/layersSetting.json 文件按需修改）。

[
    {
        "type": "MODEL",
        "name": "BIM模型",
        "customGroupId":"myId1",
        "show": true,
        "data": [
            {
                "url": "https://bosgeo.boswinner.com/geoData/models/3DTiles/BIM_G1598257565598/tileset.json",
                "name": "建筑BIM",
                "featureType": "BIM",
                "position":[121.351706, 31.281895, 6],
                "rotation":[9,0,0]
            }
        ]
    }
]

1.3. 自定义图层分组

若不指定图层分组，添加的图层会被默认添加到同一个节点下。用户可以创建自定义分组，每个分组节点对象必须包含组名（title）和唯一标识（id），组间可以通过children关键字进行嵌套分组。示例如下。

/*！！！请不要将创建分组这个动作移到创建图层后面！！！*/
//若要使用自定义图层分组,注意先初始化分组再开始添加图层。注意id不能重复
const customLayerGroup  = [
    {
        title:'组A',
        id:'a',
        children:[{title:'子组a',id:'myId1'},{title:'子组b',id:'myId2'}]
    },
    {
        title:'组other',
        id:'other'
    }
];
geomap.layerManager.initCustomLayerTree(customLayerGroup);//初始化自定义图层分组

注意1：若使用自定义分组，在代码中创建图层时需要通过customGroupId指定该图层所在分组节点的唯一标识。

let modelLayer = layerManager.createLayer(BOSGeo.LayerType.MODEL, 'xx建筑',{customGroupId:'myId1'});

注意2：若使用自定义分组，在初始化加载的图层配置文件中添加图层时，需对每个图层配置所在分组的唯一标识customGroupId。

[
    {
        "type": "MODEL",
        "name": "BIM模型",
        "customGroupId":"myId1",
        "show": true,
        "data": [
            {
                "url": "https://bosgeo.boswinner.com/geoData/models/3DTiles/BIM_G1598257565598/tileset.json",
                "name": "建筑BIM",
                "featureType": "BIM",
                "position":[121.351706, 31.281895, 6],
                "rotation":[9,0,0]
            }
        ]
    }
]

1.4. 加载模型

若要加载用户自己的模型服务，可将如下代码放到初始化的代码之后，或者直接在浏览器的控制台输入如下代码并执行。

//在图层管理工具中添加自定义图层
let layerManager = geomap.layerManager;  //图层管理对象
//创建模型图层
let modelLayer = layerManager.createLayer(BOSGeo.LayerType.MODEL, 'model123',{customGroupId:'myId1'});    
//添加模型
let tesBIMModel = modelLayer.add({
    name: 'testBIM123',    //模型名称
    url: 'https://bosgeo.boswinner.com/geoData/models/3DTiles/BIM_G1598257565598/tileset.json',    //模型服务地址
    featureType: BOSGeo.FeatureType.BIM,  //模型类型，包括BOSGeo.FeatureType.GLTF, FeatureType.TILES, FeatureType.BIM,FeatureType.PHOTO和FeatureType.POINTCLOUD
    position: [114.054437, 22.551279, 10]  //模型位置
});
modelLayer.zoomTo(tesBIMModel); //缩放至模型

1.5. 加载影像图

若要加载用户自己的影像服务，可将如下代码放到初始化的代码之后，或者直接在浏览器的控制台输入如下代码并执行。

let layerManager = geomap.layerManager;  //图层管理对象
var imgLayer = layerManager.createLayer(BOSGeo.LayerType.IMAGERY,"测试用底图-高德",{customGroupId:'raster'});
imgLayer.add({map:BOSGeo.ImageryMapType["GD_IMAGERY"]});
// imgLayer.add({map:BOSGeo.ImageryMapType.GD_IMAGERY});

1.6. 加载地形

若要加载用户自己的地形服务，可将如下代码放到初始化的代码之后，或者直接在浏览器的控制台输入如下代码并执行。需要注意的是地形图层在同一时间和空间内只能添加一个，如果添加了多个地形图层只有最后一个地形图层生效。

setTimeout(() => {
    //添加地形
    let layerManager = geomap.layerManager;  //图层管理对象
    let url='https://lab.earthsdk.com/terrain/577fd5b0ac1f11e99dbd8fd044883638'; ////地形数据服务地址，此处为格式示例，并非有效链接地址
    let terrainLayer = layerManager.createLayer(BOSGeo.LayerType.TERRAIN, '测试地形2', {customGroupId:'other'});
    terrainLayer.add({url:url});        
}, 1000);

1.7. 访问指定版本

BOSGeo以版本号前3位为历史版本命名（如2.5.0）。例如，要访问BOSGeoViewer V2.5.0的版本，在浏览器中输入网址 https://bosgeo.boswinner.com/v2.5.0/ 即可，在浏览器控制台中输入BOSGeo.VERSION可查看到对应的版本号和打包时间；若要引用BOSGeo.js和BOSGeoUI.js文件，只需参照上述代码和版本所在目录修改，即分别为 https://bosgeo.boswinner.com/v2.5.0/BOSGeo.js 和 https://bosgeo.boswinner.com/v2.5.0/BOSGeoUI.js 。其他文件和版本依此类推，具体可见下表（BOSGeo不同版本js库文件引用地址说明）。

从BOSGeo-V2.5.0开始，BOSGeo.js文件的引入地址进行了优化，省去了不必要的中间路径。

版本	地址	说明
最新版本	`https://bosgeo.boswinner.com/BOSGeo.js` `https://bosgeo.boswinner.com/BOSGeoUI.js`
V2.5.0及后续版本	`https://bosgeo.boswinner.com/v2.5.0/BOSGeo.js` `https://bosgeo.boswinner.com/v2.5.0/BOSGeoUI.js`	对于新的版本，修改对应的版本号即可；当然也可以根据以前版本的访问路径实现，但不推荐。
V2.0.0-V2.4.0	`https://bosgeo.boswinner.com/v2.4.0/build/BOSGeo/BOSGeo.js` `https://bosgeo.boswinner.com/v2.4.0/BOSGeoUI.js`	不同版本只需修改对应的版本号即可

快速入门