bgrid 1.0.0
Hierarchical coordinate system with BIP39 word encoding
Requires Python: >=3.7

# 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
```bash
git clone https://github.com/bgrid-maps/bgrid-python
cd bgrid-python
pip install -e .
```

### Using pip (when published)
```bash
pip install bgrid
```

## 🚀 Quick Start

### Basic Usage
```python
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
```python
# 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:

```bash
# 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:**
```python
BGrid(load_languages=None, bip39_dir=None)
```

**Key Methods:**
- [`dd_to_bgrid(lat, lon, level)`](bgrid.py) - Convert coordinates to BGrid
- [`bgrid_to_dd(indices)`](bgrid.py) - Convert BGrid indices to coordinates
- [`parse_bgrid_string(bgrid_str, language)`](bgrid.py) - Parse BGrid string
- [`get_area_km2(level)`](bgrid.py) - 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)`](bgrid.py) - Convert to BIP39 words
- [`to_string(use_words, language, bgrid)`](bgrid.py) - Get string representation

### Convenience Functions

- [`dd_to_bgrid(lat, lon, level, use_words, language)`](bgrid.py) - Quick coordinate conversion
- [`bgrid_to_dd(bgrid_str, language)`](bgrid.py) - 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:

```bash
python -m pytest test_bgrid.py -v
```

Or run tests directly:
```bash
python test_bgrid.py
```

## 🔐 PyPI Credentials

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

```ini
[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](examples.py):

```bash
python examples.py
```

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.