Licensing question for imglib-algorithm addition

imglib2
licensing
bonej
Tags: #<Tag:0x00007fd53f93fa50> #<Tag:0x00007fd53f93f820> #<Tag:0x00007fd53f93f500>

#1

Hi,

I want to add some code to imglib2-algorithm for fitting (hyper-)ellipsoid to point clouds. I currently have this in a private project, but I think it would be generally useful.
There are some potential licensing issues:

  1. I adapted some code from BoneJ (GPL) which is in turn adopted from a matlab script that is under BSD.
    @mdoube, would you be ok with me adding this https://gist.github.com/tpietzsch/a7323b5abee7973251a99eaba0afd3d5 to imglib2-algorithm under the BSD license? If it’s not ok, then I would go and re-implement it from scratch solely based on the matlab script.

  2. I adapted some C++ code for computing the distance from a point to an ellipsoid, which is under the Boost license. As far as I can see, this is compatible to BSD. Do you think it is ok, if I just refer to the original C++ code and Boost License in the javadoc (which would look like this https://gist.github.com/tpietzsch/5889189fac9e3904d429d4c651c302ba)? Maybe add the Boost License text file to the respective package, or the complete Boost license to the class javadoc? Maybe someone who has more insights into licensing than me could comment? @ctrueden maybe?

best regards,
Tobias


#2

Hi @tpietzsch,

Yes, please go ahead and reuse my code, which is a direct Matlab->Java port & don’t waste your time doing this chore again!

Use whatever licence you like for the derivative work. Ripping out generic bits of BoneJ code for reuse in lower-level libraries is one of @rimadoma’s main tasks at the moment, so you are really doing us a favour by handling this. There are a few other generic libraries in BoneJ (e.g. circle and sphere fitting) that would benefit from similar treatment, if it would be helpful for imglib2. If you are getting into ellipsoids in particular, I wrote an Ellipsoid class which does lots of ellipsoidy things, that you might also find useful.


#3

@mdoube thanks!
I’m working towards a PR for this now on this imglib2-algorithm branch
I have currently a HyperEllipsoid class with only the bare minimum functionality. We might add other useful stuff from BoneJ Ellipsoid later.


#4

While you are at it, would you consider including a ‘goodness of fit’ measure? It would be really helpful. I found a couple of references to measuring distances from points to ellipsoids, which I guess is what is needed to calculate residuals for a correlation calculation:

The long way and the short way

If there’s a quicker way to estimate correlation coefficient than this then please let me know.


#5

I think it’s fine to include the text of the Boost license in a NOTICE.txt file. Usually that’s what I do when there are differently-licensed third-party projects which we adapt or build upon. (Of course: IANAL)

According to tl;drLegal:

You must include the original copyright and this license in software

And from the full license:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software

Whereas the BSD-2 license says:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

And the MIT license says:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

So the Boost license appears a little more stringent to me (“must be included in all copies of the Software, in whole or in part”). If you want to be totally thorough, you could put it in the copyright header of every single source file, but doing that well is a real pain. So personally I would vote for the NOTICE.txt approach, the same as I personally would do with BSD or MIT base code. The pragmatic question is really whether anyone will get sued, and if you include the notice there, I highly doubt there will be any problems or misunderstanding.

Actually, I do sometimes also put the license blurb near the top of source files which were specifically adapted—since usually, the project only has a few files adapted in that manner, versus most other files written from scratch. If you do that (and I think it would be a good idea), I would suggest putting the blurb below your normal blanket license, so that the License Maven plugin can still easily do its job, without disrupting the Boost license portion beneath.


#6

I’m currently working on the Anisotropy command of BoneJ2, where I need ellipsoid fitting. Thus I will rewrite the “Yury Petrov” algorithm as an Op. The method seems to be based on this article. My refactoring of the code will be released under the standard BSD-2 licence (with the blessing of @mdoube), so any reuse is A-ok.

As a side note while the algorithm is adequate for our purposes, it does have two caveats:

  1. The quadratic surface solved may not, in fact, be an ellipsoid
  2. Sensitive to far away outlier points

#7

You have it.

You could use BoneJ’s Ellipsoid class to check whether the function is an ellipsoid or not - actually I see it is missing simple input checking in the constructor methods which is a bit dangerous and poor form on my part: @alessandrofelder could add some checks to make sure that junk inputs don’t result in ‘not-ellipsoids’ being instantiated, as part of his next project.

That’s a bit trickier; I wonder if there’s a way to calculate the residuals and optionally filter out the nth percentile to reduce this artefact?


#8

I found an easy way to check this, namely: “-- signs of the eigenvalues (diagonal elements of DD) determine the [quadric surface] type. If they are all positive, it is an ellipsoid; --”.


#9

Excellent - please feel free to implement. Maybe worth including as a consistency check in case cumulative operations on an Ellipsoid break it and turn it into a mutant non-ellipsoid quadric.


#10

Also - I see that it may be possible to construct an Ellipsoid with negative radii or totally junk eigenvectors…

See the preceding constructor which does do a little bit of input checking.


#11

Hi again,

I have now implemented the ops needed for ellipsoid fitting. First, there’s SolveQuadricEq, which solves the equation of a quadric (quadratic surface) which best fits the point cloud. Then there’s QuadricToEllipsoid, which tries to reverse-engineer the properties of an ellipsoid from the equation, and returns Optional.empty() if it’s unable to do so.

I’m planning to add these ops to imagej-ops or create a new module imagej-linalg-ops with them. @tpietzsch Maybe this is something I could discuss with you in Dresden? Which linear algebra library to use, how to get this stuff working in your code (if still relevant) etc.

@mdoube I’m putting the outlier filtering in the backlog for now. At least in our use cases I don’t think there will be massive outliers, but writing this forum post made me think the sensitivity to them is something I should document in the comments of the ops. Either the filtering becomes its own op, an optional parameter in the solving op, or just a few lines at the wrapper level.

Best regards,
Richard


#12

@rimadoma That would be great, yes! I haven’t looked at this for a long time because I wasn’t acutely needing it anymore but it would be fantastic to finally have this done. Finishing it at the hackathon sounds good!


#13

A goodness of fit measure would be helpful too, while you are at it.


#14

Thanks for the reminder, I will add that to the backlog.