数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载导读本文围绕 Turf 地理引擎中的turf/transform-translate模块系统讲解如何将任意 GeoJSON Feature 或 Geometry 沿 Rhumb Line恒向线按指定方向角移动指定距离覆盖参数语义、负距离反向移动、单位换算、Z 轴垂直平移与 mutate 性能优化等实战要点并结合仓库源码剖析其底层实现与测试验证帮助你在地理分析工作流中正确、高效地使用平移变换。一、模块定位与核心能力turf/transform-translate是 Turf 模块集合中的一个纯地理变换工具其功能定义非常聚焦将任意 GeoJSON Feature 或 Geometry 中的每一个坐标点沿一条 Rhumb Line恒向线在给定的方向角上移动指定的距离。官方对其行为有一个重要的边界说明该操作是逐点平移moves the points of your shape individually因此对于面积较大的多边形或跨投影的几何体整体形状可能发生肉眼可见的形变。形变程度取决于移动距离的大小与所使用投影的差异——距离越远、几何体覆盖的经纬跨度越大形变越明显。这一点在使用时务必留意它与“整体刚体平移”的直觉不同。源码注释与文档一致见 index.ts函数签名接受 GeoJSON 六大基本几何类型、Feature、FeatureCollection 以及 GeometryCollection返回被平移后的同类型对象。二、安装方式turf/transform-translate既可以作为独立模块安装也可以随全量模块turf/turf一起引入# 单独安装本模块 $ npm install turf/transform-translate # 或安装包含所有模块函数的全量包 $ npm install turf/turf在仓库中该模块的包名、版本与依赖声明见 package.json它依赖turf/meta坐标遍历、turf/helpers单位与工具函数、turf/invariant坐标取值、turf/clone深克隆以及turf/rhumb-destinationRhumb 线终点计算五个内部模块这种“小模块组合”的结构正是 Turf 模块化设计的一贯风格。三、API 与参数详解transformTranslate的函数签名含类型定义见 index.tstransformTranslateT extends GeoJSON | GeometryCollection( geojson: T, distance: number, direction: number, options?: { units?: Units; zTranslation?: number; mutate?: boolean; } ): T参数类型必填默认值说明geojsonGeoJSON \| GeometryCollection是—待平移的 GeoJSON 对象Feature、Geometry、FeatureCollection、GeometryCollection 均可distancenumber是—移动长度负值表示沿相反方向移动directionnumber是—移动方向角以“从正北起算的十进制度数”表示顺时针为正options.unitsUnits否kilometersdistance所使用的单位支持 Turf 全部合法单位kilometers、miles、meters、degrees、radians等options.zTranslationnumber否0垂直Z 轴方向移动的长度与distance使用相同单位options.mutateboolean否false是否允许直接修改传入的 GeoJSON 输入设为true可显著提升性能返回结果返回平移后的 GeoJSON 对象类型与输入保持一致见Returns (GeoJSON | GeometryCollection)。官方示例多边形平移文档给出的最小可运行示例完整复刻自 READMEvar poly turf.polygon([[[0,29],[3.5,29],[2.5,32],[0,29]]]); var translatedPoly turf.transformTranslate(poly, 100, 35); //addToMap var addToMap [poly, translatedPoly]; translatedPoly.properties {stroke: #F00, stroke-width: 4};该示例将三角形多边形沿 35° 方向自正北顺时针平移 100 公里默认单位并把平移后的结果标红以便在地图上对比。四、参数语义与底层行为深入剖析1. 负距离自动反向 180°distance传负值时函数不会报错而是将其等价转换为“反方向移动”// Invert with negative distances if (distance 0) { distance -distance; direction direction 180; }测试用例对这一点做了精确的数值验证见 test.ts原点[0, 0]以distance 10、direction 0正北移动得到[0, 0.08993203637245381]以distance -10、direction 0移动则得到[0, -0.08993203637245381]即沿正南移动相同距离。2. 零移动快捷路径源码提供“无运动短路”优化见 index.tszTranslation zTranslation ! undefined ? zTranslation : 0; if (distance 0 zTranslation 0) return geojson;当distance与zTranslation均为 0 时直接原样返回输入不做任何克隆或遍历计算。测试中也专门覆盖了这一场景shortcut no-motion仓库还提供了对应测试夹具 no-motion.geojson。3. 沿 Rhumb Line 逐点移动底层核心平移的实现不是简单的经纬度加减而是对每个坐标点调用turf/rhumb-destination计算“从该点沿恒向线走指定距离后的新位置”见 index.tscoordEach(geojson, function (pointCoords) { var newCoords getCoords( rhumbDestination(pointCoords, distance, direction, { units: units }) ); pointCoords[0] newCoords[0]; pointCoords[1] newCoords[1]; if (zTranslation pointCoords.length 3) pointCoords[2] zTranslation; });其中coordEach来自turf/meta会递归遍历任意嵌套深度的全部坐标数组rhumbDestination来自turf/rhumb-destination。深入该依赖的源码见 rhumb-destination 的 index.ts可以看到两个关键细节单位统一换算distance先经convertLength按options.units换算为米再参与计算因此units的取值直接影响结果数值180° 经线跨越补偿计算后会对结果经度做-360 / 360修正避免横跨 180° 经线国际日期变更线附近时产生跳跃式错误其球面恒向线公式calculateRhumbDestination改编自 Geodesy 公开算法包括极区纬度归一化、东西方向航行时0/0病态情况的余弦退化处理等数值稳定性保护。4. Z 轴垂直平移zTranslationzTranslation用于三维坐标的垂直移动只有当坐标数组长度为 3即含 Z 值时第三个分量才会被累加zTranslation二维坐标则不受影响。测试夹具 z-translation.geojson 提供了一个带海拔高度的三维多边形示例距离 120 英里、方向 165°、zTranslation15用于验证垂直平移路径。5. mutate默认克隆保护输入默认情况下mutate为false或未提供函数会先用turf/clone深克隆输入保证原对象不被修改只有显式传入mutate: true时才直接就地改写坐标从而跳过克隆开销、显著提升性能见 index.ts。测试中专门验证了两种模式默认模式下平移后原线串坐标完全不变input should NOT be mutatedmutate: true模式下原对象被就地修改input should be mutated见 test.ts。6. 过期 bbox 清理平移会改变几何范围因此函数在返回前调用removeBbox清除对象中携带的旧bbox字段避免使用者拿到失效的边界信息。测试translate -- removes stale bbox values见 test.ts构造了嵌套带 bbox 的 FeatureCollection验证默认克隆输出与mutate输入两种路径下 bbox 都被正确清除。五、输入校验与类型支持1. 参数校验规则抛错场景源码中的输入校验见 index.ts与测试用例一一对应见 test.ts非法输入抛出错误信息geojson为null/缺失geojson is requireddistance为null/undefined/NaNdistance is requireddirection为null/undefined/NaNdirection is requiredunits传不合法单位如foo由rhumbDestination的convertLength抛出invalid unitszTranslation传非数字zTranslation is not a numberoptions不是对象options is invalid2. 全类型输入支持transformTranslate的泛型签名T extends GeoJSON | GeometryCollection保证了输出类型与输入类型一致见 types.ts且测试明确覆盖了以下输入形式见 test.ts单个 Geometry如line.geometryFeatureCollectionGeometryCollection 的 Feature 包装与裸 Geometry 两种形态。也就是说你可以对任意层级的 GeoJSON 结构执行平移类型系统会在编译期给出正确推断。六、性能特征仓库中的 bench.ts 使用 benchmark 库对test/in下的全部夹具做了基准测试其注释记录的实测吞吐量大致为Point约 121,712 ops/sec最快单点计算开销极小Polygon约 73,538 ops/secMultiLine / MultiPoint约 55,000 ops/secMultiPolygon约 3,685 ops/sec顶点数最多最慢z-translation 场景约 44,638 ops/sec。从结构可以推断性能主要取决于坐标点总数coordEach逐点计算以及是否开启mutate克隆成本。需要说明以上数值是仓库源码注释中记录的基准运行结果仅代表该模块在作者测试环境下的相对量级可用于横向比较不同几何类型的开销差异不应视为通用性能承诺。若对性能敏感建议在mutate: true下自行用npm run bench复测模块脚本定义见 package.json。七、常见使用场景与注意事项小结风向/洋流偏移模拟将点或多边形沿固定方位角移动固定距离如模拟航迹偏移、缓冲区整体平移空间对齐把对比对象平移至同一参考位置后再做布尔运算或距离量算Z 值批量抬升/下沉通过zTranslation对含高程的 3D 坐标整体调整高度注意逐点平移的形变跨越大经纬跨度、距离较远时多边形形状可能失真必要时先用投影到平面坐标系再平移注意输入不可变约定默认不修改原对象若复用它做后续计算可放心传入追求吞吐则显式开启mutate。八、相关资源模块 API 文档README.md核心实现index.ts测试用例与夹具test.ts、test/in基准测试bench.ts底层依赖rhumb-destination 实现全量 Turf 包packages/turf赞分享数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载相关推荐turf/rhumb-distance 源码解析恒向线Rhumb Line距离计算的 Turf 实现指南turf/rhumb distance 源码解析恒向线Rhumb Line距离计算的 Turf 实现指南 导读 本文以 turf/rhumb dist数据分析turf/line-offset 指南用 Turf 为线要素生成平行偏移线turf/line offset 指南用 Turf 为线要素生成平行偏移线 turf/line offset 是 Turf 模块化地理引擎中专门用于线偏数据分析turf/simplify 指南基于 simplify-js 的 GeoJSON 几何体简化原理与实战turf/simplify 指南基于 simplify js 的 GeoJSON 几何体简化原理与实战 Turf 是一个模块化的 JavaScript/Ty数据分析上一篇深入理解portal-mulit-cluster-script架构Python2/Python3双版本兼容实现下一篇揭秘duoyibu-ai技术架构数字与AI如何融合保护传统文化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考