libgd-gis is a lightweight Ruby GIS rendering library built on top of GD. It renders geographic data (GeoJSON, points, lines, polygons) into raster images using Web Mercator tiles and a simple, explicit rendering pipeline.

This library is designed for map visualization, not for spatial analysis.

• Web Mercator tile rendering (OSM, CARTO, ESRI, Stamen, etc.)
• CRS normalization (CRS84, EPSG:4326, EPSG:3857, Gauss–Krüger Argentina)
• Layered rendering pipeline
• YAML-based styling
• Rule-based semantic classification (ontology)
• Points, lines, and polygons support
• No heavy GIS dependencies

libgd-gis intentionally does not aim to be:

• a spatial analysis engine
• a replacement for PostGIS / GEOS
• a full map server
• a vector tile generator

If you need projections beyond Web Mercator or topological correctness, use a full GIS stack.

Add to your Gemfile:

gem "libgd-gis"

Then run:

bundle install

You must also have GD available on your system.

require "gd/gis"

map = GD::GIS::Map.new(
  bbox: [-58.45, -34.7, -58.35, -34.55],
  zoom: 13,
  basemap: :carto_light,
  width: 1024,
  height: 768
)

map.style = GD::GIS::Style.load("default", from: "styles")

map.add_geojson("data/roads.geojson")
map.add_geojson("data/water.geojson")

map.render
map.save("map.png")

libgd-gis requires an explicit style definition in order to render a map.

A GD::GIS::Map instance will not render without a style, and calling map.render before assigning one will raise an error.

This is intentional.

Styles define how semantic layers (roads, water, parks, points, etc.) are mapped to visual properties such as colors, stroke widths, fills, and drawing order. No implicit or default styling is applied.

require "gd/gis"

map = GD::GIS::Map.new(
  bbox: PARIS,
  zoom: 13,
  basemap: :carto_light
)

map.style = GD::GIS::Style.load("default")

map.render

# styles/default.yml

roads:
  motorway:
    stroke: [255, 255, 255]
    stroke_width: 10
    fill: [60, 60, 60]
    fill_width: 6

  primary:
    stroke: [200, 200, 200]
    stroke_width: 7
    fill: [80, 80, 80]
    fill_width: 4

  street:
    stroke: [120, 120, 120]
    stroke_width: 1

rail:
  stroke: [255, 255, 255]
  stroke_width: 6
  fill: [220, 50, 50]
  fill_width: 4
  center: [255, 255, 255]
  center_width: 1

water:
  fill: [120, 180, 255]
  fill_width: 4
  stroke: [80, 140, 220]

park:
  fill: [40, 80, 40]

order:
  - water
  - park
  - street
  - primary
  - motorway
  - rail

This design ensures predictable rendering and makes all visual decisions explicit and reproducible.

LibGD-GIS includes a global dataset of predefined geographic areas. You can use them directly as the bbox parameter.

map = GD::GIS::Map.new(
  bbox: :argentina,
  zoom: 5,
  width: 800,
  height: 600,
  basemap: :osm
)

You can also use continents or regions:

bbox: :world
bbox: :europe
bbox: :south_america
bbox: :north_america
bbox: :asia

Supported input CRS:

• CRS84
• EPSG:4326
• EPSG:3857
• EPSG:22195 (Gauss–Krüger Argentina, zone 5)

All coordinates are normalized internally to CRS84 (lon, lat).

MIT