Grid Generation

Grid generation functions in Turf.js create regular geometric patterns of points or polygons within a specified area. These utilities are essential for spatial analysis tasks such as sampling, tessellation, and creating uniform spatial data structures. The grid generation system provides four distinct grid types: hexagonal, square, triangular, and point grids, each optimized for different analytical use cases.

For information about spatial clustering algorithms, see Clustering. For statistical analysis functions that work with grid-based data, see Statistical Analysis.

Grid Types and Module Structure

The grid generation system consists of five specialized modules, each implementing a specific grid pattern:

Module	Function	Output	Primary Use Case
@turf/point-grid	pointGrid()	Point features	Sampling, analysis locations
@turf/square-grid	squareGrid()	Square polygon features	Regular tessellation, equal-area cells
@turf/rectangle-grid	rectangleGrid()	Rectangle polygon features	Base grid implementation
@turf/hex-grid	hexGrid()	Hexagonal polygon features	Optimal coverage, adjacency analysis
@turf/triangle-grid	triangleGrid()	Triangular polygon features	Triangulation-based analysis

Module Dependencies and Architecture

100%

Point Grid Implementation

The pointGrid function generates a regular array of point features within a bounding box. This is the most commonly used grid type for sampling and analysis operations.

Function Signature and Parameters

All grid generation functions follow a consistent API pattern:

gridFunction(bbox: BBox, cellSide: number, options?: GridOptions)

Standard Parameters:

Parameter	Type	Description
bbox	BBox	Bounding box array [minX, minY, maxX, maxY] defining grid area
cellSide	number	Distance between grid cells (spacing or side length)
options	Object	Optional configuration object

Common Options:

Option	Type	Default	Modules	Description
units	string	"kilometers"	All	Unit of measurement: "miles", "kilometers", "degrees", etc.
mask	Feature<Polygon>	undefined	point-grid	Polygon to clip grid points
properties	Object	{}	All	Properties to add to each feature
triangles	boolean	false	hex-grid	Return triangular grid instead of hexagons

Grid-Specific Processing Flow

100%

Usage Examples and Configuration

Point Grid Example:

const bbox = [-95, 30, -85, 40];
const cellSide = 50;
const options = { 
  units: 'miles',
  properties: { gridType: 'analysis' }
};
const grid = pointGrid(bbox, cellSide, options);

Hexagonal Grid with Triangulation:

const bbox = [-96.6, 31.1, -84.9, 40.6];
const cellSide = 50;
const options = {
  units: 'miles',
  triangles: true,  // Returns triangular cells instead of hexagons
  properties: { foo: 'bar' }
};
const hexGrid = hexGrid(bbox, cellSide, options);
// Access properties: hexGrid.features[0].properties.foo

Square Grid via Rectangle Grid:

The squareGrid() function internally delegates to rectangleGrid() to create square cells, ensuring equal dimensions:

const bbox = [-95, 30, -85, 40];
const cellSide = 10;
const grid = squareGrid(bbox, cellSide, { units: 'kilometers' });

Configuration Options Matrix:

Grid Type	Supports Masking	Supports Triangulation	Cell Clipping Method
pointGrid	Yes (via mask option)	No	@turf/boolean-within
squareGrid	No	No	N/A
rectangleGrid	No	No	N/A
hexGrid	Yes (implicit)	Yes (via triangles option)	@turf/intersect
triangleGrid	Yes (implicit)	No	@turf/intersect

Hexagonal Grid Special Features

The @turf/hex-grid module provides unique functionality compared to other grid types:

Hexagon vs Triangle Mode

The hexGrid() function can generate either hexagonal or triangular grids based on the triangles option:

100%

Hexagon Geometry Calculation

Hexagonal grids use specialized geometry based on regular hexagon properties:

Hexagon Property	Calculation	Purpose
Side length	cellSide parameter	Direct input
Width (flat-topped)	√3 × sideLength	Horizontal spacing
Height (flat-topped)	2 × sideLength	Vertical spacing
Row offset	width / 2	Alternating row alignment
Vertex angles	Multiples of 60°	Regular hexagon vertices

Distance and Intersection Usage

The hex-grid module leverages other Turf modules for accurate calculations:

100%

Geographic Edge Cases and Projections

Grid generation handles several geographic edge cases, particularly around the International Date Line and polar regions:

Coordinate System Handling

The system processes coordinates across various geographic boundaries:

Test Case	Coordinates	Special Handling
Fiji	[-180.34, -17.11, -179.57, -16.48]	Date line crossing
Arctic	[-95.87, 74.46, -94.03, 74.90]	High latitude
Large bbox	[-220.78, -80.64, -29.53, 78.34]	Extended longitude range

Unit Conversion System

Grid spacing is specified in various units and converted to appropriate coordinate deltas:

100%

Masking and Filtering

The grid generation system supports polygon masking to limit grid points to specific geographic areas:

100%

The masking system processes complex polygons with multiple vertices, as demonstrated in the Piedmont region test case with 28 coordinate pairs defining the boundary.

Integration with Core Modules

Grid generation functions integrate closely with Turf's core helper and metadata modules:

100%

The integration ensures consistent GeoJSON output format and leverages shared coordinate processing utilities across all grid types.