Minerva

GitHub release (latest by date) GitHub PyPI - Python Version GitHub contributors CodeFactor Codacy Badge tests Read the Docs Ruff security: bandit pre-commit.ci status codecov DOI


About 🔎

Minerva is a package to aid in the building, fitting and testing of neural network models on multi-spectral geo-spatial data.

Getting Started ▶

If one wishes to use torchgeo, installation on Linux is recommended to handle the compilation of the required C-based libraries – though minerva is also tested with MacOS and Windows runners.

Installation ⬇

minerva is currently not included in any distribution. The recommended install is therefore to install the latest version from GitHub.

pip install git+https://github.com/Pale-Blue-Dot-97/Minerva.git

(back to top)

Requirements 📌

minerva now supports the use of torchgeo datasets with upcoming support for torchvision datasets.

Required Python modules for minerva are stated in the setup.cfg.

minerva currently only supports python 3.10 – 3.12.

(back to top)

Usage 🖥

The core functionality of minerva provides the modules to define models to fit and test, loaders to pre-process, load and parse data, and a Trainer to handle all aspects of a model fitting. Below is a MWE of creating datasets, initialising a Trainer and model, and fitting and testing that model then outputting the results:

MWE Driver Script 📄

import hydra
from omegaconf import DictConfig

from minerva.trainer import Trainer  # Class designed to handle fitting of model.


@hydra.main(version_base="1.3")
def main(cfg: DictConfig) -> None:
    # Initialise a Trainer. Also creates the model.
    trainer = Trainer(**cfg)

    # Run the fitting (train and validation epochs).
    trainer.fit()

    # Run the testing epoch and output results.
    trainer.test()

See scripts\MinervaExp.py as an example script implementing minerva.

Config Structure ⚙

See minerva\inbuilt_cfgs\example_config.yaml as an example config file.

Creating a Manifest for your Dataset 📑

Use scripts\ManifestMake.py to construct a manifest to act as a look-up table for a dataset.

(back to top)

Contributing 🤝

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag “enhancement”. Don’t forget to give the project a star! Thanks again!

  1. Fork the Project

  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

  3. Commit your Changes (git commit -m 'Add some AmazingFeature')

  4. Push to the Branch (git push origin feature/AmazingFeature)

  5. Open a Pull Request

(back to top)

License 🔏

Minerva is distributed under a MIT License.

(back to top)

Authors ✒

Created by Harry Baker as part of a project towards for a PhD in Computer Science from the University of Southampton. Funded by the Ordnance Survey Ltd.

Contributions also provided by:

Acknowledgments 📢

I’d like to acknowledge the invaluable supervision and contributions of Prof Jonathon Hare and Dr Isabel Sargent towards this work.

The following modules are adapted from open source third-parites:

Module

Original Author

License

Link

pytorchtools

Noah Golmant

MIT

lars

optimisers

Bjarte Mehus Sunde

MIT

early-stopping-pytorch

dfc

Lukas Liebel

GNU GPL v3.0

dfc2020_baseline

This repositry also contains some small samples from various public datasets for unit testing purposes. These are:

Dataset

Citation

License

Link

ChesapeakeCVPR

Robinson C, Hou L, Malkin K, Soobitsky R, Czawlytko J, Dilkina B, Jojic N, “Large Scale High-Resolution Land Cover Mapping with Multi-Resolution Data”. Proceedings of the 2019 Conference on Computer Vision and Pattern Recognition (CVPR 2019)

Unknown

ChesapeakeCVPR

SSL4EO-S12

Wang Y, Braham N A A, Xiong Z, Liu C, Albrecht C M, Zhu X X, “SSL4EO-S12: A Large-Scale Multi-Modal, Multi-Temporal Dataset for Self-Supervised Learning in Earth Observation”. arXiv preprint, 2023

Apache 2.0

SSL4E0-S12

DFC2020

M. Schmitt, L. H. Hughes, C. Qiu, and X. X. Zhu, “SEN12MS – A curated dataset of georeferenced multi-spectral sentinel-1/2 imagery for deep learning and data fusion,” in ISPRS Ann. Photogramm. Remote Sens. Spatial Inf. Sci. IV-2/W7, 2019, pp. 153–160.

Creative Commons Attribution

IEEE DFC2020

BigEarthNet

G. Sumbul, A. d. Wall, T. Kreuziger, F. Marcelino, H. Costa, P. Benevides, M. Caetano, B. Demir, V. Markl, “BigEarthNet-MM: A Large Scale Multi-Modal Multi-Label Benchmark Archive for Remote Sensing Image Classification and Retrieval”, IEEE Geoscience and Remote Sensing Magazine, vol. 9, no. 3, pp. 174-180, 2021, doi: 10.1109/MGRS.2021.3089174.

Community Data License Agreement – Permissive, Version 1.0

BigEarthNet

(back to top)

Project Status 🔴🟡🟢

This project is now in release beta state. Still expect some bugs and there may be breaking changes in future versions.

(back to top)

Indices and tables 📚