Metadata-Version: 2.4
Name: chandrapin
Version: 1.0.0
Summary: Modular ChandraPIN spatial addressing & pathfinding framework for lunar operations
Author: Subhra Jyoti Dey
Project-URL: Homepage, https://github.com/subhrajyotidey/ChandraPIN
Project-URL: Repository, https://github.com/subhrajyotidey/ChandraPIN
Project-URL: Issues, https://github.com/subhrajyotidey/ChandraPIN/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cbor2>=5.4.0

# ChandraPIN: Geodesic Hierarchical Hexagonal Geocoding & Telemetry Serialization

[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/chandrapin/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://img.shields.io/badge/tests-28%20passed-green.svg)]()

ChandraPIN is a scientific-grade geocoding and delay-tolerant networking (DTN) serialization library designed for lunar surface exploration, extravehicular activities (EVAs), and autonomous rover pathfinding. 

The engine implements a **2D Polar Stereographic Hierarchical Hexagonal Geocoding** schema centered at the Moon's South Pole, dividing coordinates into pointy-topped hexagonal tiles down to sub-meter tactical precision. It integrates spatial indexing with heading-dependent kinematic difficulty weights and high-reliability, space-grade CBOR binary packaging.

---

## 1. Architectural Overview

```text
ChandraPIN/
├── pyproject.toml             # PEP 517 build configuration & metadata
├── LICENSE                    # MIT license
├── README.md                  # Comprehensive technical specification
├── chandrapin/                # Production Library
│   ├── __init__.py            # Explicit API exposition & versioning
│   ├── datums.py              # Geodetic datums (IAU Moon-2000) & constraints
│   ├── core_hex.py            # Level-12 recursive bisection tiling engine
│   ├── weights.py             # Directional traversability cost models
│   ├── dtn.py                 # Space-grade CBOR serialization & CRC-8 engine
│   ├── central.py             # Prefix-indexed central registry & state sync
│   └── interfaces.py          # Astronaut HUD presentation pipelines
└── tests/
    ├── __init__.py            # Test package marker
    └── test_flight_bounds.py  # 28-test automated assertions suite
```

---

## 2. Technical & Mathematical Specifications

### 2.1 Geodetic Datum & South Polar Projection
* **Coordinate Reference System (CRS)**: IAU/IAG Moon-2000 ellipsoid model ($R_{eq} = 1,737,400\text{ m}$, flattening $f = 0.0$).
* **Latitude Constraints**: Strictly bounded to the Southern Hemisphere ($\phi \in [-90.0, 0.0]$) to eliminate hemisphere-fold collision vulnerabilities.
* **Projection Plane**: South Polar Stereographic projection maps geodetic coordinates to 2D Cartesian coordinates $(x_p, y_p)$ via:
  $$R_p = 2 R_{eq} \tan\left(\frac{\pi}{4} + \frac{\phi_{\text{rad}}}{2}\right)$$
  $$x_p = R_p \sin(\lambda_{\text{rad}}), \quad y_p = -R_p \cos(\lambda_{\text{rad}})$$

### 2.2 Pointy-Topped Hex Axial Tiling
* **Orientation**: Pointy-topped hexagons mapped via axial coordinates $(q, r)$.
* **Decomposition Resolution**: 12 levels of recursive bisection.
* **Tactical Precision**: Flat-to-flat width at Level 12 is fixed at **$0.92\text{ meters}$**, yielding sub-meter accuracy.
* **Hierarchical Formatting**: Geocodes format to a 12-character token split into four 3-character chunks: `XXX-XXX-XXX-XXX`.
* **Phonetic Alphabet**: Built using 16 acoustically distinct characters (`2C3J4K5L6M7P8F9T`) to prevent vocal confusion over noisy VHF radio links.
* **State Mapping**: At each bisection level, the 9 possible child-offset configurations $(dq, dr) \in \{-1, 0, 1\}^2$ map strictly to the first 9 alphabet characters (`2C3J4K5L6`), leaving the remaining 7 characters reserved for future telemetry flags.

### 2.3 Asymmetric Kinematic Weights
ChandraPIN cells are not static coordinates; they act as nodes in a dynamic traversability graph:
* **Permanent Solar Constancy**: Probability score $[0.0, 1.0]$ representing solar illumination (energy harvesting potential).
* **Dynamic Traversability**: 6 heading-dependent path cost multipliers $[0.0, 15.0]$ representing terrain slopes, crater hazards, or slip risks.
* **8-bit Compression**: Compresses weights into a single telemetry byte:
  * **Bits [7:4]**: Variable Traversability Cost (0–15 scale)
  * **Bits [3:0]**: Permanent Solar Reach Score (0–15 scale)

### 2.4 Delay-Tolerant Serialization (DTN)
For transmission over satellite-relay links, data is serialized into a highly optimized **19-byte packet**:
* **6-byte binary payload**: The 12-char geocode compressed using 4 bits per character.
* **1-byte telemetry bitmask**: Compressed solar reach and heading friction nibbles.
* **11-byte state string**: Relative tracking anchor ID (alphanumeric, max 16 characters) or lost-tracking state.
* **1-byte CRC-8 Checksum**: Polynomial $x^8 + x^5 + x^4 + 1$ (CRC-8-ATM, `0x07`) protecting the payload against cosmic-ray bit-flips.

---

## 3. Installation

Install the library locally in editable mode:
```bash
pip install -e .
```

---

## 4. Usage Reference

### 4.1 Geocoding & Decoding
```python
from chandrapin.core_hex import GeodesicHexEngine

# 1. Forward Geocoding: Coordinate -> Geocode
geocode = GeodesicHexEngine.ForwardProjection(latitude=-86.9, longitude=70.0)
print(geocode)  # "4CJ-4KL-4K4-C46"

# 2. Reverse Geocoding: Geocode -> Central Coordinates
lat, lon = GeodesicHexEngine.ReverseProjection(geocode, lat_ref=-86.9, lon_ref=70.0)
print(f"Decoded: {lat:.6f}, {lon:.6f}")
```

### 4.2 Spatial Pathfinding Utilities
```python
# 1. Resolve adjacent neighbor cells (Returns geocodes of the 6 surrounding tiles)
neighbors = GeodesicHexEngine.GetNeighbors(geocode)
for n in neighbors:
    print(n)

# 2. Calculate great-circle distance between two cells in meters
distance_m = GeodesicHexEngine.GetDistance("4CJ-4KL-4K4-C46", "4CJ-4KL-4K4-C4C")
print(f"Distance: {distance_m:.2f} meters")
```

### 4.3 Telemetry Weight Compilation
```python
from chandrapin.weights import AsymmetricTelemetryFrame

# Initialize a weight frame with 80% permanent solar reach
frame = AsymmetricTelemetryFrame(geocode, permanent_solar_score=0.8)

# Update traversability costs for heading directions (0 to 5)
frame.update_heading_cost(ingress_direction=0, friction_multiplier=4.2)
frame.update_heading_cost(ingress_direction=3, friction_multiplier=12.0)

# Compile telemetry byte for active heading direction 0
telemetry_byte = frame.compile_telemetry_byte(current_heading=0)
print(f"Telemetry Byte: {bin(telemetry_byte)}")
```

### 4.4 Space-Grade Serialization
```python
from chandrapin.dtn import DtnSerializer

# Serialize frame states into a robust 19-byte packet
packet = DtnSerializer.SerializeFrame(
    geocode, frame, current_heading=0, tracking_mode="RELATIVE", anchor_id="LANDER1"
)
print(f"Packet size: {len(packet)} bytes (Hex: {packet.hex()})")

# Verify and deserialize incoming packet
payload, is_valid = DtnSerializer.VerifyAndDeserializeFrame(packet)
if is_valid:
    coord_bytes, telemetry_bytes, tracking_mode = payload
    print("Verification Successful!")
```

### 4.5 Central Control Sync Broadcasts
```python
from chandrapin.central import ChandraCentralRegistry

registry = ChandraCentralRegistry()
registry.seed_permanent_solar_reach("4CJ-4KL-4K4-C46", 0.95)

# O(log n) Prefix-based broadcast compilation
sync_broadcast = registry.generate_regional_broadcast("4CJ-4KL")
print(sync_broadcast)
```

---

## 5. Testing & Verification

Run the comprehensive 28-assertion automated test suite:
```bash
python -m unittest tests/test_flight_bounds.py -v
```
All assertions verify boundary bounds validation, deserialization type schema checking, arithmetic precision, and geodetic coordinate transformations.
