{{ site.title }}

{{ theme.darkModeSwitchLabel || 'Appearance' }}

Heatmap Map Overlay Feature Design ​

Overview ​

Add map overlay functionality to the Heatmap page, allowing users to overlay updated mine site map images on top of Google Maps satellite imagery. The heatmap data points will display above the overlay layer.

Requirements ​

  • Storage: Configuration file with hardcoded overlay definitions, images in public/ directory
  • Control: Toggle switch + opacity slider (similar to existing heatmap controls)
  • Layer Order: Overlay below heatmap, so data points remain visible
  • Rotation: Pre-process images to remove rotation before adding to project

Technical Design ​

1. Configuration Structure ​

File: src/features/heatmap/overlayConfig.ts

typescript
export type MapOverlay = {
  id: string;
  name: string;           // Display name, e.g., "2024 Survey Map"
  mineSiteId: string;     // Associated mine site ID
  imagePath: string;      // Image path, e.g., "/overlays/marandoo-2024.png"
  bounds: {
    north: number;
    south: number;
    east: number;
    west: number;
  };
};

export const MAP_OVERLAYS: MapOverlay[] = [
  // Add overlay configurations here
];

export function getOverlaysForMineSite(mineSiteId: string): MapOverlay[] {
  return MAP_OVERLAYS.filter(overlay => overlay.mineSiteId === mineSiteId);
}

2. Image Storage ​

  • Location: public/overlays/
  • Format: PNG (pre-processed, no rotation)
  • Naming convention: {mine-site-name}-{year}.png

3. Google Maps Implementation ​

Use google.maps.GroundOverlay to create the overlay layer:

typescript
const overlay = new google.maps.GroundOverlay(
  imagePath,
  new google.maps.LatLngBounds(
    { lat: bounds.south, lng: bounds.west },  // SW corner
    { lat: bounds.north, lng: bounds.east }   // NE corner
  ),
  { opacity: overlayOpacity }
);
overlay.setMap(map);

Layer Order: GroundOverlay renders in overlayLayer pane by default, which is below the custom Canvas heatmap overlay.

4. UI Controls ​

Add to the "Appearance" section in the control panel:

┌─────────────────────────────────────┐
│ Map Overlay                         │
│ ┌─────────────────────────────────┐ │
│ │ [Toggle] Show Map Overlay       │ │
│ └─────────────────────────────────┘ │
│                                     │
│ Overlay Opacity          [75%]     │
│ ├──────────────●─────────────────┤ │
│                                     │
└─────────────────────────────────────┘

5. State Management ​

Add to HeatmapControlsState type:

typescript
type HeatmapControlsState = {
  // ... existing fields
  showOverlay: boolean;
  overlayOpacity: number;
};

Default values:

  • showOverlay: false
  • overlayOpacity: 0.75

Implementation Steps ​

  1. Create src/features/heatmap/overlayConfig.ts with type definitions and helper functions
  2. Create public/overlays/ directory and add test image
  3. Update HeatmapControlsState type in types.ts
  4. Update DEFAULT_CONTROLS in constants.ts
  5. Add overlay rendering logic in heatmap/index.tsx
  6. Add UI controls (toggle + opacity slider) to the control panel

Test Data ​

Using the provided test file:

  • Source: overlay/123123/files/image.png
  • Bounds from KML:
    • North: -22.51509160607861
    • South: -22.55023212272908
    • East: 119.0573010775616
    • West: 118.9966508470948

Future Considerations ​

  • If more overlays are needed, consider migrating to database storage
  • Admin upload functionality could be added later
  • Multiple overlay support per mine site (different years/surveys)