GeoJSON Shadow Generator

A powerful tool to simulate shadow geometries from 2D building footprints (as GeoJSON) using sun position (via direct angles or date-time). Supports elevation-based shadow generation and handles Polygon and MultiPolygon types.

Installation

npm install geojson-shadow-generator

or with yarn:

yarn add geojson-shadow-generator

or with vanillajs

https://cdn.jsdelivr.net/npm/geojson-shadow-generator/bundle.js

✨ Features

• Calculates shadow geometries based on:

  • Direct sun azimuth/elevation angles.
  • Automatic sun position using date-time and GeoJSON center.

• Validates input GeoJSON (Feature or FeatureCollection).

• Supports Polygon and MultiPolygon geometry types.

• Uses @turf and suncalc libraries under the hood.

• Returns output as a valid GeoJSON FeatureCollection or Feature.

Usage

Import

const GeoJSONShadowGenerator = require('geojson-shadow-generator');

Example

const geojson = require('./yourGeoJSON.json');

const generator = new GeoJSONShadowGenerator(geojson, 'elevation');

// Using direct sun angles
const shadows1 = generator.getShadowGeometries({
  type: 'direct',
  sunAzimuth: 135,        // degrees from north, clockwise
  sunElevation: 30        // degrees above horizon
});

// Using date-time and automatic sun position
const shadows2 = generator.getShadowGeometries({
  type: 'datetime',
  date: '2025-06-01T10:00:00Z'
});

Constructor

new GeoJSONShadowGenerator(geojson: FeatureCollection | Feature, elevationPropertyName?: string)

| Parameter | Type | Required | Description | | ----------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------- | | geojson | GeoJSON | ✅ | Input Feature or FeatureCollection with Polygon or MultiPolygon geometries. | | elevationPropertyName | string | ❌ | Property name in feature properties that holds the elevation value. Default is 'elevation'. |

⚙️ getShadowGeometries(options)

Generates shadow geometries.

Options

| Key | Type | Required | Description | | -------------- | -------------------------- | --------------------------------- | ------------------------------------------------------------------------ | | type | 'direct' | 'datetime' | ❌ | Type of shadow calculation. Default: 'direct'. | | sunAzimuth | number | Required if type === 'direct' | Azimuth angle (degrees from north, clockwise). | | sunElevation | number | Required if type === 'direct' | Sun elevation angle (degrees above horizon). | | date | string (ISO format) | Required if type === 'datetime' | ISO date-time string used to calculate sun position from GeoJSON center. |

GeoJSON Requirements

• Input must be a valid GeoJSON Feature or FeatureCollection.
• Geometry type must be Polygon or MultiPolygon.
• Each feature must have a numeric elevation property (or custom property if set via constructor).

Example of a valid feature:

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [27.09, 38.45],
        [27.10, 38.45],
        [27.10, 38.46],
        [27.09, 38.46],
        [27.09, 38.45]
      ]
    ]
  },
  "properties": {
    "elevation": 50
  }
}

Behind the Scenes

• Uses suncalc to compute sun azimuth and elevation from date and latitude/longitude.
• Projects coordinates to EPSG:3857 to perform shadow translation in meters.
• Offsets geometry using the solar vector and elevation.
• Combines the original and translated geometries to form shadows.
• Uses Turf's convex, difference, and union functions.

Testing

Example test case:

const test = new GeoJSONShadowGenerator(geojson, 'elevation');

const result1 = test.getShadowGeometries({
  type: 'datetime',
  date: '2025-05-31T14:30:00'
});

const result2 = test.getShadowGeometries({
  type: 'direct',
  sunAzimuth: 50,
  sunElevation: 45
});

Output

The returned result is a GeoJSON FeatureCollection that represents the shadow geometries of the input features.

Dependencies

This package uses the following libraries:

• @turf/union
• @turf/difference
• @turf/center
• @turf/convex
• @turf/helpers
• geojson-validation
• proj4
• suncalc

License

MIT © 2025 - Ali Kilic | https://akilic.com

Tip

You can visualize the shadow outputs using:

• geojson.io
• Kepler.gl
• openlayers.org
• gislayer.com
• Or web map libraries like Leaflet, Mapbox GL, or OpenLayers.