node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »


image-to-heightmap npm version Build Status

Convert a JPG or PNG image into a heightmap array

Initial Motivation

To use when creating terrains in WebGL


  1. Make a hilly terrain in a 3d modeling tool
  2. Save as heightmap image
  3. Use image-to-heightmap on image
  4. Generate a grid of GL_TRIANGLES (tiles) using the heights from the heightmap

To Install

$ npm install --save image-to-heightmap


var toHM = require('image-to-heightmap')
// This will generate an 11 x 6 heightmap array from our image 
// Why 11 x 6 ? 
// 10 x 5 tiles means we have 11 x 6 different corners 
toHM('some-image.png', 10, 5, 2, function (err, heightmap) {
    // The height of the point at the bottom left corner 

What are tiles ?

Picture a terrain that's made up of a bunch of equally sized rectangles

Each rectangle has 4 corners. Each of these corners has a height

Rectangles will share some corners with adjacent rectangles

1 tile wide x 1 tile high = 2 corners wide x 2 corners height

2 tile wide x 3 tile high = 3 corners wide x 4 corners height

etc ...


Maybe call this a grid instead of tiles?


toHM(imageURL, numXTiles, numYTiles, scale, callback)



Type: string

imageURL is the path to the file. It can be a relative path, an http url, a data url, or an in-memory Buffer

This gets passed into scijs/get-pixels



Type: number

The number of tiles wide that your terrain will be


Type: number

The number of tiles deep that your terrain will be


Type: number

image-to-heightmap generates heights with 0 <= height <= scale

A black pixel will have a height of 0

A white pixel will have a height of scale

A pixel with rgba of 50, 50, 50, 255 would have a height of (50 / 255 * scale)


Type: function

Called with an error and your 2-dimensional heightmap array

function cb (err, heightmap) {
  // The height at the top right corner of the bottom left tile


  • Talk about what types of images to use
  • Add defaults? Maybe a default scale of 1?
  • Test edge cases. ex: what happens when trying to make a 0 x 0 grid?