数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载导读turf/rectangle-grid是 Turf 模块化地理空间引擎项目仓库中的网格生成模块用于在指定的地理包围盒bbox内生成一组宽度、高度在角度degrees维度上保持一致的矩形多边形网格。本文以 packages/turf-rectangle-grid/README.md 为骨架结合模块源码 index.ts、单元测试 test.ts 与基准测试 bench.ts系统讲解rectangleGrid的完整 API、单位换算原理、居中算法、掩膜裁剪以及测试与性能表现帮助你掌握在 Turf 生态中快速生成规则矩形网格的实战能力。一、模块概览与安装turf/rectangle-grid是 Turf 众多模块中专门负责规则矩形网格生成的模块。从 package.json 可以看到它的描述是 Creates a grid of rectangular polygons with width and height consistent in degrees关键词为grid、regular、cartesian当前版本为7.4.0采用 ESM 模块规范type: module运行环境要求 Node.js 22。安装有两种方式单独安装本模块$ npm install turf/rectangle-grid或安装包含全部模块的聚合包turf/turf这样所有模块都会以函数形式挂载到turf对象上$ npm install turf/turf从 package.json 的dependencies可以看出本模块底层依赖三个 Turf 兄弟模块turf/boolean-intersects用于掩膜相交判定、turf/distance与turf/helpers提供convertLength、featureCollection、polygon等工具函数这为后续源码分析提供了线索。二、rectangleGrid API 详解rectangleGrid函数接受一个 bbox、单元格宽度、单元格高度以及可选参数返回一个FeatureCollectionPolygon类型的多边形网格。2.1 参数表参数类型说明bboxBBox网格范围按[minX, minY, maxX, maxY]顺序给出若网格无法完美填满 bbox结果会居中cellWidthnumber每个单元格的宽度单位由options.units指定cellHeightnumber每个单元格的高度单位由options.units指定optionsObject可选参数默认{}options.unitsUnits单元格宽高的单位支持 Turf 全部合法单位默认kilometersoptions.maskFeaturePolygon\|MultiPolygon可选传入 Polygon 或 MultiPolygon 时只在掩膜内部生成网格多边形options.propertiesObject传递给网格中每个多边形的属性默认{}返回值FeatureCollectionPolygon——一个包含若干矩形多边形的要素集合。2.2 官方示例原 README 给出的最小可运行示例以英里为单位生成矩形网格var bbox [-95, 30 ,-85, 40]; var cellWidth 50; var cellHeight 20; var options {units: miles}; var rectangleGrid turf.rectangleGrid(bbox, cellWidth, cellHeight, options); //addToMap var addToMap [rectangleGrid]在 ESM / TypeScript 环境下也可以直接导入模块化函数import rectangleGrid from turf/rectangle-grid; const bbox [-95, 30, -85, 40]; const grid rectangleGrid(bbox, 50, 20, { units: miles });2.3 options.units支持的单位与角度一致的语义options.units支持 Turf 定义的全部合法单位。完整的单位清单定义在 packages/turf-helpers/README_UNITS.md包括meters/metresmillimeters/millimetrescentimeters/centimetreskilometers/kilometresmilesnauticalmilesinchesyardsfeetradiansdegrees这里有一个关键语义需要特别注意README 与源码注释都反复强调如果你需要的是在线性单位如千米下宽度与高度相等的正方形网格这个模块并不适合你。因为cellWidth与cellHeight会在内部从给定单位换算为度degrees所以最终生成的多边形其宽高只在度这一角度度量上保持一致而非在地球表面真实的线性距离上保持一致。这一点是使用rectangleGrid时最容易踩的坑。三、源码级实现原理3.1 调用链与依赖关系从 index.ts 的导入语句可见函数内部依赖turf/helpers的convertLength、featureCollection、polygon以及turf/boolean-intersects的booleanIntersects。核心流程为单位换算 → 行列数计算 → 居中偏移 → 双循环生成多边形 → 掩膜过滤 → 打包成 FeatureCollection。3.2 单位换算convertLengthrectangleGrid将宽高统一换算为度const cellWidthDeg convertLength(cellWidth, options.units, degrees); const cellHeightDeg convertLength(cellHeight, options.units, degrees);convertLength定义在 packages/turf-helpers/index.ts其实现为export function convertLength( length: number, originalUnit: Units kilometers, finalUnit: Units kilometers ): number { if (!(length 0)) { throw new Error(length must be a positive number); } return radiansToLength(lengthToRadians(length, originalUnit), finalUnit); }它先将长度转为弧度再转为目标单位并且会校验length必须为非负数。这意味着传入负的cellWidth/cellHeight会直接抛出length must be a positive number错误。3.3 行列计算与居中算法const bboxWidth east - west; const bboxHeight north - south; const columns Math.floor(Math.abs(bboxWidth) / cellWidthDeg); const rows Math.floor(Math.abs(bboxHeight) / cellHeightDeg); // 若网格无法完美填满 bbox将其居中 const deltaX (bboxWidth - columns * cellWidthDeg) / 2; const deltaY (bboxHeight - rows * cellHeightDeg) / 2; let currentX west deltaX; for (let column 0; column columns; column) { let currentY south deltaY; for (let row 0; row rows; row) { // 构造 [西,南,东,北] 对应的五坐标闭合环 const cellPoly polygon( [ [ [currentX, currentY], [currentX, currentY cellHeightDeg], [currentX cellWidthDeg, currentY cellHeightDeg], [currentX cellWidthDeg, currentY], [currentX, currentY], ], ], options.properties ); ... currentY cellHeightDeg; } currentX cellWidthDeg; }可以看到实现的关键点行列数向下取整Math.floor保证了生成的网格不会超出 bbox 边界居中策略当bboxWidth % cellWidthDeg ! 0时剩余宽度的一半被作为deltaX偏移量加到起始 X 上deltaY同理使网格整体在 bbox 内居中而不是从 bbox 的西南角平铺这正是 README 中If the grid does not fill the bbox perfectly, it is centered的源码实现单元格为闭合五坐标环每个矩形由西南角起、按逆时针方向依次经过西北、东北、东南、再回到西南角共 5 个坐标构成闭合环首尾坐标相同符合 GeoJSON Polygon 的线性环闭合要求属性透传options.properties会作为第二个参数传入polygon()因此每个生成的单元格都会携带相同的自定义属性。3.4 掩膜mask过滤机制当传入options.mask时源码使用booleanIntersects做相交测试只有与掩膜相交的单元格才被保留if (options.mask) { if (intersect(options.mask, cellPoly)) { results.push(cellPoly); } } else { results.push(cellPoly); }需要注意这里采用的是**相交intersects而非包含contains**判定即只要单元格与掩膜多边形有任意重叠就会被保留。因此当掩膜是复杂的不规则多边形例如澳大利亚边界时边界处的单元格往往会被部分截断成不完整矩形输出结果是被掩膜裁剪过的网格集合。最后所有保留的单元格通过featureCollection(results)打包返回。四、实战案例来自测试夹具的完整用法模块的 test 目录 提供了 6 组真实测试夹具覆盖了不同单位、不同 bbox 大小与掩膜场景是理解 API 用法的第一手资料夹具文件bboxcellWidthcellHeightunits说明10x10-1degree.json局部范围1010degrees以度为单位的等宽高网格victoria-20x100-km.json[141, -39, 150, -34]20100kilometers千米单位、宽高不对称网格fiji-10x5-miles.json斐济范围105miles英里单位网格big-bbox-500x100-miles.json[-220.78125, -80.647, -29.53125, 78.349]500100miles跨越大范围的大 bboxglobal-grid.json[-180, -90, 180, 90]1010degrees全球范围网格australia-mask.json[110, 0, 160, -50]12degrees带澳大利亚多边形掩膜例如使用维多利亚州范围的千米单位网格{ bbox: [141, -39, 150, -34], cellWidth: 20, cellHeight: 100, units: kilometers }调用方式即const grid rectangleGrid([141, -39, 150, -34], 20, 100, { units: kilometers });再如带掩膜的用例掩膜为澳大利亚大陆的 Polygon1×2 度单元格{ bbox: [110, 0, 160, -50], cellWidth: 1, cellHeight: 2, units: degrees, mask: { type: Feature, properties: {}, geometry: { type: Polygon, coordinates: [...] } } }调用方式const grid rectangleGrid([110, 0, 160, -50], 1, 2, { units: degrees, mask: maskFeature, // 澳大利亚多边形 });4.1 如何运行测试测试脚本定义在 package.json 中pnpm test:tape # 等价于 tsx test.tstest.ts 会读取test/in下每个夹具以夹具 JSON 中的bbox、cellWidth、cellHeight、units、properties、mask字段调用rectangleGrid再用turf/truncate截断坐标精度后与test/out目录中的期望输出做深度相等断言同时会把 bbox红色与掩膜蓝色作为样式要素追加进结果便于可视化核对。若设置环境变量REGEN则会将实际结果写回test/out重新生成期望文件。4.2 性能表现bench.ts 内置了三个量级的基准测试均在[-95, 30, -85, 40]的 bbox 上场景单元格宽高单元格数量吞吐量highres1 × 2 英里约 206310 个约 5.99 ops/secmidres10 × 20 英里约 2006 个约 3388 ops/seclowres100 × 200 英里15 个约 466370 ops/sec运行基准pnpm bench # 等价于 tsx bench.ts该结果注释中记录的实测值直观地表明性能随单元格数量线性下降单元格数量是决定耗时的最主要因素因此在大范围、高分辨率网格场景下应评估数据规模与渲染/存储成本。五、使用建议与注意事项明确度的语义rectangleGrid的单元格宽高最终以度为单位一致生成的矩形在赤道附近接近真实等距在高纬度地区线性距离会被拉长。如需线性单位下真正等距的正方形网格应改用turf/square-grid或turf/point-grid等按目标投影计算的方案。bbox 顺序不可颠倒bbox必须严格按[minX, minY, maxX, maxY]传入源码直接以west bbox[0]、south bbox[1]、east bbox[2]、north bbox[3]解构顺序错误会导致网格方向与预期不符。宽高为非负数convertLength会对负数抛出length must be a positive number异常请保证cellWidth、cellHeight为正数。掩膜是相交判定options.mask按booleanIntersects过滤掩膜边界处的单元格会被保留但呈不完整形态若要精确裁剪单元格本身需对结果另行做turf/intersect处理。属性透传options.properties会原样附加到每个单元格多边形上可用于为网格附加业务字段如索引编号、区域分类无需事后二次遍历赋值。六、小结rectangleGrid是一个设计简洁、语义清晰的网格生成工具三个必选参数加上units、mask、properties三个可选参数即可在任意 bbox 内生成角度一致的矩形网格。其源码index.ts以单位换算 → 取整分行列 → 居中偏移 → 双循环构造闭合环 → 掩膜相交过滤 → 打包 FeatureCollection为主线配合 test.ts 的多组真实夹具与 bench.ts 的性能基准构成了从 API 到实现的完整闭环。在需要快速生成规则格网用于空间索引、热力分区、采样布点等场景时本模块是最直接的选择而需要线性单位等距网格时请选择 Turf 的其他网格模块。赞分享数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载相关推荐turf/difference 多边形差集运算完全指南从 API 到源码级实现解析turf/difference 多边形差集运算完全指南从 API 到源码级实现解析 在 Turf.js 的几何运算体系中 difference 差集是数据分析用 Turf 从点集生成凹包Concave Hullturf/concave 参数原理与实战指南用 Turf 从点集生成凹包Concave Hullturf/concave 参数原理与实战指南 本文围绕 Turf 生态中的 turf/concav数据分析Turf squareGrid 完全指南基于 turf/square-grid 生成经纬度一致的方形网格Turf squareGrid 完全指南基于 turf/square grid 生成经纬度一致的方形网格 导读 turf/square grid 是 Tu数据分析上一篇超实用Thief-Book-Plugin插件从安装到精通的零门槛指南下一篇终极adr-tools环境变量配置指南高级用户定制化全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Turf rectangleGrid 矩形网格生成完全指南：从 API 参数到源码级实现原理
数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载导读turf/rectangle-grid是 Turf 模块化地理空间引擎项目仓库中的网格生成模块用于在指定的地理包围盒bbox内生成一组宽度、高度在角度degrees维度上保持一致的矩形多边形网格。本文以 packages/turf-rectangle-grid/README.md 为骨架结合模块源码 index.ts、单元测试 test.ts 与基准测试 bench.ts系统讲解rectangleGrid的完整 API、单位换算原理、居中算法、掩膜裁剪以及测试与性能表现帮助你掌握在 Turf 生态中快速生成规则矩形网格的实战能力。一、模块概览与安装turf/rectangle-grid是 Turf 众多模块中专门负责规则矩形网格生成的模块。从 package.json 可以看到它的描述是 Creates a grid of rectangular polygons with width and height consistent in degrees关键词为grid、regular、cartesian当前版本为7.4.0采用 ESM 模块规范type: module运行环境要求 Node.js 22。安装有两种方式单独安装本模块$ npm install turf/rectangle-grid或安装包含全部模块的聚合包turf/turf这样所有模块都会以函数形式挂载到turf对象上$ npm install turf/turf从 package.json 的dependencies可以看出本模块底层依赖三个 Turf 兄弟模块turf/boolean-intersects用于掩膜相交判定、turf/distance与turf/helpers提供convertLength、featureCollection、polygon等工具函数这为后续源码分析提供了线索。二、rectangleGrid API 详解rectangleGrid函数接受一个 bbox、单元格宽度、单元格高度以及可选参数返回一个FeatureCollectionPolygon类型的多边形网格。2.1 参数表参数类型说明bboxBBox网格范围按[minX, minY, maxX, maxY]顺序给出若网格无法完美填满 bbox结果会居中cellWidthnumber每个单元格的宽度单位由options.units指定cellHeightnumber每个单元格的高度单位由options.units指定optionsObject可选参数默认{}options.unitsUnits单元格宽高的单位支持 Turf 全部合法单位默认kilometersoptions.maskFeaturePolygon\|MultiPolygon可选传入 Polygon 或 MultiPolygon 时只在掩膜内部生成网格多边形options.propertiesObject传递给网格中每个多边形的属性默认{}返回值FeatureCollectionPolygon——一个包含若干矩形多边形的要素集合。2.2 官方示例原 README 给出的最小可运行示例以英里为单位生成矩形网格var bbox [-95, 30 ,-85, 40]; var cellWidth 50; var cellHeight 20; var options {units: miles}; var rectangleGrid turf.rectangleGrid(bbox, cellWidth, cellHeight, options); //addToMap var addToMap [rectangleGrid]在 ESM / TypeScript 环境下也可以直接导入模块化函数import rectangleGrid from turf/rectangle-grid; const bbox [-95, 30, -85, 40]; const grid rectangleGrid(bbox, 50, 20, { units: miles });2.3 options.units支持的单位与角度一致的语义options.units支持 Turf 定义的全部合法单位。完整的单位清单定义在 packages/turf-helpers/README_UNITS.md包括meters/metresmillimeters/millimetrescentimeters/centimetreskilometers/kilometresmilesnauticalmilesinchesyardsfeetradiansdegrees这里有一个关键语义需要特别注意README 与源码注释都反复强调如果你需要的是在线性单位如千米下宽度与高度相等的正方形网格这个模块并不适合你。因为cellWidth与cellHeight会在内部从给定单位换算为度degrees所以最终生成的多边形其宽高只在度这一角度度量上保持一致而非在地球表面真实的线性距离上保持一致。这一点是使用rectangleGrid时最容易踩的坑。三、源码级实现原理3.1 调用链与依赖关系从 index.ts 的导入语句可见函数内部依赖turf/helpers的convertLength、featureCollection、polygon以及turf/boolean-intersects的booleanIntersects。核心流程为单位换算 → 行列数计算 → 居中偏移 → 双循环生成多边形 → 掩膜过滤 → 打包成 FeatureCollection。3.2 单位换算convertLengthrectangleGrid将宽高统一换算为度const cellWidthDeg convertLength(cellWidth, options.units, degrees); const cellHeightDeg convertLength(cellHeight, options.units, degrees);convertLength定义在 packages/turf-helpers/index.ts其实现为export function convertLength( length: number, originalUnit: Units kilometers, finalUnit: Units kilometers ): number { if (!(length 0)) { throw new Error(length must be a positive number); } return radiansToLength(lengthToRadians(length, originalUnit), finalUnit); }它先将长度转为弧度再转为目标单位并且会校验length必须为非负数。这意味着传入负的cellWidth/cellHeight会直接抛出length must be a positive number错误。3.3 行列计算与居中算法const bboxWidth east - west; const bboxHeight north - south; const columns Math.floor(Math.abs(bboxWidth) / cellWidthDeg); const rows Math.floor(Math.abs(bboxHeight) / cellHeightDeg); // 若网格无法完美填满 bbox将其居中 const deltaX (bboxWidth - columns * cellWidthDeg) / 2; const deltaY (bboxHeight - rows * cellHeightDeg) / 2; let currentX west deltaX; for (let column 0; column columns; column) { let currentY south deltaY; for (let row 0; row rows; row) { // 构造 [西,南,东,北] 对应的五坐标闭合环 const cellPoly polygon( [ [ [currentX, currentY], [currentX, currentY cellHeightDeg], [currentX cellWidthDeg, currentY cellHeightDeg], [currentX cellWidthDeg, currentY], [currentX, currentY], ], ], options.properties ); ... currentY cellHeightDeg; } currentX cellWidthDeg; }可以看到实现的关键点行列数向下取整Math.floor保证了生成的网格不会超出 bbox 边界居中策略当bboxWidth % cellWidthDeg ! 0时剩余宽度的一半被作为deltaX偏移量加到起始 X 上deltaY同理使网格整体在 bbox 内居中而不是从 bbox 的西南角平铺这正是 README 中If the grid does not fill the bbox perfectly, it is centered的源码实现单元格为闭合五坐标环每个矩形由西南角起、按逆时针方向依次经过西北、东北、东南、再回到西南角共 5 个坐标构成闭合环首尾坐标相同符合 GeoJSON Polygon 的线性环闭合要求属性透传options.properties会作为第二个参数传入polygon()因此每个生成的单元格都会携带相同的自定义属性。3.4 掩膜mask过滤机制当传入options.mask时源码使用booleanIntersects做相交测试只有与掩膜相交的单元格才被保留if (options.mask) { if (intersect(options.mask, cellPoly)) { results.push(cellPoly); } } else { results.push(cellPoly); }需要注意这里采用的是**相交intersects而非包含contains**判定即只要单元格与掩膜多边形有任意重叠就会被保留。因此当掩膜是复杂的不规则多边形例如澳大利亚边界时边界处的单元格往往会被部分截断成不完整矩形输出结果是被掩膜裁剪过的网格集合。最后所有保留的单元格通过featureCollection(results)打包返回。四、实战案例来自测试夹具的完整用法模块的 test 目录 提供了 6 组真实测试夹具覆盖了不同单位、不同 bbox 大小与掩膜场景是理解 API 用法的第一手资料夹具文件bboxcellWidthcellHeightunits说明10x10-1degree.json局部范围1010degrees以度为单位的等宽高网格victoria-20x100-km.json[141, -39, 150, -34]20100kilometers千米单位、宽高不对称网格fiji-10x5-miles.json斐济范围105miles英里单位网格big-bbox-500x100-miles.json[-220.78125, -80.647, -29.53125, 78.349]500100miles跨越大范围的大 bboxglobal-grid.json[-180, -90, 180, 90]1010degrees全球范围网格australia-mask.json[110, 0, 160, -50]12degrees带澳大利亚多边形掩膜例如使用维多利亚州范围的千米单位网格{ bbox: [141, -39, 150, -34], cellWidth: 20, cellHeight: 100, units: kilometers }调用方式即const grid rectangleGrid([141, -39, 150, -34], 20, 100, { units: kilometers });再如带掩膜的用例掩膜为澳大利亚大陆的 Polygon1×2 度单元格{ bbox: [110, 0, 160, -50], cellWidth: 1, cellHeight: 2, units: degrees, mask: { type: Feature, properties: {}, geometry: { type: Polygon, coordinates: [...] } } }调用方式const grid rectangleGrid([110, 0, 160, -50], 1, 2, { units: degrees, mask: maskFeature, // 澳大利亚多边形 });4.1 如何运行测试测试脚本定义在 package.json 中pnpm test:tape # 等价于 tsx test.tstest.ts 会读取test/in下每个夹具以夹具 JSON 中的bbox、cellWidth、cellHeight、units、properties、mask字段调用rectangleGrid再用turf/truncate截断坐标精度后与test/out目录中的期望输出做深度相等断言同时会把 bbox红色与掩膜蓝色作为样式要素追加进结果便于可视化核对。若设置环境变量REGEN则会将实际结果写回test/out重新生成期望文件。4.2 性能表现bench.ts 内置了三个量级的基准测试均在[-95, 30, -85, 40]的 bbox 上场景单元格宽高单元格数量吞吐量highres1 × 2 英里约 206310 个约 5.99 ops/secmidres10 × 20 英里约 2006 个约 3388 ops/seclowres100 × 200 英里15 个约 466370 ops/sec运行基准pnpm bench # 等价于 tsx bench.ts该结果注释中记录的实测值直观地表明性能随单元格数量线性下降单元格数量是决定耗时的最主要因素因此在大范围、高分辨率网格场景下应评估数据规模与渲染/存储成本。五、使用建议与注意事项明确度的语义rectangleGrid的单元格宽高最终以度为单位一致生成的矩形在赤道附近接近真实等距在高纬度地区线性距离会被拉长。如需线性单位下真正等距的正方形网格应改用turf/square-grid或turf/point-grid等按目标投影计算的方案。bbox 顺序不可颠倒bbox必须严格按[minX, minY, maxX, maxY]传入源码直接以west bbox[0]、south bbox[1]、east bbox[2]、north bbox[3]解构顺序错误会导致网格方向与预期不符。宽高为非负数convertLength会对负数抛出length must be a positive number异常请保证cellWidth、cellHeight为正数。掩膜是相交判定options.mask按booleanIntersects过滤掩膜边界处的单元格会被保留但呈不完整形态若要精确裁剪单元格本身需对结果另行做turf/intersect处理。属性透传options.properties会原样附加到每个单元格多边形上可用于为网格附加业务字段如索引编号、区域分类无需事后二次遍历赋值。六、小结rectangleGrid是一个设计简洁、语义清晰的网格生成工具三个必选参数加上units、mask、properties三个可选参数即可在任意 bbox 内生成角度一致的矩形网格。其源码index.ts以单位换算 → 取整分行列 → 居中偏移 → 双循环构造闭合环 → 掩膜相交过滤 → 打包 FeatureCollection为主线配合 test.ts 的多组真实夹具与 bench.ts 的性能基准构成了从 API 到实现的完整闭环。在需要快速生成规则格网用于空间索引、热力分区、采样布点等场景时本模块是最直接的选择而需要线性单位等距网格时请选择 Turf 的其他网格模块。赞分享数据分析【免费下载链接】turfA modular geospatial engine written in JavaScript and TypeScript项目地址https://gitcode.com/gh_mirrors/tu/turf点击查看免费下载相关推荐turf/difference 多边形差集运算完全指南从 API 到源码级实现解析turf/difference 多边形差集运算完全指南从 API 到源码级实现解析 在 Turf.js 的几何运算体系中 difference 差集是数据分析用 Turf 从点集生成凹包Concave Hullturf/concave 参数原理与实战指南用 Turf 从点集生成凹包Concave Hullturf/concave 参数原理与实战指南 本文围绕 Turf 生态中的 turf/concav数据分析Turf squareGrid 完全指南基于 turf/square-grid 生成经纬度一致的方形网格Turf squareGrid 完全指南基于 turf/square grid 生成经纬度一致的方形网格 导读 turf/square grid 是 Tu数据分析上一篇超实用Thief-Book-Plugin插件从安装到精通的零门槛指南下一篇终极adr-tools环境变量配置指南高级用户定制化全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考