sameer-graph-lib 0.1.0__tar.gz

sameer_graph_lib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sameer Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sameer_graph_lib-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: sameer-graph-lib
+Version: 0.1.0
+Summary: H3 and NetworkX based route affinity graph toolkit.
+Author-email: Sameer <sameerkumarroy073@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/iams31/sameer_graph_lib
+Project-URL: Repository, https://github.com/iams31/sameer_graph_lib
+Project-URL: Issues, https://github.com/iams31/sameer_graph_lib/issues
+Keywords: h3,networkx,geospatial,routing,graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: h3>=4.0.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: geo
+Requires-Dist: contextily>=1.5; extra == "geo"
+Requires-Dist: geopandas>=0.14; extra == "geo"
+Requires-Dist: shapely>=2.0; extra == "geo"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# sameer-graph-lib
+
+`sameer-graph-lib` is an editable Python library for building H3-based route affinity graphs with NetworkX.
+
+It turns H3 arrays, latitude/longitude sequences, and encoded polylines into connected hex chains, inserts them into a weighted graph, extracts high-affinity corridors, and decomposes the graph into a main trunk plus minor branches.
+
+## Editable install
+
+```powershell
+python -m pip install -e ".[dev,plot]"
+```
+
+Because the install is editable, changes you make inside `src/sameer_graph_lib` are picked up immediately by Python without reinstalling.
+
+If your machine uses `uv`, run commands through the managed environment:
+
+```powershell
+uv run --extra dev --extra plot python -c "import sameer_graph_lib; print(sameer_graph_lib.__version__)"
+```
+
+## Install
+
+From PyPI after publication:
+
+```powershell
+pip install sameer-graph-lib
+```
+
+With optional plotting and geospatial extras:
+
+```powershell
+pip install "sameer-graph-lib[plot,geo]"
+```
+
+## Quick start
+
+```python
+from sameer_graph_lib import HexGraph
+
+graph = HexGraph(hex_resolution=9)
+
+route = graph.add_latlng_sequence([
+    (12.9716, 77.5946),
+    (12.9760, 77.5990),
+])
+
+print(graph.get_graph_stats())
+selected = graph.get_appropriate_hexes(cutoff=0.8)
+fig = graph.visualize_graph(title="80% compact cluster", highlight_hexes=selected)
+print(graph.decompose_branches())
+```
+
+## Main APIs
+
+- `SpatialIngestor`: converts H3 arrays, lat/lng sequences, and encoded polylines into contiguous H3 chains.
+- `AffinityGraph`: NetworkX wrapper for array-based insertion, nearest attachment, affinity scoring, editing, and JSON persistence.
+- `CorridorExtractor`: uses exact all-node Dijkstra selection to extract the most compact cluster covering a target percentage of graph traversal volume.
+- `TopologyAnalyzer`: separates the main branch from residual minor branches.
+- `HexGraph`: backwards-compatible convenience class for your original code style.
+
+Graph creation follows the original per-node procedure: H3 arrays are normalized, then each hex is inserted with `add_node`/`add_hex`. Lat/lng sequences and encoded polylines are first converted into H3 arrays at the requested resolution, then inserted the same way.
+
+For QC, use:
+
+```python
+fig = graph.visualize_graph(highlight_hexes=selected)
+fig.savefig("graph_qc.png", dpi=150, bbox_inches="tight")
+
+fig = graph.visualize_step_by_step(route[:5], labels=["A", "B", "C", "D", "E"])
+fig.savefig("insertion_steps.png", dpi=150, bbox_inches="tight")
+```
+
+To plot actual H3 hex boundaries as geospatial polygons:
+
+```python
+from sameer_graph_lib import plot_h3_cells, plot_h3_cells_map
+
+fig = plot_h3_cells("88618c4f29fffff", label_full_hex=True)
+fig.savefig("single_h3_cell.png", dpi=150, bbox_inches="tight")
+
+fig = graph.plot_h3_cells(highlight_hexes=selected, show_labels=False)
+fig.savefig("h3_cell_footprint.png", dpi=150, bbox_inches="tight")
+
+fig = plot_h3_cells_map(route, selected_cells=selected)
+fig.savefig("h3_cell_basemap.png", dpi=150, bbox_inches="tight")
+```
+
+`plot_h3_cells_map` uses GeoPandas + Contextily. Install it with:
+
+```powershell
+python -m pip install -e ".[plot,geo]"
+uv run --extra plot --extra geo python -c "from sameer_graph_lib import plot_h3_cells_map"
+```
+
+To get H3 centers and a convex hull:
+
+```python
+from sameer_graph_lib import getLatLng, h3_convex_hull
+
+points = getLatLng(route)          # [(lat, lng), ...]
+hull = h3_convex_hull(route)       # Shapely geometry in (lng, lat)
+graph_hull = graph.convex_hull()   # Same, using graph nodes
+```
+
+## Useful commands
+
+```powershell
+python -m pytest
+python -m build
+uv run --extra dev pytest -q
+uv run --extra dev python -m build
+uv run --extra dev python -m twine check dist/*
+```
+
+Build artifacts will appear in `dist/` after `python -m build`.
+
+## Publish To PyPI
+
+1. Build the package:
+
+```powershell
+uv run --extra dev python -m build
+```
+
+2. Validate the package metadata:
+
+```powershell
+uv run --extra dev python -m twine check dist/*
+```
+
+3. Upload to PyPI:
+
+```powershell
+uv run --extra dev python -m twine upload dist/*
+```
+
+After upload, users can install it with:
+
+```powershell
+pip install sameer-graph-lib
+```
+
+## Publish From GitHub
+
+This repo also includes a Trusted Publishing workflow in
+[.github/workflows/publish.yml](C:/Users/rrran/Desktop/sameer_graph_lib/.github/workflows/publish.yml:1).
+
+To finish that setup:
+
+1. Create the project on PyPI, or reserve the name `sameer-graph-lib`.
+2. On PyPI, open the project settings and add a Trusted Publisher for:
+   `owner`: `iams31`
+   `repository`: `sameer_graph_lib`
+   `workflow`: `publish.yml`
+   `environment`: `pypi`
+3. Create a GitHub Release, or run the workflow manually from the Actions tab.
+
+After that, GitHub Actions can publish without storing a long-lived PyPI token.
+
+Official references:
+
+- PyPI Trusted Publishing: https://docs.pypi.org/trusted-publishers/
+- Packaging guide upload flow: https://packaging.python.org/tutorials/packaging-projects/

