🔥 Heat Map - GEO Map Hub Plugin

This guide explains how to create a heat map using region-based data values. The heat map visually represents intensity (e.g., population) using gradient colors, with hover tooltips and optional click actions.

📘 What is Heat Map?

The Heat Map feature allows you to visually represent intensity or volume-based data (like population, temperature, crime rates, etc.) on a geographic region. Each region is shaded according to its assigned data value, using a gradient between a start color and end color.

💡 Use Case

You should use Heat Map when you want to:

• 🧍 Display population density across states

• 🌡️ Visualize weather intensities (e.g., heatwaves)

• 💰 Show economic data like income or sales per region

• 🦠 Represent infection rates or public health data

• 🎓 Highlight education rates or school zones

📁 Folder Structure

Make sure the following files are correctly placed:

your-project/
├── gmh-plugin/
│    ├── assets/
│    │    ├── css/
│    │    │    └── style.css
│    │    ├── js/
│    │    │    └── script/
│    │    │    │    ├── geomaphub.js
│    │    │    │    └── lib/
│    │    │    │    │   ├── heat-map-gmh.js       ← Required
│    │    │    │    │   └── interactive-tooltip-gmh.js  ← Required for interactive (tooltips and links.)
│    ├── data/
│    │    ├── us/
│    │    │    ├── map-content.js
│    │    │    └── us.svg
│ index.html

📌 Region-Specific Configuration map_config

Each region in map_config can define its own heat_map object:

export const map_config = [
  {
    "targetClass": "US-WA",  // Unique identifier for region.
    "name": "Washington",  // Display name for the region.

    /*
     * Heat Map Configuration
     * This section defines the properties for visualizing data intensity on the map
     * using a heat map representation.
    */
    "heat_map": {
      "value": 10000,  // Intensity value for the heat map, typically determining the "heat" level.

        // Optional
      "on_click": {
        "url": "https://en.wikipedia.org/wiki/Washington",
        "target": "_blank",
        "cursor": "pointer"
      },
    },
  },
];

⚙️ Global Configuration

export const general_config = {
  "id": {
    /*
     * SVG and Element IDs
     * These IDs are used to reference specific SVG elements or HTML
     * elements in your configuration. If you want to change any of
     * these IDs, ensure you update them in the corresponding svg.js file.
    */

    "svg_id": "US-MAP-GMH",  /** ID for the main SVG map element. */
    "tooltip_id": "tooltip-gmh",  /** ID for the tooltip element. */
    "custom_tooltip_id": "custom-tooltip-gmh",  /** ID for the tooltip element. */
  },

  /*
   * Heat Map Configuration
   * This section defines the properties for visualizing data intensity on the map
   * using a heat map representation based on population estimates.
  */
  "heat_map": {
    /*
     * Tooltip Settings
     * The tooltip that will be displayed when hovering over a region.
     * You can use {name} to add the name of the region and {value} for the value.
    */
    "tooltip": "Population Estimate: {value}",  /** Tooltip text displayed on hover, showing population. */

    "html_id": "html-content-gmh",

    /*
     * Color Settings
     * Defines the color properties for the heat map.
     * The default color is used when no specific color is provided for a region.
    */
    "color": {
      "default": "#f3faff",  /** Default color if no region-specific color is set. */
      "on_hover": "#005999"   /** Color when hovering over a region. */
    },

    /*
     * Stroke (Border) Settings
     * Defines the border properties for the regions on the heat map.
    */
    "stroke": {
      "color": "white",  /** Border color for the regions. */
      "width": "1px"     /** Border width for the regions. */
    },

    /*
     * Start Region Settings
     * Defines the starting color and population values for the heat map.
    */
    "start": {
      "color": [0xDA, 0xEB, 0xF7],  /** Starting color (lightest shade) for the heat map. */
      "population": 5000,            /** Starting population value (minimum). */
      "display_text": "5K",          /** Text displayed for the starting population. */
    },

    /*
     * End Region Settings
     * Defines the ending color and population values for the heat map.
    */
    "end": {
      "color": [0x5C, 0x91, 0xC0],  /** Ending color (darkest shade) for the heat map. */
      "population": 4000000,       /** Ending population value (maximum). */
      "display_text": "4M",         /** Text displayed for the ending population. */
    },
  },
}

