gmaprium 0.1.0__tar.gz

gmaprium-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+
+# APM dependencies
+apm_modules/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.env
+examples/*.html
+.pypirc

gmaprium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kentaro Aoki
+
+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.

gmaprium-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include examples *.ipynb
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+global-exclude .pytest_cache/*
+exclude examples/*.html
+exclude apm.yml
+exclude apm.lock.yaml
+recursive-exclude apm_modules *

gmaprium-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: gmaprium
+Version: 0.1.0
+Summary: Folium-style Python helpers for rendering Google Maps.
+Project-URL: Homepage, https://github.com/KentaroAOKI/gmaprium
+Project-URL: Repository, https://github.com/KentaroAOKI/gmaprium
+Project-URL: Issues, https://github.com/KentaroAOKI/gmaprium/issues
+Author: Kentaro
+License: MIT
+License-File: LICENSE
+Keywords: folium,geojson,google-maps,heatmap,maps,streamlit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: streamlit
+Requires-Dist: streamlit>=1.30; extra == 'streamlit'
+Description-Content-Type: text/markdown
+
+# gmaprium
+
+Folium-style Python helpers for rendering Google Maps HTML.
+
+gmaprium can be used to create standalone HTML maps, display maps in Jupyter Notebook, add Google tile layers to existing Folium maps, and embed maps in Streamlit apps.
+
+## Installation
+
+```bash
+pip install gmaprium
+```
+
+## Usage
+
+```python
+from gmaprium import GeoJson, HeatMap, LayerControl, Map, Marker, Polygon
+
+m = Map(
+    location=[35.6812, 139.7671],
+    zoom_start=12,
+    api_key="YOUR_GOOGLE_MAPS_API_KEY",
+    map_type="roadmap",
+    height="500px",
+)
+
+Marker([35.6812, 139.7671], popup="Tokyo Station", tooltip="Tokyo", name="Stations").add_to(m)
+Polygon(
+    [[35.70, 139.70], [35.70, 139.82], [35.62, 139.82], [35.62, 139.70]],
+    name="Area",
+).add_to(m)
+HeatMap([[35.6812, 139.7671, 2], [35.6895, 139.6917, 1]], name="Heat").add_to(m)
+LayerControl().add_to(m)
+
+# Full HTML document.
+m.save("map.html")
+
+# Embeddable HTML fragment for web apps.
+html = m.render_fragment()
+```
+
+You can also pass the API key with the `GOOGLE_MAPS_API_KEY` environment variable.
+
+Markers use Google's `AdvancedMarkerElement`. If you add markers without passing `map_id=...`, the renderer uses Google's `DEMO_MAP_ID` for local testing.
+
+## Supported Elements
+
+- `Map`
+- `Marker`
+- `Polyline`
+- `Polygon`
+- `Circle`
+- `GeoJson`
+- `HeatMap`
+- `LayerControl`
+
+`GeoJson` accepts GeoJSON dictionaries, JSON file paths, objects with `__geo_interface__`, and GeoPandas-like objects with `to_json()`.
+
+`HeatMap` uses a canvas overlay instead of Google's deprecated JavaScript `HeatmapLayer`.
+It ports the Leaflet.heat/simpleheat rendering model, including `radius`, `blur`, `min_opacity`, `max_zoom`, `max_value`, and `gradient`.
+The defaults match Leaflet.heat/simpleheat on a typical OSM map: `radius=25`, `blur=15`, `min_opacity=0.05`, `max_zoom=18`, `max_value=1.0`, and the blue-cyan-lime-yellow-red gradient.
+Lower zoom levels are intentionally faded by Leaflet.heat's `max_zoom - zoom` intensity scale. Set `max_zoom` closer to your initial zoom if the heat fades too quickly.
+
+The legacy `google_tiles_url()` and `add_google_tiles()` helpers are still available for projects that want to add Google tile URLs to an existing Folium map.
+
+## Notebook
+
+In Jupyter Notebook, display the map by returning the `Map` object as the last expression in a cell.
+
+```python
+import os
+
+from gmaprium import HeatMap, LayerControl, Map, Marker
+
+os.environ["GOOGLE_MAPS_API_KEY"] = "your-api-key"
+
+m = Map(location=[35.6812, 139.7671], zoom_start=12, height="500px")
+Marker([35.6812, 139.7671], popup="Tokyo Station", name="Markers").add_to(m)
+HeatMap([[35.6812, 139.7671, 1.0]], name="Heat", max_zoom=14).add_to(m)
+LayerControl().add_to(m)
+
+m
+```
+
+You can also display explicitly:
+
+```python
+from IPython.display import HTML, display
+
+display(HTML(m.render_fragment()))
+```
+
+The notebook example is available at `examples/example.ipynb`.
+
+## Folium Extension
+
+If you already use Folium, add Google tile layers to a `folium.Map` with `add_google_tiles()`.
+
+```python
+import folium
+
+from gmaprium import add_google_tiles
+
+m = folium.Map(location=[35.6812, 139.7671], zoom_start=12, tiles=None)
+add_google_tiles(m, api_key="your-api-key", map_type="roadmap", name="Google Roadmap")
+add_google_tiles(m, api_key="your-api-key", map_type="satellite", name="Google Satellite", show=False)
+
+folium.LayerControl().add_to(m)
+m.save("folium_google_tiles.html")
+```
+
+This Folium extension only adds Google tile layers. It does not enable the Google Maps JavaScript API renderer or gmaprium's `HeatMap`.
+
+The Folium example is available at `examples/folium_extension.py`.
+
+## Streamlit
+
+Use `st_google_map()` to render a `gmaprium.Map` inside a Streamlit app.
+
+```python
+import os
+
+import streamlit as st
+
+from gmaprium import Map, Marker, st_google_map
+
+api_key = os.environ["GOOGLE_MAPS_API_KEY"]
+
+m = Map(location=[35.6812, 139.7671], zoom_start=12, api_key=api_key, height="600px")
+Marker([35.6812, 139.7671], popup="Tokyo Station").add_to(m)
+
+st_google_map(m)
+```
+
+Install the optional dependency and run the example app:
+
+```bash
+python -m pip install -e ".[dev,streamlit]"
+export GOOGLE_MAPS_API_KEY="your-api-key"
+streamlit run examples/streamlit_app.py
+```
+
+The Streamlit example is available at `examples/streamlit_app.py`.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+```

gmaprium-0.1.0/README.md

@@ -0,0 +1,149 @@
+# gmaprium
+
+Folium-style Python helpers for rendering Google Maps HTML.
+
+gmaprium can be used to create standalone HTML maps, display maps in Jupyter Notebook, add Google tile layers to existing Folium maps, and embed maps in Streamlit apps.
+
+## Installation
+
+```bash
+pip install gmaprium
+```
+
+## Usage
+
+```python
+from gmaprium import GeoJson, HeatMap, LayerControl, Map, Marker, Polygon
+
+m = Map(
+    location=[35.6812, 139.7671],
+    zoom_start=12,
+    api_key="YOUR_GOOGLE_MAPS_API_KEY",
+    map_type="roadmap",
+    height="500px",
+)
+
+Marker([35.6812, 139.7671], popup="Tokyo Station", tooltip="Tokyo", name="Stations").add_to(m)
+Polygon(
+    [[35.70, 139.70], [35.70, 139.82], [35.62, 139.82], [35.62, 139.70]],
+    name="Area",
+).add_to(m)
+HeatMap([[35.6812, 139.7671, 2], [35.6895, 139.6917, 1]], name="Heat").add_to(m)
+LayerControl().add_to(m)
+
+# Full HTML document.
+m.save("map.html")
+
+# Embeddable HTML fragment for web apps.
+html = m.render_fragment()
+```
+
+You can also pass the API key with the `GOOGLE_MAPS_API_KEY` environment variable.
+
+Markers use Google's `AdvancedMarkerElement`. If you add markers without passing `map_id=...`, the renderer uses Google's `DEMO_MAP_ID` for local testing.
+
+## Supported Elements
+
+- `Map`
+- `Marker`
+- `Polyline`
+- `Polygon`
+- `Circle`
+- `GeoJson`
+- `HeatMap`
+- `LayerControl`
+
+`GeoJson` accepts GeoJSON dictionaries, JSON file paths, objects with `__geo_interface__`, and GeoPandas-like objects with `to_json()`.
+
+`HeatMap` uses a canvas overlay instead of Google's deprecated JavaScript `HeatmapLayer`.
+It ports the Leaflet.heat/simpleheat rendering model, including `radius`, `blur`, `min_opacity`, `max_zoom`, `max_value`, and `gradient`.
+The defaults match Leaflet.heat/simpleheat on a typical OSM map: `radius=25`, `blur=15`, `min_opacity=0.05`, `max_zoom=18`, `max_value=1.0`, and the blue-cyan-lime-yellow-red gradient.
+Lower zoom levels are intentionally faded by Leaflet.heat's `max_zoom - zoom` intensity scale. Set `max_zoom` closer to your initial zoom if the heat fades too quickly.
+
+The legacy `google_tiles_url()` and `add_google_tiles()` helpers are still available for projects that want to add Google tile URLs to an existing Folium map.
+
+## Notebook
+
+In Jupyter Notebook, display the map by returning the `Map` object as the last expression in a cell.
+
+```python
+import os
+
+from gmaprium import HeatMap, LayerControl, Map, Marker
+
+os.environ["GOOGLE_MAPS_API_KEY"] = "your-api-key"
+
+m = Map(location=[35.6812, 139.7671], zoom_start=12, height="500px")
+Marker([35.6812, 139.7671], popup="Tokyo Station", name="Markers").add_to(m)
+HeatMap([[35.6812, 139.7671, 1.0]], name="Heat", max_zoom=14).add_to(m)
+LayerControl().add_to(m)
+
+m
+```
+
+You can also display explicitly:
+
+```python
+from IPython.display import HTML, display
+
+display(HTML(m.render_fragment()))
+```
+
+The notebook example is available at `examples/example.ipynb`.
+
+## Folium Extension
+
+If you already use Folium, add Google tile layers to a `folium.Map` with `add_google_tiles()`.
+
+```python
+import folium
+
+from gmaprium import add_google_tiles
+
+m = folium.Map(location=[35.6812, 139.7671], zoom_start=12, tiles=None)
+add_google_tiles(m, api_key="your-api-key", map_type="roadmap", name="Google Roadmap")
+add_google_tiles(m, api_key="your-api-key", map_type="satellite", name="Google Satellite", show=False)
+
+folium.LayerControl().add_to(m)
+m.save("folium_google_tiles.html")
+```
+
+This Folium extension only adds Google tile layers. It does not enable the Google Maps JavaScript API renderer or gmaprium's `HeatMap`.
+
+The Folium example is available at `examples/folium_extension.py`.
+
+## Streamlit
+
+Use `st_google_map()` to render a `gmaprium.Map` inside a Streamlit app.
+
+```python
+import os
+
+import streamlit as st
+
+from gmaprium import Map, Marker, st_google_map
+
+api_key = os.environ["GOOGLE_MAPS_API_KEY"]
+
+m = Map(location=[35.6812, 139.7671], zoom_start=12, api_key=api_key, height="600px")
+Marker([35.6812, 139.7671], popup="Tokyo Station").add_to(m)
+
+st_google_map(m)
+```
+
+Install the optional dependency and run the example app:
+
+```bash
+python -m pip install -e ".[dev,streamlit]"
+export GOOGLE_MAPS_API_KEY="your-api-key"
+streamlit run examples/streamlit_app.py
+```
+
+The Streamlit example is available at `examples/streamlit_app.py`.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+```

gmaprium-0.1.0/examples/example.ipynb

@@ -0,0 +1,131 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "example-map",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "from gmaprium import Circle, GeoJson, HeatMap, LayerControl, Map, Marker, Polygon, Polyline\n",
+    "\n",
+    "api_key = os.environ.get(\"GOOGLE_MAPS_API_KEY\")\n",
+    "if not api_key:\n",
+    "    raise RuntimeError(\"Set GOOGLE_MAPS_API_KEY before running this notebook.\")\n",
+    "\n",
+    "m = Map(\n",
+    "    location=[35.6812, 139.7671],\n",
+    "    zoom_start=12,\n",
+    "    api_key=api_key,\n",
+    "    map_type=\"roadmap\",\n",
+    "    height=\"600px\",\n",
+    ")\n",
+    "\n",
+    "Marker(\n",
+    "    [35.6812, 139.7671],\n",
+    "    popup=\"Tokyo Station\",\n",
+    "    tooltip=\"Tokyo Station\",\n",
+    "    name=\"Markers\",\n",
+    ").add_to(m)\n",
+    "\n",
+    "Polyline(\n",
+    "    [[35.6812, 139.7671], [35.6895, 139.6917]],\n",
+    "    color=\"#0b57d0\",\n",
+    "    weight=4,\n",
+    "    name=\"Route\",\n",
+    ").add_to(m)\n",
+    "\n",
+    "Polygon(\n",
+    "    [[35.7000, 139.7000], [35.7000, 139.8200], [35.6200, 139.8200], [35.6200, 139.7000]],\n",
+    "    color=\"#188038\",\n",
+    "    fill_color=\"#34a853\",\n",
+    "    fill_opacity=0.18,\n",
+    "    name=\"Area\",\n",
+    ").add_to(m)\n",
+    "\n",
+    "Circle(\n",
+    "    [35.6895, 139.6917],\n",
+    "    radius=700,\n",
+    "    color=\"#d93025\",\n",
+    "    fill_color=\"#f28b82\",\n",
+    "    fill_opacity=0.25,\n",
+    "    name=\"Circle\",\n",
+    ").add_to(m)\n",
+    "\n",
+    "GeoJson(\n",
+    "    {\n",
+    "        \"type\": \"FeatureCollection\",\n",
+    "        \"features\": [\n",
+    "            {\n",
+    "                \"type\": \"Feature\",\n",
+    "                \"properties\": {\"name\": \"Sample GeoJSON\"},\n",
+    "                \"geometry\": {\n",
+    "                    \"type\": \"Polygon\",\n",
+    "                    \"coordinates\": [\n",
+    "                        [\n",
+    "                            [139.735, 35.675],\n",
+    "                            [139.755, 35.675],\n",
+    "                            [139.755, 35.690],\n",
+    "                            [139.735, 35.690],\n",
+    "                            [139.735, 35.675],\n",
+    "                        ]\n",
+    "                    ],\n",
+    "                },\n",
+    "            }\n",
+    "        ],\n",
+    "    },\n",
+    "    name=\"GeoJSON\",\n",
+    "    style_function=lambda feature: {\n",
+    "        \"fillColor\": \"#fbbc04\",\n",
+    "        \"fillOpacity\": 0.3,\n",
+    "        \"strokeColor\": \"#f9ab00\",\n",
+    "        \"strokeWeight\": 2,\n",
+    "    },\n",
+    ").add_to(m)\n",
+    "\n",
+    "HeatMap(\n",
+    "    [\n",
+    "        [35.6812, 139.7671, 1.0],\n",
+    "        [35.6825, 139.7685, 0.95],\n",
+    "        [35.6840, 139.7700, 0.9],\n",
+    "        [35.6895, 139.6917, 0.85],\n",
+    "        [35.6920, 139.6940, 0.8],\n",
+    "        [35.6586, 139.7454, 0.8],\n",
+    "        [35.6600, 139.7480, 0.75],\n",
+    "        [35.7101, 139.8107, 0.85],\n",
+    "        [35.7085, 139.8088, 0.8],\n",
+    "    ],\n",
+    "    name=\"Heat\",\n",
+    "    max_zoom=14,\n",
+    ").add_to(m)\n",
+    "\n",
+    "LayerControl().add_to(m)\n",
+    "\n",
+    "m\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "py313",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

gmaprium-0.1.0/examples/example.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from gmaprium import Circle, GeoJson, HeatMap, LayerControl, Map, Marker, Polygon, Polyline
+
+
+api_key = os.environ.get("GOOGLE_MAPS_API_KEY", "YOUR_GOOGLE_MAPS_API_KEY")
+output_path = Path(__file__).with_name("example.html")
+
+m = Map(
+    location=[35.6812, 139.7671],
+    zoom_start=12,
+    api_key=api_key,
+    map_type="roadmap",
+    height="600px",
+)
+
+Marker(
+    [35.6812, 139.7671],
+    popup="Tokyo Station",
+    tooltip="Tokyo Station",
+    name="Markers",
+).add_to(m)
+
+Polyline(
+    [[35.6812, 139.7671], [35.6895, 139.6917]],
+    color="#0b57d0",
+    weight=4,
+    name="Route",
+).add_to(m)
+
+Polygon(
+    [[35.7000, 139.7000], [35.7000, 139.8200], [35.6200, 139.8200], [35.6200, 139.7000]],
+    color="#188038",
+    fill_color="#34a853",
+    fill_opacity=0.18,
+    name="Area",
+).add_to(m)
+
+Circle(
+    [35.6895, 139.6917],
+    radius=700,
+    color="#d93025",
+    fill_color="#f28b82",
+    fill_opacity=0.25,
+    name="Circle",
+).add_to(m)
+
+GeoJson(
+    {
+        "type": "FeatureCollection",
+        "features": [
+            {
+                "type": "Feature",
+                "properties": {"name": "Sample GeoJSON"},
+                "geometry": {
+                    "type": "Polygon",
+                    "coordinates": [
+                        [
+                            [139.735, 35.675],
+                            [139.755, 35.675],
+                            [139.755, 35.690],
+                            [139.735, 35.690],
+                            [139.735, 35.675],
+                        ]
+                    ],
+                },
+            }
+        ],
+    },
+    name="GeoJSON",
+    style_function=lambda feature: {
+        "fillColor": "#fbbc04",
+        "fillOpacity": 0.3,
+        "strokeColor": "#f9ab00",
+        "strokeWeight": 2,
+    },
+).add_to(m)
+
+HeatMap(
+    [
+        [35.6812, 139.7671, 1.0],
+        [35.6825, 139.7685, 0.95],
+        [35.6840, 139.7700, 0.9],
+        [35.6895, 139.6917, 0.85],
+        [35.6920, 139.6940, 0.8],
+        [35.6586, 139.7454, 0.8],
+        [35.6600, 139.7480, 0.75],
+        {"location": [35.7101, 139.8107], "weight": 0.85},
+        {"location": [35.7085, 139.8088], "weight": 0.8},
+    ],
+    name="Heat",
+    max_zoom=14,
+).add_to(m)
+
+LayerControl().add_to(m)
+
+m.save(output_path)
+print(f"Wrote {output_path}")