diff --git a/docs/source/getting-started/faq.rst b/docs/source/getting-started/faq.rst new file mode 100644 index 00000000..ecefaead --- /dev/null +++ b/docs/source/getting-started/faq.rst @@ -0,0 +1,130 @@ +Frequently Asked Questions +========================== + +Welcome to the Frequently Asked Questions (FAQ) section of our documentation! +Here, we address some of the most common queries and challenges faced by users of MapReader that we've encountered when we've led workshops or during our community calls. +Whether you're just starting with a MapReader project or diving into our more advanced features or contributing code, this section provides quick answers and solutions to help you navigate effectively. + +If you have a question that is not covered here, feel free to reach out to open an issue on our GitHub repository or reach out to us elsewhere. +(If you don't know how to use GitHub, we have `a section for that in the documentation `_ as well!) + +We're always here to help and welcome contributions to expand this section. + +.. + Once we have too many questions, we can start integrating them into categories (e.g., "General Questions," "Data Preparation," "Model Training," etc.) + + General Questions + ----------------- + +**Q: Do I need georeferenced maps?** + +A: MapReader is at its most useful when operating on georeferenced maps, as these allow for geospatial analysis and visualization. +However, it is possible to use non-georeferenced maps as input. +Output from non-georeferenced maps will provide details about patches or text bounding boxes based only on pixel coordinates, not geospatial coordinates. +In practice, this means that you can analyze information about patches within 1 map, or across maps based on quantiative measures (for example, how many of each label? where in the image do these labeled patches occur? what text occurs most frequently across my corpus). +But you are not able to plot this output on a map and perform spatial analysis. + +Note that you can work with non-georeferenced maps in MapReader, georeference the maps separately (for example, in QGIS or with Allmaps), and then transform the MapReader output coordinates from pixels into geospatial locations after the fact. + +**Q: Do you have good examples of maps that I can start working with?** + +A: Yes. +MapReader takes different kinds of input formats for maps. +Details are available in the `File/Map Options `_ section. +Map collections that are available as tiles, IIIF resources, and direct image downloads include: + +- **Tiles** + + - National Library of Scotland maps as web map tiles: https://www.maptiler.com/nls/ + +- **IIIF Map Collections** + + - National Library of Scotland maps as IIIF resources (when viewing 1 map, click on "Show IIIF" tab at bottom of frame) + - David Rumsey Map Collection: https://www.davidrumsey.com/ (via the "Share" menu) + - Library of Congress: https://www.loc.gov/maps/?fa=partof:geography+and+map+division (scroll down to "IIIF Presentation Manifest") + - John Carter Brown Library Map Collection: https://jcb.lunaimaging.com/luna/servlet/JCBMAPS~1~1 (same infrastructure as Rumsey collection for finding IIIF manifests) + - `Bibliotheque nationale de France/Gallica digital map collection `_ + +- **Direct Downloads** + + - David Rumsey Map Collection: https://www.davidrumsey.com/ (scroll down, to 'download' options in metadata field, or use 'export' option in top right) + - Library of Congress: https://www.loc.gov/maps/?fa=partof:geography+and+map+division + - John Carter Brown Library Map Collection: https://jcb.lunaimaging.com/luna/servlet/JCBMAPS~1~1 (export option in top right) + - `Bibliotheque nationale de France/Gallica digital map collection `_ + +**Q: Can the tool download/patchify IIIF maps?** + +A: MapReader does not yet support downloading and patchifying IIIF maps. +We are working on an integration of IIIF-based map servers with the tool to download and patchify maps as needed. +It is expected to be delivered early 2025. + +**Q: Does MapReader have a GUI?** + +A: No, MapReader does not currently have a graphical user interface. +It is designed to be used via Python scripts or Jupyter notebooks, offering flexibility for advanced users. + +**Q: How much technical background do we need to have?** + +A: Basic familiarity with Python and Jupyter notebooks is recommended. +Knowledge of geospatial data handling is a plus but not mandatory for beginners. +We have provided some `coding basics `_ in this documentation site to help you get started. + +**Q: What does the output of MapReader look like?** + +A: MapReader produces patch data, annotations, text spotting outputs, as well as model predictions. +Outputs can include CSV files for metadata and labels, annotated patches in image formats, and trained models for further inference. + +**Q: How can I contribute to the codebase?** + +A: Contributions are welcome! +You can fork the MapReader repository, make changes, and submit a pull request. +Please review our `code contribution guide `_ for details. + +**Q: Can I use MapReader to vectorize maps?** + +A: MapReader is not designed for full vectorization but can assist in creating training datasets for machine learning models, which can then infer vector-like features. + +**Q: Is it free to use MapReader?** + +A: Yes, MapReader is an open-source project and is free to use under its license. + +**Q: Why do I need to patchify my maps?** + +A: Patchifying maps is a crucial step in MapReader because it breaks down large map sheets into smaller, manageable regions called patches. +Without the step of patchifying, processing large, complex maps would be resource-intensive and less flexible for targeted analysis or model training. +Overall, this step is important as it enables some crucial features for you: + +- *Efficient data analysis*: + Analyzing smaller patches reduces computational overhead, making tasks like classification, annotation, and visualization more scalable. +- *Better machine learning models*: + Most machine learning models process data in fixed-size inputs. + Patchifying maps ensures that the data conforms to the required dimensions for training and inference. +- *Adaptability to the patch's context*: + Patchifying enables the use of context-based models, where information from surrounding patches can be incorporated for better predictions. + +**Q: How large do my patches need to be? (i.e., standards? best patch sizes?)** + +A: Patch sizes depend on the resolution of your maps and your analysis goals. +Standard sizes are 100x100 or 300x300 pixels, but experimentation may be necessary for optimal results. +You can read more in the `"Patchify" section `_ in our step-by-step guide. + +**Q: What should I use for labels? What is a good label?** + +A: Labels should correspond to a visual signal you know is present in the maps you are working with. +This visual signal can have some variety, but too much variety will lead to poor results. +Developing the name of a label and the guidelines for assigning a label to a patch is usually an iterative process that is refined as you start to annotate patches. +Labels do not need to conform to typical map features, but they can. +Previous examples of patch labels include "railspace", "building", "trees", "rocks", "water", "gardens", and "heath". + +**Q: How can I trust the output from MapReader?** + +A: Trust in MapReader's output relies on the quality of your training data and the rigor of your validation process. +Review results critically and iteratively refine models and annotations for accuracy. +We have some post-processing tools to help with this, such as the :class:`~.process.occlusion_analysis.OcclusionAnalyzer` class. + +**Q: Do I need Cartopy? What does it do in MapReader? What happens if I don't have it?** + +A: No, Cartopy is optional. It is used for plotting geospatial data on maps (e.g., via matplotlib) in methods like :meth:`~.download.sheet_downloader.SheetDownloader.plot_all_metadata_on_map` within the Download subpackage. + + - **With Cartopy**: Geospatial plots can display enhanced geographic context (e.g., basemaps). + - **Without Cartopy**: MapReader will still function, but the plots will lack certain geospatial overlays. diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst index dbd20c9d..2bdd7e80 100644 --- a/docs/source/getting-started/index.rst +++ b/docs/source/getting-started/index.rst @@ -10,3 +10,4 @@ Getting Started installation-instructions/index troubleshooting-problems + faq