acadgis 0.1.0__tar.gz

acadgis-0.1.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to **AcadGIS** are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-06-18
+
+First public release.
+
+### Added
+- `load_boundaries(country, level, within=, download=)` — boundary loader with
+  bundled-sample → local-cache → live-GADM-download resolution and friendly
+  level names (`country`/`state`/`district`/`upazila`/…).
+- `plot()` — one-line styled qualitative/categorical maps with north arrow,
+  scale bar, lat/lon graticule, legend, labels and region highlighting.
+- `choropleth()` — data-driven choropleths with automatic fuzzy **name
+  matching** (handles renames, admin suffixes and diacritics) and optional
+  `mapclassify` classification schemes.
+- `StudyArea` — multi-panel **locator figures** (country → region → detail) with
+  connecting arrows; the signature AcadGIS layout.
+- `load_world()`, `highlight_country()` and `world_locator()` — world map with a
+  selected study country marked, plus a world → zoomed-country two-panel figure
+  (bundled Natural Earth 110m layer, fully offline).
+- Batteries-included re-exports: `agis.plt` / `agis.np` / `agis.pd` /
+  `agis.gpd` / `agis.show()` so one import is enough.
+- **Customizable decorations** ported from the web app:
+  - North arrows: `classic`, `minimal`, `pointer`, `rose` — now
+    **aspect-corrected** so shapes never stretch on tall/wide maps.
+  - Scale bars: `simple`, `bar`, `stepped`, with `units` km/mi.
+  - Borders: `solid`, `checker` (zebra), `none`.
+  - Each `north_arrow` / `scale_bar` / `border` argument accepts a bool, a
+    style string, or a dict of `style`/`size`/`color`/`loc` for full control.
+- 12 colour palettes and 6 themes (`academic`, `atlas`, `mono`, `nature`,
+  `ocean`, `viridis`).
+- `points()` — overlay point markers (capital cities, study sites, sampling
+  locations) from a DataFrame, dict, or list, with optional labels; supports
+  **graduated symbols** for collected data (`value=` colour-by-value with a
+  colorbar, `size_by=` proportional marker size).
+- Bundled offline sample data for Bangladesh (adm 0/1/2), Iraq (adm 0/1),
+  USA states (adm 1, incl. Alaska & Hawaii), and India (adm 0/1/2); world
+  countries + rivers/lakes (Natural Earth).
+- Country-name aliases (e.g. ``"USA"`` → United States).
+- `save()` helper for PNG / PDF / SVG export at any DPI.
+- Branding: full brand kit in `brand/` — the "study-area map" mark (Midnight +
+  Light), wordmark lockups, animated SVG header, 1280×640 social-preview card,
+  favicons + app icons (16–512), `favicon.ico`, and a PWA `site.webmanifest`;
+  plus a redesigned GitHub `README.md` and a PyPI-tuned `README_PyPI.md`.
+  Regenerate rasters with `python scripts/build_brand.py`.
+- Nine executed tutorial notebooks and a gallery script.
+- Test suite (15 offline tests) and GitHub Actions CI.
+
+- **Terrain** (`acadgis[terrain]`): `load_dem()` downloads & mosaics Copernicus
+  GLO-30 (30 m global, no API key) for a name/bbox/GeoDataFrame; `relief()`
+  renders hillshaded + hypsometric-tinted elevation maps; `hillshade()` helper.
+- **Drainage** (`acadgis[drainage]`): `drainage()` extracts stream networks from
+  a DEM via flow accumulation; `add_streams()` weights width by flow.
+- **Hydrology**: `load_rivers()` / `load_lakes()` (bundled Natural Earth 50 m,
+  optional 10 m download/cache), `add_rivers()` / `add_water()` overlays with
+  river-name labels, and `atlas()` — WorldAtlas-style cartography with greyed &
+  labelled neighbour countries, the river network with names, water bodies, and
+  optional `cities` point markers.
+- **Dense OpenStreetMap rivers**: `fetch_osm_rivers()` and `rivers="osm"`
+  (in `atlas`/`add_rivers`) pull the full river/canal/stream network from
+  Overpass (cached), styled with realistic blues and width-by-`kind`.
+- **Topography to the ocean**: `relief(..., ocean_color=, sea_level=)` renders
+  the sea in a realistic colour so terrain reads clearly down to the coast.
+
+### Roadmap
+- CSV point-layer overlay (study sites, sampling locations).
+- Hatch / pattern fills for black-and-white printing.
+- More bundled countries; projection options (Albers, Robinson).
+- Inset locator auto-placement in a figure corner.