sameer_graph_lib-0.1.0/README.md

@@ -0,0 +1,163 @@
+# sameer-graph-lib
+
+`sameer-graph-lib` is an editable Python library for building H3-based route affinity graphs with NetworkX.
+
+It turns H3 arrays, latitude/longitude sequences, and encoded polylines into connected hex chains, inserts them into a weighted graph, extracts high-affinity corridors, and decomposes the graph into a main trunk plus minor branches.
+
+## Editable install
+
+```powershell
+python -m pip install -e ".[dev,plot]"
+```
+
+Because the install is editable, changes you make inside `src/sameer_graph_lib` are picked up immediately by Python without reinstalling.
+
+If your machine uses `uv`, run commands through the managed environment:
+
+```powershell
+uv run --extra dev --extra plot python -c "import sameer_graph_lib; print(sameer_graph_lib.__version__)"
+```
+
+## Install
+
+From PyPI after publication:
+
+```powershell
+pip install sameer-graph-lib
+```
+
+With optional plotting and geospatial extras:
+
+```powershell
+pip install "sameer-graph-lib[plot,geo]"
+```
+
+## Quick start
+
+```python
+from sameer_graph_lib import HexGraph
+
+graph = HexGraph(hex_resolution=9)
+
+route = graph.add_latlng_sequence([
+    (12.9716, 77.5946),
+    (12.9760, 77.5990),
+])
+
+print(graph.get_graph_stats())
+selected = graph.get_appropriate_hexes(cutoff=0.8)
+fig = graph.visualize_graph(title="80% compact cluster", highlight_hexes=selected)
+print(graph.decompose_branches())
+```
+
+## Main APIs
+
+- `SpatialIngestor`: converts H3 arrays, lat/lng sequences, and encoded polylines into contiguous H3 chains.
+- `AffinityGraph`: NetworkX wrapper for array-based insertion, nearest attachment, affinity scoring, editing, and JSON persistence.
+- `CorridorExtractor`: uses exact all-node Dijkstra selection to extract the most compact cluster covering a target percentage of graph traversal volume.
+- `TopologyAnalyzer`: separates the main branch from residual minor branches.
+- `HexGraph`: backwards-compatible convenience class for your original code style.
+
+Graph creation follows the original per-node procedure: H3 arrays are normalized, then each hex is inserted with `add_node`/`add_hex`. Lat/lng sequences and encoded polylines are first converted into H3 arrays at the requested resolution, then inserted the same way.
+
+For QC, use:
+
+```python
+fig = graph.visualize_graph(highlight_hexes=selected)
+fig.savefig("graph_qc.png", dpi=150, bbox_inches="tight")
+
+fig = graph.visualize_step_by_step(route[:5], labels=["A", "B", "C", "D", "E"])
+fig.savefig("insertion_steps.png", dpi=150, bbox_inches="tight")
+```
+
+To plot actual H3 hex boundaries as geospatial polygons:
+
+```python
+from sameer_graph_lib import plot_h3_cells, plot_h3_cells_map
+
+fig = plot_h3_cells("88618c4f29fffff", label_full_hex=True)
+fig.savefig("single_h3_cell.png", dpi=150, bbox_inches="tight")
+
+fig = graph.plot_h3_cells(highlight_hexes=selected, show_labels=False)
+fig.savefig("h3_cell_footprint.png", dpi=150, bbox_inches="tight")
+
+fig = plot_h3_cells_map(route, selected_cells=selected)
+fig.savefig("h3_cell_basemap.png", dpi=150, bbox_inches="tight")
+```
+
+`plot_h3_cells_map` uses GeoPandas + Contextily. Install it with:
+
+```powershell
+python -m pip install -e ".[plot,geo]"
+uv run --extra plot --extra geo python -c "from sameer_graph_lib import plot_h3_cells_map"
+```
+
+To get H3 centers and a convex hull:
+
+```python
+from sameer_graph_lib import getLatLng, h3_convex_hull
+
+points = getLatLng(route)          # [(lat, lng), ...]
+hull = h3_convex_hull(route)       # Shapely geometry in (lng, lat)
+graph_hull = graph.convex_hull()   # Same, using graph nodes
+```
+
+## Useful commands
+
+```powershell
+python -m pytest
+python -m build
+uv run --extra dev pytest -q
+uv run --extra dev python -m build
+uv run --extra dev python -m twine check dist/*
+```
+
+Build artifacts will appear in `dist/` after `python -m build`.
+
+## Publish To PyPI
+
+1. Build the package:
+
+```powershell
+uv run --extra dev python -m build
+```
+
+2. Validate the package metadata:
+
+```powershell
+uv run --extra dev python -m twine check dist/*
+```
+
+3. Upload to PyPI:
+
+```powershell
+uv run --extra dev python -m twine upload dist/*
+```
+
+After upload, users can install it with:
+
+```powershell
+pip install sameer-graph-lib
+```
+
+## Publish From GitHub
+
+This repo also includes a Trusted Publishing workflow in
+[.github/workflows/publish.yml](C:/Users/rrran/Desktop/sameer_graph_lib/.github/workflows/publish.yml:1).
+
+To finish that setup:
+
+1. Create the project on PyPI, or reserve the name `sameer-graph-lib`.
+2. On PyPI, open the project settings and add a Trusted Publisher for:
+   `owner`: `iams31`
+   `repository`: `sameer_graph_lib`
+   `workflow`: `publish.yml`
+   `environment`: `pypi`
+3. Create a GitHub Release, or run the workflow manually from the Actions tab.
+
+After that, GitHub Actions can publish without storing a long-lived PyPI token.
+
+Official references:
+
+- PyPI Trusted Publishing: https://docs.pypi.org/trusted-publishers/
+- Packaging guide upload flow: https://packaging.python.org/tutorials/packaging-projects/

