diff --git a/docs/index.rst b/docs/index.rst index aa3e1ce3fa2..ced959493a8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ torchgeo user/installation user/contributing user/glossary + user/alternatives .. toctree:: :maxdepth: 2 diff --git a/docs/user/alternatives.rst b/docs/user/alternatives.rst new file mode 100644 index 00000000000..a87bc2b8b2c --- /dev/null +++ b/docs/user/alternatives.rst @@ -0,0 +1,117 @@ +Alternatives +============ + +TorchGeo is not the only **geospatial machine learning library** out there, there are a number of alternatives that you can consider using. The goal of this page is to provide an up-to-date listing of these libraries and the features they support in order to help you decide which library is right for you. Criteria for inclusion on this list include: + +* **geospatial**: Must be primarily intended for working with geospatial, remote sensing, or satellite imagery data. This rules out libraries like `torchvision`_, which provides little to no support for multispectral data or geospatial transforms. +* **machine learning**: Must provide basic machine learning functionality. This rules out libraries like `GDAL`_, which is useful for data loading but offers no support for machine learning. +* **library**: Must be an actively developed software library with testing and releases on repositories like PyPI or CRAN. This rules out libraries like `TorchSat`_, `RoboSat`_, and `Solaris`_, which have been abandoned and are no longer maintained. + +When deciding which library is most useful to you, it is worth considering the features they support, how actively the library is being developed, and how popular the library is, roughly in that order. + +.. note:: + + Software is a living, breathing organism and is constantly undergoing change. If any of the above information is incorrect or out of date, or if you want to add a new project to this list, please open a PR! + + *Last updated: 25 December 2023* + +Features +-------- + +**Key**: ✅ full support, 🚧 partial support, ❌ no support + +.. csv-table:: + :align: center + :file: features.csv + :header-rows: 1 + :widths: auto + +\*Support for TensorFlow was dropped in Raster Vision 0.12. + +**ML Backend**: The machine learning libraries used by the project. For example, if you are a scikit-learn user, eo-learn may be perfect for you, but if you need more advanced deep learning support, you may want to choose a different library. + +**I/O Backend**: The I/O libraries used by the project to read data. This gives you a rough idea of which file formats are supported. For example, if you need to work with lidar data, a project that uses laspy may be important to you. + +**Spatial Backend**: The spatial library used to perform spatial joins and compute intersections based on geospatial metadata. This may be important to you if you intend to scale up your simulations. + +**Transform Backend**: The transform library used to perform data augmentation. For example, Kornia performs all augmentations on PyTorch Tensors, allowing you to run your transforms on the GPU for an entire mini-batch at a time. + +**Datasets**: The number of geospatial datasets built into the library. Note that most projects have something similar to TorchGeo's ``RasterDataset`` and ``VectorDataset``, allowing you to work with generic raster and vector files. Collections of datasets are only counted a single time, so data loaders for Landsats 1--9 are a single dataset, and data loaders for SpaceNets 1--8 are also a single dataset. + +**Weights**: The number of model weights pre-trained on geospatial data that are offered by the library. Note that most projects support hundreds of model architectures via a library like PyTorch Image Models, and can use models pre-trained on ImageNet. There are far fewer libraries that provide foundation model weights pre-trained on multispectral satellite imagery. + +**CLI**: Whether or not the library has a command-line interface. This low-code or no-code solution is convenient for users with limited programming experience, and can offer nice features for reproducing research and fast experimentation. + +**Reprojection**: Whether or not the library supports automatic reprojection and resampling of data. Without this, users are forced to manually warp data using a library like GDAL if they want to combine datasets in different coordinate systems or spatial resolutions. + +**STAC**: Whether or not the library supports the spatiotemporal asset catalog. STAC is becoming a popular means of indexing into spatiotemporal data like satellite imagery. + +**Time-Series**: Whether or not the library supports time-series modeling. For many remote sensing applications, time-series data provide important signals. + +GitHub +------ + +These are metrics that can be scraped from GitHub. + +.. csv-table:: + :align: right + :file: github.csv + :header-rows: 1 + :widths: auto + +**Contributors**: The number of contributors. This is one of the most important metrics for project development. The more developers you have, the higher the `bus factor `_, and the more likely the project is to survive. More contributors also means more new features and bug fixes. + +**Forks**: The number of times the git repository has been forked. This gives you an idea of how many people are attempting to modify the source code, even if they have not (yet) contributed back their changes. + +**Watchers**: The number of people watching activity on the repository. These are people who are interested enough to get notifications for every issue, PR, release, or discussion. + +**Stars**: The number of people who have starred the repository. This is not the best metric for number of users, and instead gives you a better idea about the amount of *hype* surrounding the project. + +**Issues**: The total number of open and closed issues. Although it may seem counterintuitive, the more issues, the better. Large projects like PyTorch have tens of thousands of open issues. This does not mean that PyTorch is broken, it means that it is popular and has enough issues to discover corner cases or open feature requests. + +**PRs**: The total number of open and closed pull requests. This tells you how active development of the project has been. Note that this metric can be artificially inflated by bots like dependabot. + +**Releases**: The number of software releases. The frequency of releases varies from project to project. The important thing to look for is multiple releases. + +**Commits**: The number of commits on the main development branch. This is another metric for how active development has been. However, this can vary a lot depending on whether PRs are merged with or without squashing first. + +**Core SLOCs**: The number of source lines of code in the core library, excluding empty lines and comments. This tells you how large the library is, and how long it would take someone to write something like it themselves. We use `scc `_ to compute SLOCs. + +**Test SLOCs**: The number of source lines of code in the testing suite, excluding empty lines and comments. This tells you how well tested the project is. A good goal to strive for is a similar amount of code for testing as there is in the core library itself. + +**Test Coverage**: The percentage of the core library that is hit by unit tests. This is especially important for interpreted languages like Python and R where there is no compiler type checking. 100% test coverage is ideal, but 80% is considered good. + +**License**: The license the project is distributed under. For commercial researchers, this may be very important and decide whether or not they are able to use the software. + +Downloads +--------- + +These are download metrics for the project. Note that these numbers can be artificially inflated by installs during continuous integration. They give you a better idea of the number of projects that depend on a library than the number of users of that library. + +.. csv-table:: + :align: right + :file: downloads.csv + :header-rows: 1 + :widths: auto + +**PyPI Downloads**: The number of downloads from the Python Packaging Index. PyPI download metrics are computed by `PePy `_. + +**CRAN Downloads**: The number of downloads from the Comprehensive R Archive Network. CRAN download metrics are computed by `Meta CRAN `_. + +**Conda Downloads**: The number of downloads from Conda Forge. Conda download metrics are computed by `Conda Forge `_. + +.. _torchvision: https://github.com/pytorch/vision +.. _GDAL: https://github.com/OSGeo/gdal +.. _TorchSat: https://github.com/sshuair/torchsat +.. _RoboSat: https://github.com/mapbox/robosat +.. _Solaris: https://github.com/CosmiQ/solaris + +.. _TorchGeo: https://github.com/microsoft/torchgeo +.. _eo-learn: https://github.com/sentinel-hub/eo-learn +.. _Raster Vision: https://github.com/azavea/raster-vision +.. _PaddleRS: https://github.com/PaddlePaddle/PaddleRS +.. _DeepForest: https://github.com/weecology/DeepForest +.. _SITS: https://github.com/e-sensing/sits +.. _segment-geospatial: https://github.com/opengeos/segment-geospatial +.. _GeoTorchAI: https://github.com/wherobots/GeoTorchAI +.. _Moonshine: https://github.com/moonshinelabs-ai/moonshine diff --git a/docs/user/downloads.csv b/docs/user/downloads.csv new file mode 100644 index 00000000000..e82a1048255 --- /dev/null +++ b/docs/user/downloads.csv @@ -0,0 +1,10 @@ +Library,PyPI/CRAN Last Week,PyPI/CRAN Last Month,PyPI/CRAN All Time,Conda All Time,Total All Time +`TorchGeo`_,"4,227","15,709","172,020","14,994","187,014" +`eo-learn`_,542,"2,224","119,657","29,806","149,463" +`Raster Vision`_,286,"1,446","53,029","2,211","55,240" +`PaddleRS`_,18,56,"1,196",0,"1,196" +`DeepForest`_,"2,429","11,092","686,997","48,368","735,365" +`SITS`_,128,728,"8,438","54,587","63,025" +`segment-geospatial`_,987,"6,088","64,067","8,226","72,293" +`GeoTorchAI`_,40,150,"2,210",0,"2,210" +`Moonshine`_,61,275,"6,243",0,"6,243" diff --git a/docs/user/features.csv b/docs/user/features.csv new file mode 100644 index 00000000000..f9dc1b00dbe --- /dev/null +++ b/docs/user/features.csv @@ -0,0 +1,10 @@ +Library,ML Backend,I/O Backend,Spatial Backend,Transform Backend,Datasets,Weights,CLI,Reprojection,STAC,Time-Series +`TorchGeo`_,PyTorch,"GDAL, h5py, laspy, OpenCV, pandas, pillow, scipy",R-tree,Kornia,71,43,✅,✅,❌,🚧 +`eo-learn`_,scikit-learn,"GDAL, OpenCV, pandas",geopandas,numpy,0,0,❌,✅,❌,🚧 +`Raster Vision`_,"PyTorch, TensorFlow*","GDAL, OpenCV, pandas, pillow, scipy, xarray",STAC,Albumentations,0,6,✅,✅,✅,✅ +`PaddleRS`_,PaddlePaddle,"GDAL, OpenCV",shapely,numpy,7,14,🚧,✅,❌,🚧 +`DeepForest`_,PyTorch,"GDAL, OpenCV, pandas, pillow, scipy",R-tree,Albumentations,0,2,❌,❌,❌,❌ +`SITS`_,R Torch,GDAL,-,tidyverse,22,0,❌,✅,✅,✅ +`segment-geospatial`_,PyTorch,"GDAL, OpenCV, pandas",geopandas,numpy,0,0,❌,✅,❌,❌ +`GeoTorchAI`_,PyTorch,"GDAL, pandas, xarray",Sedona,numpy,14,0,❌,❌,❌,🚧 +`Moonshine`_,PyTorch,-,-,numpy,0,3,❌,❌,❌,❌ diff --git a/docs/user/github.csv b/docs/user/github.csv new file mode 100644 index 00000000000..32a55c1c977 --- /dev/null +++ b/docs/user/github.csv @@ -0,0 +1,10 @@ +Library,Contributors,Forks,Watchers,Stars,Issues,PRs,Releases,Commits,Core SLOCs,Test SLOCs,Test Coverage,License +`TorchGeo`_,56,243,44,"2,010",366,"1,315",10,"1,720","28,942","15,488",100%,MIT +`eo-learn`_,40,288,45,"1,058",159,622,40,"2,439","8,135","5,915",92%,MIT +`Raster Vision`_,30,375,74,"1,950",687,"1,220",19,"3,416","20,965","8,339",86%,Apache-2.0 +`PaddleRS`_,22,83,12,311,68,112,1,643,"21,859","2,156",48%,Apache-2.0 +`DeepForest`_,13,154,15,409,368,206,43,650,"2,375","1,149",86%,MIT +`SITS`_,13,74,29,415,564,495,41,"5,720","22,770","6,162",95%,GPL-2.0 +`segment-geospatial`_,11,244,51,"2,453",102,82,22,156,"5,355",92,22%,MIT +`GeoTorchAI`_,4,31,13,431,22,20,1,207,"6,153",550,38%,AGPL-3.0 +`Moonshine`_,1,1,4,121,2,5,1,48,245,56,69%,MIT