使用 @turf/clusters-kmeans 对 GeoJSON 点要素执行 K-Means 空间聚类

数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载turf/clusters-kmeans是 Turf 地理空间引擎中的 K-Means 聚类模块输入一个由点要素Point组成的 FeatureCollection输出被划分为k个簇、并在每个要素属性中标注簇编号与簇质心的点集合。本文围绕该模块的 API 参数、返回结构、源码实现原理、配套聚类工具及测试基准展开帮助你在空间数据可视化、地理分组与降噪场景中直接落地使用。函数签名与参数说明clustersKmeans的完整签名如下源码见 packages/turf-clusters-kmeans/index.tsclustersKmeans( points: FeatureCollectionPoint, options?: { numberOfClusters?: number; mutate?: boolean; } ): FeatureCollectionPoint, KmeansProps参数类型默认值说明pointsFeatureCollectionPoint必填待聚类的点要素集合options.numberOfClustersnumberMath.round(Math.sqrt(count / 2))期望生成的簇数量k其中count为输入点的总数options.mutatebooleanfalse是否允许直接修改输入的 GeoJSON设为true时跳过克隆性能显著提升两个关键边界行为同样体现在源码中index.tsnumberOfClusters缺省时按Math.sqrt(count / 2)四舍五入自动推算无需人工指定当传入的numberOfClusters大于点的总数时会自动回退为点数count保证算法不会产生空簇。返回值cluster与centroid两个附加属性函数返回与输入同结构的FeatureCollectionPoint但每个要素的properties会被追加两个字段clusternumber该点所属的簇编号clusterId从0开始centroid[number, number]所属簇质心的经纬度坐标格式为[Longitude, Latitude]。对应的类型定义在 packages/turf-clusters-kmeans/index.ts 中type KmeansProps GeoJsonProperties { cluster?: number; centroid?: [number, number]; };因此你可以直接从每个要素的属性中读取分组结果例如feature.properties.cluster和feature.properties.centroid。快速上手示例以下示例来自模块 README随机生成 100 个点聚成 7 簇// 生成 bbox 内 100 个随机点 var points turf.randomPoint(100, { bbox: [0, 30, 20, 50] }); var options { numberOfClusters: 7 }; var clustered turf.clustersKmeans(points, options); // 用于地图叠加展示 var addToMap [clustered];借助 Turf 的配套工具可以很方便地把聚类结果拆回独立集合例如用getCluster取出cluster属性等于0的全部点详见 packages/turf-clusters/index.ts// 取出第 0 个簇的所有点 var cluster0 turf.getCluster(clustered, { cluster: 0 }); // 按 cluster 属性逐个遍历每个簇 turf.clusterEach(clustered, cluster, function (cluster, clusterValue, currentIndex) { // cluster 当前簇的点集合 // clusterValue 当前簇编号 // currentIndex 当前遍历索引 }); // 统计簇总数等价于 Array.reduce 语义 var total turf.clusterReduce(clustered, cluster, function (previousValue) { return previousValue 1; }, 0);源码实现原理从坐标收集到质心标注clustersKmeans内部依赖 skmeans完整流程可以拆解为四步对应 index.ts参数归一化计算默认numberOfClusters并对超出点数的取值做回退防止副作用当mutate ! true时先通过turf/clone深克隆输入保证原始 GeoJSON 不被污染坐标收集与初始化用coordAll来自turf/meta把所有点的坐标抽成纯数组data并以data.slice(0, numberOfClusters)取前k个坐标作为初始质心seed从而避免 skmeans 初始化漂移导致结果不稳定聚类与标注调用skmeans(data, numberOfClusters, initialCentroids)得到每个点的簇归属idxs与质心集合centroids最后通过featureEach把cluster和centroid写回每个要素的属性。正是第 3 步的固定初始质心策略让相同输入下重复调用会得到稳定的结果这比随机初始化更利于测试与复现。参数深入mutate的性能含义mutate参数对应的是“是否跳过克隆”mutate: false默认先clone(points)再在副本上写属性输入数据保持原样mutate: true直接原地修改传入的 FeatureCollection省去整份深拷贝的开销。测试 packages/turf-clusters-kmeans/test.ts 对两种模式都有断言验证默认模式下原输入点属性的cluster仍为undefined而mutate: true调用后原输入属性已被写入cluster。若你的输入数据是一次性的例如刚生成完的随机点、加载后不再复用的数据集开启mutate可以获得明显的性能收益若输入还要继续复用请保持默认值。类型体验与自定义属性透传模块提供了独立的类型校验文件 packages/turf-clusters-kmeans/types.ts其中演示了读取properties.cluster与properties.centroid时类型分别为number与[number, number]若试图把cluster赋值为foo或把centroid赋值为字符串TypeScript 会直接报类型错误调用时numberOfClusters、mutate均为可选可省略全部 options要素原有的自定义属性如properties.foo在聚类后依然可以访问说明函数不会清空原有属性测试 test.ts 同样验证了foo: bar被保留。测试夹具与基准表现模块的测试与基准都基于test/in目录下的 5 份 GeoJSON 夹具见 test 目录fiji.geojson斐济周边 6 个点many-points.geojson约 4000 个点的压力数据集points-with-properties.geojson带自定义属性的点集points1.geojson/points2.geojson在要素集合顶层properties.numberOfClusters中显式指定簇数分别为 3 和 4的小数据集见 points1.geojson。运行方式package.json 脚本见 packages/turf-clusters-kmeans/package.json# 运行 tape 单元测试 pnpm test:tape # 运行 benchmark 基准测试 pnpm bench # 校验类型 pnpm test:typesbench.ts 中记录了各数据集的耗时参考不同机器会有差异many-points约 35ms 级别fiji、points-with-properties在毫秒级小数据集在 0.1ms 量级。测试中还展示了典型的聚类可视化方案用chromatism为每个簇分配颜色、用turf/centroid计算簇质心点、用concaveman生成簇的凹包多边形见 test.ts这一套组合可以直接迁移到你的地图渲染管线中。安装与引入方式与其他 Turf 模块一致支持单模块安装与全家桶安装两种方式# 仅安装本模块 $ npm install turf/clusters-kmeans # 安装包含全部模块的 turf/turf $ npm install turf/turf从turf/turf引入时通过turf.clustersKmeans调用若单独安装本模块则直接import { clustersKmeans } from turf/clusters-kmeans;使用注意事项小结points必须是FeatureCollectionPoint非点要素集合不在本模块支持范围内显式指定numberOfClusters时应结合数据规模与业务语义权衡默认的sqrt(count/2)适合大多数场景对结果做后续分析时优先使用turf/clusters的getCluster/clusterEach/clusterReduce避免手写属性过滤需要高性能处理大数据量点集时开启mutate: true可减少克隆开销但请确认输入数据可被修改由于初始质心取自前k个点极端情况下如点顺序特殊、数据量极小聚类结果会受输入顺序影响可通过显式指定簇数并结合业务校验来规避。赞分享数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载相关推荐turf/clusters-dbscan使用 DBSCAN 算法对 GeoJSON 点要素进行空间聚类turf/clusters dbscan使用 DBSCAN 算法对 GeoJSON 点要素进行空间聚类 导读 turf/clusters dbscan 是数据分析turf/collect 详解使用 Turf 将点要素属性按多边形空间聚合turf/collect 详解使用 Turf 将点要素属性按多边形空间聚合 导读 turf/collect 是 Turf 地理引擎中的一个空间聚合模块它数据分析使用 turf/clusters 处理 GeoJSON 聚类数据getCluster、clusterEach 与 clusterReduce 实战指南使用 turf/clusters 处理 GeoJSON 聚类数据getCluster、clusterEach 与 clusterReduce 实战指南 导读数据分析上一篇langchain/weaviate 演进全解析从 LangChain v1.0 兼容到 jsonSchema 原生支持下一篇Megatron-LM 对象存储训练与检查点管理实战Multi-Storage Client (MSC) 集成完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考