No python modules, just scripts?

[jannik-el]

Hey there, nice repo looks great if it works - problem is I can't quite figure out for who you've developed this for haha...

I mean I absolutely understand the use case, that's why I'm hear, I have some underwater videos that I want to transform into a mosaic, and openCV stitching only gets you so far.

And when I saw this library and found it as a pip library I expected like every other python library this would allow me download some python modules which I could use to do some form of mosaic-ing (or whatever you want to call it). However that is not the case, since everything is run over args in scripts, and to use the code it is expected to download the pip library, and the repo?

IDK it feels like someone did a great job developing some scripts for their class at DTU and then someone else said "hey we could make a public library out of this" and then created a repo and just uploaded some helper functions to pip. Which is fine - just don't put it on pip then unless its a proper python library.

The repo documentation and pip documentation is also more geared towards someone who has never used python before (which I know is the case for many marine biologists), with exercises to teach people? I mean its obvious this was taken from a DTU course. And thats fine I get this has to start from somewhere, it just irritates me that this was released and it feels like never really completed, yet still comes up as the top library when you search for underwater video development library in python.

So let me make you a proposition: I'm a student in Denmark as well, at the IT University of Copenhagen, and I also work for DHI so DTU Aqua isn't a very distant party (which has zero effect on the collaboration online, its just worth mentioning). If there is a serious intention to complete this library then I will be happy to help develop this into a proper library, and add some more modern techniques such as the Deep WaveNet UW-Image Enhancement transformation, among others. Mainly because I would like to use this library, and it contains tools which are absolutely needed.

If there isn't any intention on continuing the development then I'll branch it off and create a new library - I'd rather not do that though. So let me know what the situation is.

[FletcherFT]

Hi @jannik-el , Main maintainer here. Thanks for your feedback and glad to hear folks are interested in the subject. Projects like this one are rarely ever completed, they are just due. So it's great to receive suggestions from end-users or other devs to keep them alive. I find it a bit difficult to decide what is actionable here in your issue, perhaps you could reply with what specifically is unfinished so I can tag this issue for road mapping.

I agree that the documentation is not geared for developers looking to integrate mosaic-library into their projects, you're bang on the money that the README was intended for aquatic sciences students to quickly get their heads around image processing, registration and homography transformations. Though the project itself was originally intended for low-cost benthic mapping. We are in the process of publishing an article about the library.

Under the hood you'll find most of the library features are implemented as modules that allow devs to implement their own mosaicking. The mosaic module is intended as an implementation using the other modules, so it could be here where you are left wondering where the libary is.

• [x] preprocessing: functions for correcting images.
• [x] registration: functions for extracting and matching features in image pairs.
• [x] transformations: functions for computing homography transforms (rigid, similarity, affine, and perspective), as well as applying them.
• [x] utils: functions for parsing command line usage, class for video playback, and utility functions for reading in camera orientation data.

Are any of these modules properly documented? No. Sorry about that. There is future work planned to refactor the README for essential build and install instructions and a wiki that will include both library API reference and the current README demonstration examples.

Is this project under active development? Yes. Just not publicly released at this time.

What is the roadmap? Right now we are focussing on:

• [ ] Performance: Features and refactoring to improve mosaicking speed and memory usage.
• [ ] Accuracy: Features (such as loop closure detection and bundle adjustment) to correct the homography chain.
• [ ] Project structure: refactor of project layout to be more in-line with standards and to bring in CI/CD features.
• [ ] Testing: aiming for complete coverage, but this is a lofty goal with one dev.
• [ ] Documentation: Wiki and API references.

Other points that aren't on the roadmap (yet):

• [ ] Refactor mosaic.py: divide the script into classes and functions that can be implemented in dependent projects.
• [ ] Refactor calibration.py: divide the script into classes and functions that can be implemented in dependent projects.

Thanks for the collaboration offer and we're happy to engage with you at any level. We're MIT licensed and welcome open development. If you want to just keep it to a github level: we are very much open to pull requests and suggestions for further development in separate issues. Otherwise for more involved collaboration: you can contact me or the author listed on the pypi project via email.

[jannik-el]

Hey @FletcherFT - amazing that sounds really good to hear.

I absolutely understand where you are coming from and it's great to hear that there is continued development underway! I saw the roadmap in the readme and I also understand why you have chosen these, I see that they are in line with submitting a research paper.

As an end-user/developer I would be more interested in the refactoring of the scripts such that they can be applied.

I'm a bit swamped right now but mid june I'll create pull requests which refactor mosaic and calibration.py so they can be reused in a more module like way. I'll also create a documentation pull request to add more info to the readme for developers - I need to spend some time figuring out exactly how your preprocessing, registration and utils modules function, so I may as well note down a description of that on the way. Although I'm considering if it is maybe best to add docstrings to the functions, as to best enable a future form of automated documentation? Up to you.

I also suggest that you create a specific outline of what the intended purpose of this repo/library is. I think the scope is getting quite wide right now and partially away from the underwater mosaicing toolkit - idk maybe that's just my impression, difficult for me to gauge.

As I understand it, mosaicing is a central focus, and the other kits and features are added on top as tools (such as the UW-image enhancement). I would just be careful not to become another openCV wrapper and focus on the uniqueness of the mosaicing and underwater images - for example sharpen_image in preprocessing. Great as a feature for ease of use but as a developer I would rather just implement that my self using a specified kernel unique for my data.

I hope that gives a good outline? Lets continue this discussion, I am really interested in continuing the development of this library. Also you should consider presenting it at the Marine Imaging Workshop maybe? https://miw2024.org/