BGrid Python Library

A Python implementation of the BGrid hierarchical coordinate system that divides Earth into 2048 parcels per level, with support for BIP39 mnemonic words in multiple languages.

🌟 Features

• ✅ Convert decimal degrees (DD) coordinates to BGrid format
• ✅ Convert BGrid coordinates back to DD with bounds
• ✅ Support for 1-4 hierarchical levels
• ✅ BIP39 word encoding/decoding in 9 languages
• ✅ Calculate cell areas at each level
• ✅ Zero external dependencies (uses only Python standard library)
• ✅ Type hints and dataclasses for better IDE support
• ✅ Command-line interface included
• ✅ Comprehensive unit tests

📦 Installation

From Source

git clone https://github.com/bgrid-maps/bgrid-python
cd bgrid-python
pip install -e .

Using pip (when published)

pip install bgrid

🚀 Quick Start

Basic Usage

from bgrid import BGrid, Language, dd_to_bgrid, bgrid_to_dd

# Quick conversion: Coordinates to BGrid
bgrid_str = dd_to_bgrid(40.7128, -74.0060, level=3)
print(bgrid_str)  # "1234,567,89"

# Quick conversion: BGrid to coordinates
lat, lon = bgrid_to_dd("1234,567,89")
print(f"({lat}, {lon})")  # Center coordinates

# Using BIP39 words
bgrid_words = dd_to_bgrid(40.7128, -74.0060, level=2, use_words=True)
print(bgrid_words)  # "abandon,ability"

Advanced Usage

# Initialize BGrid with multiple languages
bgrid = BGrid(load_languages=[Language.ENGLISH, Language.SPANISH])

# Convert coordinates to BGrid coordinate object
coord = bgrid.dd_to_bgrid(40.7128, -74.0060, level=3)
print(f"Center: {coord.center_lat}, {coord.center_lon}")
print(f"Bounds: {coord.bounds}")
print(f"Area: ~{bgrid.get_area_km2(coord.level):.2f} km²")

# Convert to words in different languages
words_en = coord.to_words(Language.ENGLISH, bgrid)
words_es = coord.to_words(Language.SPANISH, bgrid)

🖥️ Command Line Interface

The library includes a CLI tool for quick conversions:

# Encode coordinates to BGrid
python bgrid_cli.py encode 40.7128 -74.0060 --level 3

# Decode BGrid to coordinates
python bgrid_cli.py decode "1234,567,89"

📖 API Reference

Core Classes

BGrid

Main class for BGrid operations.

Constructor:

BGrid(load_languages=None, bip39_dir=None)

Key Methods:

• dd_to_bgrid(lat, lon, level) - Convert coordinates to BGrid
• bgrid_to_dd(indices) - Convert BGrid indices to coordinates
• parse_bgrid_string(bgrid_str, language) - Parse BGrid string
• get_area_km2(level) - Get cell area at level

BGridCoordinate

Represents a BGrid coordinate with properties and methods.

Properties:

• indices - List of BGrid indices
• level - Hierarchical level
• center_lat, center_lon - Center coordinates
• bounds - Cell boundaries

Methods:

• to_words(language, bgrid) - Convert to BIP39 words
• to_string(use_words, language, bgrid) - Get string representation

Convenience Functions

• dd_to_bgrid(lat, lon, level, use_words, language) - Quick coordinate conversion
• bgrid_to_dd(bgrid_str, language) - Quick BGrid parsing

🌍 Supported Languages

The library supports BIP39 word lists in 9 languages:

• 🇺🇸 English (Language.ENGLISH)
• 🇪🇸 Spanish (Language.SPANISH)
• 🇫🇷 French (Language.FRENCH)
• 🇧🇷 Portuguese (Language.PORTUGUESE)
• 🇨🇳 Chinese Simplified (Language.CHINESE)
• 🇮🇹 Italian (Language.ITALIAN)
• 🇯🇵 Japanese (Language.JAPANESE)
• 🇰🇷 Korean (Language.KOREAN)
• 🇨🇿 Czech (Language.CZECH)

📊 Hierarchical Levels

The BGrid system uses up to 4 hierarchical levels:

Level	Grid Size	Total Cells	Approx. Area per Cell
1	64×32	2,048	~249,000 km²
2	32×64	2,048²	~122 km²
3	64×32	2,048³	~0.06 km²
4	32×64	2,048⁴	~0.00003 km²

🧪 Testing

Run the test suite:

python -m pytest test_bgrid.py -v

Or run tests directly:

python test_bgrid.py

🔐 PyPI Credentials

This project expects credentials in ~/.pypirc. Example:

[distutils]
index-servers =
  pypi
  testpypi

[pypi]
username = __token__
password = pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

📁 Project Structure

bgrid-python/
├── bgrid.py          # Main library code
├── bgrid_cli.py      # Command-line interface
├── examples.py       # Usage examples
├── test_bgrid.py     # Unit tests
├── setup.py          # Package setup
├── requirements.txt  # Dependencies
├── README.md         # This file
├── LICENSE          # MIT license
└── .gitignore       # Git ignore rules

📄 Examples

For comprehensive usage examples, see examples.py:

python examples.py

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.