LibGD GIS

---

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.

---

Features

• 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

---

Non-Goals

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.

---

Installation

Add to your Gemfile:

gem "libgd-gis"

Then run:

bundle install

You must also have GD available on your system.

---

Basic Usage

Create a map

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
)

Load a style

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

Load GeoJSON

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

Render

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

---

Styles Are Mandatory

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.

Example:

require "gd/gis"

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

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

map.render

Example:

# 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.

---

CRS Support

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).

---

License

MIT