mapelements 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. mapelements-0.1.0/CHANGELOG.md +38 -0
  2. mapelements-0.1.0/LICENSE +21 -0
  3. mapelements-0.1.0/MANIFEST.in +16 -0
  4. mapelements-0.1.0/PKG-INFO +198 -0
  5. mapelements-0.1.0/README.md +150 -0
  6. mapelements-0.1.0/docs/assets/cookbook-cartopy.png +0 -0
  7. mapelements-0.1.0/docs/assets/elements-graticule.png +0 -0
  8. mapelements-0.1.0/docs/assets/elements-northarrow.png +0 -0
  9. mapelements-0.1.0/docs/assets/elements-scalebar.png +0 -0
  10. mapelements-0.1.0/docs/assets/example-map.png +0 -0
  11. mapelements-0.1.0/docs/assets/layout-panels.png +0 -0
  12. mapelements-0.1.0/docs/en/api.md +157 -0
  13. mapelements-0.1.0/docs/en/cookbook.md +130 -0
  14. mapelements-0.1.0/docs/en/elements.md +175 -0
  15. mapelements-0.1.0/docs/en/export.md +123 -0
  16. mapelements-0.1.0/docs/en/faq.md +112 -0
  17. mapelements-0.1.0/docs/en/index.md +73 -0
  18. mapelements-0.1.0/docs/en/installation.md +73 -0
  19. mapelements-0.1.0/docs/en/layout.md +101 -0
  20. mapelements-0.1.0/docs/en/projections.md +108 -0
  21. mapelements-0.1.0/docs/en/quickstart.md +119 -0
  22. mapelements-0.1.0/docs/index.md +44 -0
  23. mapelements-0.1.0/docs/landing.html +57 -0
  24. mapelements-0.1.0/docs/make_figures.py +159 -0
  25. mapelements-0.1.0/docs/zh/api.md +151 -0
  26. mapelements-0.1.0/docs/zh/cookbook.md +127 -0
  27. mapelements-0.1.0/docs/zh/elements.md +164 -0
  28. mapelements-0.1.0/docs/zh/export.md +117 -0
  29. mapelements-0.1.0/docs/zh/faq.md +102 -0
  30. mapelements-0.1.0/docs/zh/index.md +69 -0
  31. mapelements-0.1.0/docs/zh/installation.md +67 -0
  32. mapelements-0.1.0/docs/zh/layout.md +91 -0
  33. mapelements-0.1.0/docs/zh/projections.md +98 -0
  34. mapelements-0.1.0/docs/zh/quickstart.md +113 -0
  35. mapelements-0.1.0/examples/artists_api.py +59 -0
  36. mapelements-0.1.0/examples/demo_map.py +57 -0
  37. mapelements-0.1.0/mkdocs.en.yml +33 -0
  38. mapelements-0.1.0/mkdocs.zh.yml +33 -0
  39. mapelements-0.1.0/pyproject.toml +88 -0
  40. mapelements-0.1.0/setup.cfg +4 -0
  41. mapelements-0.1.0/src/mapelements/__init__.py +50 -0
  42. mapelements-0.1.0/src/mapelements/api.py +114 -0
  43. mapelements-0.1.0/src/mapelements/artists.py +335 -0
  44. mapelements-0.1.0/src/mapelements/export.py +153 -0
  45. mapelements-0.1.0/src/mapelements/geom.py +101 -0
  46. mapelements-0.1.0/src/mapelements/py.typed +0 -0
  47. mapelements-0.1.0/src/mapelements/style.py +71 -0
  48. mapelements-0.1.0/src/mapelements.egg-info/SOURCES.txt +50 -0
  49. mapelements-0.1.0/tests/conftest.py +25 -0
  50. mapelements-0.1.0/tests/test_artists.py +113 -0
  51. mapelements-0.1.0/tests/test_finish.py +46 -0
  52. mapelements-0.1.0/tests/test_geom.py +25 -0
  53. mapelements-0.1.0/tests/test_save.py +28 -0