🎨 Color Gradient Calculation

Each region's value is normalized between the start.population and end.population, then interpolated between the start.color and end.color.

🔌 Script Block Setup

Include the module script like so:

<!-- Heat Map -->
<script type="module">
  const currentCountry = "us";

  async function initMap() {
    try {
      // Dynamically import map-specific data
      const {map_config, general_config} = await import(`/gmh-plugin/data/${currentCountry}/map-content.js`);
      const {GEOMapHub} = await import('/gmh-plugin/assets/js/script/geomaphub.js');
      const {geoMapHubHeatMap} = await import('/gmh-plugin/assets/js/script/lib/heat-map-gmh.js');
      const {geoMapHubInteractiveTooltip} = await import('/gmh-plugin/assets/js/script/lib/interactive-tooltip-gmh.js');

        const map = new GEOMapHub("#svg-wrapper-gmh", {
          svgUrl: `/gmh-plugin/data/${currentCountry}/${currentCountry}.svg`,
          mapConfig: map_config,
          generalConfig: general_config,
        });

        map.registerPlugin(geoMapHubHeatMap);
        map.registerPlugin(geoMapHubInteractiveTooltip);

        map.init();
    } catch (error) {
      console.error("Error initializing map:", error);
    }
  }

  initMap();
</script>
<!-- Heat Map -->

Here's a working example to display the map

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>GEO Map Hub – Heat Map</title>
  <link rel="stylesheet" href="/gmh-plugin/assets/css/style.css" />
</head>

<body>
  <div id="tooltip-gmh"></div>
  <div id="custom-tooltip-gmh"></div>

  <div class="row row-gap-2">
    <div class="col-lg-8 col-12">
      <div class="svg-container-gmh">
        <div id="html-content-gmh"></div>
        <div id="svg-wrapper-gmh"></div>
      </div>
    </div>
  </div>

  <!-- Heat Map -->
  <script type="module">
    const currentCountry = "us";

    async function initMap() {
      try {
        // Dynamically import map-specific data
        const {map_config, general_config} = await import(`/gmh-plugin/data/${currentCountry}/map-content.js`);
        const {GEOMapHub} = await import('/gmh-plugin/assets/js/script/geomaphub.js');
        const {geoMapHubHeatMap} = await import('/gmh-plugin/assets/js/script/lib/heat-map-gmh.js');
        const {geoMapHubInteractiveTooltip} = await import('/gmh-plugin/assets/js/script/lib/interactive-tooltip-gmh.js');

        const map = new GEOMapHub("#svg-wrapper-gmh", {
          svgUrl: `/gmh-plugin/data/${currentCountry}/${currentCountry}.svg`,
          mapConfig: map_config,
          generalConfig: general_config,
        });

        map.registerPlugin(geoMapHubHeatMap);
        map.registerPlugin(geoMapHubInteractiveTooltip);

        map.init();
      } catch (error) {
        console.error("Error initializing map:", error);
      }
    }

    initMap();
  </script>
  <!-- Heat Map -->
</body>

</html>

⚠️ Local CORS Warning

If you're testing with a .html file locally and see this error:

Access to script at 'file:///...' from origin 'null' has been blocked by CORS policy...

It means you're loading the file using the file:// protocol.

✅ How to Fix

Option 1: Use a Local Server (Recommended for HTML)

• Live Server (VS Code Extension)

  Install Live Server, right-click your HTML, and choose “Open with Live Server”.

• Or use any other local server:

  # Python 3
  python -m http.server
  
  # Node.js
  npx http-server
  
  # PHP
  php -S localhost:8080
  

• Or use a local web server (e.g., XAMPP or Laragon)

Option 2: Deploy to a Real Server

You can upload your files to:

• Your cPanel or shared hosting

• A staging VPS or domain

Once the files are accessible via http:// or https://, the plugin works without issues.

📌 Tooltip Placeholder Variables

You can customize tooltip display using placeholders in the config:

• {name} → Region name (e.g., “California”)

• {value} → Heat value (e.g., “20000”)

🎯 Output Behavior

✅ Each region is shaded according to its value, interpolated between start.color and end.color.

✅ Tooltip on hover shows population or data value.

✅ Optional on_click lets you attach links or actions per region.