M3S: Multi Spatial Subdivision System#

Unified Spatial Grid Systems for Python

A comprehensive toolkit for working with multiple spatial indexing systems

M3S (Multi Spatial Subdivision System) is a powerful Python library that provides an intuitive interface for working with 11 spatial grid systems including H3, Geohash, S2, MGRS, and more.

New in v0.5.1: Simplified API with direct grid access, universal geometry handling, and intelligent auto-precision selection. No instantiation required—just import m3s and start working!

Also Available: Advanced GridBuilder API with fluent interface and 5 intelligent precision selection strategies.

🌍 Multi-Grid Support

Support for 10+ spatial grid systems including Geohash, MGRS, H3, S2, QuadKey, and more with a consistent API.

⚡ Performance Optimized

Built with performance in mind, offering threaded parallelism for large-scale spatial operations.

🔧 Easy Integration

Seamless integration with GeoPandas, Shapely, and the broader Python geospatial ecosystem.

Getting Started#

Installation#

Install M3S using uv (recommended):

uv pip install m3s

Or using pip:

pip install m3s

Quick Example - Simplified API (v0.5.1+)#

The easiest way to get started:

import m3s
from shapely.geometry import Polygon

# Direct grid access - no instantiation needed!
cell = m3s.Geohash.from_geometry((40.7128, -74.0060))
print(f"Cell: {cell.id}, Area: {cell.area_km2:.2f} km²")

# Works with any geometry type
polygon = Polygon([(-74.1, 40.7), (-73.9, 40.7), (-73.9, 40.8), (-74.1, 40.8)])
cells = m3s.H3.from_geometry(polygon)

# Get neighbors
neighbors = m3s.Geohash.neighbors(cell)

# Convert to GeoDataFrame
gdf = cells.to_gdf()

# Convert between grid systems
h3_cells = cells.to_h3()

# Find optimal precision
precision = m3s.H3.find_precision(polygon, method='auto')
cells = m3s.H3.from_geometry(polygon, precision=precision)

Advanced Example - GridBuilder API#

For complex workflows with method chaining:

from m3s import GridBuilder, PrecisionSelector

# Intelligent precision selection
selector = PrecisionSelector('h3')
rec = selector.for_use_case('neighborhood')

# Fluent query with method chaining
result = (GridBuilder
    .for_system('h3')
    .with_auto_precision(rec)
    .at_point(40.7128, -74.0060)  # NYC
    .find_neighbors(depth=1)
    .execute())

print(f"Found {len(result)} cells at precision {rec.precision}")

# Type-safe result access
gdf = result.to_geodataframe()

Multi-Grid Comparison#

Compare same location across multiple grid systems:

from m3s import MultiGridComparator

comparator = MultiGridComparator([
    ('geohash', 5),
    ('h3', 7),
    ('s2', 10)
])

results = comparator.query_all(40.7128, -74.0060)
for system, cell in results.items():
    print(f"{system}: {cell.identifier} ({cell.area_km2:.2f} km²)")

Supported Grid Systems#

M3S supports 11 spatial grid systems with unified precision parameters:

Grid System	Description	Use Cases	Precision Range
H3	Hexagonal hierarchical spatial index	Analytics, ride-sharing, logistics	0-15
Geohash	Base-32 string location encoding	Databases, simple indexing	1-12
S2	Google’s spherical geometry library	Global applications, planetary-scale	0-30
MGRS	Military Grid Reference System	Military, surveying, precise reference	1-6 (100km→1m)
Quadkey	Microsoft Bing Maps tile system	Web mapping, tile services	1-23
Slippy	OpenStreetMap standard tiles	Web maps, tile servers, caching	0-20
C-squares	Marine data indexing	Oceanography, marine biology	1-5
GARS	Global Area Reference System	Military, area reference	1-3
Maidenhead	Amateur radio grid locator	Amateur radio, QSO logging	1-6
Plus Codes	Open Location Codes	Address replacement, geocoding	2-15
What3Words	3-meter precision squares	Precise location reference	1 (fixed)

Key Features#

✨ Simplified API (New!): Direct grid access with m3s.H3, m3s.Geohash, etc. No instantiation needed—just import and use!
🌐 Universal Geometry Handling: Single from_geometry() method accepts points, polygons, bounding boxes, and GeoDataFrames.
🎯 Intelligent Precision Selection: Auto-select optimal precision with 5 strategies: minimize variance, fewer/more cells, balanced, or target count. Use case presets for common scenarios (building, neighborhood, city, etc.).
🔄 Easy Grid Conversion: Convert between any grid systems with .to_h3(), .to_geohash(), .to_s2(), etc.
📦 Powerful Collections: GridCellCollection provides filtering, mapping, hierarchical operations, and easy exports.
🔗 Fluent Builder Interface: Advanced GridBuilder API for complex workflows with method chaining.
📊 Multi-Grid Comparison: Simultaneously analyze multiple grid systems and compare coverage patterns.
🚀 High Performance: Optimized precision finding with fast path for large areas, caching, and lazy evaluation.
📈 Scalable Operations: Memory-efficient streaming, threaded parallel processing, and adaptive chunking for large datasets.
🛠️ GeoPandas Integration: Native support for GeoDataFrames with automatic CRS transformation and UTM zone detection.
🔙 Full Backward Compatibility: Existing code continues to work—new API is additive, not breaking.

Community & Support#

📚 Documentation: Complete API reference and examples
🐛 Issue Tracker: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Contact: Nicolas Karasiak

License#

M3S is released under the MIT License. See the LICENSE file for details.

Made with ❤️ by the M3S team | ⭐ Star us on GitHub