mapreader 1.0.5__tar.gz → 1.0.7__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 (48) hide show
  1. mapreader-1.0.7/PKG-INFO +205 -0
  2. mapreader-1.0.7/README.md +140 -0
  3. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/__init__.py +2 -0
  4. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/_version.py +3 -3
  5. mapreader-1.0.7/mapreader/annotate/annotator.py +930 -0
  6. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/annotate/utils.py +215 -196
  7. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/classify/classifier.py +243 -212
  8. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/classify/classifier_context.py +36 -32
  9. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/classify/custom_models.py +2 -2
  10. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/classify/datasets.py +85 -44
  11. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/classify/load_annotations.py +159 -49
  12. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/download/data_structures.py +4 -3
  13. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/download/downloader.py +20 -14
  14. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/download/downloader_utils.py +32 -19
  15. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/download/sheet_downloader.py +354 -175
  16. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/download/tile_loading.py +6 -12
  17. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/download/tile_merging.py +29 -22
  18. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/load/geo_utils.py +14 -14
  19. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/load/images.py +239 -207
  20. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/load/loader.py +14 -13
  21. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/process/process.py +11 -13
  22. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/utils/compute_and_save_stats.py +1 -1
  23. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/utils/slice_parallel.py +1 -1
  24. mapreader-1.0.7/mapreader.egg-info/PKG-INFO +205 -0
  25. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader.egg-info/SOURCES.txt +3 -0
  26. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader.egg-info/requires.txt +2 -2
  27. {mapreader-1.0.5 → mapreader-1.0.7}/setup.py +23 -17
  28. mapreader-1.0.7/tests/test_annotator.py +257 -0
  29. mapreader-1.0.7/tests/test_geo_pipeline.py +95 -0
  30. {mapreader-1.0.5 → mapreader-1.0.7}/tests/test_import.py +2 -9
  31. mapreader-1.0.7/tests/test_sheet_downloader.py +548 -0
  32. {mapreader-1.0.5 → mapreader-1.0.7}/versioneer.py +197 -135
  33. mapreader-1.0.5/PKG-INFO +0 -129
  34. mapreader-1.0.5/README.md +0 -98
  35. mapreader-1.0.5/mapreader.egg-info/PKG-INFO +0 -129
  36. mapreader-1.0.5/tests/test_sheet_downloader.py +0 -313
  37. {mapreader-1.0.5 → mapreader-1.0.7}/LICENSE +0 -0
  38. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/annotate/__init__.py +0 -0
  39. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/classify/__init__.py +0 -0
  40. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/download/__init__.py +0 -0
  41. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/load/__init__.py +0 -0
  42. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/process/__init__.py +0 -0
  43. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader/utils/__init__.py +0 -0
  44. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader.egg-info/dependency_links.txt +0 -0
  45. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader.egg-info/entry_points.txt +0 -0
  46. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader.egg-info/not-zip-safe +0 -0
  47. {mapreader-1.0.5 → mapreader-1.0.7}/mapreader.egg-info/top_level.txt +0 -0
  48. {mapreader-1.0.5 → mapreader-1.0.7}/setup.cfg +0 -0