acadgis-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

acadgis-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include NOTICE
+include README_PyPI.md
+include CHANGELOG.md
+recursive-include acadgis/data/samples *.geojson

acadgis-0.1.0/NOTICE

@@ -0,0 +1,13 @@
+AcadGIS
+Copyright 2026 AcadGIS contributors
+
+This product includes software developed at AcadGIS (https://acadgis.com).
+
+Administrative boundary sample data bundled under acadgis/data/samples/ is
+derived from the GADM database (https://gadm.org), version 4.1, and is used
+for academic / non-commercial purposes in accordance with the GADM license.
+When you download boundaries at runtime, data is retrieved from GADM via the
+`pygadm` package.
+
+This software is licensed under the Apache License, Version 2.0. See the
+LICENSE file for the full text.

acadgis-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: acadgis
+Version: 0.1.0
+Summary: Publication-ready academic GIS study-area maps in a few lines of Python.
+Author-email: Ripon Chandra Malo <riponce.buet@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://acadgis.com
+Project-URL: Repository, https://github.com/riponcm/AcadGIS
+Project-URL: Issues, https://github.com/riponcm/AcadGIS/issues
+Keywords: gis,geospatial,cartography,mapping,map,study-area-map,research-map,choropleth,choropleth-map,locator-map,thesis-map,publication,geopandas,matplotlib,administrative-boundaries,gadm,openstreetmap,terrain,hillshade,dem,rivers,spatial-analysis,qgis-alternative,academic,research
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: geopandas>=0.12
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.5
+Requires-Dist: shapely>=2.0
+Provides-Extra: full
+Requires-Dist: pygadm>=0.5; extra == "full"
+Requires-Dist: rapidfuzz>=3.0; extra == "full"
+Requires-Dist: mapclassify>=2.5; extra == "full"
+Requires-Dist: rasterio>=1.3; extra == "full"
+Requires-Dist: rioxarray>=0.13; extra == "full"
+Requires-Dist: pysheds>=0.3; extra == "full"
+Provides-Extra: download
+Requires-Dist: pygadm>=0.5; extra == "download"
+Provides-Extra: match
+Requires-Dist: rapidfuzz>=3.0; extra == "match"
+Provides-Extra: terrain
+Requires-Dist: rasterio>=1.3; extra == "terrain"
+Requires-Dist: rioxarray>=0.13; extra == "terrain"
+Provides-Extra: drainage
+Requires-Dist: pysheds>=0.3; extra == "drainage"
+Requires-Dist: rasterio>=1.3; extra == "drainage"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pygadm>=0.5; extra == "dev"
+Requires-Dist: rapidfuzz>=3.0; extra == "dev"
+Requires-Dist: mapclassify>=2.5; extra == "dev"
+Requires-Dist: rasterio>=1.3; extra == "dev"
+Requires-Dist: rioxarray>=0.13; extra == "dev"
+Requires-Dist: pysheds>=0.3; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/riponcm/AcadGIS/main/brand/logo.svg" alt="AcadGIS" width="120">
+</p>
+
+<h1 align="center">AcadGIS</h1>
+
+<p align="center"><b>Publication-ready study area maps for research — in a few lines of Python.</b></p>
+
+<p align="center">
+  <a href="https://pypi.org/project/acadgis/"><img src="https://img.shields.io/badge/version-0.1.0-2b6cb0.svg" alt="Version"></a>
+  <a href="https://pypi.org/project/acadgis/"><img src="https://img.shields.io/badge/python-3.9%2B-2d6a4f.svg" alt="Python"></a>
+  <a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/license-Apache--2.0-1b9aaa.svg" alt="License"></a>
+  <a href="https://doc.acadgis.com"><img src="https://img.shields.io/badge/docs-acadgis.com-ffb567.svg" alt="Docs"></a>
+</p>
+
+<p align="center">
+  <b><a href="https://acadgis.com">Website</a></b> &nbsp;&middot;&nbsp;
+  <b><a href="https://doc.acadgis.com">Documentation</a></b> &nbsp;&middot;&nbsp;
+  <b><a href="https://github.com/riponcm/AcadGIS">Source</a></b>
+</p>
+
+---
+
+AcadGIS is a Python package (and a no-code web app) for making publication-ready study area
+maps, choropleth maps, locator insets, terrain relief and river maps — for research papers,
+theses and reports. Name a place, add your data, and export a journal-ready figure in three
+lines: no QGIS, ArcGIS or shapefiles required.
+
+```python
+import acadgis as agis
+
+sa = agis.StudyArea("Iraq").zoom_into("Babil")
+sa.figure(suptitle="Study Area: Babil Governorate, Iraq")
+sa.save("study_area.png", dpi=300)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/riponcm/AcadGIS/main/examples/outputs/study_area_iraq.png" width="80%" alt="locator figure">
+</p>
+
+## Install
+
+```bash
+pip install acadgis                 # core (offline demo data + plotting)
+pip install "acadgis[full]"         # + live download, fuzzy matching, terrain, drainage
+```
+
+Optional extras: `acadgis[download]` (any-country boundaries via `pygadm`), `acadgis[match]`
+(fuzzy names), `acadgis[terrain]` (DEM relief), `acadgis[drainage]` (streams from a DEM).
+Bangladesh, Iraq, India and the USA ship bundled — everything works offline.
+
+## What it does
+
+- Boundaries on demand — country, state, district and sub-district, by name, from GADM.
+- One-line styled maps — 12 palettes, 6 themes, north arrows, scale bars, checker borders,
+  graticules and legends.
+- Choropleths and graduated symbols with automatic name matching (Chittagong matches
+  Chattogram, dropped admin-suffixes, diacritics) and `mapclassify` schemes.
+- Locator insets — the country to region to detail figure with connecting arrows.
+- Terrain — shaded relief and hypsometric tint from Copernicus GLO-30 (no API key), with
+  realistic land-to-ocean colouring.
+- Hydrology — Natural Earth or dense OpenStreetMap river networks and water bodies.
+- Drainage — stream networks extracted from a DEM.
+- Export — PNG, PDF or SVG at any DPI.
+
+## Quick start
+
+```python
+import acadgis as agis
+
+gdf = agis.load_boundaries("Bangladesh", level="district")     # auto-download + cache
+agis.plot(gdf, palette="spectral", title="Bangladesh — Districts")
+
+agis.choropleth(gdf, df, value="incidence", palette="magma")   # messy names welcome
+
+ax = agis.plot(gdf, highlight="Comilla")
+agis.points(ax, survey_df, value="value", size_by="value", cmap="magma", legend=True)
+
+dem = agis.load_dem("Bagrote Valley")
+agis.relief(dem, hillshade=True, ocean_color="#cce5f0")
+```
+
+## Links and attribution
+
+- Web app: https://acadgis.com
+- Documentation: https://doc.acadgis.com
+- Source: https://github.com/riponcm/AcadGIS
+- Data: GADM (boundaries), Copernicus GLO-30 (terrain), Natural Earth and OpenStreetMap
+  (hydrography). Free for academic and non-commercial use — please cite the sources.
+
+## License
+
+Apache License 2.0.

acadgis-0.1.0/README.md

@@ -0,0 +1,183 @@
+<div align="center">
+
+<img src="brand/header.svg" alt="AcadGIS — publication-ready academic GIS study-area maps" width="100%">
+
+<br><br>
+
+[![Version](https://img.shields.io/badge/version-0.1.0-2b6cb0.svg)](https://pypi.org/project/acadgis/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-2d6a4f.svg)](https://pypi.org/project/acadgis/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-1b9aaa.svg)](LICENSE)
+[![Built on](https://img.shields.io/badge/built%20on-geopandas%20%C2%B7%20matplotlib-3ad29f.svg)](https://geopandas.org)
+[![Docs](https://img.shields.io/badge/docs-acadgis.com-ffb567.svg)](https://doc.acadgis.com)
+
+<!-- After publishing to PyPI and making the repo public, swap to live badges:
+[![PyPI](https://img.shields.io/pypi/v/acadgis)](https://pypi.org/project/acadgis/)
+[![Downloads](https://img.shields.io/pypi/dm/acadgis)](https://pypi.org/project/acadgis/)
+[![Stars](https://img.shields.io/github/stars/riponcm/AcadGIS)](https://github.com/riponcm/AcadGIS/stargazers)
+-->
+
+### Publication-ready study area maps for research — in a few lines of Python
+
+**[Website](https://acadgis.com)** &nbsp;&middot;&nbsp; **[Documentation](https://doc.acadgis.com)** &nbsp;&middot;&nbsp; **[PyPI](https://pypi.org/project/acadgis/)** &nbsp;&middot;&nbsp; **[Changelog](CHANGELOG.md)** &nbsp;&middot;&nbsp; **[Quick start](#quick-start)**
+
+</div>
+
+---
+
+AcadGIS is a Python package (and a no-code web app) for making **publication-ready study area
+maps, choropleth maps, locator insets, terrain relief and river maps** — for research papers,
+theses and reports. Name a place, add your data, and export a journal-ready figure: no QGIS,
+ArcGIS or shapefiles required.
+
+```python
+import acadgis as agis
+
+sa = agis.StudyArea("Iraq").zoom_into("Babil")
+sa.figure(suptitle="Study Area: Babil Governorate, Iraq")
+sa.save("study_area.png", dpi=300)
+```
+
+Prefer no code? The companion web app at **[acadgis.com](https://acadgis.com)** offers the
+same figures with interactive editing — in the browser.
+
+---
+
+## Install
+
+```bash
+pip install acadgis                    # core (offline demo data + plotting)
+pip install "acadgis[full]"            # + live download, fuzzy matching, terrain, drainage
+```
+
+| Extra | Adds | For |
+|-------|------|-----|
+| `acadgis[download]` | `pygadm` | live boundary download for any country |
+| `acadgis[match]` | `rapidfuzz` | fuzzy name matching |
+| `acadgis[terrain]` | `rasterio`, `rioxarray` | DEM shaded relief / elevation maps |
+| `acadgis[drainage]` | `pysheds` | stream networks from a DEM |
+| `acadgis[full]` | everything above + `mapclassify` | the lot |
+
+Bangladesh, Iraq, India and the USA ship bundled, so you can try everything offline. One
+import gives you the whole stack: `agis.plt`, `agis.np`, `agis.pd`, `agis.gpd`.
+
+---
+
+## Gallery
+
+<table>
+<tr>
+<td width="33%"><img src="examples/outputs/study_area_iraq.png" alt="locator figure"><br><sub>Locator figure (country to region)</sub></td>
+<td width="33%"><img src="examples/outputs/india_wb_kolkata_survey.png" alt="collected data"><br><sub>Collected data &middot; graduated symbols</sub></td>
+<td width="33%"><img src="examples/outputs/choropleth_bd.png" alt="choropleth"><br><sub>Choropleth with name matching</sub></td>
+</tr>
+<tr>
+<td><img src="examples/outputs/terrain_relief.png" alt="terrain relief"><br><sub>DEM shaded relief</sub></td>
+<td><img src="examples/outputs/atlas_osm_rivers.png" alt="osm rivers"><br><sub>Dense OpenStreetMap rivers</sub></td>
+<td><img src="examples/outputs/coast_naples.png" alt="coast to ocean"><br><sub>Topography to the ocean</sub></td>
+</tr>
+<tr>
+<td><img src="examples/outputs/usa_states.png" alt="usa poster"><br><sub>Poster map with capitals and insets</sub></td>
+<td><img src="examples/outputs/atlas_bangladesh.png" alt="atlas style"><br><sub>Atlas-style cartography</sub></td>
+<td><img src="examples/outputs/themes_grid.png" alt="themes"><br><sub>Built-in themes</sub></td>
+</tr>
+</table>
+
+---
+
+## Quick start
+
+```python
+import acadgis as agis
+
+# 1. Boundaries by friendly level name (auto-download + cache)
+gdf = agis.load_boundaries("Bangladesh", level="district")
+dhaka = agis.load_boundaries("Bangladesh", "district", within="Dhaka")
+
+# 2. A styled map in one call
+agis.plot(gdf, palette="spectral", title="Bangladesh — Districts")
+
+# 3. Choropleth from a spreadsheet — messy names welcome (Chittagong matches Chattogram)
+agis.choropleth(gdf, df, value="incidence", palette="magma", scheme="natural_breaks")
+
+# 4. Collected data as graduated symbols, study city highlighted
+ax = agis.plot(gdf, highlight="Comilla")
+agis.points(ax, survey_df, value="value", size_by="value", cmap="magma", legend=True)
+
+# 5. Terrain relief down to a realistic sea
+dem = agis.load_dem("Bagrote Valley")
+agis.relief(dem, hillshade=True, ocean_color="#cce5f0")
+
+# 6. The signature multi-panel locator
+agis.StudyArea("India", context_level="state").zoom_into(
+    "West Bengal", detail_level="district").figure()
+```
+
+Every decoration is customizable — pass `True`/`False`, a style name, or a dict:
+
+```python
+agis.plot(gdf,
+    north_arrow={"style": "rose", "size": 0.13, "loc": (0.9, 0.85)},
+    scale_bar={"style": "stepped", "length_km": 100},
+    border={"style": "checker"})
+```
+
+---
+
+## What it does
+
+- **Boundaries on demand** — country, state, district and sub-district, by name, from
+  [GADM](https://gadm.org); cached after first use.
+- **One-line styled maps** — 12 palettes, 6 themes, north arrows (4 styles), scale bars
+  (3 styles), checker border, graticule and legend.
+- **Choropleths and graduated symbols** with automatic name matching (renames,
+  admin-suffixes, diacritics) and `mapclassify` schemes.
+- **Locator insets** — the country to region to detail figure with connecting arrows.
+- **Terrain** — shaded relief and hypsometric tint from Copernicus GLO-30 (no API key),
+  with realistic land-to-ocean colouring.
+- **Hydrology** — Natural Earth or dense OpenStreetMap river networks and water bodies.
+- **Drainage** — stream networks extracted from a DEM by flow accumulation.
+- **Publication export** — PNG, PDF or SVG at any DPI.
+
+---
+
+## Documentation and tutorials
+
+Full documentation and runnable, step-by-step tutorials live at
+**[doc.acadgis.com](https://doc.acadgis.com)**:
+
+- Quick start — load, plot, themes
+- Choropleths and name matching
+- Study-area locator figures
+- World maps and country highlighting
+- Customizing decorations (arrows, scale bars, borders)
+- Terrain, hydrology and drainage
+- Collected-data maps with graduated symbols
+
+---
+
+## Data and attribution
+
+Administrative boundaries: [GADM](https://gadm.org) 4.1 (via
+[`pygadm`](https://pypi.org/project/pygadm/)). Terrain: Copernicus GLO-30 (AWS Open Data).
+Rivers, water and world layers: Natural Earth and OpenStreetMap (© OpenStreetMap
+contributors, ODbL). All free for academic and non-commercial use — please cite the sources
+in your work. See [`NOTICE`](NOTICE).
+
+## Citation
+
+```bibtex
+@software{acadgis,
+  title  = {AcadGIS: publication-ready academic GIS study-area maps},
+  author = {Ripon Chandra Malo},
+  year   = {2026},
+  url    = {https://github.com/riponcm/AcadGIS},
+  note   = {Web app: https://acadgis.com}
+}
+```
+
+## License
+
+[Apache License 2.0](LICENSE) — free to use, modify and distribute, including in academic
+work. If AcadGIS helps your research, a citation or a star is appreciated.
+
+<div align="center"><sub>Built on geopandas, matplotlib and shapely — for researchers, by a researcher.</sub></div>