Better documentation for Exiv2::lensName ?

[agriggio]

The API docs for Exiv2::lensName simply state that the function:

Return the name of the lens used.

However, it seems that the function is supposed to work only for "vanilla cases" (source: https://discuss.pixls.us/t/lens-spec-display-bug/30301/16) and only under somewhat simplistic assumptions, which might result in incorrect names in some cases. Would it make sense to add a warning about this in the docs?

Thanks!

[hassec]

I guess adding a sentence or two can't hurt. How about something that explains that this is information that is not just read from the file but needs to be reconstructed based on a good deal of other metadata found in the file, and thus can't always be determined correctly?

[agriggio]

Something like this?

Please note that this function uses some heuristics to reconstruct the lens name, which might involve combinig information from multiple tags and interpreting numeric codes. While the heuristics try to cover most cases, they can't be perfect and might fail in some circumstances, leading to imprecise results

[hassec]

I think that's a reasonable addition, WDYT @piponazo ?

[kmilos]

IMHO, the warning shouldn't be limited to lensName() only, but all of easyaccess API - there's ISO and other data we try to pull out (or somehow deduce/calculate) from "most usual/known" MakerNote places, but can't really guarantee it is done 100% correctly.

E.g. "These accessors are provided for convenience only and will return expected/desired metadata most of the time. However, there might be specific cases where you will want to use lower level Exiv2 API functions to access targeted Exif tags and/or MakerNote fields for more specific processing, like e.g. non-trivial lens identification."

[norbertwg]

According to my understanding, lens name is a specifc problem in easyaccess API. In general the rule in easyaccess API is to check several tags for one topic like ISO until one filled tag is found and then its value is returned. In this approach the potential gap is, that a maker specific tag is not considered in the implementation. If this not considered tag was the only one in the file, which was filled, the API will return no value. This can also happen with lens name, but additionally it may happen that the rules return a wrong value - which is worse than returning no value. As I just recently started to pariticpate, I am not sure, if my understanding is correct. If it is correct, we should differentiate between lens name and other parts of easyaccess API so that users have a better understanding what can be expected and do not get too much wrong doubts about the return values from exiv2. Could you please tell me where you intend to enhance the documentation. Then I could suggest a congrete wording.

[postscript-dev]

@norbertwg As far as I know, there are three places where the EasyAccessAPI is written about.

1. [The project API docs on exiv2.org](https://exiv2.org/doc/namespaceExiv2.html#a00abed868b1cd46fdeb8ab331af246cd]. When the website is updated the text is automatically generated from the comments in https://github.com/Exiv2/exiv2/blob/main/include/exiv2/easyaccess.hpp .
2. [The Exiv2 Wiki](https://github.com/Exiv2/exiv2/wiki contains a larger explanation of the feature.
3. samples/easyaccess-test.cpp has a practical example.

[norbertwg]

Thanks for links. My suggestion: In Wiki after example in Overview:

Please keep in mind that these accessors are provided for convenience only and will return expected/desired metadata most of the time. The accessors check several Exif tags and/or MakerNote fields, but in rare cases this list of fields checked may not be complete (e.g. if a maker writes a new tag) and then nothing is returned. So there might be specific cases where you will want to use lower level Exiv2 API functions to access targeted Exif tags and/or MakerNote fields for more specific processing. Please note also that lens name function uses some heuristics to reconstruct the lens name, which might involve combinig information from multiple tags and interpreting numeric codes. While the heuristics try to cover most cases, they can't be perfect and might fail in some circumstances, leading to imprecise results.

The above text could be added in the begin of https://github.com/Exiv2/exiv2/blob/main/samples/easyaccess-test.cpp as well.

For the API documentation I think we should take a shorter text, e.g. for ISO speed: //! Return the ISO speed used to shoot the image. Please keep in mind that this accessor is provided for convenience only and will return expected/desired metadata most of the time.

For lensname: //! Return the name of the lens used. Please keep in mind that this accessor is provided for convenience only and will return expected/desired metadata most of the time. Please note also that lens name function uses some heuristics to reconstruct the lens name, which might involve combinig information from multiple tags and interpreting numeric codes. While the heuristics try to cover most cases, they can't be perfect and might fail in some circumstances, leading to imprecise results.

If you agree to this wording, I volunteer to do the needed typing work and provide a pull request.

[norbertwg]

@kmilos I had a look into https://discuss.pixls.us/t/lens-spec-display-bug/30301/16. Are you involved in the developing of ART? Then perhaps following hint could help: In my application I also use the easyaccess API. Some time ago I noticed, that one lens was shown wrong. My error was that I called MetaDatum::print without argument. This worked fine for many lenses, but for one not. Perhaps in ART is the same problem.

[kmilos]

@norbertwg No, just lurking around, more actively contributing to darktable in fact... But thanks!

[norbertwg]

Long time until I have again some time for exiv2 ... As I see no objections against my suggestion, I started to prepare a pull request and noticed a problem: I do not see how I can change the text in Wiki and assume this needs to be done by someone else.

[norbertwg]

The code changes are merged, but so far I did not get a response regarding the suggested changes in Wiki. Anybody who can help on that?