Show Posts
1
Python and Java API / Please make the API more stable
« on: October 19, 2022, 05:02:51 AM »
One of the best things about Metashape is that it offers a complete Python API. However, that API is unnecessarily frustrating to use for 2 main reasons:
The first is documentation, which although it exists is rather minimal and very difficult to navigate due to being delivered as a pdf with no useful table of contents. An interactive webpage similar to docs.python.org would be much easier to use.
The second big cause of frustration is how much churn there is in the API. Right now while looking at the 2.0.0 changelog I see this:
and can only imagine how much pain that is going to cause people who don't have their scripts version guarded. Now arguably, this is a major release so it is the right time to make these kinds of breaking changes. However, it seems like these kinds of breaking changes happen in almost every new version, including minor X.X.1 patch releases. For example 1.7.4 includes `Renamed ClusteringMethod enum to ClassificationMethod`. Searching for "Renamed' yields 177 hits in the changelog and that's just the beginning as there are many other breaking changes that were documented in other ways, i.e. removal of methods and functions, changing default arguments, and sometimes completely changing the way a method or function behaves.
Agisoft doesn't even attempt to keep their own example scripts up to date. When 1.8.0 was released, it appears they simply bumped the version number check on all the scripts in their example repo,
https://github.com/agisoft-llc/metashape-scripts/commit/e964870c639a66d76d05627cb76af8c7d5dbf7bd
without actually updating the scripts for any of the changes in that release and as a result many of those scripts have probably been broken for months.
Which brings me back to documentation. Because the written documentation is so sparse the best way to learn the Metashape API is via examples and experimentation. However, because the API is constantly changing many of the examples, both in public repos and in snippets on this forum are out of date and it is often difficult to figure out how to port them to the current API. That leaves experimentation, which is often needlessly time consuming and frustrating.
My 3 suggestions for how to improve this situation would be:
Please consider these suggestions to improve the stability and user friendliness of Metashape's API. I love the fact that Metashape provides such a detailed API, and we likely wouldn't be users if it didn't, however, its instability is a major hinderance and greatly reduces our ability to test and deploy new versions of the software.
The first is documentation, which although it exists is rather minimal and very difficult to navigate due to being delivered as a pdf with no useful table of contents. An interactive webpage similar to docs.python.org would be much easier to use.
The second big cause of frustration is how much churn there is in the API. Right now while looking at the 2.0.0 changelog I see this:
- Renamed PointCloud class to TiePoints
- Renamed DenseCloud class to PointCloud
and can only imagine how much pain that is going to cause people who don't have their scripts version guarded. Now arguably, this is a major release so it is the right time to make these kinds of breaking changes. However, it seems like these kinds of breaking changes happen in almost every new version, including minor X.X.1 patch releases. For example 1.7.4 includes `Renamed ClusteringMethod enum to ClassificationMethod`. Searching for "Renamed' yields 177 hits in the changelog and that's just the beginning as there are many other breaking changes that were documented in other ways, i.e. removal of methods and functions, changing default arguments, and sometimes completely changing the way a method or function behaves.
Agisoft doesn't even attempt to keep their own example scripts up to date. When 1.8.0 was released, it appears they simply bumped the version number check on all the scripts in their example repo,
https://github.com/agisoft-llc/metashape-scripts/commit/e964870c639a66d76d05627cb76af8c7d5dbf7bd
without actually updating the scripts for any of the changes in that release and as a result many of those scripts have probably been broken for months.
Which brings me back to documentation. Because the written documentation is so sparse the best way to learn the Metashape API is via examples and experimentation. However, because the API is constantly changing many of the examples, both in public repos and in snippets on this forum are out of date and it is often difficult to figure out how to port them to the current API. That leaves experimentation, which is often needlessly time consuming and frustrating.
My 3 suggestions for how to improve this situation would be:
- Follow semantic versioning, i.e. given a version number MAJOR.MINOR.PATCH, backwards compatibility can only be broken in a MAJOR release.
- Test that provided example scripts are compatible with the currently released version. This will help users stay up to date on best practices, while helping assure that point 1 is being adhered to.
- Move written documentation to a more usable platform than the pdf currently provided.
Please consider these suggestions to improve the stability and user friendliness of Metashape's API. I love the fact that Metashape provides such a detailed API, and we likely wouldn't be users if it didn't, however, its instability is a major hinderance and greatly reduces our ability to test and deploy new versions of the software.