@@ -0,0 +1,38 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
+ and this project adheres to [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.1.0] - 2026-11-21
8
+
9
+ ### Added
10
+
11
+ - `ScaleBar`, `NorthArrow`, `Graticule` as `matplotlib.artist.Artist` subclasses:
12
+ they can be added with `ax.add_artist()`, removed, re-used via `.copy()`, and
13
+ are rebuilt at draw time so they follow changes to limits and figure size.
14
+ - `scale_bar()`, `north_arrow()`, `graticule()` function wrappers.
15
+ - `finish()` one-call helper (extent + graticule + scale bar + north arrow).
16
+ - `fit()` to remove subplot margins on single-panel map figures.
17
+ - `pub_style()` with journal defaults (`pdf.fonttype=42`, `svg.fonttype="none"`,
18
+ 7–8 pt type) and `figure()` sized in millimetres.
19
+ - `save()` with vector self-checks (`NotVectorError` on failure) and
20
+ `check_vector()` for arbitrary PDF/SVG files.
21
+ - `CN_ALBERS` constant (Albers Equal Area, standard parallels 25°N/47°N).
22
+ - Scale bars are computed from a geodesic east–west chord at the bar's own
23
+ latitude, so projection scale factors are accounted for automatically.
24
+ - North arrows are rotated by the projection's meridian convergence.
25
+ - Bilingual documentation under `docs/en/` and `docs/zh/` (installation,
26
+ quickstart, map elements, projections, layout, export, API, cookbook, FAQ),
27
+ with `mkdocs.en.yml` / `mkdocs.zh.yml` site configs and `check_docs.py`
28
+ for link/anchor checking.
29
+ - Static documentation site (English at `/en/`, Chinese at `/zh/`, bilingual
30
+ landing page) published to GitHub Pages by `.github/workflows/docs.yml`.
31
+ - `docs/make_figures.py`, which renders the six figures embedded in the manual.
32
+
33
+ ### Fixed
34
+
35
+ - `ScaleBar.get_window_extent()` raised `AttributeError` when the figure used
36
+ `constrained_layout` (the child artists had no figure attached yet).
37
+
38
+ [0.1.0]: https://github.com/zhangbo/mapelements/releases/tag/v0.1.0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The mapelements authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,16 @@
1
+ include LICENSE
2
+ include README.md
3
+ include CHANGELOG.md
4
+ include pyproject.toml
5
+ include mkdocs.en.yml
6
+ include mkdocs.zh.yml
7
+
8
+ recursive-include src/mapelements *.py py.typed
9
+ recursive-include tests *.py
10
+ recursive-include examples *.py
11
+ recursive-include docs *.md *.png *.py
12
+
13
+ recursive-exclude * __pycache__
14
+ recursive-exclude * *.py[co]
15
+ prune src/mapelements.egg-info
16
+ include docs/landing.html
@@ -0,0 +1,198 @@
1
+ Metadata-Version: 2.4
2
+ Name: mapelements
3
+ Version: 0.1.0
4
+ Summary: Journal-quality vector map elements for matplotlib: scale bars, north arrows and graticules that stay editable in PDF/SVG.
5
+ Author: zhangbo
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/zhangbo/mapelements
8
+ Project-URL: Repository, https://github.com/zhangbo/mapelements
9
+ Project-URL: Issues, https://github.com/zhangbo/mapelements/issues
10
+ Project-URL: Documentation, https://github.com/zhangbo/mapelements/tree/main/docs
11
+ Project-URL: Changelog, https://github.com/zhangbo/mapelements/blob/main/CHANGELOG.md
12
+ Keywords: matplotlib,cartopy,geopandas,cartography,scale-bar,north-arrow,graticule,vector-graphics,publication
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Scientific/Engineering :: GIS
25
+ Classifier: Topic :: Scientific/Engineering :: Visualization
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.9
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+ Requires-Dist: matplotlib>=3.6
31
+ Requires-Dist: numpy>=1.22
32
+ Requires-Dist: pyproj>=3.4
33
+ Provides-Extra: geo
34
+ Requires-Dist: geopandas>=0.13; extra == "geo"
35
+ Provides-Extra: cartopy
36
+ Requires-Dist: cartopy>=0.22; extra == "cartopy"
37
+ Provides-Extra: test
38
+ Requires-Dist: pytest>=7; extra == "test"
39
+ Provides-Extra: dev
40
+ Requires-Dist: geopandas>=0.13; extra == "dev"
41
+ Requires-Dist: cartopy>=0.22; extra == "dev"
42
+ Requires-Dist: pytest>=7; extra == "dev"
43
+ Requires-Dist: build>=1.0; extra == "dev"
44
+ Requires-Dist: twine>=5.0; extra == "dev"
45
+ Provides-Extra: docs
46
+ Requires-Dist: mkdocs>=1.5; extra == "docs"
47
+ Dynamic: license-file
48
+
49
+ # mapelements
50
+
51
+ [![PyPI](https://img.shields.io/pypi/v/mapelements.svg)](https://pypi.org/project/mapelements/)
52
+ [![Python](https://img.shields.io/pypi/pyversions/mapelements.svg)](https://pypi.org/project/mapelements/)
53
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
54
+ [![CI](https://github.com/zhangbo/mapelements/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangbo/mapelements/actions/workflows/ci.yml)
55
+
56
+ **矢量**地图要素,专为期刊插图:比例尺、指北针、经纬网。
57
+
58
+ 全部用 matplotlib 的 `Patch` / `Line2D` / `Text` 绘制,不产生任何位图。
59
+ 导出 PDF/SVG 后线条仍是路径、文字仍是文字,在 Illustrator 里可以直接改。
60
+ 配合 `pdf.fonttype = 42`(`pub_style()` 会自动设置),满足"图中文字可修改"
61
+ 的投稿要求。
62
+
63
+ ## 文档
64
+
65
+ | 语言 | 内容 |
66
+ |---|---|
67
+ | [English](docs/en/index.md) | installation, quickstart, elements, projections, layout, export, API, cookbook, FAQ |
68
+ | [中文](docs/zh/index.md) | 安装、快速开始、地图要素、投影、版式、投稿导出、API、实用配方、常见问题 |
69
+
70
+ 本地预览:
71
+
72
+ ```bash
73
+ pip install -e ".[docs]"
74
+ mkdocs serve -f mkdocs.en.yml # http://127.0.0.1:8000
75
+ mkdocs serve -f mkdocs.zh.yml
76
+ ```
77
+
78
+ 在线站点(推送 `main` 后由 `.github/workflows/docs.yml` 自动发布):
79
+ <https://zhangbo.github.io/mapelements/>
80
+
81
+ 文档自检(链接、锚点、图片、代码块语法):
82
+
83
+ ```bash
84
+ python check_docs.py
85
+ ```
86
+
87
+ 文档里的插图由 [`docs/make_figures.py`](docs/make_figures.py) 生成:
88
+
89
+ ```bash
90
+ python docs/make_figures.py
91
+ ```
92
+
93
+ ## 安装
94
+
95
+ ```bash
96
+ pip install mapelements
97
+
98
+ # 需要 geopandas / cartopy 时
99
+ pip install "mapelements[geo,cartopy]"
100
+ ```
101
+
102
+ ## 快速开始
103
+
104
+ ```python
105
+ import matplotlib.pyplot as plt
106
+ import mapelements
107
+
108
+ mapelements.pub_style() # 刊物版式:Type42、7-8 pt
109
+ fig, ax = mapelements.figure("double", 110) # 170 mm 宽
110
+
111
+ gdf.to_crs(mapelements.CN_ALBERS).plot(ax=ax, column="value", cmap="YlGnBu")
112
+
113
+ mapelements.finish(ax, crs=mapelements.CN_ALBERS, data=gdf)
114
+ mapelements.save(fig, "Fig1") # figs/Fig1.pdf + .svg + .png
115
+ ```
116
+
117
+ ## 三种用法
118
+
119
+ **Artist 方式**(和 matplotlib 原生写法一致,可 `remove()`、可 `copy()`)
120
+
121
+ ```python
122
+ from mapelements import ScaleBar, NorthArrow, Graticule
123
+
124
+ ax.add_artist(Graticule(crs=CRS, extent=(94, 121, 26, 43), step=5))
125
+ ax.add_artist(ScaleBar(length=500, crs=CRS, loc=(0.05, 0.06)))
126
+ ax.add_artist(NorthArrow(crs=CRS, loc="upper right"))
127
+ ```
128
+
129
+ **函数方式**
130
+
131
+ ```python
132
+ mapelements.scale_bar(ax, length=500, crs=CRS)
133
+ mapelements.north_arrow(ax, crs=CRS)
134
+ ```
135
+
136
+ **一站式**
137
+
138
+ ```python
139
+ mapelements.finish(ax, crs=CRS, data=gdf, scalebar="auto", north="upper right")
140
+ ```
141
+
142
+ ## 多子图复用
143
+
144
+ ```python
145
+ sb = ScaleBar(length=500, crs=CRS)
146
+ nw = NorthArrow(crs=CRS)
147
+ for ax in axs.flat:
148
+ ax.add_artist(sb.copy()) # 每个 Axes 需要一份副本
149
+ ax.add_artist(nw.copy())
150
+ ```
151
+
152
+ ## 为什么不用现成的包
153
+
154
+ | | `matplotlib_scalebar` | `matplotlib_map_utils` | **mapelements** |
155
+ |---|---|---|---|
156
+ | 矢量 | 是 | **否**(整条渲染成位图) | 是 |
157
+ | 文字可编辑 | 是 | 否 | 是 |
158
+ | 黑白分段 | 否 | 是 | 是 |
159
+ | 指北针 / 经纬网 | 否 | 是 / 否 | 是 |
160
+ | 依赖 | 额外一个包 | 额外一个包 + 临时 figure 渲染 | 只要 matplotlib + pyproj |
161
+
162
+ ## API
163
+
164
+ | 对象 | 说明 |
165
+ |---|---|
166
+ | `ScaleBar(length="auto", crs=None, loc=(0.05, 0.06), divisions=4, colors=("black", "white"), height_frac=0.010, fontsize=7, unit_label="km", show_mid=False, ref_lon=None, ref_lat=None)` | 黑白分段比例尺;`"auto"` 按图幅取 1/2/5×10ⁿ |
167
+ | `NorthArrow(crs=None, loc="upper right", length_pts=14, label="N", weight="normal")` | 真北指北针(按经线收敛定向) |
168
+ | `Graticule(crs=None, extent=(lon0, lon1, lat0, lat1), step=5, color="0.55", lw=0.35, ls=":")` | 经纬网 |
169
+ | `scale_bar(ax, **kw)` / `north_arrow(ax, **kw)` / `graticule(ax, **kw)` | 构造并添加,返回 artist |
170
+ | `finish(ax, crs, data=None, extent=None, graticule=5, scalebar="auto", north="upper right", fill=True, legend=False)` | 一站式收尾 |
171
+ | `fit(ax)` | 单幅地图铺满画布(多子图自动跳过) |
172
+ | `save(fig, "Fig1", outdir="figs", formats=("pdf", "svg", "png"))` | 导出并自检,不通过抛 `NotVectorError` |
173
+ | `check_vector(path)` | 检查已有 PDF/SVG 是否可编辑矢量 |
174
+ | `pub_style(extra=None)` / `figure(width, height_mm)` | 刊物版式 / 按 mm 建图 |
175
+
176
+ 常量:`CN_ALBERS`(Albers 25/47,中央经线 105°E)、`MM`、`SINGLE_COLUMN`、`DOUBLE_COLUMN`。
177
+
178
+ ## 设计要点
179
+
180
+ - **绘制时才计算几何**:`draw()` 中按当前 `xlim`、轴尺寸构建子图元,改了范围或
181
+ 画布大小后自动重排,不需要重新添加;先 `add_artist` 再 `set_xlim` 也可以。
182
+ - **比例尺精度**:按参考纬度处正东方向的测地线长度换算,自动吸收投影尺度因子。
183
+ - **指北针精度**:按投影的经线收敛角旋转,锥形投影边缘不会指偏。
184
+ - **cartopy 兼容**:`crs=ax.projection` 即可(内部取 `proj4_init` 交给 pyproj)。
185
+ - **不栅格化**:没有 `OffsetImage`、没有临时 figure 渲染。
186
+
187
+ ## 开发
188
+
189
+ ```bash
190
+ git clone https://github.com/zhangbo/mapelements
191
+ cd mapelements
192
+ pip install -e ".[dev]"
193
+ pytest
194
+ ```
195
+
196
+ ## 许可证
197
+
198
+ MIT,见 [LICENSE](LICENSE)。
@@ -0,0 +1,150 @@
1
+ # mapelements
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/mapelements.svg)](https://pypi.org/project/mapelements/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/mapelements.svg)](https://pypi.org/project/mapelements/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6
+ [![CI](https://github.com/zhangbo/mapelements/actions/workflows/ci.yml/badge.svg)](https://github.com/zhangbo/mapelements/actions/workflows/ci.yml)
7
+
8
+ **矢量**地图要素,专为期刊插图:比例尺、指北针、经纬网。
9
+
10
+ 全部用 matplotlib 的 `Patch` / `Line2D` / `Text` 绘制,不产生任何位图。
11
+ 导出 PDF/SVG 后线条仍是路径、文字仍是文字,在 Illustrator 里可以直接改。
12
+ 配合 `pdf.fonttype = 42`(`pub_style()` 会自动设置),满足"图中文字可修改"
13
+ 的投稿要求。
14
+
15
+ ## 文档
16
+
17
+ | 语言 | 内容 |
18
+ |---|---|
19
+ | [English](docs/en/index.md) | installation, quickstart, elements, projections, layout, export, API, cookbook, FAQ |
20
+ | [中文](docs/zh/index.md) | 安装、快速开始、地图要素、投影、版式、投稿导出、API、实用配方、常见问题 |
21
+
22
+ 本地预览:
23
+
24
+ ```bash
25
+ pip install -e ".[docs]"
26
+ mkdocs serve -f mkdocs.en.yml # http://127.0.0.1:8000
27
+ mkdocs serve -f mkdocs.zh.yml
28
+ ```
29
+
30
+ 在线站点(推送 `main` 后由 `.github/workflows/docs.yml` 自动发布):
31
+ <https://zhangbo.github.io/mapelements/>
32
+
33
+ 文档自检(链接、锚点、图片、代码块语法):
34
+
35
+ ```bash
36
+ python check_docs.py
37
+ ```
38
+
39
+ 文档里的插图由 [`docs/make_figures.py`](docs/make_figures.py) 生成:
40
+
41
+ ```bash
42
+ python docs/make_figures.py
43
+ ```
44
+
45
+ ## 安装
46
+
47
+ ```bash
48
+ pip install mapelements
49
+
50
+ # 需要 geopandas / cartopy 时
51
+ pip install "mapelements[geo,cartopy]"
52
+ ```
53
+
54
+ ## 快速开始
55
+
56
+ ```python
57
+ import matplotlib.pyplot as plt
58
+ import mapelements
59
+
60
+ mapelements.pub_style() # 刊物版式:Type42、7-8 pt
61
+ fig, ax = mapelements.figure("double", 110) # 170 mm 宽
62
+
63
+ gdf.to_crs(mapelements.CN_ALBERS).plot(ax=ax, column="value", cmap="YlGnBu")
64
+
65
+ mapelements.finish(ax, crs=mapelements.CN_ALBERS, data=gdf)
66
+ mapelements.save(fig, "Fig1") # figs/Fig1.pdf + .svg + .png
67
+ ```
68
+
69
+ ## 三种用法
70
+
71
+ **Artist 方式**(和 matplotlib 原生写法一致,可 `remove()`、可 `copy()`)
72
+
73
+ ```python
74
+ from mapelements import ScaleBar, NorthArrow, Graticule
75
+
76
+ ax.add_artist(Graticule(crs=CRS, extent=(94, 121, 26, 43), step=5))
77
+ ax.add_artist(ScaleBar(length=500, crs=CRS, loc=(0.05, 0.06)))
78
+ ax.add_artist(NorthArrow(crs=CRS, loc="upper right"))
79
+ ```
80
+
81
+ **函数方式**
82
+
83
+ ```python
84
+ mapelements.scale_bar(ax, length=500, crs=CRS)
85
+ mapelements.north_arrow(ax, crs=CRS)
86
+ ```
87
+
88
+ **一站式**
89
+
90
+ ```python
91
+ mapelements.finish(ax, crs=CRS, data=gdf, scalebar="auto", north="upper right")
92
+ ```
93
+
94
+ ## 多子图复用
95
+
96
+ ```python
97
+ sb = ScaleBar(length=500, crs=CRS)
98
+ nw = NorthArrow(crs=CRS)
99
+ for ax in axs.flat:
100
+ ax.add_artist(sb.copy()) # 每个 Axes 需要一份副本
101
+ ax.add_artist(nw.copy())
102
+ ```
103
+
104
+ ## 为什么不用现成的包
105
+
106
+ | | `matplotlib_scalebar` | `matplotlib_map_utils` | **mapelements** |
107
+ |---|---|---|---|
108
+ | 矢量 | 是 | **否**(整条渲染成位图) | 是 |
109
+ | 文字可编辑 | 是 | 否 | 是 |
110
+ | 黑白分段 | 否 | 是 | 是 |
111
+ | 指北针 / 经纬网 | 否 | 是 / 否 | 是 |
112
+ | 依赖 | 额外一个包 | 额外一个包 + 临时 figure 渲染 | 只要 matplotlib + pyproj |
113
+
114
+ ## API
115
+
116
+ | 对象 | 说明 |
117
+ |---|---|
118
+ | `ScaleBar(length="auto", crs=None, loc=(0.05, 0.06), divisions=4, colors=("black", "white"), height_frac=0.010, fontsize=7, unit_label="km", show_mid=False, ref_lon=None, ref_lat=None)` | 黑白分段比例尺;`"auto"` 按图幅取 1/2/5×10ⁿ |
119
+ | `NorthArrow(crs=None, loc="upper right", length_pts=14, label="N", weight="normal")` | 真北指北针(按经线收敛定向) |
120
+ | `Graticule(crs=None, extent=(lon0, lon1, lat0, lat1), step=5, color="0.55", lw=0.35, ls=":")` | 经纬网 |
121
+ | `scale_bar(ax, **kw)` / `north_arrow(ax, **kw)` / `graticule(ax, **kw)` | 构造并添加,返回 artist |
122
+ | `finish(ax, crs, data=None, extent=None, graticule=5, scalebar="auto", north="upper right", fill=True, legend=False)` | 一站式收尾 |
123
+ | `fit(ax)` | 单幅地图铺满画布(多子图自动跳过) |
124
+ | `save(fig, "Fig1", outdir="figs", formats=("pdf", "svg", "png"))` | 导出并自检,不通过抛 `NotVectorError` |
125
+ | `check_vector(path)` | 检查已有 PDF/SVG 是否可编辑矢量 |
126
+ | `pub_style(extra=None)` / `figure(width, height_mm)` | 刊物版式 / 按 mm 建图 |
127
+
128
+ 常量:`CN_ALBERS`(Albers 25/47,中央经线 105°E)、`MM`、`SINGLE_COLUMN`、`DOUBLE_COLUMN`。
129
+
130
+ ## 设计要点
131
+
132
+ - **绘制时才计算几何**:`draw()` 中按当前 `xlim`、轴尺寸构建子图元,改了范围或
133
+ 画布大小后自动重排,不需要重新添加;先 `add_artist` 再 `set_xlim` 也可以。
134
+ - **比例尺精度**:按参考纬度处正东方向的测地线长度换算,自动吸收投影尺度因子。
135
+ - **指北针精度**:按投影的经线收敛角旋转,锥形投影边缘不会指偏。
136
+ - **cartopy 兼容**:`crs=ax.projection` 即可(内部取 `proj4_init` 交给 pyproj)。
137
+ - **不栅格化**:没有 `OffsetImage`、没有临时 figure 渲染。
138
+
139
+ ## 开发
140
+
141
+ ```bash
142
+ git clone https://github.com/zhangbo/mapelements
143
+ cd mapelements
144
+ pip install -e ".[dev]"
145
+ pytest
146
+ ```
147
+
148
+ ## 许可证
149
+
150
+ MIT,见 [LICENSE](LICENSE)。
@@ -0,0 +1,157 @@
1
+ # API reference
2
+
3
+ ```python
4
+ import mapelements
5
+ ```
6
+
7
+ ## Artists
8
+
9
+ ### `ScaleBar`
10
+
11
+ ```python
12
+ ScaleBar(
13
+ length="auto", crs=None, loc=(0.05, 0.06),
14
+ height_frac=0.010, divisions=4, colors=("black", "white"),
15
+ lw=0.5, fontsize=7, unit_label="km", show_mid=False,
16
+ ref_lon=None, ref_lat=None, zorder=30,
17
+ )
18
+ ```
19
+
20
+ | Parameter | Type | Description |
21
+ |---|---|---|
22
+ | `length` | `float \| "auto"` | bar length in km; `"auto"` = 18 % of the map width snapped to 1/2/5 × 10ⁿ |
23
+ | `crs` | PROJ string, EPSG, `pyproj.CRS`, cartopy CRS | projection of the axes; defaults to `ax.projection` |
24
+ | `loc` | `(fx, fy)` | lower-left corner in axes fraction |
25
+ | `height_frac` | `float` | bar height as a fraction of the axes height |
26
+ | `divisions` | `int` | number of blocks |
27
+ | `colors` | sequence | cycled over the blocks, e.g. `("black", "white")` |
28
+ | `lw` | `float` | outline width in points |
29
+ | `fontsize` | `float` | label size in points |
30
+ | `unit_label` | `str` | appended to the last label; `""` to omit |
31
+ | `show_mid` | `bool` | also label the midpoint (even `divisions` only) |
32
+ | `ref_lon`, `ref_lat` | `float \| None` | latitude at which the geodesic is evaluated; defaults to the bar position |
33
+ | `zorder` | `float` | drawing order |
34
+
35
+ Attributes: `.length`, `.loc`, `.divisions`, `.height_frac`, `.colors`,
36
+ `.fontsize`, `.unit_label`, `.show_mid`, `.crs` are read/write properties.
37
+ `.resolved_length` holds the numeric length after the first draw (`None` before).
38
+
39
+ ### `NorthArrow`
40
+
41
+ ```python
42
+ NorthArrow(
43
+ crs=None, loc="upper right", length_pts=14, lw=0.6,
44
+ fontsize=8, label="N", weight="normal", lon=None, lat=None, zorder=30,
45
+ )
46
+ ```
47
+
48
+ | Parameter | Type | Description |
49
+ |---|---|---|
50
+ | `crs` | CRS | defaults to `ax.projection` |
51
+ | `loc` | `str \| (fx, fy)` | `"upper right"`, `"upper left"`, `"lower right"`, `"lower left"` |
52
+ | `length_pts` | `float` | arrow length in points |
53
+ | `lw` | `float` | outline width |
54
+ | `fontsize` | `float` | label size |
55
+ | `label` | `str` | usually `"N"` |
56
+ | `weight` | `str` | `"normal"` or `"bold"` |
57
+ | `lon`, `lat` | `float \| None` | point where true north is evaluated |
58
+
59
+ The arrow direction is the projection's meridian convergence, computed from a
60
+ 1 km geodesic step due north.
61
+
62
+ ### `Graticule`
63
+
64
+ ```python
65
+ Graticule(
66
+ crs=None, extent=None, step=5.0, color="0.55",
67
+ lw=0.35, ls=":", npts=120, zorder=1,
68
+ )
69
+ ```
70
+
71
+ | Parameter | Type | Description |
72
+ |---|---|---|
73
+ | `extent` | `(lon0, lon1, lat0, lat1)` | required; which meridians/parallels to draw |
74
+ | `step` | `float` | spacing in degrees |
75
+ | `color`, `lw`, `ls` | | line style |
76
+ | `npts` | `int` | samples per line; raise for very wide maps |
77
+ | `zorder` | `float` | keep below the data |
78
+
79
+ ## Functions
80
+
81
+ ### `scale_bar(ax, **kwargs)` · `north_arrow(ax, **kwargs)` · `graticule(ax, **kwargs)`
82
+
83
+ Construct the corresponding artist, add it to `ax`, and return it.
84
+
85
+ ```python
86
+ sb = mapelements.scale_bar(ax, length=500, crs=CRS)
87
+ sb.fontsize = 8 # the artist is returned, so you can tweak it
88
+ ```
89
+
90
+ ### `finish(ax, crs=None, data=None, extent=None, graticule=5.0, scalebar="auto", north="upper right", scalebar_loc=None, pad=0.02, legend=False, fill=True, zorder=30)`
91
+
92
+ One-call map furniture.
93
+
94
+ | Parameter | Description |
95
+ |---|---|
96
+ | `crs` | projection; defaults to `ax.projection` |
97
+ | `data` | `GeoDataFrame`; extent taken from `total_bounds` after `to_crs(crs)` |
98
+ | `extent` | lon/lat box; overrides `data` |
99
+ | `graticule` | spacing in degrees; `None`/`False` disables |
100
+ | `scalebar` | km, `"auto"`, or `None`/`False` |
101
+ | `north` | alias, tuple, or `None`/`False` |
102
+ | `scalebar_loc` | axes fraction; defaults to the corner opposite the north arrow |
103
+ | `pad` | fractional padding around the extent (default 2 %) |
104
+ | `legend` | `True` to place a borderless legend upper-left |
105
+ | `fill` | `True` to call `fit()` (single-axes figures only) |
106
+
107
+ Returns `ax`.
108
+
109
+ ### `fit(ax)`
110
+
111
+ Set the axes to `[0, 0, 1, 1]` and adjust the figure height to the data aspect
112
+ ratio. No-op when the figure has more than one axes. Returns `ax`.
113
+
114
+ ### `save(fig, stem, outdir="figs", formats=("pdf", "svg", "png"), dpi=600, allow_images=False, expect_text=None, strict=True)`
115
+
116
+ Write the figure and run `check_vector()` on the PDF/SVG. Returns
117
+ `{format: Path}`. Raises `NotVectorError` when `strict=True` and the check
118
+ fails.
119
+
120
+ ### `check_vector(path, expect_text=None, allow_images=False) -> bool`
121
+
122
+ Inspect a PDF or SVG and print a report. Returns `True` when the file is
123
+ editable vector artwork.
124
+
125
+ ### `pub_style(extra=None)`
126
+
127
+ Apply the journal defaults (`pdf.fonttype=42`, `svg.fonttype="none"`, 8 pt base
128
+ size, 0.8 pt axes). `extra` is merged into the defaults.
129
+
130
+ ### `figure(width="double", height=90, **kwargs)`
131
+
132
+ Create `(fig, ax)` with a millimetre size. `width` accepts `"single"` (85 mm),
133
+ `"double"` (170 mm) or a number.
134
+
135
+ ## Constants
136
+
137
+ | Name | Value |
138
+ |---|---|
139
+ | `CN_ALBERS` | Albers Equal Area, standard parallels 25°N/47°N, central meridian 105°E |
140
+ | `SINGLE_COLUMN` | `85.0` (mm) |
141
+ | `DOUBLE_COLUMN` | `170.0` (mm) |
142
+ | `MM` | `1 / 25.4` |
143
+
144
+ ## Utilities
145
+
146
+ ### `nice_length(km) -> float`
147
+
148
+ Round up to the next 1/2/5 × 10ⁿ value: `473 → 500`, `2.2 → 5`.
149
+
150
+ ### `map_width_km(ax, crs) -> float`
151
+
152
+ Geodesic width of the current axis at its central latitude, in km.
153
+
154
+ ## Exceptions
155
+
156
+ `NotVectorError` — raised by `save()` when the exported PDF/SVG fails the vector
157
+ checks.