sameer_graph_lib-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sameer-graph-lib"
+version = "0.1.0"
+description = "H3 and NetworkX based route affinity graph toolkit."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Sameer", email = "sameerkumarroy073@gmail.com" }
+]
+dependencies = [
+  "h3>=4.0.0",
+  "networkx>=3.0"
+]
+keywords = ["h3", "networkx", "geospatial", "routing", "graph"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: GIS"
+]
+
+[project.urls]
+Homepage = "https://github.com/iams31/sameer_graph_lib"
+Repository = "https://github.com/iams31/sameer_graph_lib"
+Issues = "https://github.com/iams31/sameer_graph_lib/issues"
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7"]
+geo = ["contextily>=1.5", "geopandas>=0.14", "shapely>=2.0"]
+dev = ["pytest>=8.0", "build>=1.2", "twine>=5.1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

sameer_graph_lib-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sameer_graph_lib-0.1.0/src/sameer_graph_lib/__init__.py

@@ -0,0 +1,28 @@
+"""Public API for sameer_graph_lib."""
+
+from .affinity_graph import AffinityGraph
+from .corridor_extractor import CorridorExtractor
+from .geometry import getLatLng, get_latlng, h3_convex_hull, h3_convex_hull_geojson, makingHull, making_hull
+from .hex_graph import HexGraph
+from .plotting import cells_to_geodataframe, plot_h3_cells, plot_h3_cells_map
+from .spatial_ingestor import SpatialIngestor
+from .topology_analyzer import TopologyAnalyzer
+
+__all__ = [
+    "AffinityGraph",
+    "CorridorExtractor",
+    "HexGraph",
+    "cells_to_geodataframe",
+    "getLatLng",
+    "get_latlng",
+    "h3_convex_hull",
+    "h3_convex_hull_geojson",
+    "makingHull",
+    "making_hull",
+    "plot_h3_cells",
+    "plot_h3_cells_map",
+    "SpatialIngestor",
+    "TopologyAnalyzer",
+]
+
+__version__ = "0.1.0"

sameer_graph_lib-0.1.0/src/sameer_graph_lib/_h3.py

@@ -0,0 +1,123 @@
+"""Small compatibility layer for h3-py 3.x and 4.x APIs."""
+
+from __future__ import annotations
+
+import math
+from typing import List, Tuple
+
+import h3
+
+LatLng = Tuple[float, float]
+
+EARTH_RADIUS_KM = 6371.0088
+
+
+def is_valid_cell(cell: str) -> bool:
+    fn = getattr(h3, "is_valid_cell", None) or getattr(h3, "h3_is_valid", None)
+    return bool(fn(cell)) if fn else False
+
+
+def latlng_to_cell(lat: float, lng: float, resolution: int) -> str:
+    fn = getattr(h3, "latlng_to_cell", None)
+    if fn:
+        return fn(lat, lng, resolution)
+    return h3.geo_to_h3(lat, lng, resolution)
+
+
+def cell_to_latlng(cell: str) -> LatLng:
+    fn = getattr(h3, "cell_to_latlng", None)
+    if fn:
+        lat, lng = fn(cell)
+    else:
+        lat, lng = h3.h3_to_geo(cell)
+    return float(lat), float(lng)
+
+
+def cell_to_boundary(cell: str) -> List[LatLng]:
+    fn = getattr(h3, "cell_to_boundary", None)
+    if fn:
+        return [(float(lat), float(lng)) for lat, lng in fn(cell)]
+
+    legacy_fn = getattr(h3, "h3_to_geo_boundary", None)
+    if legacy_fn:
+        return [(float(lat), float(lng)) for lat, lng in legacy_fn(cell, geo_json=False)]
+
+    raise RuntimeError("Installed h3 package does not expose cell boundary helpers.")
+
+
+def get_resolution(cell: str) -> int:
+    fn = getattr(h3, "get_resolution", None) or getattr(h3, "h3_get_resolution", None)
+    return int(fn(cell))
+
+
+def grid_path_cells(start: str, end: str) -> List[str]:
+    fn = getattr(h3, "grid_path_cells", None) or getattr(h3, "h3_line", None)
+    if not fn:
+        raise RuntimeError("Installed h3 package does not expose grid path helpers.")
+    return list(fn(start, end))
+
+
+def average_hexagon_edge_length(resolution: int, unit: str = "km") -> float:
+    fn = getattr(h3, "average_hexagon_edge_length", None)
+    if fn:
+        return float(fn(resolution, unit=unit))
+
+    fn = getattr(h3, "edge_length", None)
+    if fn:
+        try:
+            return float(fn(resolution, unit=unit))
+        except TypeError:
+            return float(fn(res=resolution, unit=unit))
+
+    raise RuntimeError("Installed h3 package does not expose edge length helpers.")
+
+
+def cell_area(cell: str, unit: str = "km^2") -> float:
+    fn = getattr(h3, "cell_area", None)
+    if not fn:
+        raise RuntimeError("Installed h3 package does not expose cell_area.")
+    return float(fn(cell, unit=unit))
+
+
+def haversine_km(a: LatLng, b: LatLng) -> float:
+    lat1, lng1 = map(math.radians, a)
+    lat2, lng2 = map(math.radians, b)
+    dlat = lat2 - lat1
+    dlng = lng2 - lng1
+    sin_dlat = math.sin(dlat / 2.0)
+    sin_dlng = math.sin(dlng / 2.0)
+    h = sin_dlat**2 + math.cos(lat1) * math.cos(lat2) * sin_dlng**2
+    return 2.0 * EARTH_RADIUS_KM * math.asin(min(1.0, math.sqrt(h)))
+
+
+def approximate_grid_distance(start: str, end: str) -> int:
+    if start == end:
+        return 0
+
+    resolution = get_resolution(start)
+    edge_km = average_hexagon_edge_length(resolution, unit="km")
+    center_spacing_km = max(edge_km * math.sqrt(3), 1e-9)
+    distance_km = haversine_km(cell_to_latlng(start), cell_to_latlng(end))
+    return max(1, int(round(distance_km / center_spacing_km)))
+
+
+def grid_distance(start: str, end: str) -> int:
+    """Return native H3 grid distance between two cells."""
+    if start == end:
+        return 0
+
+    fn = getattr(h3, "grid_distance", None)
+    if fn:
+        try:
+            return int(fn(start, end))
+        except Exception:
+            pass
+
+    legacy_fn = getattr(h3, "h3_distance", None)
+    if legacy_fn:
+        try:
+            return int(legacy_fn(start, end))
+        except Exception:
+            pass
+
+    return approximate_grid_distance(start, end)