Severe insufficiencies in the documentation of Connected Components Segmentation
It is impossible to use the application Connected Components with the current documentation. If this documentation is not going to be improved, it would be better to remove this application from the package or at least label it as "severely under-documented": in its current situation, the user just wastes time trying it and never gets any meaningful result.
Yannick recognized in Feb 2020 (https://forum.orfeo-toolbox.org/t/segmentation-bias-towards-rivers/563/3): "OBIA expressions are not very well documented in OTB" (they are actually not documented at all) and said he was "going to open an issue to improve documentation of this application". I have not been able to find any issue related to this in GitLab, so I'm doing it here.
In the same message, Yannick could just suggest https://wiki.orfeo-toolbox.org/index.php/Connected_component_segmentation_module a page that was last modified on 14 March 2013 !!! (BTW, where is the nice interactive GUI that is reproduced on that page?)
Problems I have found in the documentation (https://www.orfeo-toolbox.org/CookBook/Applications/app_ConnectedComponentSegmentation.html?highlight=connected):
- "For instance, expression “((b1>80) and intensity>95)” will merge two neighbouring pixel in a single segment if their intensity is more than 95 and their value in the first image band is more than 80. See parameters documentation for a list of available attributes"
- Where is "intensity" defined? Is it the sum or the mean of a given pixel across all bands?
- Where is the "parameters documentation" that the user is supposed to consult?
- Regarding OBIA, the only documentation is
OBIA Expression -obia string
OBIA mathematical expression
along with the example:
"-obia "SHAPE_Elongation>8"
Where is the documentation on valid OBIA expressions?
Problems I have found in the wiki page (https://wiki.orfeo-toolbox.org/index.php/Connected_component_segmentation_module)
- The wiki page refers to the ITK Software guide for the "computed attributes". Considering that such a guide is a 985 pp document, at least the appropriate section should be stated. Actually, I have ve not been able to locate any info related to these attributes in that guide...
- The wiki page states "intensity of each pixel is accessible by intensity (arithmetic mean of pixel band)." This definition is likely to be wrong, I understand the author meant "intensity of a pixel = mean(b1, b2, b3...) for that pixel", so I understand there is a missing "s" in the writing
"(arithmetic mean of pixel bandS)": with no final "S", intensity would be understood as the average of a given band over all pixels. Sometimes a single "s" may mean a lot, and a formal notation would be less ambiguous. - The wiki page states: "intensity_p1 (intensity_p2) : mean intensity of first pixel (resp. second pixel)."
- What is meant by "first pixel"??? first of what?
- The wiki page states: "pXbY : Band Y value of pixel X."
- How is "X" stated? An example is required here.
- The wiki page states: "spectralAngle : Spectral angle between adjacent pixels (first pixel is set as reference)."
- is it really spectral angle or its cosinus? if angle, radians? degrees?
- "SHAPE_Flusser01" to "SHAPE_Flusser11" appear in the wiki page, what is that???