@@ -0,0 +1,205 @@
1
+ Metadata-Version: 2.1
2
+ Name: mapreader
3
+ Version: 1.0.7
4
+ Summary: A computer vision pipeline for the semantic exploration of maps/images at scale
5
+ Home-page: https://github.com/Living-with-machines/MapReader
6
+ Download-URL: https://github.com/Living-with-machines/MapReader/archive/refs/heads/main.zip
7
+ Author: MapReader team
8
+ License: MIT License
9
+ Keywords: Computer Vision,Classification,Deep Learning,living with machines
10
+ Platform: OS Independent
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Natural Language :: English
14
+ Classifier: Programming Language :: Python :: 3.7
15
+ Classifier: Programming Language :: Python :: 3.8
16
+ Classifier: Intended Audience :: End Users/Desktop
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Intended Audience :: Education
19
+ Classifier: Intended Audience :: Science/Research
20
+ Classifier: Operating System :: Unix
21
+ Classifier: Operating System :: Microsoft :: Windows
22
+ Classifier: Operating System :: MacOS
23
+ Classifier: Operating System :: OS Independent
24
+ Classifier: Topic :: Software Development
25
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
26
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
27
+ Requires-Python: >=3.7, <3.11
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+ Requires-Dist: matplotlib<4.0.0,>=3.5.0
31
+ Requires-Dist: numpy<2.0.0,>=1.21.5
32
+ Requires-Dist: pandas<2.0.0,>=1.3.4
33
+ Requires-Dist: pyproj<4.0.0,>=3.2.0
34
+ Requires-Dist: azure-storage-blob<13.0.0,>=12.9.0
35
+ Requires-Dist: aiohttp<4.0.0,>=3.8.1
36
+ Requires-Dist: Shapely<3.0.0,>=2.0.0
37
+ Requires-Dist: nest-asyncio<2.0.0,>=1.5.1
38
+ Requires-Dist: scikit-image>=0.18.3
39
+ Requires-Dist: scikit-learn<2.0.0,>=1.0.1
40
+ Requires-Dist: torch<2.0.0,>=1.10.0
41
+ Requires-Dist: torchvision<0.12.1,>=0.11.1
42
+ Requires-Dist: jupyter<2.0.0,>=1.0.0
43
+ Requires-Dist: ipykernel<7.0.0,>=6.5.1
44
+ Requires-Dist: ipywidgets<9.0.0,>=8.0.0
45
+ Requires-Dist: ipyannotate==0.1.0-beta.0
46
+ Requires-Dist: Cython<0.30.0,>=0.29.24
47
+ Requires-Dist: PyYAML<7.0,>=6.0
48
+ Requires-Dist: tensorboard<3.0.0,>=2.7.0
49
+ Requires-Dist: parhugin<0.0.4,>=0.0.3
50
+ Requires-Dist: geopy==2.1.0
51
+ Requires-Dist: rasterio<2.0.0,>=1.2.10
52
+ Requires-Dist: simplekml<2.0.0,>=1.3.6
53
+ Requires-Dist: versioneer>=0.28
54
+ Requires-Dist: tqdm<5.0.0
55
+ Requires-Dist: torchinfo<2.0.0
56
+ Requires-Dist: openpyxl<4.0.0
57
+ Requires-Dist: geopandas<1.0.0
58
+ Provides-Extra: dev
59
+ Requires-Dist: pytest<8.0.0; extra == "dev"
60
+ Requires-Dist: pytest-cov<5.0.0,>=4.1.0; extra == "dev"
61
+ Requires-Dist: timm<1.0.0; extra == "dev"
62
+ Requires-Dist: transformers<5.0.0; extra == "dev"
63
+ Requires-Dist: black<24.0.0,>=23.7.0; extra == "dev"
64
+ Requires-Dist: flake8<7.0.0,>=6.0.0; extra == "dev"
65
+
66
+ <div align="center">
67
+ <br>
68
+ <p align="center">
69
+ <h1>MapReader</h1>
70
+ <h2>A computer vision pipeline for exploring and analyzing images at scale</h2>
71
+ </p>
72
+ </div>
73
+
74
+ <p align="center">
75
+ <a href="https://pypi.org/project/mapreader/">
76
+ <img alt="PyPI" src="https://img.shields.io/pypi/v/MapReader">
77
+ </a>
78
+ <a href="https://github.com/Living-with-machines/MapReader/blob/main/LICENSE">
79
+ <img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg">
80
+ </a>
81
+ <a href="https://github.com/Living-with-machines/MapReader/actions/workflows/mr_ci.yml/badge.svg">
82
+ <img alt="Integration Tests badge" src="https://github.com/Living-with-machines/MapReader/actions/workflows/mr_ci.yml/badge.svg">
83
+ </a>
84
+ <a href="https://zenodo.org/badge/latestdoi/430661738"><img src="https://zenodo.org/badge/430661738.svg" alt="DOI"></a>
85
+ <br/>
86
+ </p>
87
+
88
+
89
+ ## What is MapReader?
90
+
91
+ <div align="center">
92
+ <figure>
93
+ <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/river_banner_8bit.png"
94
+ alt="Annotated Map with Prediction Outputs"
95
+ width="70%">
96
+ </figure>
97
+ </div>
98
+
99
+ MapReader is an end-to-end computer vision (CV) pipeline for exploring and analyzing images at scale.
100
+
101
+ MapReader was developed in the [Living with Machines](https://livingwithmachines.ac.uk/) project to analyze large collections of historical maps but is a _**generalizable**_ computer vision pipeline which can be applied to _**any images**_ in a wide variety of domains.
102
+
103
+ ## Overview
104
+
105
+ MapReader is a groundbreaking interdisciplinary tool that emerged from a specific set of geospatial historical research questions. It was inspired by methods in biomedical imaging and geographic information science, which were adapted for use by historians, for example in our [Journal of Victorian Culture](https://doi.org/10.1093/jvcult/vcab009) and [Geospatial Humanities 2022 SIGSPATIAL workshop](https://arxiv.org/abs/2111.15592) papers. The success of the tool subsequently generated interest from plant phenotype researchers working with large image datasets, and so MapReader is an example of cross-pollination between the humanities and the sciences made possible by reproducible data science.
106
+
107
+ ### MapReader pipeline
108
+
109
+ <div align="center">
110
+ <figure>
111
+ <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/docs/source/figures/pipeline_explained.png"
112
+ alt="MapReader pipeline"
113
+ width="70%">
114
+ </figure>
115
+ </div>
116
+
117
+ The MapReader pipeline consists of a linear sequence of tasks which, together, can be used to train a computer vision (CV) classifier to recognize visual features within maps and identify patches containing these features across entire map collections.
118
+
119
+ See our [About MapReader](https://mapreader.readthedocs.io/en/latest/About.html) page to learn more.
120
+
121
+ ## Documentation
122
+
123
+ The MapReader documentation can be found at https://mapreader.readthedocs.io/en/latest/index.html.
124
+
125
+ **New users** should refer to the [Installation instructions](https://mapreader.readthedocs.io/en/latest/Install.html) and [Input guidance](https://mapreader.readthedocs.io/en/latest/Input-guidance.html) for help with the initial set up of MapReader.
126
+
127
+ **All users** should refer to our [User Guide](https://mapreader.readthedocs.io/en/latest/User-guide/User-guide.html) for guidance on how to use MapReader. This contains end-to-end instructions on how to use the MapReader pipeline, plus a number of worked examples illustrating use cases such as:
128
+
129
+ - Geospatial images (i.e. maps)
130
+ - Non-geospatial images
131
+
132
+ **Developers and contributors** may also want to refer to the [API documentation](https://mapreader.readthedocs.io/en/latest/api/index.html) and [Contribution guide](https://mapreader.readthedocs.io/en/latest/Contribution-guide.html) for guidance on how to contribute to the MapReader package.
133
+
134
+ **Join our Slack workspace!**
135
+ Please fill out [this form](https://forms.gle/dXjECHZQkwrZ3Xpt9) to receive an invitation to the Slack workspace.
136
+
137
+ ## What is included in this repo?
138
+
139
+ The MapReader package provides a set of tools to:
140
+
141
+ - **Download** images/maps and metadata stored on web-servers (e.g. tileservers which can be used to retrieve maps from OpenStreetMap (OSM), the National Library of Scotland (NLS), or elsewhere).
142
+ - **Load** images/maps and metadata stored locally.
143
+ - **Pre-process** images/maps:
144
+ - patchify (create patches from a parent image),
145
+ - resample (use image transformations to alter pixel-dimensions/resolution/orientation/etc.),
146
+ - remove borders outside the neatline,
147
+ - reproject between coordinate reference systems (CRS).
148
+ - **Annotate** images/maps (or their patches) using an interactive annotation tool.
149
+ - **Train or fine-tune** Computer Vision (CV) models and use these to **predict** labels (i.e. model inference) on large sets of images/maps.
150
+
151
+ Various **plotting and analysis** functionalities are also included (based on packages such as _matplotlib_, _cartopy_, _Google Earth_, and _[kepler.gl](https://kepler.gl/))_.
152
+
153
+ ## How to cite MapReader
154
+
155
+ If you use MapReader in your work, please cite both the MapReader repo and [our SIGSPATIAL paper](https://dl.acm.org/doi/10.1145/3557919.3565812):
156
+
157
+ - Kasra Hosseini, Daniel C. S. Wilson, Kaspar Beelen, and Katherine McDonough. 2022. MapReader: a computer vision pipeline for the semantic exploration of maps at scale. In Proceedings of the 6th ACM SIGSPATIAL International Workshop on Geospatial Humanities (GeoHumanities '22). Association for Computing Machinery, New York, NY, USA, 8–19. https://doi.org/10.1145/3557919.3565812
158
+ - Kasra Hosseini, Rosie Wood, Andy Smith, Katie McDonough, Daniel C.S. Wilson, Christina Last, Kalle Westerling, and Evangeline Mae Corcoran. “Living-with-machines/mapreader: End of Lwm”. Zenodo, July 27, 2023. https://doi.org/10.5281/zenodo.8189653.
159
+
160
+
161
+ ## Acknowledgements
162
+
163
+ This work was supported by Living with Machines (AHRC grant AH/S01179X/1) and The Alan Turing Institute (EPSRC grant EP/N510129/1).
164
+
165
+ Living with Machines, funded by the UK Research and Innovation (UKRI) Strategic Priority Fund, is a multidisciplinary collaboration delivered by the Arts and Humanities Research Council (AHRC), with The Alan Turing Institute, the British Library and the Universities of Cambridge, East Anglia, Exeter, and Queen Mary University of London.
166
+
167
+ Maps above reproduced with the permission of the National Library of Scotland https://maps.nls.uk/index.html
168
+
169
+ ## Contributors
170
+
171
+ <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
172
+ [![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)
173
+ <!-- ALL-CONTRIBUTORS-BADGE:END -->
174
+
175
+ <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
176
+ <!-- prettier-ignore-start -->
177
+ <!-- markdownlint-disable -->
178
+ <table>
179
+ <tbody>
180
+ <tr>
181
+ <td align="center" valign="top" width="14.28%"><a href="https://www.turing.ac.uk/people/researchers/katherine-mcdonough"><img src="https://avatars.githubusercontent.com/u/20363927?v=4?s=100" width="100px;" alt="Katie McDonough"/><br /><sub><b>Katie McDonough</b></sub></a><br /><a href="#research-kmcdono2" title="Research">🔬</a> <a href="#ideas-kmcdono2" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=kmcdono2" title="Documentation">📖</a> <a href="#eventOrganizing-kmcdono2" title="Event Organizing">📋</a> <a href="#projectManagement-kmcdono2" title="Project Management">📆</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akmcdono2" title="Reviewed Pull Requests">👀</a> <a href="#talk-kmcdono2" title="Talks">📢</a> <a href="#tutorial-kmcdono2" title="Tutorials">✅</a></td>
182
+ <td align="center" valign="top" width="14.28%"><a href="http://danielwilson.info"><img src="https://avatars.githubusercontent.com/u/34318222?v=4?s=100" width="100px;" alt="Daniel C.S. Wilson"/><br /><sub><b>Daniel C.S. Wilson</b></sub></a><br /><a href="#research-dcsw2" title="Research">🔬</a> <a href="#ideas-dcsw2" title="Ideas, Planning, & Feedback">🤔</a> <a href="#talk-dcsw2" title="Talks">📢</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=dcsw2" title="Documentation">📖</a> <a href="#eventOrganizing-dcsw2" title="Event Organizing">📋</a></td>
183
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/kasra-hosseini"><img src="https://avatars.githubusercontent.com/u/1899856?v=4?s=100" width="100px;" alt="Kasra Hosseini"/><br /><sub><b>Kasra Hosseini</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=kasra-hosseini" title="Code">💻</a> <a href="#ideas-kasra-hosseini" title="Ideas, Planning, & Feedback">🤔</a> <a href="#research-kasra-hosseini" title="Research">🔬</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akasra-hosseini" title="Reviewed Pull Requests">👀</a> <a href="#talk-kasra-hosseini" title="Talks">📢</a></td>
184
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/rwood-97"><img src="https://avatars.githubusercontent.com/u/72076688?v=4?s=100" width="100px;" alt="Rosie Wood"/><br /><sub><b>Rosie Wood</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=rwood-97" title="Code">💻</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=rwood-97" title="Documentation">📖</a> <a href="#ideas-rwood-97" title="Ideas, Planning, & Feedback">🤔</a> <a href="#talk-rwood-97" title="Talks">📢</a> <a href="#tutorial-rwood-97" title="Tutorials">✅</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Arwood-97" title="Reviewed Pull Requests">👀</a> <a href="#maintenance-rwood-97" title="Maintenance">🚧</a> <a href="#research-rwood-97" title="Research">🔬</a></td>
185
+ <td align="center" valign="top" width="14.28%"><a href="http://www.westerling.nu"><img src="https://avatars.githubusercontent.com/u/7298727?v=4?s=100" width="100px;" alt="Kalle Westerling"/><br /><sub><b>Kalle Westerling</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=kallewesterling" title="Code">💻</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=kallewesterling" title="Documentation">📖</a> <a href="#maintenance-kallewesterling" title="Maintenance">🚧</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akallewesterling" title="Reviewed Pull Requests">👀</a> <a href="#talk-kallewesterling" title="Talks">📢</a></td>
186
+ <td align="center" valign="top" width="14.28%"><a href="https://maps.nls.uk"><img src="https://avatars.githubusercontent.com/u/3666702?v=4?s=100" width="100px;" alt="Chris Fleet"/><br /><sub><b>Chris Fleet</b></sub></a><br /><a href="#data-ChrisFleet" title="Data">🔣</a></td>
187
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/kasparvonbeelen"><img src="https://avatars.githubusercontent.com/u/11618160?v=4?s=100" width="100px;" alt="Kaspar Beelen"/><br /><sub><b>Kaspar Beelen</b></sub></a><br /><a href="#ideas-kasparvonbeelen" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akasparvonbeelen" title="Reviewed Pull Requests">👀</a> <a href="#research-kasparvonbeelen" title="Research">🔬</a></td>
188
+ </tr>
189
+ <tr>
190
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/andrewphilipsmith"><img src="https://avatars.githubusercontent.com/u/5346065?v=4?s=100" width="100px;" alt="Andy Smith"/><br /><sub><b>Andy Smith</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=andrewphilipsmith" title="Code">💻</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=andrewphilipsmith" title="Documentation">📖</a> <a href="#mentoring-andrewphilipsmith" title="Mentoring">🧑‍🏫</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Aandrewphilipsmith" title="Reviewed Pull Requests">👀</a></td>
191
+ </tr>
192
+ </tbody>
193
+ </table>
194
+
195
+ <!-- markdownlint-restore -->
196
+ <!-- prettier-ignore-end -->
197
+
198
+ <!-- ALL-CONTRIBUTORS-LIST:END -->
199
+ <!-- prettier-ignore-start -->
200
+ <!-- markdownlint-disable -->
201
+
202
+ <!-- markdownlint-restore -->
203
+ <!-- prettier-ignore-end -->
204
+
205
+ <!-- ALL-CONTRIBUTORS-LIST:END -->
@@ -0,0 +1,140 @@
1
+ <div align="center">
2
+ <br>
3
+ <p align="center">
4
+ <h1>MapReader</h1>
5
+ <h2>A computer vision pipeline for exploring and analyzing images at scale</h2>
6
+ </p>
7
+ </div>
8
+
9
+ <p align="center">
10
+ <a href="https://pypi.org/project/mapreader/">
11
+ <img alt="PyPI" src="https://img.shields.io/pypi/v/MapReader">
12
+ </a>
13
+ <a href="https://github.com/Living-with-machines/MapReader/blob/main/LICENSE">
14
+ <img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg">
15
+ </a>
16
+ <a href="https://github.com/Living-with-machines/MapReader/actions/workflows/mr_ci.yml/badge.svg">
17
+ <img alt="Integration Tests badge" src="https://github.com/Living-with-machines/MapReader/actions/workflows/mr_ci.yml/badge.svg">
18
+ </a>
19
+ <a href="https://zenodo.org/badge/latestdoi/430661738"><img src="https://zenodo.org/badge/430661738.svg" alt="DOI"></a>
20
+ <br/>
21
+ </p>
22
+
23
+
24
+ ## What is MapReader?
25
+
26
+ <div align="center">
27
+ <figure>
28
+ <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/figs/river_banner_8bit.png"
29
+ alt="Annotated Map with Prediction Outputs"
30
+ width="70%">
31
+ </figure>
32
+ </div>
33
+
34
+ MapReader is an end-to-end computer vision (CV) pipeline for exploring and analyzing images at scale.
35
+
36
+ MapReader was developed in the [Living with Machines](https://livingwithmachines.ac.uk/) project to analyze large collections of historical maps but is a _**generalizable**_ computer vision pipeline which can be applied to _**any images**_ in a wide variety of domains.
37
+
38
+ ## Overview
39
+
40
+ MapReader is a groundbreaking interdisciplinary tool that emerged from a specific set of geospatial historical research questions. It was inspired by methods in biomedical imaging and geographic information science, which were adapted for use by historians, for example in our [Journal of Victorian Culture](https://doi.org/10.1093/jvcult/vcab009) and [Geospatial Humanities 2022 SIGSPATIAL workshop](https://arxiv.org/abs/2111.15592) papers. The success of the tool subsequently generated interest from plant phenotype researchers working with large image datasets, and so MapReader is an example of cross-pollination between the humanities and the sciences made possible by reproducible data science.
41
+
42
+ ### MapReader pipeline
43
+
44
+ <div align="center">
45
+ <figure>
46
+ <img src="https://raw.githubusercontent.com/Living-with-machines/MapReader/main/docs/source/figures/pipeline_explained.png"
47
+ alt="MapReader pipeline"
48
+ width="70%">
49
+ </figure>
50
+ </div>
51
+
52
+ The MapReader pipeline consists of a linear sequence of tasks which, together, can be used to train a computer vision (CV) classifier to recognize visual features within maps and identify patches containing these features across entire map collections.
53
+
54
+ See our [About MapReader](https://mapreader.readthedocs.io/en/latest/About.html) page to learn more.
55
+
56
+ ## Documentation
57
+
58
+ The MapReader documentation can be found at https://mapreader.readthedocs.io/en/latest/index.html.
59
+
60
+ **New users** should refer to the [Installation instructions](https://mapreader.readthedocs.io/en/latest/Install.html) and [Input guidance](https://mapreader.readthedocs.io/en/latest/Input-guidance.html) for help with the initial set up of MapReader.
61
+
62
+ **All users** should refer to our [User Guide](https://mapreader.readthedocs.io/en/latest/User-guide/User-guide.html) for guidance on how to use MapReader. This contains end-to-end instructions on how to use the MapReader pipeline, plus a number of worked examples illustrating use cases such as:
63
+
64
+ - Geospatial images (i.e. maps)
65
+ - Non-geospatial images
66
+
67
+ **Developers and contributors** may also want to refer to the [API documentation](https://mapreader.readthedocs.io/en/latest/api/index.html) and [Contribution guide](https://mapreader.readthedocs.io/en/latest/Contribution-guide.html) for guidance on how to contribute to the MapReader package.
68
+
69
+ **Join our Slack workspace!**
70
+ Please fill out [this form](https://forms.gle/dXjECHZQkwrZ3Xpt9) to receive an invitation to the Slack workspace.
71
+
72
+ ## What is included in this repo?
73
+
74
+ The MapReader package provides a set of tools to:
75
+
76
+ - **Download** images/maps and metadata stored on web-servers (e.g. tileservers which can be used to retrieve maps from OpenStreetMap (OSM), the National Library of Scotland (NLS), or elsewhere).
77
+ - **Load** images/maps and metadata stored locally.
78
+ - **Pre-process** images/maps:
79
+ - patchify (create patches from a parent image),
80
+ - resample (use image transformations to alter pixel-dimensions/resolution/orientation/etc.),
81
+ - remove borders outside the neatline,
82
+ - reproject between coordinate reference systems (CRS).
83
+ - **Annotate** images/maps (or their patches) using an interactive annotation tool.
84
+ - **Train or fine-tune** Computer Vision (CV) models and use these to **predict** labels (i.e. model inference) on large sets of images/maps.
85
+
86
+ Various **plotting and analysis** functionalities are also included (based on packages such as _matplotlib_, _cartopy_, _Google Earth_, and _[kepler.gl](https://kepler.gl/))_.
87
+
88
+ ## How to cite MapReader
89
+
90
+ If you use MapReader in your work, please cite both the MapReader repo and [our SIGSPATIAL paper](https://dl.acm.org/doi/10.1145/3557919.3565812):
91
+
92
+ - Kasra Hosseini, Daniel C. S. Wilson, Kaspar Beelen, and Katherine McDonough. 2022. MapReader: a computer vision pipeline for the semantic exploration of maps at scale. In Proceedings of the 6th ACM SIGSPATIAL International Workshop on Geospatial Humanities (GeoHumanities '22). Association for Computing Machinery, New York, NY, USA, 8–19. https://doi.org/10.1145/3557919.3565812
93
+ - Kasra Hosseini, Rosie Wood, Andy Smith, Katie McDonough, Daniel C.S. Wilson, Christina Last, Kalle Westerling, and Evangeline Mae Corcoran. “Living-with-machines/mapreader: End of Lwm”. Zenodo, July 27, 2023. https://doi.org/10.5281/zenodo.8189653.
94
+
95
+
96
+ ## Acknowledgements
97
+
98
+ This work was supported by Living with Machines (AHRC grant AH/S01179X/1) and The Alan Turing Institute (EPSRC grant EP/N510129/1).
99
+
100
+ Living with Machines, funded by the UK Research and Innovation (UKRI) Strategic Priority Fund, is a multidisciplinary collaboration delivered by the Arts and Humanities Research Council (AHRC), with The Alan Turing Institute, the British Library and the Universities of Cambridge, East Anglia, Exeter, and Queen Mary University of London.
101
+
102
+ Maps above reproduced with the permission of the National Library of Scotland https://maps.nls.uk/index.html
103
+
104
+ ## Contributors
105
+
106
+ <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
107
+ [![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)
108
+ <!-- ALL-CONTRIBUTORS-BADGE:END -->
109
+
110
+ <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
111
+ <!-- prettier-ignore-start -->
112
+ <!-- markdownlint-disable -->
113
+ <table>
114
+ <tbody>
115
+ <tr>
116
+ <td align="center" valign="top" width="14.28%"><a href="https://www.turing.ac.uk/people/researchers/katherine-mcdonough"><img src="https://avatars.githubusercontent.com/u/20363927?v=4?s=100" width="100px;" alt="Katie McDonough"/><br /><sub><b>Katie McDonough</b></sub></a><br /><a href="#research-kmcdono2" title="Research">🔬</a> <a href="#ideas-kmcdono2" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=kmcdono2" title="Documentation">📖</a> <a href="#eventOrganizing-kmcdono2" title="Event Organizing">📋</a> <a href="#projectManagement-kmcdono2" title="Project Management">📆</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akmcdono2" title="Reviewed Pull Requests">👀</a> <a href="#talk-kmcdono2" title="Talks">📢</a> <a href="#tutorial-kmcdono2" title="Tutorials">✅</a></td>
117
+ <td align="center" valign="top" width="14.28%"><a href="http://danielwilson.info"><img src="https://avatars.githubusercontent.com/u/34318222?v=4?s=100" width="100px;" alt="Daniel C.S. Wilson"/><br /><sub><b>Daniel C.S. Wilson</b></sub></a><br /><a href="#research-dcsw2" title="Research">🔬</a> <a href="#ideas-dcsw2" title="Ideas, Planning, & Feedback">🤔</a> <a href="#talk-dcsw2" title="Talks">📢</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=dcsw2" title="Documentation">📖</a> <a href="#eventOrganizing-dcsw2" title="Event Organizing">📋</a></td>
118
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/kasra-hosseini"><img src="https://avatars.githubusercontent.com/u/1899856?v=4?s=100" width="100px;" alt="Kasra Hosseini"/><br /><sub><b>Kasra Hosseini</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=kasra-hosseini" title="Code">💻</a> <a href="#ideas-kasra-hosseini" title="Ideas, Planning, & Feedback">🤔</a> <a href="#research-kasra-hosseini" title="Research">🔬</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akasra-hosseini" title="Reviewed Pull Requests">👀</a> <a href="#talk-kasra-hosseini" title="Talks">📢</a></td>
119
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/rwood-97"><img src="https://avatars.githubusercontent.com/u/72076688?v=4?s=100" width="100px;" alt="Rosie Wood"/><br /><sub><b>Rosie Wood</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=rwood-97" title="Code">💻</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=rwood-97" title="Documentation">📖</a> <a href="#ideas-rwood-97" title="Ideas, Planning, & Feedback">🤔</a> <a href="#talk-rwood-97" title="Talks">📢</a> <a href="#tutorial-rwood-97" title="Tutorials">✅</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Arwood-97" title="Reviewed Pull Requests">👀</a> <a href="#maintenance-rwood-97" title="Maintenance">🚧</a> <a href="#research-rwood-97" title="Research">🔬</a></td>
120
+ <td align="center" valign="top" width="14.28%"><a href="http://www.westerling.nu"><img src="https://avatars.githubusercontent.com/u/7298727?v=4?s=100" width="100px;" alt="Kalle Westerling"/><br /><sub><b>Kalle Westerling</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=kallewesterling" title="Code">💻</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=kallewesterling" title="Documentation">📖</a> <a href="#maintenance-kallewesterling" title="Maintenance">🚧</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akallewesterling" title="Reviewed Pull Requests">👀</a> <a href="#talk-kallewesterling" title="Talks">📢</a></td>
121
+ <td align="center" valign="top" width="14.28%"><a href="https://maps.nls.uk"><img src="https://avatars.githubusercontent.com/u/3666702?v=4?s=100" width="100px;" alt="Chris Fleet"/><br /><sub><b>Chris Fleet</b></sub></a><br /><a href="#data-ChrisFleet" title="Data">🔣</a></td>
122
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/kasparvonbeelen"><img src="https://avatars.githubusercontent.com/u/11618160?v=4?s=100" width="100px;" alt="Kaspar Beelen"/><br /><sub><b>Kaspar Beelen</b></sub></a><br /><a href="#ideas-kasparvonbeelen" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Akasparvonbeelen" title="Reviewed Pull Requests">👀</a> <a href="#research-kasparvonbeelen" title="Research">🔬</a></td>
123
+ </tr>
124
+ <tr>
125
+ <td align="center" valign="top" width="14.28%"><a href="https://github.com/andrewphilipsmith"><img src="https://avatars.githubusercontent.com/u/5346065?v=4?s=100" width="100px;" alt="Andy Smith"/><br /><sub><b>Andy Smith</b></sub></a><br /><a href="https://github.com/Living-with-machines/MapReader/commits?author=andrewphilipsmith" title="Code">💻</a> <a href="https://github.com/Living-with-machines/MapReader/commits?author=andrewphilipsmith" title="Documentation">📖</a> <a href="#mentoring-andrewphilipsmith" title="Mentoring">🧑‍🏫</a> <a href="https://github.com/Living-with-machines/MapReader/pulls?q=is%3Apr+reviewed-by%3Aandrewphilipsmith" title="Reviewed Pull Requests">👀</a></td>
126
+ </tr>
127
+ </tbody>
128
+ </table>
129
+
130
+ <!-- markdownlint-restore -->
131
+ <!-- prettier-ignore-end -->
132
+
133
+ <!-- ALL-CONTRIBUTORS-LIST:END -->
134
+ <!-- prettier-ignore-start -->
135
+ <!-- markdownlint-disable -->
136
+
137
+ <!-- markdownlint-restore -->
138
+ <!-- prettier-ignore-end -->
139
+
140
+ <!-- ALL-CONTRIBUTORS-LIST:END -->
@@ -15,6 +15,8 @@ from mapreader.classify import custom_models
15
15
 
16
16
  from mapreader.process import process
17
17
 
18
+ from mapreader.annotate.annotator import Annotator
19
+
18
20
  from . import _version
19
21
 
20
22
  __version__ = _version.get_versions()["version"]
@@ -8,11 +8,11 @@ import json
8
8
 
9
9
  version_json = '''
10
10
  {
11
- "date": "2023-07-24T17:44:16+0100",
11
+ "date": "2023-12-12T16:49:22+0000",
12
12
  "dirty": false,
13
13
  "error": null,
14
- "full-revisionid": "9ed7c867f537d6b7455febf5ca09edd7256a9f07",
15
- "version": "1.0.5"
14
+ "full-revisionid": "9ee0cdf877d82bcfefadfe64733f15957fbe37e4",
15
+ "version": "1.0.7"
16
16
  }
17
17
  ''' # END VERSION_JSON
18
18