D3.js - Geographies

D3.js - Working with Geographic Data

D3.js provides robust tools for visualizing geographic data, often used for maps displaying information like population density, weather patterns, or election results. Key D3 modules for geospatial data include d3-geo for projections and path generation, and often topojson-client for working with TopoJSON data.

Core components for D3 geographies are:

• GeoJSON/TopoJSON: Standard formats for encoding geographic data structures.
• Projections (d3-geo): Functions that convert spherical coordinates (longitude, latitude) into 2D Cartesian coordinates suitable for display on a screen.
• Path Generators (d3-geo): Functions that take GeoJSON geometry and a projection to generate SVG path data (the d attribute for <path> elements) or render to a Canvas.

D3 Geo Path Generator

A geographic path generator, created with d3.geoPath(), is used to convert GeoJSON features into SVG path strings or to render them onto an HTML5 Canvas. It requires a projection to perform the coordinate transformation.

// 1. Create a projection (e.g., Mercator)
const projection = d3.geoMercator()
    .scale(100) // Example scale
    .translate([width / 2, height / 2]); // Center the map

// 2. Create a geo path generator and link it to the projection
const pathGenerator = d3.geoPath()
    .projection(projection);

// 3. Use the path generator with GeoJSON data
svg.selectAll("path")
  .data(geoJsonFeatures) // An array of GeoJSON feature objects
  .enter()
  .append("path")
    .attr("d", pathGenerator); // pathGenerator(d) returns the SVG path string

For example, to draw the states of a country from a GeoJSON FeatureCollection called statesGeoJson:

svg.append("g")
  .selectAll("path")
  .data(statesGeoJson.features)
  .join("path")
    .attr("d", pathGenerator)
    .attr("fill", "steelblue")
    .attr("stroke", "white");

Geographic Projections

Projections transform spherical polygonal geometry (longitude, latitude) to planar polygonal geometry (x, y coordinates). D3 offers a wide variety of projection types, each with different properties regarding distortion of area, shape, distance, or direction.

• Azimuthal: Project the sphere directly onto a plane (e.g., d3.geoOrthographic(), d3.geoStereographic()).
• Conic: Project the sphere onto a cone, then unroll the cone (e.g., d3.geoAlbers(), d3.geoConicEqualArea()).
• Cylindrical: Project the sphere onto a cylinder, then unroll the cylinder (e.g., d3.geoMercator(), d3.geoEquirectangular()).
• Composite: Combine multiple projections (e.g., d3.geoAlbersUsa() for USA with Alaska and Hawaii).

To create a new projection, you call the specific projection function:

const projection = d3.geoMercator(); // Creates a Mercator projection

// Common configuration methods:
projection
    .scale(number)        // Sets the projection's scale factor
    .translate([x, y])  // Sets the projection's translation offset (center of map in pixels)
    .center([lon, lat])   // Sets the projection's center point (longitude, latitude)
    .rotate([lambda, phi, gamma]) // Sets the projection's three-axis rotation

Some popular projections:

• d3.geoOrthographic(): Shows a hemisphere as if viewed from space.
• d3.geoGnomonic(): Projects great circles as straight lines.
• d3.geoEquirectangular(): A simple cylindrical projection, often used for raster data.
• d3.geoMercator(): Commonly used for web maps; preserves angles locally but distorts areas significantly at high latitudes.
• d3.geoAlbersUsa(): A composite projection specifically for the United States.

Working Example: Drawing a Map from TopoJSON

Let’s create a map of a country (e.g., India) using TopoJSON data. TopoJSON is an extension of GeoJSON that encodes topology, often resulting in smaller file sizes.

Step 1: Include D3.js and TopoJSON client library. You’ll need a TopoJSON file (e.g., india-states.topojson).

<!-- In your HTML -->
<script src="https://d3js.org/d3.v7.min.js"></script>
<script src="https://unpkg.com/topojson-client@3"></script> <!-- topojson-client library -->

Step 2: Define SVG dimensions and projection.

const width = 600;
const height = 500;

const projection = d3.geoMercator()
    .center([82, 22]) // Approximate center of India
    .scale(800)       // Adjust scale to fit
    .translate([width / 2, height / 2]);

const pathGenerator = d3.geoPath().projection(projection);

Step 3: Create SVG container.

const svg = d3.select("body").append("svg")
    .attr("width", width)
    .attr("height", height)
    .style("border", "1px solid black");

Step 4: Load TopoJSON data and render the map. We use d3.json() which returns a Promise.

// Assume 'india-states.topojson' is available at this path
d3.json("india-states.topojson").then(function(topology) {
    // Convert TopoJSON to GeoJSON features
    // 'states' is the name of the object in your TopoJSON file that contains geometries
    const states = topojson.feature(topology, topology.objects.states);

    svg.append("g")
      .selectAll("path")
      .data(states.features)
      .join("path")
        .attr("d", pathGenerator)
        .attr("fill", (d) => {
            // Example: Color Tamil Nadu (TN) differently if ID is available
            if (d.id === "TN") return "red";
            return "#ccc";
        })
        .attr("stroke", "#333")
        .attr("stroke-width", 0.5);

}).catch(function(error) {
    console.error("Error loading or processing TopoJSON:", error);
});

Step 5: (Optional) Add CSS for styling.

/* CSS (optional) */
path {
  /* Default styles for paths if not overridden by .attr */
}

path:hover {
  fill: orange; /* Example hover effect */
}

A note on TopoJSON data (india-states.topojson): This file would contain geographic data. The topology.objects.states part refers to a specific named object within the TopoJSON file. A highly truncated example of such a file’s structure:

{
  "type": "Topology",
  "transform": { /* scale and translate info */ },
  "objects": {
    "states": {  // This key 'states' is used in topojson.feature
      "type": "GeometryCollection",
      "geometries": [
        { "type": "Polygon", "arcs": [[...]], "id": "AP", "properties": { "name": "Andhra Pradesh" } },
        { "type": "MultiPolygon", "arcs": [[...]], "id": "TN", "properties": { "name": "Tamil Nadu" } },
        // ... more state geometries
      ]
    }
    // ... other objects like 'districts' could be here
  },
  "arcs": [ /* array of shared line segments */ ]
}

This example demonstrates loading geographic data, converting it using topojson.feature, and rendering it with D3’s path generator and projection. The exact properties (d.id, d.properties.name) depend on your specific GeoJSON/TopoJSON file.