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.
- mapelements-0.1.0/CHANGELOG.md +38 -0
- mapelements-0.1.0/LICENSE +21 -0
- mapelements-0.1.0/MANIFEST.in +16 -0
- mapelements-0.1.0/PKG-INFO +198 -0
- mapelements-0.1.0/README.md +150 -0
- mapelements-0.1.0/docs/assets/cookbook-cartopy.png +0 -0
- mapelements-0.1.0/docs/assets/elements-graticule.png +0 -0
- mapelements-0.1.0/docs/assets/elements-northarrow.png +0 -0
- mapelements-0.1.0/docs/assets/elements-scalebar.png +0 -0
- mapelements-0.1.0/docs/assets/example-map.png +0 -0
- mapelements-0.1.0/docs/assets/layout-panels.png +0 -0
- mapelements-0.1.0/docs/en/api.md +157 -0
- mapelements-0.1.0/docs/en/cookbook.md +130 -0
- mapelements-0.1.0/docs/en/elements.md +175 -0
- mapelements-0.1.0/docs/en/export.md +123 -0
- mapelements-0.1.0/docs/en/faq.md +112 -0
- mapelements-0.1.0/docs/en/index.md +73 -0
- mapelements-0.1.0/docs/en/installation.md +73 -0
- mapelements-0.1.0/docs/en/layout.md +101 -0
- mapelements-0.1.0/docs/en/projections.md +108 -0
- mapelements-0.1.0/docs/en/quickstart.md +119 -0
- mapelements-0.1.0/docs/index.md +44 -0
- mapelements-0.1.0/docs/landing.html +57 -0
- mapelements-0.1.0/docs/make_figures.py +159 -0
- mapelements-0.1.0/docs/zh/api.md +151 -0
- mapelements-0.1.0/docs/zh/cookbook.md +127 -0
- mapelements-0.1.0/docs/zh/elements.md +164 -0
- mapelements-0.1.0/docs/zh/export.md +117 -0
- mapelements-0.1.0/docs/zh/faq.md +102 -0
- mapelements-0.1.0/docs/zh/index.md +69 -0
- mapelements-0.1.0/docs/zh/installation.md +67 -0
- mapelements-0.1.0/docs/zh/layout.md +91 -0
- mapelements-0.1.0/docs/zh/projections.md +98 -0
- mapelements-0.1.0/docs/zh/quickstart.md +113 -0
- mapelements-0.1.0/examples/artists_api.py +59 -0
- mapelements-0.1.0/examples/demo_map.py +57 -0
- mapelements-0.1.0/mkdocs.en.yml +33 -0
- mapelements-0.1.0/mkdocs.zh.yml +33 -0
- mapelements-0.1.0/pyproject.toml +88 -0
- mapelements-0.1.0/setup.cfg +4 -0
- mapelements-0.1.0/src/mapelements/__init__.py +50 -0
- mapelements-0.1.0/src/mapelements/api.py +114 -0
- mapelements-0.1.0/src/mapelements/artists.py +335 -0
- mapelements-0.1.0/src/mapelements/export.py +153 -0
- mapelements-0.1.0/src/mapelements/geom.py +101 -0
- mapelements-0.1.0/src/mapelements/py.typed +0 -0
- mapelements-0.1.0/src/mapelements/style.py +71 -0
- mapelements-0.1.0/src/mapelements.egg-info/SOURCES.txt +50 -0
- mapelements-0.1.0/tests/conftest.py +25 -0
- mapelements-0.1.0/tests/test_artists.py +113 -0
- mapelements-0.1.0/tests/test_finish.py +46 -0
- mapelements-0.1.0/tests/test_geom.py +25 -0
- 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
|
+
[](https://pypi.org/project/mapelements/)
|
|
52
|
+
[](https://pypi.org/project/mapelements/)
|
|
53
|
+
[](LICENSE)
|
|
54
|
+
[](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
|
+
[](https://pypi.org/project/mapelements/)
|
|
4
|
+
[](https://pypi.org/project/mapelements/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](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)。
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -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.
|