使用 @turf/circle 生成圆多边形：Turf 地理引擎中的半径圆缓冲区实战指南

数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载turf/circle是 Turf 模块化地理引擎中用于“以指定点为圆心、按给定半径生成圆形多边形”的核心工具。本文以 packages/turf-circle/README.md 为主线结合 实现源码、测试用例 与 基准测试完整讲解其参数、用法、单位体系与底层测地学原理帮助你在地图可视化、缓冲区分析、选址圈选等场景中正确使用它。功能概述从一个点到一圈边界circle函数接收一个Point点要素或坐标数组根据给定的半径radius与精度步数steps计算出对应的圆形Polygon多边形要素。返回值是一个符合 GeoJSON 规范的FeaturePolygon可直接用于turf/turf生态的后续分析或渲染。其核心价值在于它不是绘制一个平面几何圆而是在球面地球模型上基于测地学距离计算出每个边界点从而保证半径在任何纬度和单位下都代表真实的地表距离。这在半径覆盖数百公里的场景下尤为关键——此时平面近似会产生明显偏差。参数详解circle的完整签名如下以 packages/turf-circle/index.ts 的类型声明为准circle(center, radius, options)参数类型默认值说明centerFeaturePoint|number[]无必填圆心。可传入点要素也可直接传入[经度, 纬度]坐标数组radiusnumber无必填圆的半径数值options.stepsnumber64边界采样步数即构成圆多边形的顶点数用于控制精度options.unitsUnitskilometers半径的单位支持 Turf 全部合法长度单位见下文单位表options.propertiesObject{}附加到结果多边形上的自定义属性其中options整体默认为{}因此circle(center, radius)的最小调用方式是合法的。若steps未显式提供源码中通过options.steps || 64回退到默认值 64见 index.ts 第 35 行。关于 center 的两种输入形态坐标数组如[-75.343, 39.984]即[经度, 纬度]顺序。点要素FeaturePoint此时可携带properties详见下文“属性传递”小节。完整示例README 官方示例 演示了最基本的用法——以费城某点为中心、半径 5默认单位 kilometers、10 步精度的圆var center [-75.343, 39.984]; var radius 5; var options { steps: 10, units: kilometers, properties: { foo: bar }, }; var circle turf.circle(center, radius, options); // addToMap var addToMap [turf.point(center), circle];该示例中的圆心坐标[-75.343, 39.984]与测试夹具 test/in/circle1.geojson 中的coordinates完全一致后者通过properties.radius: 5声明了同样的半径是同一场景在单元测试中的复现。若使用 TypeScript类型测试 types.ts 展示了受支持的组合形态import { point } from turf/helpers; import { circle } from ./index.js; const center point([-75.343, 39.984]); const units kilometers; const radius 5; const steps 10; circle(center, radius); // 全部默认 circle(center, radius, { steps }); // 只调步数 circle(center, radius, { steps, units }); // 调步数与单位 circle([-75, 39], radius, { steps, units, properties: { foo: bar } }); // 坐标数组 属性安装方式按官方文档既可以单独安装本模块也可以安装聚合包turf/turf# 单独安装 turf/circle npm install turf/circle # 安装包含全部模块的聚合包 npm install turf/turf当前仓库中该包的版本为 7.4.0见 packages/turf-circle/package.json采用 ES Moduletype: module打包运行时要求 Node.js 22依赖turf/destination与turf/helpers两个模块。深入源码圆是怎么被“算”出来的README 只给出了函数签名与示例真正的几何原理藏在实现里。整个 实现文件 只有约 50 行核心逻辑可拆解为三步1. 逐个方位角求边界点const coordinates []; for (let i 0; i steps; i) { coordinates.push( destination(center, radius, (i * -360) / steps, options).geometry.coordinates ); } coordinates.push(coordinates[0]);循环从 0 到steps - 1每次以负角度i * -360 / steps作为方位角调用turf/destination即从正北方向开始、顺时针依次取得每个边界点坐标方位角为0°、-36°、-72°……。循环结束后再把首个坐标追加到末尾显式闭合多边形环。2. 测地学距离计算Haversine 公式destination的实现位于 packages/turf-destination/index.ts其文件头注释明确引用了 Haversine formulaconst longitude1 degreesToRadians(coordinates1[0]); const latitude1 degreesToRadians(coordinates1[1]); const bearingRad degreesToRadians(bearing); const radians lengthToRadians(distance, options.units); const latitude2 Math.asin( Math.sin(latitude1) * Math.cos(radians) Math.cos(latitude1) * Math.sin(radians) * Math.cos(bearingRad) ); const longitude2 longitude1 Math.atan2( Math.sin(bearingRad) * Math.sin(radians) * Math.cos(latitude1), Math.cos(radians) - Math.sin(latitude1) * Math.sin(latitude2) );也就是说每个圆边界点是“从圆心出发、沿某个方位角走半径这么长的测地线”的终点。lengthToRadians负责把radius例如 5 千米换算成球面上的弧度长度因此不同units下的半径会被正确统一到同一球面尺度上——这正是circle在不同纬度和单位下都能保持真实地表距离的原因。3. 组装 Polygon 与属性最后通过turf/helpers的polygon([coordinates], properties)将闭合坐标环组装成FeaturePolygon返回。单位Units支持一览options.units的类型定义来自 packages/turf-helpers/index.ts支持以下全部取值类别取值公制meters/metres/m、kilometers/kilometres/km、millimeters/millimetres/mm、centimeters/centimetres/cm英制miles/mi、inches/in、yards/yd、feet/ft、nauticalmiles/nmi角度radians/rad、degrees/deg⚠️谨慎使用角度类单位Turf 官方在类型定义处packages/turf-helpers/index.ts特别警告——radians与degrees这类单位所代表的距离会随纬度而变化经度 1 度在不同纬度的实际地表长度不同因此用它们定义圆半径时应充分理解其语义避免误用。若传入未定义的单位turf/helpers中的换算函数会抛出unit units is invalid错误见 radiansToLength / lengthToRadians 实现。属性properties的传递规则options.properties用于给结果圆多边形挂载自定义业务属性如{foo: bar}。源码中还内置了一条自动继承逻辑index.ts 第 36-40 行若显式传入options.properties优先使用否则如果center是点要素FeaturePoint且自身带properties则自动沿用圆心的属性两者都没有时回退为空对象{}。这意味着当你传入一个带属性的点要素作为圆心时生成的多边形会自动带上这些属性省去手动复制的步骤。精度权衡steps 如何影响结果steps决定圆多边形由多少个顶点构成。在 基准测试 bench.ts 中记录了不同步数下的性能对照数据为源码注释中留存的实际采样结果步数吞吐量16 steps约 140,793 ops/sec±5.92%32 steps约 84,428 ops/sec±2.28%64 steps约 45,202 ops/sec±1.85%可见顶点数翻倍计算量近似线性增长。实际选值时可视化用途1632 步通常已足够平滑且性能更优高精度分析/出版级输出使用默认 64 步甚至更高步数过少如 48时圆会呈现明显的多边形棱角。测试与 GeoJSON 合规性验证测试文件 test.ts 展示了该模块的两类验证思路也为你自己的集成测试提供参考夹具回归测试读取 test/in/circle1.geojson 中的圆心与properties.radius5调用circle后用turf/truncate截断坐标精度与期望输出逐点比对夹具缺失的steps同样回退到 64。设置环境变量REGEN可重新生成期望输出文件。GeoJSON 合法性校验直接调用circle([0, 0], 100)生成结果并用placemarkio/check-geojson的check()校验其结构符合 GeoJSON 规范。应用建议与注意事项与 Turf 生态协作circle返回的是标准FeaturePolygon可直接传给turf/boolean-contains、turf/intersect、turf/area、turf/bbox等模块做缓冲区查询、区域叠加或范围圈选。坐标系前提本实现基于 WGS84 经纬度坐标与球面测地学模型输入坐标应使用经度/纬度顺序[lng, lat]。闭合环保证返回的多边形是显式闭合的首尾坐标相同可直接用于需要闭合环的下游算法。综上turf/circle以极小的 API 表面积提供了可靠的球面圆多边形生成能力理解steps、units、properties三个选项的语义再结合其底层destination Haversine 的实现机制即可在各类地理应用中准确地画出“等距圆”。赞分享数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载相关推荐turf/ellipse 实战指南基于 Turf 生成球面高精度椭圆多边形turf/ellipse 实战指南基于 Turf 生成球面高精度椭圆多边形 本指南围绕 Turf 模块化地理计算引擎中的 turf/ellipse 模块展数据分析Turf 空间引擎 lineArc 指南用 turf/line-arc 在球面上绘制精确圆弧Turf 空间引擎 lineArc 指南用 turf/line arc 在球面上绘制精确圆弧 turf/line arc 是 Turf 模块化地理空间引擎数据分析turf/buffer 完全指南基于 JSTS 的 GeoJSON 缓冲区生成原理与实战turf/buffer 完全指南基于 JSTS 的 GeoJSON 缓冲区生成原理与实战 turf/buffer 是 Turf 模块化地理计算引擎中用于生数据分析上一篇5步快速掌握LocalAI开源AI引擎的终极本地部署指南下一篇7个超实用SVGR SVG组合动画技巧轻松同步多个动态效果创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考