GridMapper

A JavaScript library for allocating geographic points to a grid using Mixed Integer Programming (MIP). This library provides an optimized solution for spatial data visualization by mapping geographic coordinates to grid cells while preserving spatial relationships.


Inspiration

This library is inspired by and builds upon the work of Jo Wood's Grid Map Allocation library (@gridmap_allocation). The original implementation demonstrated the concept of using linear programming to allocate geographic points to grid cells. This library extends that work with small additional features and optimizations.

Features

- Simple API: Matches the original Jo Wood library API for easy migration
- Advanced API: Extended features including:
- Auto-calculation of grid dimensions based on aspect ratio
- Principal Component Analysis (PCA) rotation for better alignment
- Support for hexagonal and rectangular grids
- Adjacency constraints for compact clustering
- Post-processing optimization with simulated annealing
- Flexible MIP Solver: Works with any MIP solver that implements the required interface (GLPK.js included)

Installation

``bash
npm install gridmapper
`

Quick Start

$3

`javascript
import { GridMapper } from 'gridmapper';
import { GLPKSolver } from 'gridmapper/glpk-solver';
import glpk from 'glpk.js';

const glpkInstance = await glpk();
const mapper = new GridMapper();

const points = [
[longitude1, latitude1],
[longitude2, latitude2],
// ... more points
];

const result = await mapper.allocateSimple(
points,
7, // rows
12, // cols
0.6, // compactness (0-1)
[], // spacers
{
mip: () => new GLPKSolver(glpkInstance)
}
);

console.log(result.cells); // [[row, col], ...]
`

$3

`javascript
import { GridMapper } from 'gridmapper';
import { GLPKSolver } from 'gridmapper/glpk-solver';
import glpk from 'glpk.js';

const glpkInstance = await glpk();
const mapper = new GridMapper();

const data = [
{ name: 'Location A', lon: -74.0, lat: 40.7 },
{ name: 'Location B', lon: -73.9, lat: 40.8 },
// ... more locations
];

const result = await mapper.allocate(data, {
xAccessor: d => d.lon,
yAccessor: d => d.lat,
compactness: 0.6,
rotateByPCA: true, // Align grid to principal axis
gridType: 'rect', // or 'hex'
mip: () => new GLPKSolver(glpkInstance)
// rows and cols are auto-calculated if not provided
});

// Result includes gridX and gridY properties added to each data item
result.assignments.forEach(item => {
console.log(${item.name}: grid[${item.gridX}, ${item.gridY}]);
});
`

API Reference

$3

#### allocateSimple(points, nRows, nCols, compactness, spacers, options)

Simple allocation API matching the original Jo Wood library.

Parameters:
- points (Array): Array of [x, y] coordinates or objects with x/y accessors
- nRows (number): Number of grid rows
- nCols (number): Number of grid columns
- compactness (number): 0 to 1. 0.5 = relative geo position, 1 = center cluster
- spacers (Array): Optional array of [row, col] spacer positions
- options (Object): Optional configuration
- xAccessor (Function): Accessor for x coordinate
- yAccessor (Function): Accessor for y coordinate
- mip (Function): Factory function returning MIP solver instance

Returns: Promise