Markers Spatial Hash 🗺️

A lightweight and efficient map visualization package that helps you manage and render large sets of markers on a 100x100 grid. By categorizing and organizing markers into a grid, this package significantly improves map performance, especially when panning or zooming.

✨ Features

• Efficient Grid System: Optimized for managing and rendering large sets of markers on a 100x100 grid.
• Spatial Hashing: Handles large datasets efficiently by categorizing markers based on their geographic coordinates.
• Performance Boost 🚀: Enhances map rendering performance by organizing markers into cells, reducing computation when the map view changes (zooming, panning).

⚙️ Prerequisites

• Node.js and npm installed on your system.

📦 Installation

To install the markers-spatial-hash package, run the following command:

npm install markers-spatial-hash

🚀 Usage

Here is an example usage of the SpatialHash class.

Example 1: Using Multiple Categories 🚌🚲🚆

import SpatialHash from 'markers-spatial-hash';
import MapView, { Marker } from 'react-native-maps';
import { v4 as uuidv4 } from 'uuid';

const markers = [
  { name: "Marker 1", lat: 37.7749, lon: -122.4194, category: "BUS" },
  { name: "Marker 2", lat: 37.7849, lon: -122.4094, category: "BICYCLE" },
  { name: "Marker 3", lat: 37.7649, lon: -122.4294, category: "TRAIN" }
];

const categories = ["BUS", "BICYCLE", "TRAIN"];

// Initialize SpatialHash
const spatialHash = new SpatialHash(markers, categories);

// Add markers to the spatial hash
markers.forEach(marker => {
  spatialHash.addPoint(marker, marker.category);
});

// Get markers for a specific region
const region = {
  latitude: 37.7749,
  longitude: -122.4194,
  latitudeDelta: 0.05,
  longitudeDelta: 0.05
};
const markersInRegion = spatialHash.getPointsInRegion(region, 0.05);

// Use in your map component
const renderMarkers = () => {
  const shownMarkers = markersInRegion;
  return shownMarkers.map(marker => (
    <Marker
      key={uuidv4()}
      coordinate={{ latitude: marker.lat, longitude: marker.lon }}
      title={marker.name}
    />
  ));
};

const Map = () => (
  <MapView style={{ flex: 1 }}>
    {renderMarkers()}
  </MapView>
);

export default Map;

Example 2: Using a Single Category 🎯

If you only have one category of markers, you can still use the SpatialHash class effectively. In this case, you can pass a single category when initializing the class:

import SpatialHash from 'markers-spatial-hash';
import MapView, { Marker } from 'react-native-maps';

const markers = [
  { name: "Marker 1", lat: 37.7749, lon: -122.4194 },
  { name: "Marker 2", lat: 37.7849, lon: -122.4094 },
  { name: "Marker 3", lat: 37.7649, lon: -122.4294 }
];

// Only one category for the markers
const categories = ["DEFAULT"];

// Initialize SpatialHash
const spatialHash = new SpatialHash(markers, categories);

// Add markers to the spatial hash
markers.forEach(marker => {
  spatialHash.addPoint(marker, "DEFAULT");
});

// Get markers for a specific region
const region = {
  latitude: 37.7749,
  longitude: -122.4194,
  latitudeDelta: 0.05,
  longitudeDelta: 0.05
};
const markersInRegion = spatialHash.getPointsInRegion(region, 0.05);

// Use in your map component
const renderMarkers = () => {
  const shownMarkers = markersInRegion["DEFAULT"];
  return shownMarkers.map(marker => (
    <Marker
      key={marker.uniqueId}
      coordinate={{ latitude: marker.lat, longitude: marker.lon }}
      title={marker.name}
    />
  ));
};

const Map = () => (
  <MapView style={{ flex: 1 }}>
    {renderMarkers()}
  </MapView>
);

export default Map;

📚 API Reference

SpatialHash(markers, categories)

• markers: Array of marker objects, each containing lat, lon, and optionally other properties like name.
• categories: Array of categories to group the markers.

addPoint(point, category)

• point: An object representing the marker. Must contain lat and lon.
• category: The category to which this marker belongs.

getPointsInRegion(region, minDelta)

• region: An object representing the map region. Must contain latitude, longitude, latitudeDelta, and longitudeDelta.
• minDelta: Minimum delta value to filter markers based on zoom level.

📝 License

This package is open-sourced and licensed under the MIT License.