https://github.com/falseinput/geogrid-maplibre-gl

GeoGrid is a MapLibre GL JS plugin for adding a highly customizable geographic grid to your map.
https://github.com/falseinput/geogrid-maplibre-gl

Last synced: 22 days ago
JSON representation

GeoGrid is a MapLibre GL JS plugin for adding a highly customizable geographic grid to your map.

• Host: GitHub
• URL: https://github.com/falseinput/geogrid-maplibre-gl
• Owner: falseinput
• License: mit
• Created: 2024-11-20T20:47:52.000Z (about 2 months ago)
• Default Branch: main
• Last Pushed: 2024-12-07T11:20:48.000Z (about 1 month ago)
• Last Synced: 2024-12-07T12:19:41.475Z (about 1 month ago)
• Language: TypeScript
• Size: 2.07 MB
• Stars: 17
• Watchers: 2
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-maplibre - geogrid-maplibre-gl - Renders customizable graticule (geographic grid). (Map Rendering Plugins / JavaScript)

README

        

# GeoGrid for MapLibre GL  

**GeoGrid** is a MapLibre GL JS plugin for adding a highly customizable geographic grid (graticule) to your map.

![GeoGrid example](./assets/geogrid.jpg)

## Features

- **Display Geographic Grid**: Adds a grid with labeled coordinates to the map.

- **[Experimental] Globe Projection Support** - Works with globe projection in maplibre-gl-js 5.x.

- **Customizable Grid Density**: Adjust grid density dynamically based on zoom level.

- **Zoom Level Visibility Range**: Control grid visibility with the `zoomLevelRange` option.

- **Custom Label Formats**: Change the label format to suit your needs. Default format:  

  ```[degrees]° [minutes]’ [seconds]’’```

- **Flexible Styling**: Modify grid and labels styles using JS API. For advanced use cases, override container and label CSS.

- **Layer Placement Control**: Place grid lines under any existing map layer using `beforeLayerId`.

- **Dynamic Label Visibility**: Labels automatically hide when the map is rotated away from north.

- **Optimized Performance**: Only elements visible in the viewport are rendered, ensuring no performance impact.

- **Easy Removal**: Remove the grid programmatically using the `remove()` method.

- **TypeScript Support**: Includes TypeScript definitions for better development experience.

- **ES Module Ready**: Available as a JavaScript module for modern workflows.

## Installation

Get it from NPM:

```bash

npm i geogrid-maplibre-gl

```

Or use it from the CDN:

```html

```

## Usage

### Minimal example

```js

import { GeoGrid } from 'geogrid-maplibre-gl';

// Import css from 'geogrid-maplibre-gl/dist/geogrid.css'

// const map = new maplibregl.Map(...);

new GeoGrid({ map });

```

### All options

```js

import { GeoGrid } from 'geogrid-maplibre-gl';

// const map = new maplibregl.Map(...);

new GeoGrid({ 

    map,

    beforeLayerId: 'labels'

    gridStyle: {

        color: 'rgba(255, 255, 255, 0.5)'

        width: 2,

        dasharray: [5, 10]

    },

    labelStyle: {

        color: 'rgba(255, 255, 255, 0.5)',

        fontSize: 18,

        textShadow: '0 0 10px rgba(0, 0, 0)'

    },

    zoomLevelRange: [0, 13],

    gridDensity: (zoomLevel) => 10;

    formatLabels: (degreesFloat) => Math.floor(degreesFloat);

});

```

Programatically removing and re-adding:

```js

const geogrid = new GeoGrid({ map });

// On some event

geogrid.remove();

// On another event

geogrid.add();

```

## Styling

Most of the styling can be done with API options `gridStyle` and `labelStyle`.

If those options are not enough, it is possible to override CSS classes:

* `geogrid` - The main container for labels.

* `geogrid__label` - Invidual label elements.

* `geogrid__label--left` - Labels on the left.

* `geogrid__label--right` - Labels on the right.

* `geogrid__label--top` - Labels on the top.

* `geogrid__label--bottom` - Labels on the bottom.

To prevent overriding default properties, nest overrides inside `.geogrid-overrides` selector.

For example:

```css

.geogrid-overrides .geogrid__label {

    color: red

}

```