@3clear/basegis 0.1.6 → 0.1.8

package/README.md

@@ -498,6 +498,9 @@ onMounted(() => {
     // 也可以传 container: HTMLElement。
     containerId: 'map',
     config: {
+      // 地图 / 底图投影与无元数据栅格默认源投影分开配置。
+      crs: 'EPSG:3857',
+      sourceProjectionCrs: 'EPSG:3857',
       view: {
         // 可选 2d / 2.5d / 3d。
         defaultSceneMode: '3d',
@@ -571,7 +574,7 @@ onBeforeUnmount(() => {
 | 配置入口 | 适用场景 | 是否写入运行时配置 | 是否立即重建地图 |
 | --- | --- | --- | --- |
 | `new BaseGIS({ ... })` | 创建实例并设置默认引擎、容器和整套配置。 | 是 | 否，仍需调用 `init()`。 |
-| `init(options)` | 创建或重新创建地图，并单次覆盖容器、引擎、场景模式或初始视角。 | `engineType` 会写入；`sceneMode / initialView` 不写入。 | 是 |
+| `init(options)` | 创建或重新创建地图，并单次覆盖容器、引擎、CRS、场景模式或初始视角。 | `engineType` 会写入；`crs / sceneMode / initialView` 不写入。 | 是 |
 | `setConfig(config)` | 修改实例保存的配置，供后续初始化或配置查询使用。 | 是 | 否 |
 
 ### 构造参数
@@ -581,6 +584,8 @@ const mapCore = new BaseGIS({
   engineType: 'cesium',
   containerId: 'map',
   config: {
+    crs: 'EPSG:3857',
+    sourceProjectionCrs: 'EPSG:3857',
     view: {
       defaultSceneMode: '3d',
       initialView: {
@@ -602,7 +607,8 @@ const mapCore = new BaseGIS({
 | `container` | `HTMLElement \| string` | - | 地图容器 DOM，也兼容传容器 id 字符串。 |
 | `containerId` | `string` | - | 地图容器 id。与 `container` 二选一即可。 |
 | `config` | `Object` | 内置配置 | 推荐的配置入口，与内置配置做深合并。 |
-| `engine / view / basemap / dem / sourceTransport` | `Object` | - | 兼容直接写在构造参数顶层；推荐统一放入 `config`，避免与控制参数混淆。同名配置同时出现时，`config` 中的值优先。 |
+| `crs / sourceProjectionCrs` | `string` | 见下文 | 分别表示地图 / 底图投影和无元数据栅格的默认源投影，支持 `EPSG:4326` / `EPSG:3857`。 |
+| `engine / view / basemap / dem / sourceTransport` | `Object` | - | 兼容直接写在构造参数顶层；`crs / sourceProjectionCrs` 也可如此传入。推荐统一放入 `config`，同名时 `config` 中的值优先。 |
 
 ### `init(options)` 参数与优先级
 
@@ -611,6 +617,7 @@ const result = mapCore.init({
   // 都是选填；构造时已经设置过的内容不需要重复传。
   containerId: 'map',
   engineType: 'cesium',
+  crs: 'EPSG:3857',
   sceneMode: '3d',
   initialView: {
     center: [104, 35],
@@ -630,6 +637,7 @@ if (!result.success) {
 | `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`。 |
 
@@ -641,6 +649,7 @@ if (!result.success) {
 | --- | --- |
 | 容器 | `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` → 引擎内置安全视角 |
 
@@ -656,16 +665,29 @@ if (result.success) {
 
 ### 完整配置分组
 
-`config` 当前只有以下五个顶层分组。页面不要直接依赖包内部的 `src/gis/config` 文件；需要查看当前实例最终合并后的配置时，使用 `mapCore.getConfig()`。
+`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` 引擎配置
 
 | 配置项 | 内置默认值 | 说明 |
@@ -721,6 +743,9 @@ Leaflet 不加载 DEM。`cesium-world-terrain` 需要 Cesium Ion 能力；`tiand
 const mapCore = new BaseGIS({
   containerId: 'map',
   config: {
+    // 地图瓦片与无元数据栅格的默认投影分开管理。
+    crs: 'EPSG:3857',
+    sourceProjectionCrs: 'EPSG:3857',
     engine: {
       active: 'cesium',
       cesium: {
@@ -831,7 +856,7 @@ mapCore.setConfig({
 
 ### `setConfig()` 怎么用
 
-`setConfig(overrideConfig)` 是同步方法，不校验配置，也没有统一结果对象或其他返回值。它只更新 `BaseGIS` 实例保存的配置，不会把新配置推送给已经创建的 adapter，也不会自动改变当前场景、视角、底图、DEM 或渲染质量。`engine.active` 是一个需要特别注意的例外：它会同步实例记录的引擎类型，但不会真正替换当前底层地图。
+`setConfig(overrideConfig)` 是同步方法，没有统一结果对象或其他返回值。它只更新 `BaseGIS` 实例保存的配置，不会把新配置推送给已经创建的 adapter，也不会自动改变当前场景、视角、底图、DEM 或渲染质量。`crs / sourceProjectionCrs` 会归一化为 BaseGIS 支持的名称；修改 `crs` 后需重新 `init()`，修改 `sourceProjectionCrs` 只作为后续新数据的回退值。`engine.active` 是另一个需要特别注意的字段：它会同步实例记录的引擎类型，但不会真正替换当前底层地图。
 
 需要让整套初始化配置生效时，直接再次 `init()`，不要先调用 `destroy()`；否则托管图层快照会被清空：
 
@@ -909,6 +934,7 @@ basemap: {
 - `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()`。
 
 ### 底图切换
 
@@ -2345,6 +2371,9 @@ const imageLayer = new ImageLayerController({
   // 选填：默认图片类型。color 表示图片已经填色；grayscale 表示灰度图需要运行时着色。
   imageSourceType: 'color',
 
+  // 普通图片未单独配置时，继承 mapCore 的 sourceProjectionCrs。
+  // 同一批数据不需要在每次 update 中重复声明。
+
   // 选填：默认小数位，网格标注或探针显示数值时使用。
   decimalPlaces: 2,
 })
@@ -2377,6 +2406,9 @@ await imageLayer.update({
     endLat: 54,
   },
 
+  // 选填：只有这张图与 BaseGIS 默认不同时才覆盖；area 仍是 WGS84。
+  sourceProjectionCrs: 'EPSG:4326',
+
   // 选填：color 表示图片本身已经填色，不需要再按色带处理。
   imageSourceType: 'color',
 
@@ -2636,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` | 灰度图必填 | 色带映射最小值。 |
@@ -2656,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>
 
@@ -2668,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'
@@ -2685,6 +2715,8 @@ const gridLayer = new GridLayerController({
 
 await gridLayer.loadTif({
   tifUrl: '/data/grid/temp.tif',
+  // 文件没有可靠 CRS GeoKey 时可显式声明；有 GeoKey 时通常无需传。
+  sourceProjectionCrs: 'EPSG:3857',
 })
 
 await gridLayer.loadGrayImage({
@@ -2739,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。
+
 ### 方法
 
 | 方法 | 说明 |
@@ -4408,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,
@@ -4432,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 中心”配置显式开启。
 
@@ -4475,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`。 |
@@ -4488,8 +4526,10 @@ await rasterContour.loadGrid({
 | `thresholds/levels` | `number[]` | 三选一 | - | 显式等值线级别，仅保留实际值域内的值。 |
 | `interval/contourInterval` | `number` | 三选一 | - | 固定等值距。 |
 | `thresholdCount/levelCount` | `number` | 三选一 | `12` | 自动均分级别数量，范围 1~100。 |
-| `smooth` | `boolean` | 否 | `true` | 是否平滑等值线。 |
+| `smooth` | `boolean` | 否 | `true` | 是否使用 d3 的边上线性插值定位等值点；与高斯滤波、Chaikin 开关独立。 |
 | `smoothingIterations` | `number` | 否 | `0` | Chaikin 补点平滑次数，范围 0~3；气象格点通常取 1~2，次数越高，点数越多。 |
+| `gridSmoothing` | `object` | 否 | 见下表 | 提线前的可分离高斯滤波；默认关闭，保留原始网格与 NoData。 |
+| `wrapLongitude` | `boolean` | 否 | `false` | 对经度跨度为 360°（容差 0.001°）的栅格启用周期取样、补列、完整线拼接和平滑；区域数据不启用。 |
 | `excludeBoundary` | `boolean` | 否 | `true` | 去掉 d3 面边界中贴着栅格四边的伪矩形线。 |
 | `maxCells` | `number` | 否 | `1000000` | 超过该像元数时先等比例抽样，避免大图阻塞页面。 |
 | `minimumLinePoints` | `number` | 否 | `3` | 最短线点数，用于过滤栅格四角的两点补边。 |
@@ -4499,24 +4539,60 @@ await rasterContour.loadGrid({
 
 级别选择优先级为 `thresholds` → `interval` → `thresholdCount`。显式传入 `thresholds` 时，只保留实际值域内的级别。
 
+### 格点平滑与全球接缝
+
+| `gridSmoothing` 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `false` | 显式开启格点高斯滤波。 |
+| `radius` | `2` | 邻域半径，以 `maxCells` 降采样后的格点为单位，取整并限制为 0~6；0 跳过滤波。 |
+| `sigma` | `null` | 正数；省略、null 或非正数时自动取 `Math.max(radius / 2, 0.8)`，单位同样为格点。 |
+| `passes` | `1` | 水平和垂直方向各处理一次为一轮，取整并限制为 1~3 轮。 |
+
+```js
+await rasterContour.loadGrid({
+  values, width, height, area,
+  interval: 2,
+  maxCells: 360000,
+  gridSmoothing: { enabled: true, radius: 2, sigma: null, passes: 1 },
+  smooth: true,
+  smoothingIterations: 1,
+  wrapLongitude: true,
+})
+
+// 嵌套参数按字段合并，保留 enabled / passes；sigma 为 null 时随半径自动调整。
+await rasterContour.update({ gridSmoothing: { radius: 3 } })
+// 关闭额外平滑，仍保留等值点线性插值和全球接缝连续性。
+await rasterContour.update({ gridSmoothing: { enabled: false }, smoothingIterations: 0 })
+// 标签、样式和渲染简化更新直接复用已有等值线。
+await rasterContour.update({ showLabel: false, smoothFactor: 0.15 })
+```
+
+处理顺序是原始网格 → 降采样 → 高斯滤波 → 全球补列（可选）→ d3 提线 → 拼接完整周期线（可选）→ Chaikin → 短线过滤 → 裁切和坐标取整。周期线在拼接前保留精度，避免低 `coordinatePrecision` 合并不同接缝端点；只按完整曲线判断 `minimumLinePoints`，切回边界后的片段允许小于该长度。源数据为 0°~360° 且需要左右半幅交换时，继续使用 `isSplit: true`。
+
+滤波跳过无效邻点并重新归一化权重，原始 NoData 中心保持为空。`getRasterData()` 始终返回未经高斯滤波、未经周期补列的标准原始网格，反复调参不会累积平滑。高斯改变用于提线的数值场，Chaikin 调整线形，因此输出是平滑后的近似等值线。H/L 的 `closed-contour` 模式共用降采样和高斯滤波后的标量场；原 `neighborhood` 模式仍独立使用原始网格和 `centerDetection.smoothingIterations`。
+
+`test-page-18` 的“平滑与接缝”“高 / 低值中心”“计算与渲染控制”面板可调整上述参数，滑杆松开时自动应用，并显示当前配置 JSON、中心筛选统计、线点数与耗时。演示数据为 ECMWF 海平面气压灰度图（`2026091015`），值差单位是 hPa；灰度 0~255 对应 950.9156494140625~1040.6756591796875 hPa。计算目前仍在主线程执行；可以通过 `maxCells` 和迭代次数限制开销。
+
 ### 自动检测 H/L 中心
 
-该能力默认关闭。它使用标准化后的数值网格查找局部极大值（H）和局部极小值（L），而不是根据已经生成的线反推。因此只应用于确实存在 H/L 语义的栅格数据。
+该能力默认关闭。它从数值网格查找局部极大值（H）和局部极小值（L），支持原邻域均值模式和闭合值差模式；仅在需要表达高低值中心时开启。下面是全球气压数据的闭合值差配置示例，输入单位为 hPa：
 
 ```js
 await rasterContour.loadGrid({
   values: pressureValues,
   width,
   height,
-  area: [70, 10, 140, 60],
-  interval: 4,
+  area: [-180, -90, 180, 90],
+  wrapLongitude: true,
+  interval: 2,
+  gridSmoothing: { enabled: true, radius: 2, sigma: null, passes: 1 },
   showLabel: true,
   centerDetection: {
     enabled: true,
-    radius: 6,
-    minProminence: 2,
-    minGridDistance: 20,
-    maxCount: 12,
+    method: 'closed-contour',
+    minProminence: 1,
+    minDistanceKm: 250,
+    maxCount: 256,
   },
   centerAnnotation: {
     visible: true,
@@ -4530,15 +4606,23 @@ await rasterContour.loadGrid({
 | `centerDetection` 参数 | 默认值 | 说明 |
 | --- | --- | --- |
 | `enabled` | `false` | 开启 H/L 自动检测。 |
-| `radius` | `6` | 计算局部显著度的网格半径。 |
-| `minProminence` | `2` | 中心值与邻域平均值的最小差异，单位与输入网格一致。 |
-| `minGridDistance` | `20` | 同类中心的最小网格距离，距离过近时合并。 |
-| `maxCount` | `12` | H/L 合计最大输出数。 |
+| `method` | `'neighborhood'` | `'neighborhood'` 保留原邻域均值筛选；`'closed-contour'` 检查闭合值差。 |
+| `minProminence` | `2` | 单位与输入网格一致。闭合模式中是最小闭合值差；邻域模式中是中心与邻域均值的差。 |
+| `minDistanceKm` | `250` | 仅闭合模式：同类中心最小球面距离，单位 km；`0` 关闭距离筛选，距离过近时优先保留更高的 H 或更低的 L。 |
+| `maxCount` | `12` | 全部 H/L 合计最大输出数；全球图建议显式提高并通过诊断计数检查是否触及上限。闭合模式按 H/L 交替取数，各类型内部按更高 H、更低 L 排序。 |
 | `includeHigh/includeLow` | `true/true` | 是否输出 H 或 L。 |
-| `excludeBoundary` | `true` | 排除贴近边界或 NoData 空洞的候选。 |
-| `smoothingIterations` | `1` | 3×3 有效值平滑次数，范围 0~3。 |
+| `radius` | `6` | 仅邻域模式：计算邻域均值的网格半径。 |
+| `minGridDistance` | `20` | 仅邻域模式：同类中心的最小网格距离。 |
+| `excludeBoundary` | `true` | 仅邻域模式：排除贴近边界或 NoData 空洞的候选。闭合模式始终排除开口。 |
+| `smoothingIterations` | `1` | 仅邻域模式：独立的 3×3 有效值平滑次数，范围 0~3。闭合模式共用顶层 `gridSmoothing`，不额外平滑。 |
+
+闭合模式先合并八连通的同值平台，每个平台只保留一个位于平台内部、接近平台中心的代表点，再检查整个边界是否满足局部极值。从 H 向外下降 `minProminence`、从 L 向外上升 `minProminence`，用漫水检查这段值差范围内是否遇到区域边界、缺测区或更强的同类中心。出现开口、或在达到阈值之前并入更强中心则过滤；恰好在阈值处合并允许通过。独立同值极值若在阈值内相连，只保留一个。它检查的是给定值差下的闭合性和合并通路，不输出完整的等值线树或真实鞍点显著度，也不要求当前 `thresholds` 正好绘制出那一条闭合线。
 
-检测流程会先进行轻量平滑，再按显著度过滤、合并过近的同类中心并限制数量。超过 100 万格时只对候选搜索做块均值抽样，最终仍回到原网格取精确值和坐标。关闭检测后会清理上一次自动中心。
+闭合模式与等值线共用 `maxCells` 降采样及高斯滤波后的标量场，中心值取该场的代表格点值，中心位置与 d3 一致采用像元中心坐标。`wrapLongitude: true` 且数据覆盖完整 360° 时，左右邻域周期相接；南北边界不循环。距离筛选用球面公里距离，因此同一经度差在不同纬度不会当作相同距离。最后再应用 `maxCount`。
+
+原邻域模式先独立进行轻量平滑，再按中心与窗口均值的差过滤、合并过近同类中心并限制数量；超过 100 万格时只对候选搜索做块均值抽样，最终回到原网格取值和坐标。两种模式的 `minProminence` 含义不同，调参时不应直接等同。关闭检测后会清理上一次自动中心。
+
+新模式通过 `getState().centerDiagnostics` 返回 `candidates`（极值候选）、`closed`（通过闭合检查）、`rejectedOpen`（边界或缺测开口）、`rejectedWeak`（阈值内合并）、`rejectedDistance`（距离去重）及 `rejectedLimit`（数量上限）。`closed` 包含之后被距离和数量筛掉的点。原模式返回 `null`；`clear/destroy` 清空诊断。`centerCount` 是实际输出中心数，`centerLabelCount` 是经过当前视野和碰撞避让后的可见标注数，两者可以不同。
 
 `RasterContourController` 也可直接传顶层 `centers`。手工数组（包括 `[]`）优先于自动检测；传 `centers: null` 可恢复使用当前 `centerDetection` 的结果。检测只产生中心数据，仍需 `centerAnnotation.visible: true` 才会显示。
 
@@ -4551,12 +4635,14 @@ await rasterContour.loadGrid({
 | `loadGeoTiff(payload, options)` | 从 GeoTIFF 生成。 |
 | `loadGrayImage(payload, options)` | 从灰度图生成。 |
 | `loadGrid(payload, options)` | 从数值网格生成。 |
-| `update(payload)` | 合并配置后重新计算；仅修改等值线或渲染参数时复用已解析网格，修改数据源参数时自动重新加载。 |
+| `update(payload)` | 算法参数变化时从原始网格重算；标签、颜色、线宽、渲染简化等显示参数直接复用等值线；修改数据源参数时重新加载。`gridSmoothing` 支持字段级合并。 |
 | `show/hide/toggle` | 统一控制等值线、线值标签和中心标注显隐。 |
 | `clear/destroy` | 清空或销毁控制器。 |
-| `getState()` | 返回尺寸、值域、级别、线数、`centerCount`、标注数、投影、耗时和底层 contour 状态。 |
+| `getState()` | 返回尺寸、值域、级别、线数、`pointCount`、`centerCount`、标注数、投影、耗时和底层 contour 状态；另含实际 `gridSmoothing`、`wrapLongitude`、`gridSmoothingElapsed`、`contoursReused`、`centerDiagnostics`。 |
 | `getRasterData()` | 返回当前标准栅格，包含 `values/width/height/area`。 |
 
+`gridSmoothingElapsed` 已包含在 `generateElapsed` 中，不能重复相加；显示更新复用几何时，两项均为 0，`contoursReused` 为 true。`renderWidth/renderHeight` 不包含内部周期补列。`clear()` 释放等值线缓存并保留原始网格；`destroy()` 同时释放两者。
+
 ```js
 // clear 只清空当前渲染结果，控制器仍可继续 update/load。
 rasterContour.clear()