Metadata-Version: 2.5
Name: hexalate
Version: 0.3.1
Summary: A package for generating hexagonal tessellations
Project-URL: Homepage, https://github.com/james-see/hexalate
Project-URL: Repository, https://github.com/james-see/hexalate
Project-URL: Issues, https://github.com/james-see/hexalate/issues
Author-email: James Campbell <james@jamescampbell.us>
Maintainer-email: James Campbell <james@jamescampbell.us>
License-Expression: MIT
Keywords: geometry,hexagon,hexgrid,mcp,tessellation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: numpy>=1.26.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Hexalate

A Python library for generating hexagonal tessellations with support for axial coordinates, colormap plotting, GeoJSON export, and more.

## Installation

```bash
pip install hexalate
```

## Quick Start

```python
import hexalate as hx

grid = hx.HexGrid(width=10, height=8, hex_size=0.5)
grid.plot()
```

## HexGrid

The main class. Creates a grid that fills a rectangular area.

```python
grid = hx.HexGrid(
    width=10,
    height=8,
    hex_size=0.5,
    orientation="pointy",  # "pointy" (default) or "flat" top
)
```

### Orientation

```python
pointy = hx.HexGrid(10, 8, 0.5, orientation="pointy")  # ⬡ pointy top (default)
flat = hx.HexGrid(10, 8, 0.5, orientation="flat")  # ⬡ flat top
```

### Iterating and accessing hexagons

```python
for h in grid:
    print(h.x, h.y, h.q, h.r)  # Cartesian center + axial coords

# Access by axial coordinates
h = grid.get(q=0, r=0)

# Get all 6 existing neighbors
neighbors = grid.neighbors(q=0, r=0)
```

### Hexagon properties

Each `Hexagon` dataclass exposes:

| Attribute | Type | Description |
|-----------|------|-------------|
| `x`, `y` | float | Cartesian center |
| `q`, `r` | int | Axial coordinates |
| `s` | int | Third cube coordinate (`-q - r`) |
| `coords` | list | 7 `(x, y)` vertex tuples |

```python
h = grid.get(2, 3)
print(h.s)  # cube coordinate
print(h.distance_to(grid.get(0, 0)))  # hex distance
print(h.neighbor_coords())  # list of (q, r) neighbor positions
```

### Plotting

```python
# Basic
grid.plot()

# With a colormap driven by per-hex values
import random

values = [random.random() for _ in grid]
grid.plot(values=values, colormap="plasma")

# Save to file instead of showing
grid.plot(output="grid.png", dpi=200)
grid.plot(values=values, colormap="viridis", output="heatmap.svg")

# Convenience shortcut
grid.save_to_file("grid.png", dpi=150)
```

### Export

```python
# Pandas DataFrame (requires pandas)
df = grid.to_dataframe()
# columns: x, y, q, r

# GeoJSON
geojson = grid.to_geojson()  # dict
grid.save_geojson("grid.geojson")

# Backward-compatible list of dicts
data = grid.to_list()
# keys: x, y, q, r, coords
```

## Module-level functions (v0.1 / v0.2 compatible)

The original API still works:

```python
tessellation = hx.create_hexagonal_tessellation(width=10, height=5, hex_size=0.5)
hx.plot_hexagonal_tessellation(tessellation)

# With colormap
import random

values = [random.random() for _ in tessellation]
hx.plot_hexagonal_tessellation(tessellation, colormap="coolwarm", values=values)

# Save to file
hx.plot_hexagonal_tessellation(tessellation, output="grid.png")
```

## Single hexagon

```python
vertices = hx.hexagon(x_center=0.0, y_center=0.0, size=1.0)  # pointy
vertices = hx.hexagon(x_center=0.0, y_center=0.0, size=1.0, orientation="flat")
```

Returns a list of 7 `(x, y)` tuples (closed polygon).

## Examples

Ready-to-run recipes in the [`examples/`](examples/) folder:

| File | What it shows |
|------|---------------|
| [`distance_rings.py`](examples/distance_rings.py) | Concentric color rings radiating from the center hex using cube-distance |
| [`wave_heatmap.py`](examples/wave_heatmap.py) | sin × cos function mapped over the grid — drop in any real data |
| [`game_board.py`](examples/game_board.py) | Catan-style island board with terrain types and a flat-top orientation |
| [`checkerboard.py`](examples/checkerboard.py) | 3-color tiling via axial coords (`q mod 3`) — no adjacency checks needed |
| [`geojson_export.py`](examples/geojson_export.py) | Export full grid + distance-filtered zone to GeoJSON for QGIS / kepler.gl |
| [`dataframe_analysis.py`](examples/dataframe_analysis.py) | Attach custom metrics in pandas, filter to inner rings, re-plot the subset |

```bash
cd examples
python distance_rings.py     # → distance_rings.png
python wave_heatmap.py       # → wave_heatmap.png
python game_board.py         # → game_board.png
python checkerboard.py       # → checkerboard.png
python geojson_export.py     # → full_grid.geojson, center_zone.geojson
python dataframe_analysis.py # → dataframe_analysis.png (requires pandas)
```

## Command Line

```bash
# Display
hexalate --width 10 --height 8 --size 0.5

# Flat-top orientation
hexalate --width 10 --height 8 --size 0.5 --orientation flat

# Random colormap coloring
hexalate --width 10 --height 8 --size 0.5 --colormap plasma

# Save to file
hexalate --width 10 --height 8 --size 0.5 --output grid.png
hexalate --width 10 --height 8 --size 0.5 --colormap viridis --output heatmap.svg
```

## License

MIT License.
