Improvement of the Python API documentation

[bmartin]

Hello,

I just started my first scripts in Python for Photoscan and I find searching through the Pdf API documentation very difficult. 

If the PhotoScan Python Reference Pdf were structured just like the Agisoft PhotoScan User Manual with a hierarchical menu linked to the different document sections, it would be very easy to use (see attached snapshot).  It's present lack of structure makes it very frustrating to use, if not almost useless.

Is it something that you could improve easily?

[Gall]

While I second this request, I would add that improving the content of the documentation is also mandatory.

At the moment, function and attribute descriptions are nearly nonexistent and most of the time you have to ask how something should be used, has changed or should behave. It's a lot of wasted time for everyone.

For example:

• Added Chunk.buildDepthMaps(), Chunk.importPoints(), Chunk.refineModel() and Chunk.removeLighting()
  methods

buildDenseCloud: Generate dense cloud for the chunk.
buildDepthMaps: Generate depth maps for the chunk.

I would never have seen that the dense cloud step has been split in two parts if I had not randomly seen a post about "why dense cloud step doesn't work anymore". No mention, no description of what is required prior to use each method, nothing (the quote is the complete documentation for the two methods).

This is a pity that the Python API does not receive more attention while it is, in my opinion, one the greatest strength of Photoscan.

[n@sk]

Well said, Gall.

[jedfrechette]

I'll add a +1 for better API docs.

The current pdf documentation is extremely difficult to use.

Online documentation based on something like Sphinx, which Read the Docs uses, would be very much appreciated.

Certainly improving the content as well as the presentation would also be well received as much of it is currently a bit terse and cryptic.

[SAV]

+1

Agree with Gall.

[Yoann Courtois]

I agree that API doc would need improvement, as there is still some inconsistencies since 1.3 major API update.
As far as I remember some commands are somewhere described with old parameters (I mean parameters used until 1.2.6 version), which then need us to search through the forum to get the right syntax.

But on another hand, reading the second half of Gall post bring me out in a rash. Please be believable while posting here :
First of all, Depth maps are well display in PhotoScan User Doc.
Then, I would think that before going through Python Scripting, a quite deep study of basic workflow is needed. Hours of dense cloud calculations would have, I hope, allowed you to have a look at the log, or even only to the process window, where dense cloud process is well cut in two parts : Depth maps reconstruction and Dense cloud generation...

Regards

[Gall]

I think you don't understand how an API documentation is supposed to be used. You're not supposed to only list all the signatures and expect the user to study thousands of lines of logs to match procedures to specific functions for every release. That is of course in the case that you don't want to waste that user's time and the time of every other persons (support included) that will have to help him.

I don't complain about missing functions/classes but about having a more complete documentation.
Then, studying the basic workflow is irrelevant here. I took this example because the change log is missing some important information, mainly that the function was split in two distinct functions. That is a big information that Python API users need to notice right away, not after N system failures, not after 48h hours of tests and digging to see if any part has been altered in any way.

That is something that every developer realizes the hard way when you have to rely on more than one software and library.

To actually add to this, this problem is way beyond the scope of your answer because there is some script procedures that may not be inferable by just knowing the complete GUI workflow and looking at the log. It is always frustrating to waste days trying to script a basic behavior available through a single menu and realize that this is either not possible or crash the software, fill a bug report and wait months while this bad behavior was present for several releases because no one had the courage to do it before because they are no Python expert and could not penetrate a very obscure documentation.

Please don't take it personally if I may sound harsh.

[Yoann Courtois]

Hi Gall,

No problem, I understand your point of view
I just pointed out that your example makes no sense :

Indeed good API doesn't required the user to go deeply through GUI workflow.
But "N system failures and 48h of test" to understand that depth maps are missing for dense cloud generation demonstrate basically a lack of photogrammetric knowledge.

We clearly have a consensus that PhotoScan API needs a deep rewriting, but I regret your example didn't give a good credibility to this topic

[Gall]

Well, I understand this is a matter of where photogrammetry sits in your workflow. In mine, this is just a small brick that have to be used by many people working on interpretation or later methods (and they can't afford to spend too much time on pre-processing because there is a lot of projects) so this exaggerated case could actually happen (because automation).

What you call a lack of credibility comes probably from the fact that you may not have a big pipeline around Photoscan. Spending a lot of time making sure a system will not perform a worst case scenario doesn't mean it cannot happen.

Now, if this is not a problem in your case that's good for you.