3D边界地图
文档基于3D边界地图V2 -2.0.0版本编写
该组件主要以三维形态对相对宏观地图数据进行展示，支持添加点位、热力、标牌、柱图、飞线等地图子图层的效果叠加。
注：全新版3D边界地图是对之前组件的进一步升级优化，如对之前组件比较熟悉的，可查看功能升级清单辅助了解更新功能👉🏻3D边界地图V2功能升级清单📑
通用概念
主地图
主地图就是每次一进入看到的地图级别，就是默认地图层级。可以从主地图下钻到子级地图，但不能从主地图返回上一级到更高的层级，主地图已经是最高层级的地图了。
地图块
某一层级的地图中，构成地图的每一个行政区划边界的所围成的区域就是地图块。3D边界地图中地图块包括顶面、顶线、侧面和底线等部分。一般地图块上面显示着区域名称，还有当前地图块所属的子组件，这两种元素都会随着地图块抬升或下降。
在开启了相关配置项的情况下，鼠标移入某个地图块会触发地图块抬升，鼠标单击地图块会触发镜头聚焦这个地图块，鼠标双击地图块会触发下钻子级地图。
如下图所示红色方框圈出的不规则边界内是衢州市的地图块：
配置项
基础配置
设备像素比
单位分辨率
数据来源
设置地图的geojson数据，并且设置主地图。可支持使用EasyV官方提供的数据，也可以自己上传数据包实现自定义数据。
来源
来源分为两种：系统默认和自定义，详见下文。
投影方式
设置地理坐标的投影方式，包括WGS84和墨卡托两种。
通常投影方式的改变只会影响地图区域的形状，如“墨卡托一般比WGS84更方”，不会直接影响经纬度点位的配准。但如果发现卫星图与地图块没有对上，则可能是和投影方式不正确有关。
关于投影方式的相关理论知识，请查阅相关资料。
系统默认
提供了包括全国、省、市级别的geojson数据（未提供区县级的数据），可在这些级别范围内设置主地图和自由下钻。
（虽然我们提供这些地图数据，但我们不是地图供应商，原则上我们只是用于组件的默认效果展示的示例，我们不对数据的准确性和实时性做保证。如果您对数据的可靠性有很高的要求，请使用您自己的地图数据。）
可在地图范围配置项下选择各个行政区的边界数据作为主地图。
自定义
选择来源为自定义后可看到下方出现数据的配置项，可以点击上传地图数据压缩包。
地图数据压缩包
压缩包格式必须是zip，需要把所有可能下钻的区域的数据都放到压缩包里。如下图所示：
地图下钻时，会从地图数据压缩包中查找子级地图的geojson数据，查找的是以子级地图的adcode为名的json文件。如果地图压缩包中存在这个文件，则会成功下钻，并且显示以该文件为数据的地图；如果在压缩包中未找到该文件，则下钻无效，感知上是没有任何反应。
所以由上述原理可以得知，需要把所有子级地图以adcode为名称，以json（或者geojson）为格式，放到zip压缩包的一级目录下（不得有文件夹结构）。
关于自定义地图数据的更详细的内容请参阅：
相机
镜头范围限制
调试模式
动画
勾选此项可以开启场景旋转的动画，设置旋转速度配置项来调节旋转动画的快慢，负数则是反方向旋转。
地图样式
地图模型
此配置下可以设置地图块的样式。
一个地图块在样式上分为顶面、顶线、侧面、底线四个部分，其中顶面和侧面可以支持贴图，会受到光照影响；顶线和底线不受光照影响。
厚度
设置地图块的厚度。
由于设定上地图表面必然是世界坐标下的高度为0的平面，所以增加厚度后会让地图块的朝下拉长，也就是说厚度的增加是朝下的，所以要注意是不是有东西挡住了增加的部分。
支持透明
默认不开启半透渲染，也就是说默认不支持透明效果。如果顶线、顶面、底线、侧面的配置项中有半透明元素（设置了有透明度的颜色，上传了半透明的图片作为贴图），则必须勾选此项才能看到半透明效果，否则可能显示异常。
由于半透明渲染的理论上原因，地图中开启半透明渲染很容易看到遮挡关系错乱的现象（就是感觉怪怪的），所以通常建议不开启半透明，就是说不使用半透明元素。如果确实要使用，可以配置叠加混合，就是设置混合模式为叠加，可以消除遮挡关系的错误。（前提是你能够接受这种渲染风格）
关于半透明渲染的理论知识，可以参见《3D知识-效果篇》中半透明渲染的部分。
叠加混合
会影响地图块的混合模式，勾选后渲染时与背景色的混合模式为叠加，不勾选则混合模式为正常。 参见《通用配置项》中的叠加混合部分。
顶面
地图块表面就是顶面。
Tint颜色
一般用于调节顶面贴图的色相和亮度，或者用于纯色顶面。
这个颜色将会和贴图颜色做乘法。如果没有贴图，则顶面表现为这个颜色本身；如果有贴图，则与贴图颜色做乘法，类似于做了正片叠加的效果，会与贴图颜色更好地融合在一起。
如果不需要顶面贴图，想直接用纯色做顶面，则务必把顶面贴图给删除了；如果需要顶面贴图，但不需要给顶面贴图调节色相和亮度，则必须把这个颜色设置成纯白色（#FFFFFF），这就不会对顶面贴图有任何影响。
如果发现顶面贴图导入后表现的颜色与预期的不符，可能与Tint颜色不是纯白色有关。（也可能和灯光子组件的颜色、环境光的颜色有关）
颜色贴图类型
可以设置三种顶面颜色的类型：
- 无：使用纯色填充顶面，不使用颜色贴图。这时顶面的颜色完全取决于Tint颜色。
- 单张：使用一张贴图填充顶面。如果需要下钻，则可能子级地图时顶面贴图不正确。
- 压缩包：如果需要下钻到子级，并且每个子级都要有自己的一张贴图，则使用此项。
单张贴图
设置颜色贴图类型为单张，则配置项变成如下所示：
点击颜色贴图配置项可以上传图片格式的文件作为顶面的贴图，包括常见的jpg、png、bmp等。
贴图压缩包
设置颜色贴图类型为压缩包，则配置项变成如下所示：
贴图压缩包必须为zip格式，上传zip文件之后，会多一个下拉列表的配置项，列表列出了zip中读取到的文件，可以选择一个文件作为默认贴图。
每次显示一个地图层级时，会在顶面贴图压缩包中查找当前层级的贴图文件，查找的是一个以当前层级的adcode为名图片文件。如果查看成功，则会以该图片为顶面贴图；如果未找到，则使用上文中提到的默认贴图作为自身的顶面贴图。
使用贴图压缩包的情况下也可以使用Tint颜色和颜色贴图内边距。
颜色贴图边距
由于顶面贴图和地图块表面可能会不完全贴图（原因可能是地图数据和卫星图等贴图没有取自完全相同的经纬度范围或坐标系），可以调整这4个参数来实现对齐。
参数的数值是一个比例值，标准的取值范围是0到1，取值为1时对应的就是100%的贴图大小。设置上、下、左、右四个参数为正数后，结果分别是贴图在顶部、底部、左边、右边收缩。设置上、下、左、右四个参数为负数后，结果分别是贴图在顶部、底部、左边、右边扩展。
例如设置下参数为0.25表示贴图在底部收缩25%，设置右参数为-0.13表示在贴图在右边扩展13%。
法线贴图
上传法线贴图增加顶面的细节感，关于法线贴图的理论知识可以查阅相关资料。
法线贴图可以支持一般的图片的格式，和颜色贴图一致。
法线贴图边距的使用方法和上文所述的颜色贴图边距一致，只不过这个是针对法线贴图的。
法线系数影响法线贴图的强度，设置为0则无任何效果，最大值是1。
顶线
顶线就是一个地图下各个小区域的边界线的线条。
设置线条的颜色和粗细。如果要支持半透明颜色则必须在上面的配置项中勾选支持透明。
侧面
设置地图块的侧面，可以设置成纯色或颜色贴图。
侧面的Tint颜色和顶面的Tint颜色用法完全一致，只不过它是作用于侧面的。
侧面的颜色贴图和顶面的单张贴图的用法完全一致，只不过它是作用于侧面的。
底线
底线是位于地图块底部的线条。
设置线条的颜色和粗细。如果要支持半透明颜色则必须在上面的配置项中勾选支持透明。
区域名称
区域名称就是地图上行政区划的名称，如下图所示：
如果要显示区域名称，首先得勾选启用的配置项。可以设置区域名称的文本样式以及是否是始终面向镜头的UI，还可以对某个特定的区域名称进行一定的偏移。
启用
勾选以启用区域名称。
文本样式
设置区域名称的文本样式。
始终面向镜头
勾选此项表示区域名称会一直正对着镜头，不会随着镜头移动而旋转缩放，这是大部分3D场景中的UI的显示方式。
不始终面向镜头
如果不勾选上文所述的始终面向镜头的配置项，表示区域名称是3D平面，会随着镜头移动而表现出和一般的3D物体的一样旋转缩放并且受到透视效果的影响而近大远小，如下图所示：
这时区域名称的大小取决于两个因素：文本样式中的字体大小和基础配置中的单位分辨率。
区域名称大小的计算原理如下：字体大小决定了要用多少像素来渲染这个区域名称的一个字，例如设置字体大小为50px，则表示渲染一个文字时，在水平方向和垂直方向都是50个像素；而单位分辨率决定了一定的世界大小内的渲染像素的个数，例如单位分辨率为10，则表示1个世界单位内，渲染的UI在水平方向和垂直方向都是10像素。则因为区域名称显示为3D平面，它渲染时的大小取决于它在世界坐标系中的大小。于是得出最终渲染一个文字的世界单位是50/10=5，这样就确定了一个文字在世界中的大小了。
结合上述原理可以推断出，字体大小越大，文字越大，文字也越清晰；单位分辨率越大，文字越小，文字也越清晰。
所以，如果觉得文字不够清晰，其实是这个观察距离下像素个数不够多，也就是分辨率不够高，就需要增大单位分辨率；如果觉得文字不够大，就直接增大字体大小就是了，但可能引发文字变模糊，这是就需要增加单位分辨率。
另一种情况就是单位分辨率过于大了，文字不仅显示得很清晰，还“清晰过头”了。“清晰过头”会导致过多地渲染像素，造成性能浪费。不过我们无法观察到“清晰过头”，所以可能无法得知潜在的性能浪费的情况。所以在设置单位分辨率的时候一定是“够用就行”。
方向
可以设置不始终面向镜头时的文字的方向。
如果设置为水平，则文字“平躺”在地图表面，如下所示：
如果设置为竖立，则文字“站立”在地图表面，如下所示：
文字处理
可对某个区域名称的文字进行偏移，可以规避一些文字重叠的问题（典型的就是珠三角那一块的区域文字），或者为了整体的美观做一个微调。可以添加任意多个项对多个区域名称进行处理。对于不同层级的文字，都罗列在此处即可，下钻到该层级时会自动生效。
文本内容
进行文字处理时，会对每一项的文字内容进行匹配，如果在当前层级的区域名称中找到了和文字内容一致（必须完全一致，需要注意空白字符和特殊字符）的区域名称，则对该区域名称应用偏移。
偏移
使用文字内容匹配成功后，设置偏移值对该区域名称进行偏移。如果是始终面向相机的文字，则偏移数值是以像素为单位的；如果不是始终面向相机的文字，则偏移数值是世界单位。
场景效果
场景效果可以给提升画面效果，提高整体的表现力，也可以配置出不同的画面风格如科技风、写实风等。可调整的场景效果如下图所示：
很多效果都是3D组件通用的，可以参阅《通用3D-主组件》的场景效果部分。
环境光
阴影
HDRI
可以使用一张HDR格式图像作为场景的天空背景，并给物体提供间接光，并且可以设置色调映射来提升写实场景的效果。
色调映射
颜色调整
泛光
抗锯齿
雾
给场景覆盖一层起雾的效果，可以用来虚化远景，或者营造朦胧的氛围。
交互设置
设置和交互相关的配置项，包括对镜头的控制，以及地图块在鼠标悬浮、鼠标单击和鼠标双击时的交互设置。如果要启用地图下钻功能，则必须开启双击下钻。单击聚焦启用后，可在点击地图块后发送回调和自定义事件。
拖拽
是否允许使用鼠标控制镜头的移动、旋转和缩放。不勾选此项则场景进入后使用默认视角，不能手动改变视角。
镜头灵敏度
感觉控制镜头的操作太快或太慢时，可以调节此项。请查看《通用3D-主组件》中的镜头灵敏度部分。
悬停
启用此项则鼠标移入某个地图块后，该地图块会处于悬停状态。悬停状态的具体表现取决于抬升、高亮和悬停区域颜色的配置，可以自由搭配这些配置来设置悬停效果。
抬升
勾选抬升配置项则鼠标移入某个地图块后，该地图块会凸起；移出后则恢复。如下图所示：
可以设置抬升高度配置项来调整抬升的高度，设置为0则不抬升。
高亮
勾选高亮配置项则鼠标移入某个地图块后，该地图块的顶面会覆盖一层颜色，用来表现高亮；移出后则恢复。如下图所示：
勾选高亮后，会出现下面如下配置项：
- 顶面叠加：设置高亮时叠加到顶面的颜色。
- 顶线叠加：设置高亮时叠加到顶线的颜色。
上面两个配置项说明高亮时可以单独设置顶面和顶线的颜色，并且设置的颜色与顶面或顶线之前的颜色是使用透明度混合的方式来叠加的。
透明度混合的颜色有如下特点：颜色的透明度设置为0%，则对原始颜色毫无影响；颜色的透明度设置成100%，则完全覆盖原始的颜色；处于二者之间的透明度，则按比例与原始颜色叠加。
悬停区域名称
启用此配置项后鼠标移入某个地图块后，该地图块的区域名称的文本样式将会成这里配置的样式，从而实现文本样式的悬浮高亮。
双击下钻
启用双击下钻后，则双击某个地图块可以下钻到子级地图。具体能不能下钻成功，取决于地图数据中是否有该层级的数据，如果没有则无任何反应，参见上文对地图数据的描述。
勾选双击空白返回则可以在下钻到子级地图后，双击鼠标可触发返回上一级地图的操作，等同于点击返回按钮。当然，如果已经是主地图，则无法返回。
下钻过渡动画
启用此项则在地图下钻和返回上一级时会有一个切换的过渡效果，增强用户体验。
- 时长：过渡效果的动画持续的时长，单位是秒。
- 缓动系数：过渡效果的动画淡入淡出的速度快慢。
返回按钮
启用此项，则在场景之上显示一个按钮UI，点击这个按钮则可以触发返回上一层地图的操作。当然要下钻到子级地图才能看到这个按钮。如下图所示：
位置
设置返回按钮的放置的位置。它是以组件左上角为原点，X轴向右，Y轴向下的坐标系。数值是像素，相对于组件的宽高。如果设置负数或者超过组件宽高的数值，可能会导致该按钮不可见。
背景配置
配置返回按钮的背景，上传图片作为背景并设置尺寸。这个按钮的大小也是依据与这个尺寸，就算背景的图片为空。
文字配置
配置按钮上的文字，一般是“返回上层”、“返回上一级”等字样。
- 文字：设置按钮上显示文字。
- 位置：设置文字相对于按钮中心的偏移。
- 文本样式：设置按钮文字的文本样式。
单击聚焦
启用此项后点击地图块后，进入聚焦状态。进入聚焦状态后，一般会有镜头移动、地图块抬升或高亮等效果，并发送回调和自定义事件。具体的聚焦效果取决于抬升、高亮、聚焦动画的配置项。
单击聚焦下的抬升、高亮、抬升高度、顶面叠加、顶线颜色配置，和悬浮配置项的这个5个配置的用法和意义相同，只不过是在聚焦状态下触发的。可以点击相应配置项的超链接直接跳转到上文查看。
聚焦动画
勾选此项则地图块进入聚焦状态后，镜头会移动并聚焦到该地图块，聚焦的中心是该地图块的中心。
设置一定的视点距离，控制聚焦动画结束时相对于地图块的中心的距离，可设置聚焦的远近。
自动轮播
勾选此项则每个地图块会自动轮流进入聚焦状态。聚焦状态的效果和上文所述的完全一致，一般会有镜头移动、地图块抬升或高亮等效果，并发送回调和自定义事件。轮播的顺序取决于地图数据geojson中顺序。
设置轮播间隔来控制轮播到另一个地图块的间隔时间。
场景管理
场景管理可以设置一系列镜头视角，作为刚进入场景时的默认视角，或者后续通过触发自定义事件切换到这些视角。点击下方按钮可以进入场景管理的界面：
场景管理的具体说明请查看《通用3D-主组件》中的场景管理部分。
数据
该组件可以在数据中设置主地图，通过在数据中设置主地图的adcode来实现。数据格式如下：
[
{
"adcode": 330000
}
]在数组的第一个对象中设置adcode字段为需要设置的主地图的adcode即可。
如果在组件运行中设置或者改变数据中的adcode，则会直接改变主地图。
交互
回调和自定义事件
该组件中回调和自定义事件有着完全相同的触发时机，并且发送完全一样的数据，所以二者综合起来说明。
下钻
触发下钻操作后发送该回调和自定义事件。
触发时机
- 双击地图块（开启相关配置项的情况下）
- 自定义动作-下钻
数据格式
回调和自定义事件发送的数据就是下钻后的子级地图的geojson数据里的properties字段的值。properties字段的值包含什么字段，回调就可以发送这些字段，自定义事件的自定义条件里就可以根据它来判断条件。
发送的数据除了包含properties的值之外，还有一个_layer_字段，如下所示：
{
"_layer_": 2,
// 以下是properties的值
"adcode": 330100,
"name": "杭州市",
//......省略其他properties的值
}_layer_字段是一个数字，表示当前地图层级下钻的是第几级。如果是主地图，_layer_是1，其他子级地图的_layer_值依次增加。这个字段可以用来针对某些层级的地图做下钻限制，例如限制只能下钻一级。（要注意这个字段名的英文layer两边是下划线字符）
返回上一级
返回上一级是下钻的反向动作，下钻后触发返回上一级地图的操作则会发送该回调或自定义事件。
触发时机
- 点击返回按钮
- 双击空白处（开启相关配置项的情况下）
- 自定义动作-返回上一级
数据格式
回调和自定义事件发送的数据就是一个包含adcode字段的对象，如下所示：
{
"adcode": 330100
}聚焦
某个地图块触发聚焦状态则发送聚焦的回调或自定义事件。
触发的时机
单击地图块（开启相关配置项的情况下）
地图块的轮播聚焦（开启配置项单击聚焦-自动轮播）
数据格式
回调和自定义事件发送的数据就是聚焦的地图块的geojson数据里的properties字段的值。和下钻的数据格式类似（不过这里没有_layer_字段）。
取消聚焦
之前有地图块进入聚焦状态，然后整个地图都没有地图块处于聚焦状态，则是取消了聚焦，会发送取消聚焦的回调和自定义事件。
触发时机
在有某个地图块处于聚焦状态时单击空白处则发送取消聚焦。
数据格式
对于回调来说，不管字段值填什么，发送的回调值始终是undefined，所以需要在代码中对undefined做判断。对于自定义事件来说，发送的数据是空对象{}，如下所示：
{}自定义动作
切换场景
下钻
控制地图进行下钻，下钻成功取决于是否开启相关配置项以及是否有子级地图数据。不能下钻到一个不存在的adcode，也不能跨层级下钻，必须是当前地图的子级地图才能进行下钻。
配置项
下钻的配置项是一个代码输入框，用来指定需要下钻的地图的层级。
可以设置一个固定值，如下所示：
return 330100在输入框中写上“return加空格加adcode”就可以指定下钻到330100的子级地图了。
一般需要动态指定下钻的级别，就需要读取自定义事件的数据，如下所示：
return data.adcode代码框环境下的data变量就是触发本动作的自定义事件的数据，对这个数据进行一些代码处理就能动态指定下钻层级。
返回上一级
地图下钻之后可以执行返回上一级的动作来返回上一级地图。如果已经是主地图了，则执行本动作无效。
休眠
请查看《通用3D-主组件》的休眠部分。
唤醒
请查看《通用3D-主组件》的唤醒部分。
切换顶面贴图
在配置项中的地图样式-地图模型-顶面-颜色贴图类型选择压缩包选项并上传贴图压缩包后，可使用动作控制顶面贴图的切换。可以实现保持地图层级不变的情况下，让地图贴图配合外部组件一起切换业务上的场景。
配置项
选择该自定义动作后，配置项上出现如下配置：
可在文件配置项的下拉列表中选择上文所述的压缩包中的某个文件，它应该是个图片文件，这样就能在执行自定义动作后切换地图顶面为这张图片。
子组件
正在完善中