🖼️ Custom Image Markers - GEO Map Hub Plugin

This guide explains how to add images markers to regions on your SVG map.

📘 What is a Image Marker?

The Custom Image Marker feature in GEO Map Hub allows you to place visual markers using images (like icons, logos, or flags) anywhere on the map. These markers act as interactive points of interest (POIs) and can be fully customized with:

• Tooltips on hover

• Links that open on click

• Precise positioning (x, y)

• Scalable image sizes

💡 Use Case

✅ Highlight important locations such as:

• 🌍 Country or state flags

• 🏥 Hospital or landmark icons

• 🏨 Business branches or headquarters

• 🏛️ Historical monuments

• 🚩 Event locations

✅ How to Use

• Open map-content.js inside your map folder

• Under a region like "US-WA", define the markers array

• Use image_marker to set up image URL, position, tooltip, dimensions, etc.

📁 Folder Structure

Ensure your project follows this structure:

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

📄 Configuration Breakdown

🔹 Region-Level (map_config)

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

    /**
     * Marker Configuration
     *
     * This section defines different types of markers that can be added to the map.
     * Each marker type has its own structure and properties, allowing customization for
     * specific use cases such as displaying images, labels, vectors, or color markers.
     *
     * Supported Marker Types:
     * - color_marker: Basic markers with customizable colors, shapes, and hover effects.
     * - image_marker: Markers using custom images to represent POIs.
     * - label_marker: Markers with text labels.
     * - vector_marker: Markers using vector graphics for more complex shapes.
    */
    "markers": [
      {
        "targetClass": "MARKER-US-WA-1",  // Unique identifier for this marker.

        /*
         * Custom Image Marker Configuration
         * Defines markers using image assets (e.g., flags, icons) to represent locations or regions on the map.
        */
        "image_marker": [
          {
            "targetClass": "IM-US-WA-1", // Unique identifier for the image marker.

            "tooltip": "Washington", // Text displayed when hovering over the marker.

            /*
             * Image Source
             * Specify the file path or URL to the image asset to be used as the marker.
            */
            x22;src": "/gmh-plugin/assets/images/flags/us/us-wa.svg", // Path to the Washington state flag image.

            /*
             * Dimensions
             * Set the width and height of the image marker for proper rendering.
            */
            "width": "24px",  // Width of the image marker.
            "height": "", // Height of the image marker.

            /*
             * Positioning Properties
             * Specifies the marker's coordinates (x, y) for placement on the map.
            */
            "position": {
              "x": 108, // X-coordinate of the marker's position.
              "y": 58   // Y-coordinate of the marker's position.
            },

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

🔹 Global-Level (general_config)

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. */
    "marker_id": "US-MARKER-GMH",  /** ID for the marker element. */
    "map_group_id": "US-MAP-GROUP",  /** ID for the group element. */
    "tooltip_id": "tooltip-gmh",  /** ID for the tooltip element. */
    "custom_tooltip_id": "custom-tooltip-gmh",  /** ID for the tooltip element. */
  },

  /*
   * Image Marker Configuration
   * This section defines the settings for image markers on the map,
   * including color and stroke properties.
  */
  "image_marker": {
    /*
     * Image Marker Color Settings
     * Defines the default color for image markers.
    */
    "color": {
      "default": "#f3faff",  /** Default color for image markers. */
    },

    /*
     * Image Marker Stroke Settings
     * Defines the border (stroke) properties for the image markers, including
     * the color and width of the border.
    */
    "stroke": {
      "color": "#6B8B9E",  /** Border color for the image marker. */
      "width": "0.8px"     /** Border width for the image marker. */
    },
  },
}

⚙️ Script Setup

<script type="module">
  const currentCountry = "us";

  async function initMap() {
    try {
      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 {geoMapHubImageMarker} = await import('/gmh-plugin/assets/js/script/lib/custom-image-marker-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(geoMapHubImageMarker);
      map.registerPlugin(geoMapHubInteractiveTooltip);

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

  initMap();
</script>

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 – Custom Image Marker</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="svg-container-gmh">
    <div id="svg-wrapper-gmh"></div>
  </div>

  <!-- Custom Image Marker -->
  <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 {geoMapHubImageMarker} = await import('/gmh-plugin/assets/js/script/lib/custom-image-marker-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(geoMapHubImageMarker);
        map.registerPlugin(geoMapHubInteractiveTooltip);

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

    initMap();
  </script>
  <!-- Custom Image Marker -->
</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.

📌 Final Checklist

✅ Added image_marker config inside a region

✅ Set image src, size, and tooltip

✅ Configured position: {x, y}

✅ Registered geoMapHubImageMarker plugin

✅ Included IDs and stroke/color styles in general_config

🎯 Result

You will see your custom image (icon, flag, etc.) placed on the map with a tooltip and optional click behavior. These markers enhance the visual appeal and interactivity of your SVG maps-perfect for presentations, dashboards, or geo-location-based storytelling.