@3clear/basegis 0.1.5 → 0.1.7

package/README.md

@@ -8,276 +8,360 @@
 - `methods`：多地图实时视角联动、独立线图层、台风路径、图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场等高级控制器。
 - `layers`：天地图、GeoServer 金字塔瓦片、WMS、WMTS 图层配置快捷构造器。
 - `assets`：站点、工厂、信息标记和台风中心 SVG 资源。
-- `style.css`：Leaflet、GIS 图层和标注相关基础样式。
+- `style.css`：BaseGIS 自有图层、标注和截图框选样式，不内嵌 Leaflet 官方 CSS。
 
 ## 能力总览
 
 以下按类型展示 `@3clear/basegis` 的主要业务能力；工具型辅助函数不单独作为能力卡展示。点击名称可跳转到下方详细说明，完整导入方式见[出口](#出口)。
 
-### Core 核心（1）
+### 快速开始
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#base-gis-lifecycle"><strong>初始化与生命周期</strong></a></small></td>
       <td>
-        <a href="#base-gis"><strong>BaseGIS</strong></a><br>
-        <small>Cesium / Leaflet 统一 GIS 主入口 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>创建并初始化 BaseGIS 实例，管理实例状态、尺寸刷新和资源销毁。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
-  </tbody>
-</table>
-
-### DEM 地形
-
-<table>
-  <tbody>
     <tr>
+      <td><small><a href="#map-init-config"><strong>地图初始化配置</strong></a></small></td>
       <td>
-        <a href="#dem-terrain"><strong>DEM 地形</strong></a><br>
-        <small>Cesium 椭球地形、World Terrain 与地形夸张</small>
+        <small>说明构造参数、init() 参数优先级、完整配置分组，以及 setConfig() 的用法与生效规则。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#engine-switch"><strong>切换引擎</strong></a></small></td>
+      <td>
+        <small>支持 Cesium / Leaflet 运行时切换，并保留当前视野、恢复托管图层。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
-  </tbody>
-</table>
-
-### 地图截图导出
-
-<table>
-  <tbody>
     <tr>
+      <td><small><a href="#view-control-scene"><strong>视角控制与场景模式</strong></a></small></td>
       <td>
-        <a href="#map-screenshot"><strong>BaseGIS.screenshot</strong></a><br>
-        <small>当前视口、框选及指定范围截图 · <a href="http://61.50.111.214:31166/lgmap/test-page-40" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>支持视角缩放、重置、范围适配，以及 2D、2.5D、3D 场景模式切换。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#map-view-listener"><strong>地图视角监听</strong></a></small></td>
+      <td>
+        <small>监听地图移动、缩放和视角变化的开始、过程与结束状态。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-36" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#map-click-events"><strong>点击事件</strong></a></small></td>
+      <td>
+        <small>统一监听 Cesium / Leaflet 地图点击，返回坐标及命中目标信息。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### 多地图联动（双屏联动）
+### 地图工具（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#map-screenshot"><strong>地图截图导出</strong></a></small></td>
+      <td>
+        <small>支持当前视口、框选区域及指定范围截图，并导出 PNG 图片。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-40" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#map-view-link-controller"><strong>多地图联动</strong></a></small></td>
       <td>
-        <a href="#map-view-link-controller"><strong>MapViewLinkController</strong></a><br>
-        <small>多地图实例注册与移动、缩放、视角实时联动 · <a href="http://61.50.111.214:31166/lgmap/test-page-36" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>支持多地图实例注册，以及移动、缩放和视角实时联动。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-36" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Graphics 图形与点位（4）
+### 通用点位图层（5）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
-      <td width="50%">
-        <a href="#basic-graphics"><strong>绘制点、线、面、文字和 Marker</strong></a><br>
-        <small>BaseGIS 基础绘图与清理，支持 Cesium / Leaflet · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#basic-graphics"><strong>基础图形与点位</strong></a></small></td>
+      <td>
+        <small>绘制点、线、面、文字和 Marker，支持 Cesium / Leaflet。</small>
       </td>
-      <td width="50%">
-        <a href="#point-large-layer-controller"><strong>PointLargeLayerController</strong></a><br>
-        <small>海量点 · <a href="http://61.50.111.214:31166/lgmap/test-page-5" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#point-large-layer-controller"><strong>海量点</strong></a></small></td>
+      <td>
+        <small>使用批量渲染展示大规模点位数据。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-5" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
     <tr>
-      <td width="50%">
-        <a href="#point-cluster-controller"><strong>PointClusterController</strong></a><br>
-        <small>点位聚合 · <a href="http://61.50.111.214:31166/lgmap/test-page-29" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#point-cluster-controller"><strong>点位聚合</strong></a></small></td>
+      <td>
+        <small>根据地图视图和缩放层级对邻近点位进行聚合展示。</small>
       </td>
-      <td width="50%">
-        <a href="#point-density-controller"><strong>PointDensityController</strong></a><br>
-        <small>点位视野裁剪抽稀 · <a href="http://61.50.111.214:31166/lgmap/test-page-8" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-29" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#point-density-controller"><strong>点位抽稀</strong></a></small></td>
+      <td>
+        <small>根据当前视野裁剪点位，并按屏幕密度进行抽稀展示。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-8" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
-  </tbody>
-</table>
-
-### geojson
-
-<table>
-  <tbody>
     <tr>
+      <td><small><a href="#marker-icons"><strong>图标</strong></a></small></td>
       <td>
-        <a href="#geojson-layer"><strong>BaseGIS.upsertGeoJsonLayer</strong></a><br>
-        <small>GeoJSON 点、线、面与按要素设置样式 · <a href="http://61.50.111.214:31166/lgmap/test-page-23" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>提供项目常用图标及告警扩散效果图标。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-41" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### 图标
+### 行政区划边界图层（1）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#geojson-layer"><strong>GeoJSON 图层</strong></a></small></td>
       <td>
-        <a href="#marker-icons"><strong>图标</strong></a><br>
-        <small>提供了一些项目中常用的图标及告警扩散效果图标 · <a href="http://61.50.111.214:31166/lgmap/test-page-41" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>支持 GeoJSON 点、线、面、行政区划边界，以及数据驱动的边线、填充和点样式。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-23" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Line 线图层（1）
+### 轨迹路径图层（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#line-layer-controller"><strong>走航路径</strong></a></small></td>
       <td>
-        <a href="#line-layer-controller"><strong>LineLayerController</strong></a><br>
-        <small>独立线图层、实线/虚线、固定/流动渐变与沿线动画 · <a href="http://61.50.111.214:31166/lgmap/test-page-34" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：逐顶点色、时间裁剪和图标引领的逐步出线；走航轨迹见 <a href="http://61.50.111.214:31166/lgmap/test-page-43" target="_blank" rel="noopener noreferrer">走航示例</a></small>
+        <small>轨迹折线、逐顶点浓度着色、时间裁剪与沿线动画；底层支持实线/虚线、固定/流动渐变和图标引领的逐步出线。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-43" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
-  </tbody>
-</table>
-
-### Typhoon 台风路径（1）
-
-<table>
-  <tbody>
     <tr>
+      <td><small><a href="#typhoon-path-controller"><strong>台风路径</strong></a></small></td>
       <td>
-        <a href="#typhoon-path-controller"><strong>TyphoonPathController</strong></a><br>
-        <small>实况路径、强度节点、当前中心、四象限风圈、多机构预报与路径播放 · <a href="http://61.50.111.214:31166/lgmap/test-page-10" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：Cesium / Leaflet 同一份规范化台风数据与引擎切换恢复</small>
+        <small>实况路径、强度节点、当前中心、四象限风圈、多机构预报与路径播放；支持 Cesium / Leaflet 同一份规范化台风数据与引擎切换恢复。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-10" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Image 图片图层（1）
+### 格点填色图层（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#image-layer-controller"><strong>图片填色图层</strong></a></small></td>
       <td>
-        <a href="#image-layer-controller"><strong>ImageLayerController</strong></a><br>
-        <small>图片覆盖层与时次切换 · <a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：PNG / JPG / WebP 等浏览器图片、灰度图；可配套 GeoTIFF 取值</small>
+        <small>支持 PNG / JPG / WebP 等图片覆盖、灰度图及时次切换，可配套 GeoTIFF 取值。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
-  </tbody>
-</table>
-
-### Grid 数值网格（1）
-
-<table>
-  <tbody>
     <tr>
+      <td><small><a href="#grid-layer-controller"><strong>网格数值图层</strong></a></small></td>
       <td>
-        <a href="#grid-layer-controller"><strong>GridLayerController</strong></a><br>
-        <small>栅格数值注记与鼠标探针 · <a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：GeoTIFF、灰度图、直接数值网格</small>
+        <small>支持 GeoTIFF、灰度图和直接数值网格的数值注记与鼠标探针。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-4" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Contour 通用等值线与中心标注（2）
+### 等值线图层（2）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
-      <td width="50%">
-        <a href="#contour-layer-controller"><strong>ContourLayerController</strong></a><br>
-        <small>已有等值线、线值标签与中心标注 · <a href="http://61.50.111.214:31166/lgmap/test-page-19" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#contour-layer-controller"><strong>通用等值线</strong></a></small></td>
+      <td>
+        <small>已有等值线数据，支持线平滑、线值标签、中心标注与标注避让。</small>
       </td>
-      <td width="50%">
-        <a href="#raster-contour-controller"><strong>RasterContourController</strong></a><br>
-        <small>从栅格追线，可选自动检测 H/L 中心 · <a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-19" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#raster-contour-controller"><strong>栅格等值线</strong></a></small></td>
+      <td>
+        <small>没有等值线数据，需要前端通过格点数据自动生成等值线，支持线平滑、标注避让，可选自动检测 H/L 中心。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-18" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Source 源解析传输（1）
+### 三维渲染（不支持2维）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#dem-terrain"><strong>DEM 地形</strong></a></small></td>
       <td>
-        <a href="#source-transport"><strong>BaseGIS.upsertSourceTransportLayer</strong></a><br>
-        <small>Cesium 专有；贡献弧线、灰色烟羽点云、移动烟团与目标汇聚体 · <a href="http://61.50.111.214:31166/lgmap/test-page-42" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>页面最少只传 target + flows，体云复用 BaseGIS 现有体渲染</small>
+        <small>Cesium 专用，支持椭球地形、World Terrain 与地形夸张。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
-  </tbody>
-</table>
-
-### Volume 三维体渲染（1）
-
-<table>
-  <tbody>
     <tr>
+      <td><small><a href="#source-transport"><strong>源解析传输</strong></a></small></td>
       <td>
-        <a href="#volume-rendering"><strong>BaseGIS.upsertVolumeLayer</strong></a><br>
-        <small>Cesium 专有；三维标量场体积采样与裁切 · <a href="http://61.50.111.214:31166/lgmap/test-page-14" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：一维体数据 + rows / cols / heights 网格维度、原位更新体数据与屏幕位置取值</small>
+        <small>展示贡献弧线、灰色烟羽点云、移动烟团与目标汇聚体，体云复用现有体渲染。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-42" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
-  </tbody>
-</table>
-
-### Section 三维切片 / 剖面（1）
-
-<table>
-  <tbody>
     <tr>
+      <td><small><a href="#volume-rendering"><strong>盒子体渲染</strong></a></small></td>
       <td>
-        <a href="#section-rendering"><strong>BaseGIS.upsertSectionLayer</strong></a><br>
-        <small>Cesium 专有；按经度、纬度、气压层切片 · <a href="http://61.50.111.214:31166/lgmap/test-page-15" target="_blank" rel="noopener noreferrer">查看示例</a></small><br>
-        <small>支持：{ Bound, DataAry } 三维格点数据</small>
+        <small>对三维标量场进行体积采样与裁切，支持原位更新体数据及按屏幕位置取值。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-14" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#section-rendering"><strong>切片/剖面渲染</strong></a></small></td>
+      <td>
+        <small>基于三维格点数据，按经度、纬度或气压层渲染切片与剖面。</small>
+      </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-15" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Wind 风场（2）
+### 风场图层（2）
 
-风场分为 GPU 和 Canvas 两种渲染方式。推荐使用 [BaseGIS.upsertWindLayer](#unified-wind-layer) 统一入口：Cesium 自动使用 GPU，Leaflet 自动使用 Canvas，切换引擎时自动恢复风场。
+<p><small>推荐使用 <a href="#unified-wind-layer"><code>BaseGIS.upsertWindLayer</code></a> 统一入口：Cesium 自动使用 GPU，Leaflet 自动使用 Canvas，切换引擎时自动恢复风场。</small></p>
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
+      <td><small><a href="#gpu-wind-layer"><strong>GPU 风场</strong></a></small></td>
       <td>
-        <a href="#gpu-wind-layer"><strong>GPU 风场</strong></a><br>
-        <small>Cesium 专用，使用 GPU 绘制风场粒子，支持地形采样 · <a href="http://61.50.111.214:31166/lgmap/test-page-21" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>Cesium 专用，使用 GPU 绘制风场粒子，支持地形采样。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-21" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
     <tr>
+      <td><small><a href="#wind-field-methods"><strong>Canvas 风场</strong></a></small></td>
       <td>
-        <a href="#wind-field-methods"><strong>Canvas 风场</strong></a><br>
-        <small>通过 WindFieldMethods 在 Cesium / Leaflet 上绘制风场粒子，支持风速底图 · <a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+        <small>通过 Canvas 在 Cesium / Leaflet 上绘制风场粒子，支持风速底图。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-3" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
 
-### Layers 图层构造器（4）
+### 影像瓦片图层（4）
 
-<table>
+<table width="90%">
+  <thead>
+    <tr>
+      <th width="20%"><small>名称</small></th>
+      <th width="65%"><small>介绍</small></th>
+      <th width="15%"><small>查看</small></th>
+    </tr>
+  </thead>
   <tbody>
     <tr>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createTiandituLayer</strong></a><br>
-        <small>天地图图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#layer-config-builders"><strong>天地图图层</strong></a></small></td>
+      <td>
+        <small>生成天地图矢量、影像、地形及注记图层配置。</small>
       </td>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createGeoserverPyramidLayer</strong></a><br>
-        <small>GeoServer 金字塔瓦片配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#layer-config-builders"><strong>GeoServer 金字塔瓦片</strong></a></small></td>
+      <td>
+        <small>生成 GeoServer 金字塔瓦片图层配置，支持标准瓦片地址模板。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
     <tr>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createWmsLayer</strong></a><br>
-        <small>WMS 图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="#layer-config-builders"><strong>WMS 图层</strong></a></small></td>
+      <td>
+        <small>生成 WMS 服务图层配置，支持图层名称及附加请求参数。</small>
       </td>
-      <td width="50%">
-        <a href="#layer-config-builders"><strong>createWmtsLayer</strong></a><br>
-        <small>WMTS 图层配置 · <a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
+    </tr>
+    <tr>
+      <td><small><a href="#layer-config-builders"><strong>WMTS 图层</strong></a></small></td>
+      <td>
+        <small>生成 WMTS 标准瓦片图层配置，可指定 Cesium / Leaflet 引擎支持范围。</small>
       </td>
+      <td><small><a href="http://61.50.111.214:31166/lgmap/test-page-2" target="_blank" rel="noopener noreferrer">查看示例</a></small></td>
     </tr>
   </tbody>
 </table>
@@ -317,13 +401,29 @@ npm install @3clear/basegis leaflet axios
 
 `d3-contour`、`pixi.js`、`leaflet-pixi-overlay` 和 `html2canvas` 已随 BaseGIS 构建产物发布，业务项目不需要单独安装。其中 Pixi 相关代码只在首次使用 Leaflet 海量点能力时按需加载，`html2canvas` 只在首次调用 Leaflet 截图时按需加载。
 
-使用样式：
+在应用入口引入 BaseGIS 与自有样式：
+
+```js
+import { BaseGIS } from '@3clear/basegis'
+import '@3clear/basegis/style.css'
+```
+
+外部依赖版本以 `package.json` 为准：当前为 `leaflet ^1.9.4`、`axios ^1.15.1`。
+
+当前限制：完整 BaseGIS 入口中的剖面工具仍在模块加载时访问 `Cesium.Cartesian3`，因此即使只创建 Leaflet 地图，也需在导入 BaseGIS 前加载下文的 Cesium 脚本，否则会报 `Cesium is not defined`。这是既有的引擎依赖问题，与本次 Leaflet CSS 共用处理无关；纯原生 Leaflet 不受此限制。
+
+Leaflet JS 和 `leaflet/dist/leaflet.css` 都由宿主依赖提供。BaseGIS 保留对官方 CSS 的导入，因此上面的原有用法仍然有效；官方规则不再另行内嵌到包的 `style.css` 中。
+
+如果项目同时使用原生 Leaflet，可以在应用入口统一引入：
 
 ```js
+import L from 'leaflet'
+import 'leaflet/dist/leaflet.css'
+import { BaseGIS } from '@3clear/basegis'
 import '@3clear/basegis/style.css'
 ```
 
-外部依赖版本以 `package.json` 为准：当前为 `leaflet ^1.9.4`、`axios ^1.15.1`。仅使用 Leaflet 时，不需要加载 Cesium。
+确保 BaseGIS 与业务代码解析到同一份安装的 Leaflet，宿主构建器即可复用同路径的 JS / CSS。不同地图使用各自容器；不需要挂载 `window.L` 或注册 Vue 插件，其他模块需要使用 `L` / `BaseGIS` 时仍按需 import。纯原生页面若不导入 BaseGIS JS，必须自行引入 `leaflet/dist/leaflet.css`，仅引入包的 `style.css` 不包含官方规则。
 
 Cesium 不随 npm 包发布。使用 Cesium 时，宿主项目需自行加载 `Cesium.js` 和 `Widgets/widgets.css`，并保留 `Workers`、`Assets` 等完整静态目录；初始化前必须能访问 `window.Cesium`。`config.engine.cesium.scriptUrl/cssUrl` 不会自动注入脚本和样式。
 
@@ -398,6 +498,9 @@ onMounted(() => {
     // 也可以传 container: HTMLElement。
     containerId: 'map',
     config: {
+      // 地图 / 底图投影与无元数据栅格默认源投影分开配置。
+      crs: 'EPSG:3857',
+      sourceProjectionCrs: 'EPSG:3857',
       view: {
         // 可选 2d / 2.5d / 3d。
         defaultSceneMode: '3d',
@@ -413,8 +516,6 @@ onMounted(() => {
       basemap: {
         // 默认内置值：tianditu-imagery。
         defaultVisibleId: 'tianditu-imagery',
-        // 默认内置值：tianditu-vector-label。
-        defaultAnnotationId: 'tianditu-vector-label',
       },
     },
   })
@@ -464,15 +565,344 @@ onBeforeUnmount(() => {
 
 `getEngineType()`、`getConfig()`、`getMapInstance()` 等读取方法直接返回值；`createMarkerIcon()` 直接返回图标参数或 `null`。控制器的 `getState()` 也返回状态对象，不能一律按 `result.data` 读取。
 
-## 配置与底图
+<a id="map-init-config"></a>
 
-说明：
+## 地图初始化与运行时配置
+
+`BaseGIS` 的初始化参数分为两类：需要长期保留的默认配置放在构造函数的 `config` 中；只想覆盖本次初始化时，传给 `init(options)`。地图已经创建后，`setConfig()` 只更新实例保存的配置，不会直接改变当前画面；初始化默认值通常需要重新 `init()` 才会生效。
+
+| 配置入口 | 适用场景 | 是否写入运行时配置 | 是否立即重建地图 |
+| --- | --- | --- | --- |
+| `new BaseGIS({ ... })` | 创建实例并设置默认引擎、容器和整套配置。 | 是 | 否，仍需调用 `init()`。 |
+| `init(options)` | 创建或重新创建地图，并单次覆盖容器、引擎、CRS、场景模式或初始视角。 | `engineType` 会写入；`crs / sceneMode / initialView` 不写入。 | 是 |
+| `setConfig(config)` | 修改实例保存的配置，供后续初始化或配置查询使用。 | 是 | 否 |
+
+### 构造参数
+
+```js
+const mapCore = new BaseGIS({
+  engineType: 'cesium',
+  containerId: 'map',
+  config: {
+    crs: 'EPSG:3857',
+    sourceProjectionCrs: 'EPSG:3857',
+    view: {
+      defaultSceneMode: '3d',
+      initialView: {
+        center: [104, 35],
+        height: 5000000,
+        zoom: 5,
+        heading: 0,
+        pitch: -90,
+        roll: 0,
+      },
+    },
+  },
+})
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `engineType` | `'cesium' \| 'leaflet'` | `config.engine.active`，内置为 `cesium` | 默认引擎。该参数最终覆盖 `config.engine.active`。 |
+| `container` | `HTMLElement \| string` | - | 地图容器 DOM，也兼容传容器 id 字符串。 |
+| `containerId` | `string` | - | 地图容器 id。与 `container` 二选一即可。 |
+| `config` | `Object` | 内置配置 | 推荐的配置入口，与内置配置做深合并。 |
+| `crs / sourceProjectionCrs` | `string` | 见下文 | 分别表示地图 / 底图投影和无元数据栅格的默认源投影，支持 `EPSG:4326` / `EPSG:3857`。 |
+| `engine / view / basemap / dem / sourceTransport` | `Object` | - | 兼容直接写在构造参数顶层；`crs / sourceProjectionCrs` 也可如此传入。推荐统一放入 `config`，同名时 `config` 中的值优先。 |
+
+### `init(options)` 参数与优先级
+
+```js
+const result = mapCore.init({
+  // 都是选填；构造时已经设置过的内容不需要重复传。
+  containerId: 'map',
+  engineType: 'cesium',
+  crs: 'EPSG:3857',
+  sceneMode: '3d',
+  initialView: {
+    center: [104, 35],
+    height: 5000000,
+    zoom: 5,
+    pitch: -90,
+  },
+})
+
+if (!result.success) {
+  console.warn(result.message)
+}
+```
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| `container` | `HTMLElement \| string` | 本次使用的容器 DOM 或容器 id，优先级最高。 |
+| `containerId` | `string` | 本次使用的容器 id。 |
+| `engineType` | `'cesium' \| 'leaflet'` | 本次使用的引擎，同时更新实例保存的 `engine.active`。 |
+| `crs` | `'EPSG:4326' \| 'EPSG:3857'` | 本次创建地图使用的 CRS；只覆盖本次初始化，不写回 `config.crs`。 |
+| `sceneMode` | `'2d' \| '2.5d' \| '3d'` | 本次初始化的场景模式；Leaflet 只支持 `2d`。不会写回 `config.view.defaultSceneMode`。 |
+| `initialView` | `Object` | 本次初始化的视角。不会写回 `config.view.initialView`。 |
+
+`init({ config: ... })` 不是有效写法；`init()` 不会合并 `config`。持久配置必须在构造函数中传入，或先调用 `setConfig()`。
+
+各参数的实际取值顺序如下，左侧优先级更高：
+
+| 项目 | 取值优先级 |
+| --- | --- |
+| 容器 | `init.container` → `init.containerId` → 构造函数 `container` → 构造函数 `containerId` |
+| 引擎 | `init.engineType` → 实例当前引擎（由构造函数 `engineType` 或 `config.engine.active` 得到）→ `cesium` |
+| 地图 CRS | `init.crs` → `config.crs` → 旧版引擎默认（Leaflet `EPSG:4326`，Cesium `EPSG:3857`） |
+| 场景模式 | Cesium：`init.sceneMode` → `config.view.defaultSceneMode` → `3d`；Leaflet 始终为 `2d` |
+| 初始视角 | `init.initialView` → `config.view.initialView` → 引擎内置安全视角 |
+
+重复调用 `init()` 时会先销毁旧 adapter，再创建新地图；BaseGIS 托管图层会异步恢复。`init()` 本身同步返回初始化结果，后续逻辑依赖图层恢复时还需等待：
+
+```js
+const result = mapCore.init()
+if (result.success) {
+  const restore = await mapCore.whenReady()
+  console.log(restore.restored, restore.failed)
+}
+```
+
+### 完整配置分组
+
+`config` 顶层包含两个 CRS 值和以下五个配置分组。页面不要直接依赖包内部的 `src/gis/config` 文件；需要查看当前实例最终合并后的配置时，使用 `mapCore.getConfig()`。
+
+| 配置项 / 组 | 用途 | 主要生效时机 |
+| --- | --- | --- |
+| `crs` | 地图平面投影与底图瓦片矩阵。 | `init()` / 重新 `init()` |
+| `sourceProjectionCrs` | 无 CRS 元数据栅格的默认源投影。 | 后续创建或更新栅格图层时 |
+| `engine` | 默认引擎、引擎接入元数据及 Cesium 渲染质量。 | `init()` / 重新 `init()` |
+| `view` | 默认场景模式和初始视角。 | `init()` / 重新 `init()` |
+| `basemap` | 初始底图、可切换底图列表及内置服务元数据。 | `init()`；列表也供 `setBasemapById()` 查询 |
+| `dem` | Cesium 默认地形及可切换地形列表。 | Cesium `init()`；列表也供 `loadDEMById()` 查询 |
+| `sourceTransport` | 源解析传输图层的实例级默认视觉参数。 | 创建 adapter 时锁定；`setConfig()` 后需重新 `init()`，新 adapter 创建图层时才会读取 |
+
+#### `crs` 与 `sourceProjectionCrs`
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `crs` | `''` | 地图平面和底图瓦片矩阵；空值保留旧版引擎默认，Leaflet 为 `EPSG:4326`，Cesium 为 `EPSG:3857`。 |
+| `sourceProjectionCrs` | `'EPSG:4326'` | PNG / JPG / 灰度图 / 数值网格不携带 CRS 元数据时的默认源投影。 |
+
+两个值独立：修改底图 `crs` 不会重新解释栅格数据，修改 `sourceProjectionCrs` 也不会改变底图矩阵。`area`、视角以及点线面业务坐标始终使用 WGS84 经纬度。Cesium 中 `crs` 控制 2D / Columbus 平面投影和内置底图矩阵，不改变 3D 地球的 WGS84 坐标。
+
+栅格源投影的取值顺序是：单个数据源的 `sourceProjectionCrs`（兼容旧名 `sourceProjection`）→ GeoTIFF 可识别 GeoKey → BaseGIS `sourceProjectionCrs` → 内置 `EPSG:4326`。GeoTIFF 已声明但当前不支持的 CRS 会返回错误，不会被全局默认值覆盖。修改 `crs` 后必须重新 `init()`；修改 `sourceProjectionCrs` 只影响之后新建或重新加载且没有显式投影的栅格，不会自动重解释已加载数据。
+
+#### `engine` 引擎配置
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `engine.active` | `'cesium'` | 默认引擎；构造参数 `engineType` 或 `init({ engineType })` 的优先级更高。 |
+| `engine.cesium.sourceType` | `'local-script'` | Cesium 接入方式说明字段。 |
+| `engine.cesium.scriptUrl` | `'/lib/Cesium/Cesium.js'` | Cesium 脚本地址说明字段；BaseGIS 不会自动加载该脚本。 |
+| `engine.cesium.cssUrl` | `'/lib/Cesium/Widgets/widgets.css'` | Cesium 样式地址说明字段；BaseGIS 不会自动加载该样式。 |
+| `engine.cesium.renderQuality.maximumDevicePixelRatio` | `2` | Cesium 最大设备像素比，实际值限制在 `1～3`；越高越清晰，也越耗 GPU。 |
+| `engine.cesium.renderQuality.fxaa` | `true` | 是否启用 Cesium FXAA。 |
+| `engine.cesium.renderQuality.msaaSamples` | `4` | Cesium MSAA 采样数，取整并限制在 `1～8`。 |
+| `engine.leaflet.sourceType` | `'npm'` | Leaflet 接入方式说明字段。 |
+| `engine.leaflet.packageName` | `'leaflet'` | Leaflet 依赖包名说明字段。 |
+
+`scriptUrl / cssUrl` 只是接入元数据。Cesium 资源的实际加载方法见[安装](#安装)。渲染质量在创建 Cesium Viewer 时读取，修改后需要重新 `init()`。
+
+#### `view` 视角配置
+
+| 配置项 | 内置默认值 | Cesium | Leaflet | 说明 |
+| --- | --- | --- | --- | --- |
+| `view.defaultSceneMode` | `'3d'` | 使用 | 只接受 `2d` | 默认场景，可选 `2d / 2.5d / 3d`。 |
+| `view.initialView.center` | `[121.4737, 31.2304]` | 使用 | 使用 | `[经度, 纬度]`。 |
+| `view.initialView.height` | `1800000` | 使用 | 忽略 | Cesium 相机高度，单位米。 |
+| `view.initialView.zoom` | `7` | 忽略 | 使用 | Leaflet 缩放级别。 |
+| `view.initialView.heading` | `0` | 使用 | 忽略 | Cesium 航向角，单位度。 |
+| `view.initialView.pitch` | `-90` | 使用 | 忽略 | Cesium 俯仰角，单位度；`-90` 表示垂直俯视。 |
+| `view.initialView.roll` | `0` | 使用 | 忽略 | Cesium 翻滚角，单位度。 |
+
+#### `basemap` 底图配置
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `basemap.defaultVisibleId` | `'tianditu-imagery'` | 初始化时从 `basemap.list` 选择的底图 id。 |
+| `basemap.defaultAnnotationId` | `'tianditu-vector-label'` | 当前为保留字段，初始化流程尚未读取；注记应通过所选底图项的 `annotationResourceKey` 配置，天地图也会按底图资源自动推断注记。 |
+| `basemap.list` | 内置天地图、WMS、WMTS 示例列表 | 底图资源数组；完整默认项和字段见下方[默认底图配置](#default-basemap-config)。外部传入数组会整体替换内置数组。 |
+| `basemap.providers` | 内置天地图 provider | 内置服务的地址、子域名、token 池及资源映射。当前适配器读取包内 provider，构造参数或 `setConfig()` 中的覆盖值尚不会生效；自定义服务请在 `basemap.list` 中配置 URL。 |
+
+#### `dem` 地形配置
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `dem.defaultEnabled` | `true` | Cesium 初始化时是否加载默认 DEM；`false` 时跳过。 |
+| `dem.defaultVisibleId` | `'ellipsoid-flat'` | 默认 DEM id，必须能在 `dem.list` 中找到、`visible !== false` 且支持 Cesium，否则初始化失败。 |
+| `dem.list` | 平面地形、Cesium World Terrain、天地图 DEM 占位项 | DEM 资源数组；外部传入时整体替换。列表项常用字段为 `id / name / sourceType / factory / url / visible / engineSupport / options`，详细用法见[DEM 地形](#dem-terrain)。 |
+
+Leaflet 不加载 DEM。`cesium-world-terrain` 需要 Cesium Ion 能力；`tianditu-dem` 是待补真实服务地址的占位项。
+
+#### 常用地图初始化配置示例
+
+下面示例把真正参与地图创建的常用配置集中写在一起。未传的字段继续使用上表中的内置默认值：
+
+```js
+const mapCore = new BaseGIS({
+  containerId: 'map',
+  config: {
+    // 地图瓦片与无元数据栅格的默认投影分开管理。
+    crs: 'EPSG:3857',
+    sourceProjectionCrs: 'EPSG:3857',
+    engine: {
+      active: 'cesium',
+      cesium: {
+        renderQuality: {
+          maximumDevicePixelRatio: 2,
+          fxaa: true,
+          msaaSamples: 4,
+        },
+      },
+    },
+    view: {
+      defaultSceneMode: '3d',
+      initialView: {
+        center: [104, 35],
+        height: 5000000,
+        zoom: 5,
+        heading: 0,
+        pitch: -90,
+        roll: 0,
+      },
+    },
+    basemap: {
+      defaultVisibleId: 'tianditu-imagery',
+    },
+    dem: {
+      defaultEnabled: true,
+      defaultVisibleId: 'ellipsoid-flat',
+    },
+  },
+})
+
+const result = mapCore.init()
+if (!result.success) {
+  console.warn(result.message)
+}
+```
+
+#### `sourceTransport` 源解析传输默认配置
+
+这一组不是地图容器或相机初始化参数，而是 Cesium [源解析传输](#source-transport)图层的实例级默认值。
+
+| 配置项 | 内置默认值 | 说明 |
+| --- | --- | --- |
+| `sourceTransport.visible` | `true` | 新建图层默认是否显示。 |
+| `sourceTransport.running` | `true` | 新建图层默认是否播放烟羽动画。 |
+| `sourceTransport.colors` | 内置 7 色数组 | 多来源默认色板。 |
+| `sourceTransport.path` | 内置对象 | 弧线路径分段、高度与弯曲参数。 |
+| `sourceTransport.line` | 内置对象 | 线宽、透明度、辉光、收尖和命中宽度。 |
+| `sourceTransport.smoke` | 内置对象 | 烟羽数量、大小、透明度、扩散和速度。 |
+| `sourceTransport.sourceNode` | 内置对象 | 来源节点大小与标签数量。 |
+| `sourceTransport.targetNode` | 内置对象 | 目标节点颜色与环半径。 |
+| `sourceTransport.volume` | 内置对象 | 目标体云开关、网格尺寸、渲染参数及色带。 |
+| `sourceTransport.interaction` | 内置对象 | 交互开关、命中容差和鼠标样式。 |
+| `sourceTransport.fog` | 内置对象 | 雾效开关与密度。 |
+| `sourceTransport.camera` | 内置对象 | 定位图层时的俯仰角、高度和动画时长。 |
+
+单个图层传入的同名参数优先于这里的实例默认值。
+
+### 配置合并规则
+
+构造函数和 `setConfig()` 使用同一套合并规则：
+
+| 数据类型 | 合并方式 |
+| --- | --- |
+| 普通对象 | 按层级递归合并，只传一个叶子字段不会删除同组其他字段。 |
+| 数组 | 整体替换，不会追加；`basemap.list`、`dem.list`、`sourceTransport.colors` 都遵循此规则。 |
+| 基本类型、函数及其他值 | 使用新值替换旧值。 |
+| 未传字段 | 保留当前配置中的值。 |
+
+配置会被克隆后保存，不会直接修改包内默认配置。`getConfig()` 返回当前实例持有的配置对象引用，建议只读；修改配置统一调用 `setConfig()`。
+
+例如，只覆盖 Cesium 像素比不会丢失 `fxaa` 和 `msaaSamples`：
+
+```js
+mapCore.setConfig({
+  engine: {
+    cesium: {
+      renderQuality: {
+        maximumDevicePixelRatio: 1.5,
+      },
+    },
+  },
+})
+```
+
+如果要在现有底图列表后追加一项，必须自行保留原数组：
+
+```js
+const currentConfig = mapCore.getConfig()
 
-- `containerId` 和 `container` 二选一即可；`init()` 时也可以再次传入。
-- 页面传入的 `config` 会覆盖内置默认配置。
-- `basemap.list` 和 `dem.list` 是数组，外部传入时会整体覆盖内置列表；如果要使用内置默认底图，不要传空数组覆盖。
-- Cesium 默认视角 `pitch: -90`，表示垂直俯视。
-- `BaseGIS` 只保存运行时配置，调用 `setConfig()` 不会自动重建地图，需要重新 `init()` 才会创建新地图实例。
+mapCore.setConfig({
+  basemap: {
+    list: [
+      ...currentConfig.basemap.list,
+      {
+        id: 'custom-xyz',
+        name: '自定义 XYZ',
+        category: 'basemap',
+        type: 'xyz',
+        provider: 'custom',
+        url: 'https://example.com/tiles/{z}/{x}/{y}.png',
+        engineSupport: ['cesium', 'leaflet'],
+      },
+    ],
+  },
+})
+```
+
+### `setConfig()` 怎么用
+
+`setConfig(overrideConfig)` 是同步方法，没有统一结果对象或其他返回值。它只更新 `BaseGIS` 实例保存的配置，不会把新配置推送给已经创建的 adapter，也不会自动改变当前场景、视角、底图、DEM 或渲染质量。`crs / sourceProjectionCrs` 会归一化为 BaseGIS 支持的名称；修改 `crs` 后需重新 `init()`，修改 `sourceProjectionCrs` 只作为后续新数据的回退值。`engine.active` 是另一个需要特别注意的字段：它会同步实例记录的引擎类型，但不会真正替换当前底层地图。
+
+需要让整套初始化配置生效时，直接再次 `init()`，不要先调用 `destroy()`；否则托管图层快照会被清空：
+
+```js
+mapCore.setConfig({
+  engine: {
+    cesium: {
+      renderQuality: {
+        maximumDevicePixelRatio: 1.5,
+        fxaa: true,
+        msaaSamples: 4,
+      },
+    },
+  },
+  view: {
+    defaultSceneMode: '2d',
+    initialView: {
+      center: [116.4, 39.9],
+      height: 1800000,
+      zoom: 7,
+      pitch: -90,
+    },
+  },
+})
+
+const result = mapCore.init()
+if (result.success) {
+  await mapCore.whenReady()
+}
+```
+
+如果目标只是立即操作当前地图，不要用 `setConfig() + init()` 代替已有的实时 API：
+
+| 目标 | 推荐 API | 是否重建地图 |
+| --- | --- | --- |
+| 切换 Cesium / Leaflet | `await mapCore.setEngine(engineType)` | 是，并自动恢复托管图层 |
+| 切换当前场景模式 | `mapCore.setSceneMode({ mode })` | 否 |
+| 移动当前视角 | `mapCore.setInitialView(view)` | 否 |
+| 切换当前底图 | `mapCore.setBasemapById(id)` 或 `mapCore.setBasemap(payload)` | 否 |
+| 切换当前 DEM | `mapCore.loadDEMById(id)`、`mapCore.loadDefaultDEM()` 或 `mapCore.loadDEM(payload)` | 否 |
+| 修改当前或新建源解析传输层 | `mapCore.updateSourceTransportLayer(payload)` 或 `mapCore.upsertSourceTransportLayer(payload)` | 否 |
+| 修改 Cesium 渲染质量或整套初始化默认值 | `setConfig()` 后重新 `init()` | 是 |
+
+特别注意：不要用 `setConfig({ engine: { active: 'leaflet' } })` 切换已经显示的地图；应直接调用 `setEngine('leaflet')`。前者会让 `getEngineType()` 变成 `leaflet`，但底层仍可能是 Cesium，随后调用相同目标的 `setEngine('leaflet')` 还会被当作“已经是当前引擎”而跳过。若已经这样修改，应调用 `init()` 重建并校正地图实例。
+
+<a id="default-basemap-config"></a>
 
 ### 默认底图配置
 
@@ -481,6 +911,7 @@ onBeforeUnmount(() => {
 ```js
 basemap: {
   defaultVisibleId: 'tianditu-imagery',
+  // 当前为保留字段，初始化时不会读取。
   defaultAnnotationId: 'tianditu-vector-label',
 }
 ```
@@ -492,16 +923,18 @@ basemap: {
 | `tianditu-vector` | 天地图矢量底图 | `basemap` | `true` | `wmts` | `tianditu` | `vector` | 可作为 `defaultVisibleId` | Cesium / Leaflet |
 | `tianditu-imagery` | 天地图影像底图 | `basemap` | `true` | `wmts` | `tianditu` | `imagery` | 内置 `defaultVisibleId` | Cesium / Leaflet |
 | `tianditu-terrain` | 天地图地形底图 | `basemap` | `true` | `wmts` | `tianditu` | `terrain` | 可作为 `defaultVisibleId` | Cesium / Leaflet |
-| `tianditu-vector-label` | 天地图矢量注记 | `annotation` | `true` | `wmts` | `tianditu` | `vectorLabel` | 内置 `defaultAnnotationId` | Cesium / Leaflet |
-| `tianditu-terrain-label` | 天地图地形注记 | `annotation` | `true` | `wmts` | `tianditu` | `terrainLabel` | 可作为 `defaultAnnotationId` | Cesium / Leaflet |
+| `tianditu-vector-label` | 天地图矢量注记 | `annotation` | `true` | `wmts` | `tianditu` | `vectorLabel` | 可作为底图的 `annotationResourceKey` | Cesium / Leaflet |
+| `tianditu-terrain-label` | 天地图地形注记 | `annotation` | `true` | `wmts` | `tianditu` | `terrainLabel` | 可作为底图的 `annotationResourceKey` | Cesium / Leaflet |
 
 说明：
 
 - `defaultVisibleId` 应指向 `category: 'basemap'` 的底图。
-- `defaultAnnotationId` 应指向 `category: 'annotation'` 的注记层。
+- `defaultVisibleId` 找不到可用项时，会回退到 `basemap.list` 中第一个 `enabled !== false`、分类和引擎均匹配的底图；仍找不到时使用内置天地图矢量兜底配置。
+- `defaultAnnotationId` 当前只是保留字段，不参与初始化。要指定注记，给底图项设置 `annotationResourceKey`；天地图矢量、影像和地形底图未显式设置时，也会分别推断对应注记资源。
 - `tianditu-terrain` 是天地图地形底图瓦片，不是 Cesium 的 DEM 高程地形；如果要控制 Cesium terrainProvider，请看后文 DEM。
 - `geoserver-wmts-sample` 和 `geoserver-wms-sample` 默认 `enabled: false`，只是配置格式示例；如果要作为默认底图，需要替换真实服务地址并改为 `enabled: true`。
 - 天地图 provider 内置资源还包括 `imageryLabel`；默认 `basemap.list` 没有单独注册影像注记 id，但 `resourceKey: 'imagery'` 会自动推断使用 `imageryLabel` 注记。
+- 内置天地图会根据地图 `crs` 选择 `_c` 或 `_w` 瓦片矩阵；自定义 XYZ / WMTS / WMS 的 URL 和矩阵必须由业务保证与地图 `crs` 一致。地图已创建后不能通过普通底图切换改变 CRS，必须修改配置并重新 `init()`。
 
 ### 底图切换
 
@@ -654,9 +1087,11 @@ const mapCore = new BaseGIS({
 
 这一节列的是 `BaseGIS` 主入口直接提供的基础能力。业务页面优先调用这些方法；图片图层、网格图层、海量点、点位聚合、点位抽稀、等值线、风场等更复杂能力，建议使用后文 `methods` 中对应的 Controller。
 
-### 1. 生命周期、实例与引擎切换
+<a id="base-gis-lifecycle"></a>
 
-`BaseGIS` 支持 `cesium` 和 `leaflet` 两种引擎。引擎可以在构造时指定，也可以在 `init()` 时指定。
+### 1. 生命周期与实例
+
+`BaseGIS` 负责地图实例的初始化、状态读取、尺寸刷新和销毁。构造参数、完整配置项、参数优先级及 `setConfig()` 的生效规则见[地图初始化与运行时配置](#map-init-config)。
 
 ```js
 const mapCore = new BaseGIS({
@@ -664,60 +1099,49 @@ const mapCore = new BaseGIS({
   containerId: 'map',
 })
 
-// 创建地图实例。
-mapCore.init()
-
-// 只传目标引擎即可完成切换、视野保留和托管图层恢复。
-await mapCore.setEngine('leaflet')
+const initResult = mapCore.init()
+if (!initResult.success) {
+  console.warn(initResult.message)
+}
 
-// 覆盖运行时配置，不会自动重建地图。
-mapCore.setConfig({ view: { defaultSceneMode: '2d' } })
+const engineType = mapCore.getEngineType()
+const config = mapCore.getConfig() // 只读使用，不要直接修改。
+const mapInstance = mapCore.getMapInstance()
 
-// 读取当前地图引擎
-mapCore.getEngineType()
-//获取当前地图配置
-mapCore.getConfig()
-//获取地图实例
-mapCore.getMapInstance()
-// 销毁当前地图实例。
+mapCore.resize()
 mapCore.destroy()
 ```
 
-Cesium 默认使用最高 2 倍设备像素比、FXAA 和 4 倍 MSAA，避免高分屏上的细线出现明显像素阶梯。可按设备性能覆盖：
-
-```js
-const mapCore = new BaseGIS({
-  config: {
-    engine: {
-      cesium: {
-        renderQuality: {
-          maximumDevicePixelRatio: 1.5,
-          fxaa: true,
-          msaaSamples: 4,
-        },
-      },
-    },
-  },
-})
-```
-
 方法说明：
 
 | 方法 | 参数 | 说明 |
 | --- | --- | --- |
-| `init(options)` | `{ container, containerId, engineType }` | 初始化地图。重复调用时会自动恢复 BaseGIS 托管图层。 |
-| `setEngine(engineType, options)` | 引擎类型、初始化参数 | 未初始化时记录默认引擎；已初始化时自动切换、保留视野并恢复托管图层。 |
-| `switchEngine(engineType, options)` | 引擎类型、初始化参数 | `setEngine()` 的兼容别名。 |
+| `init(options)` | `{ container, containerId, engineType, sceneMode, initialView }` | 初始化地图。重复调用会重建地图并异步恢复 BaseGIS 托管图层。 |
 | `whenReady()` | 无 | 等待最近一次 `init()` 触发的托管图层恢复完成。 |
 | `destroy()` | 无 | 销毁当前地图实例和 adapter，并清空托管图层快照。 |
-| `setConfig(config)` | `Object` | 合并运行时配置；不自动重建地图。 |
+| `setConfig(config)` | `Object` | 合并实例配置，无返回值且不自动重建地图；[查看完整规则](#map-init-config)。 |
 | `getEngineType()` | 无 | 返回当前引擎类型。 |
-| `getConfig()` | 无 | 返回当前运行时配置。 |
+| `getConfig()` | 无 | 返回当前配置对象引用，建议只读。 |
 | `getMapInstance()` | 无 | 返回底层地图实例：Cesium `viewer` 或 Leaflet `map`。 |
 | `getMapContainer()` | 无 | 返回统一结果，`data.container` 为地图容器 DOM。 |
 | `resize()` | 无 | 在容器尺寸改变、隐藏面板重新显示后刷新地图尺寸。 |
 
-#### 推荐的引擎切换写法
+<a id="engine-switch"></a>
+
+### 2. 切换引擎
+
+`BaseGIS` 支持 `cesium` 和 `leaflet` 两种引擎。调用 `setEngine()` 可以在运行时切换引擎、保留当前视野，并恢复 BaseGIS 托管图层。
+
+| 方法 | 参数 | 说明 |
+| --- | --- | --- |
+| `setEngine(engineType, options)` | 引擎类型、初始化参数 | 未初始化时记录默认引擎；已初始化时自动切换、保留视野并恢复托管图层。 |
+| `switchEngine(engineType, options)` | 引擎类型、初始化参数 | `setEngine()` 的兼容别名。 |
+
+目标引擎与当前引擎相同时，`setEngine()` 会直接返回，不会应用 `options.sceneMode / initialView / container`。同一引擎下调整场景或视角应调用 `setSceneMode()`、`setInitialView()`；需要重建地图时直接调用 `init()`。
+
+发生实际切换时，`setEngine()` 会把目标场景模式，以及显式传入或从当前地图保留的视角写回 `config.view`，供之后再次初始化使用。
+
+#### 推荐写法
 
 页面上做 Cesium / Leaflet 切换时，直接调用 `setEngine()`。它会保留当前视野、重建目标引擎，并等待托管图层自动恢复。
 
@@ -774,7 +1198,9 @@ console.log(result.data?.restore?.failed)
 
 `result.success` 表示引擎初始化/切换是否成功，不保证每个图层都恢复成功；应同时检查 `data.restore.failed`。不要在切换前先调用 `destroy()`，它会清空托管快照。
 
-### 2. 视角控制与场景模式
+<a id="view-control-scene"></a>
+
+### 3. 视角控制与场景模式
 
 视角控制分为缩放、重置视角、设置初始视角、场景模式切换、视图状态读取和视图变化监听。
 
@@ -844,6 +1270,8 @@ const pointResult = mapCore.projectToContainerPoint({
 // pointResult.data: { x, y }
 ```
 
+<a id="map-view-listener"></a>
+
 视图变化监听：
 
 ```js
@@ -888,7 +1316,7 @@ viewListener.data?.off?.()
 
 <a id="map-screenshot"></a>
 
-### 3. 地图截图与导出
+### 4. 地图截图与导出
 
 `screenshot()` 用于导出当前 Cesium 或 Leaflet 地图，两个引擎使用完全相同的调用方式、参数和结果对象。默认截取当前可视范围（地图视口）并下载 PNG，不会自动拼接视口外尚未渲染的地图内容；只截取地图内容，不包含页面工具栏、弹窗等地图容器外的 DOM 浮层。
 
@@ -970,7 +1398,7 @@ if (captureResult.success) {
 
 <a id="basic-graphics"></a>
 
-### 4. 绘制点、线、面、文字和 Marker
+### 5. 绘制点、线、面、文字和 Marker
 
 这些方法用于轻量绘制和样例验证。大量点位请优先使用后文的 `PointLargeLayerController`、`PointClusterController`、`PointDensityController` 等控制器。
 
@@ -1284,9 +1712,9 @@ mapCore.clearGraphics()
 
 <a id="geojson-layer"></a>
 
-### 5. GeoJSON 图层
+### 6. GeoJSON 图层
 
-`upsertGeoJsonLayer()` 用同一个 `layerId` 创建或替换 GeoJSON 点、线、面图层，两个引擎共用数据与样式参数。坐标按 GeoJSON 顺序传入 `[经度, 纬度, 可选高度]`。
+`upsertGeoJsonLayer()` 用同一个 `layerId` 创建或替换 GeoJSON 点、线、面图层，两个引擎共用数据与样式参数。图层基础样式使用 `style`，按要素覆盖的完整样式由 `styleCallback(feature, index)` 返回。坐标按 GeoJSON 顺序传入 `[经度, 纬度, 可选高度]`。
 
 ```js
 const result = await mapCore.upsertGeoJsonLayer({
@@ -1296,18 +1724,24 @@ const result = await mapCore.upsertGeoJsonLayer({
     features: [{
       type: 'Feature',
       id: 'region-1',
-      properties: { name: '示例区域', level: 'warning' },
+      properties: {
+        name: '示例区域',
+      },
       geometry: {
         type: 'Polygon',
         coordinates: [[[103, 34], [105, 34], [105, 36], [103, 36], [103, 34]]],
       },
     }],
   },
-  style: { color: '#2f80ff', weight: 2, fillOpacity: 0.2 },
   styleCallback(feature) {
-    return feature?.properties?.level === 'warning'
-      ? { color: '#ff4d4f', fillColor: '#ff4d4f' }
-      : {}
+    return {
+      color: '#36d3ff',
+      weight: 3,
+      opacity: 1,
+      dashArray: '8 4',
+      fillColor: '#1677ff',
+      fillOpacity: 0.4,
+    }
   },
   onClick({ feature, properties }) {
     console.log(properties.name, feature)
@@ -1324,8 +1758,8 @@ if (result.success && result.data.bounds) {
 | `layerId` | 必填，图层唯一 id。 |
 | `data` | 必填；支持 FeatureCollection、Feature、Geometry、Feature 数组、JSON 字符串或 URL。也兼容 `geojson / geoJson / source / url`。 |
 | `fetchOptions` | 使用 URL 时传给 Fetch 的请求参数。业务接口通常由宿主 `api/modules` 获取后再传入 `data`。 |
-| `style` | 统一样式：`color / weight / opacity / fillColor / fillOpacity / stroke / fill`；Leaflet 圆点大小用 `radius`，Cesium 标记大小用 `markerSize`。 |
-| `styleCallback(feature, index)` | 按要素返回样式覆盖；异常时使用基础样式。 |
+| `style` | 统一样式：`color / weight / opacity / dashArray / fillColor / fillOpacity / stroke / fill`；Leaflet 圆点大小用 `radius`，Cesium 标记大小用 `markerSize`。 |
+| `styleCallback(feature, index)` | 按数据返回样式覆盖；线、面支持全部 `style` 字段，点还支持 `radius / markerSize`；异常时使用基础样式。 |
 | `onClick(event)` | 返回 `layerId / feature / properties / data / event / target / engineType`；`data` 为原始 Feature。 |
 | `visible` | 默认 `true`。 |
 | `clampToGround` | Cesium 是否贴地，默认 `true`。 |
@@ -1340,11 +1774,13 @@ mapCore.clearGeoJsonLayer({ layerId: 'region-boundaries' }) // 清空要素，
 mapCore.removeGeoJsonLayer({ layerId: 'region-boundaries' }) // 删除图层。
 ```
 
+`styleCallback` 可直接返回完整样式；需要按要素变化时，在回调中读取 `feature.properties` 后决定返回值即可。`opacity: 0`、`fillOpacity: 0`、`stroke: false`、`fill: false` 都会按原值保留。两个引擎都会渲染虚线，但 `dashArray` 的具体节奏是近似效果。
+
 上述管理方法也可直接传 id 字符串；方法名兼容大写 `GeoJSON`，例如 `upsertGeoJSONLayer()`。更新时需重新提供完整数据和样式。GeoJSON 当前不在自动恢复清单中，切换引擎后需重新调用 `upsertGeoJsonLayer()`。
 
 <a id="dem-terrain"></a>
 
-### 6. DEM 地形
+### 7. DEM 地形
 
 仅 Cesium 支持。默认使用 `ellipsoid-flat` 椭球地形；`tianditu-terrain` 是底图瓦片，不会提供高程。当前 DEM 接口支持椭球和 Cesium World Terrain，配置中的 `tianditu-dem` 仍是占位项，不能作为已实现地形源使用。
 
@@ -1373,7 +1809,9 @@ console.log(mapCore.getDEMState().data)
 
 恢复平面地形可调用 `mapCore.loadDEMById('ellipsoid-flat')`。Leaflet 不提供 DEM；调用失败时应检查 `success / code / message`，不要直接假定结果包含地形状态。
 
-### 7. 点击事件
+<a id="map-click-events"></a>
+
+### 8. 点击事件
 
 `onClick` 注册地图点击事件；`offClick` 移除当前点击监听。当前每个 adapter 只保留一个基础点击监听，重复调用 `onClick` 会先移除旧监听。
 
@@ -1933,6 +2371,9 @@ const imageLayer = new ImageLayerController({
   // 选填：默认图片类型。color 表示图片已经填色；grayscale 表示灰度图需要运行时着色。
   imageSourceType: 'color',
 
+  // 普通图片未单独配置时，继承 mapCore 的 sourceProjectionCrs。
+  // 同一批数据不需要在每次 update 中重复声明。
+
   // 选填：默认小数位，网格标注或探针显示数值时使用。
   decimalPlaces: 2,
 })
@@ -1965,6 +2406,9 @@ await imageLayer.update({
     endLat: 54,
   },
 
+  // 选填：只有这张图与 BaseGIS 默认不同时才覆盖；area 仍是 WGS84。
+  sourceProjectionCrs: 'EPSG:4326',
+
   // 选填：color 表示图片本身已经填色，不需要再按色带处理。
   imageSourceType: 'color',
 
@@ -2224,10 +2668,8 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | `name` | 选填 | 当前数据名称，便于页面展示。 |
 | `imageUrl` | 普通图片、灰度图、图片+TIF 必填 | 图片地址。仅 TIF 模式建议传空字符串清掉旧图片。 |
 | `tifUrl` | 仅 TIF、图片+TIF 必填 | GeoTIFF 数值地址，用于鼠标探针或网格注记，不会单独生成彩色图片底图。 |
-| `area` | 传 `imageUrl` 时必填 | 图片范围：`startLon / startLat / endLon / endLat`。 |
-| `sourceProjection` | 选填 | 源图投影；当前支持将 `EPSG:3857` 图片重采样为经纬度图片，不是任意投影转换器。 |
-| `sourceArea` | 选填 | 源图片范围，默认使用 `area`；支持墨卡托米坐标范围或经纬度范围。 |
-| `targetProjection` | 选填 | 默认从地图 CRS 推断；源投影与目标相同则不重采样。 |
+| `area` | 传 `imageUrl` 时必填 | WGS84 经纬度范围：`startLon / startLat / endLon / endLat`；不随图片或底图投影改变。 |
+| `sourceProjectionCrs` / `sourceProjection` | 选填 | 普通图片像素的排列投影，支持 `EPSG:4326`、`EPSG:3857`；不传时继承 BaseGIS `sourceProjectionCrs`。前者是推荐名称，后者保留兼容。 |
 | `imageSourceType` | 灰度图必填，其他选填 | `color` 表示已填色图片；`grayscale` 表示灰度图。 |
 | `colorize` | 灰度图必填 | 灰度图业务值和色带配置。 |
 | `colorize.minValue` | 灰度图必填 | 色带映射最小值。 |
@@ -2244,7 +2686,7 @@ imageLayer.destroy({ layerId: 'radar-image' })
 | `gridTotal` | 选填 | 切片网格数量。 |
 | `tileSize` | 选填 | 切片尺寸。 |
 
-图片重采样依赖 Canvas 读取像素，跨域图片需要服务端允许 CORS。
+页面只声明源投影，不需要传目标投影。未传时使用 BaseGIS `sourceProjectionCrs`，单个图层的 `sourceProjectionCrs`（兼容 `sourceProjection`）优先。Cesium 和 Leaflet 都会以当前地图 `crs` 为目标：投影相同直接使用原图，投影不同时做一次纬度方向逆向重采样；相同 URL、范围和处理参数在当前页面生命周期内复用缓存。目标为 EPSG:4326 时 Cesium 使用 `SingleTileImageryProvider`，目标为 EPSG:3857 时使用单级 WebMercator Provider。图片重采样、灰度着色和左右换位依赖 Canvas 读取像素，跨域图片需要服务端允许 CORS。
 
 <a id="grid-layer-controller"></a>
 
@@ -2256,9 +2698,9 @@ imageLayer.destroy({ layerId: 'radar-image' })
 
 | 数据模式 | 核心字段 | 数据契约 |
 | --- | --- | --- |
-| GeoTIFF | `tifUrl` | `.tif/.tiff` 地址；读取第一个栅格波段及文件地理范围。 |
-| 灰度图 | `imageUrl/grayImageUrl + area` | 浏览器可解码的灰度图；通过 `grayMinValue/grayMaxValue/minValue/maxValue/noDataValue` 换算业务值。 |
-| 直接数值网格 | `imageGridData` | `{ values, width, height, area }` 或 `{ values, width, height, bbox }`；`values` 必须是长度不小于 `width * height` 的一维数组或 TypedArray。 |
+| GeoTIFF | `tifUrl` | `.tif/.tiff` 地址；读取第一个栅格波段、文件范围和投影 GeoKey。 |
+| 灰度图 | `imageUrl/grayImageUrl + area` | 浏览器可解码的灰度图；`area` 是 WGS84 经纬度，像素行投影默认继承 BaseGIS `sourceProjectionCrs`。 |
+| 直接数值网格 | `imageGridData` | `{ values, width, height, area/bbox, projection?, bboxProjection? }`；`values` 必须是长度不小于 `width * height` 的一维数组或 TypedArray。 |
 
 ```js
 import { GridLayerController } from '@3clear/basegis/methods'
@@ -2273,6 +2715,8 @@ const gridLayer = new GridLayerController({
 
 await gridLayer.loadTif({
   tifUrl: '/data/grid/temp.tif',
+  // 文件没有可靠 CRS GeoKey 时可显式声明；有 GeoKey 时通常无需传。
+  sourceProjectionCrs: 'EPSG:3857',
 })
 
 await gridLayer.loadGrayImage({
@@ -2327,6 +2771,8 @@ gridLayer.destroy()
 
 灰度图要表达真实业务值时，应显式传入 `minValue / maxValue`。数值图层不使用色带绘制背景；如果需要同时显示彩色图片，请使用 `ImageLayerController`。
 
+投影判定顺序是：单个数据源的 `sourceProjectionCrs`（兼容 `sourceProjection`）、GeoTIFF 文件的投影 / 经纬度 GeoKey、BaseGIS `sourceProjectionCrs`、内置 EPSG:4326。GeoTIFF 已声明但不支持的投影会返回友好错误，不会被全局值覆盖。采样时会把鼠标经纬度转换到栅格 bbox 的坐标系，不会为探针重复转换整份 TIF。直接数值网格中，`projection` 描述像元排列，未传时继承 BaseGIS 默认；`bboxProjection` 单独描述 bbox 坐标单位，使用 WGS84 `area` 时固定为 EPSG:4326。
+
 ### 方法
 
 | 方法 | 说明 |
@@ -3996,14 +4442,16 @@ if (!result.success) {
 await rasterContour.update({ interval: 2 })
 ```
 
-GeoTIFF 依赖宿主页面提供 `window.GeoTIFF`。控制器会读取波段、尺寸、坐标系和范围；当前原生支持 EPSG:4326、EPSG:3857。其他投影可先转换为 WGS84，或传入 WGS84 `area` 覆盖原始范围。
+GeoTIFF 依赖宿主页面提供 `window.GeoTIFF`。控制器会读取波段、尺寸、坐标系和范围；当前原生支持 EPSG:4326、EPSG:3857。文件 GeoKey 优先于 BaseGIS `sourceProjectionCrs` 回退值，只有缺少可用 CRS 元数据时才使用全局值；单份数据仍可显式覆盖。其他投影（如 UTM）需先在数据生产环节转换为这两种投影之一，只传 WGS84 `area` 不能代替真实的栅格重投影。
 
 ### 灰度图
 
 ```js
 await rasterContour.loadGrayImage({
   grayImageUrl: '/data/pressure-gray.png',
-  area: [-180, -90, 180, 90],
+  area: [73, 4, 135, 54],
+  // 只有这份数据与 BaseGIS 默认不同时才需要覆盖。
+  sourceProjectionCrs: 'EPSG:3857',
   grayMinValue: 0,
   grayMaxValue: 255,
   minValue: 960,
@@ -4020,7 +4468,7 @@ await rasterContour.loadGrayImage({
        * (maxValue - minValue) + minValue
 ```
 
-灰度图片本身没有地理范围和业务值含义，因此 `area` 必填；要表达真实数据，还应传正确的灰度范围与业务值范围。已经着色的彩色 PNG 不能反推出原始业务值，应使用对应 TIF 或直接传数值网格。
+灰度图片本身没有地理范围、CRS 和业务值含义，因此 `area` 必填，像素投影未传时继承 BaseGIS `sourceProjectionCrs`（其内置默认为 EPSG:4326）；要表达真实数据，还应传正确的灰度范围与业务值范围。控制器只读取一次灰度值，生成线时按像素投影直接反算为 WGS84 坐标，不会为 Cesium / Leaflet 分别重采样整张图。已经着色的彩色 PNG 不能反推出原始业务值，应使用对应 TIF 或直接传数值网格。
 
 上例虽然使用了气压值域，但 `centerDetection` 默认关闭，因此只生成普通等压线和线值标签。需要 H/L 中心时，按下方“自动检测 H/L 中心”配置显式开启。
 
@@ -4063,7 +4511,9 @@ await rasterContour.loadGrid({
 | `values/data/grid` | `Array/TypedArray` | 数值网格必填 | - | 一维或二维数值。 |
 | `width/height` | `number` | 一维网格必填 | `0` | 一维数组的网格尺寸。 |
 | `area` | `object/number[]` | 图片和普通网格必填 | `null` | WGS84 范围；数组顺序为 `[west,south,east,north]`。 |
-| `sourceProjection` | `string` | 否 | 自动读取 | 支持 `EPSG:4326`、`EPSG:3857`。 |
+| `sourceProjectionCrs/sourceProjection` | `string` | 否 | TIF GeoKey → BaseGIS `sourceProjectionCrs` | 灰度图/网格像元的排列投影，支持 `EPSG:4326`、`EPSG:3857`；前者是推荐名称，后者保留兼容。 |
+| `projection` | `string` | 否 | BaseGIS `sourceProjectionCrs` | 直接数值网格的像元排列投影别名。 |
+| `bboxProjection` | `string` | 否 | 使用 `area` 时为 `EPSG:4326`，否则跟随像元投影 | 使用 `bbox` 时声明 bbox 的坐标单位；使用 WGS84 `area` 时固定为 `EPSG:4326`。 |
 | `noDataValue` | `number` | 否 | TIF 自动读取 | 指定无效值；灰度图不传时仅透明像素无效。 |
 | `validMin/validMax` | `number` | 否 | - | 过滤值域外数据。 |
 | `scale/offset` | `number` | 否 | `1/0` | 数值换算为 `value * scale + offset`。 |
@@ -4436,6 +4886,7 @@ SOFTWARE.
 
 ```bash
 npm run build:basegis
+npm run test:basegis
 npm run pack:basegis
 ```
 
@@ -4451,6 +4902,8 @@ packages/basegis/dist/style.css
 
 分发时必须保留完整 `packages/basegis/dist`，不能只复制上述入口文件。`pack:basegis` 不会自动构建，修改源码后应先执行 `build:basegis`。
 
+`test:basegis` 会先构建包，再检查 Leaflet JS / CSS 外部依赖及样式产物边界，防止包重新内嵌一份官方 CSS。
+
 当前包版本为 `0.1.4`，`pack:basegis` 会在仓库根目录生成以下文件；后续以 `packages/basegis/package.json` 中的版本及实际输出为准：
 
 ```text
@@ -4489,12 +4942,29 @@ npm publish ./packages/basegis --access public
 
 ### Leaflet 样式异常
 
-确认已引入：
+BaseGIS JS 会导入宿主的 Leaflet 官方 CSS；使用 npm 包时还需引入自有样式。也可以在应用入口显式统一加载两者：
 
 ```js
+import 'leaflet/dist/leaflet.css'
 import '@3clear/basegis/style.css'
 ```
 
+### 全局同时引入 BaseGIS 和原生 Leaflet 会覆盖吗
+
+按[安装](#安装)中的共同使用示例引入，并确保解析到同一份 Leaflet。包不再把官方 CSS 复制进 `style.css`，宿主可复用对 `leaflet/dist/leaflet.css` 的引用；不要再叠加 CDN 或其他版本的 Leaflet。
+
+这解决的是重复打包，不会隔离 CSS 的全局作用域。业务直接修改 `.leaflet-*` 仍会影响所有匹配的地图；页面定制应限定在自己的容器内，例如：
+
+```vue
+<style scoped lang="scss">
+.native-map-page {
+  :deep(.leaflet-popup-content) {
+    color: #333;
+  }
+}
+</style>
+```
+
 ### 调用方法返回 NOT_INITIALIZED
 
 说明地图还没有初始化成功。先执行：
@@ -4506,7 +4976,7 @@ console.log(result.success, result.message)
 
 ### 切换配置后地图没有变化
 
-`setConfig()` 只更新内部配置，需要再次 `init()` 才会重建地图。不要先手动 `destroy()`，以免清空托管图层快照：
+`setConfig()` 不会更新当前 adapter；需要再次 `init()` 才会按新配置重建地图。不要先手动 `destroy()`，以免清空托管图层快照：
 
 ```js
 mapCore.setConfig(nextConfig)
@@ -4516,6 +4986,8 @@ if (result.success) await mapCore.whenReady()
 
 `init()` 内部会先销毁旧适配器，再创建新实例。
 
+完整的配置项、生效时机和实时操作 API 对照见[地图初始化与运行时配置](#map-init-config)。
+
 ### 切换引擎后图层没了
 
 先确认通过 `setEngine()` 切换且没有提前 `destroy()`，再查看恢复结果：