Use Go-style return values for gocv functions that have result Mat

[willdurand]

When reviewing #135, I was like "wait, why is this test actually passing?". The test was about flipping a Mat into a brand new Mat, both passed to a function that looks roughly like this:

func Flip(src Mat, dst Mat, flipCode int) {}

In Go, parameters passed by value (default like above) should not be modified (and in any case, it will never change the value in the parent block). In gocv, this would works though because we manipulate a C pointer under the hood but this is a bit misleading.

Question is: could we agree on a "convention" stating that all arguments modified should be passed by pointer?

If we take the Flip() function as an example:

src := ...
dst := gocv.NewMat()

// wait, how does `dst` can be updated? No return-value either? Hmmm.
gocv.Flip(src, dst, 0);

// versus

// oh right so `Flip` takes a `src` Mat and puts the result in `dst`. Lovely <3
gocv.Flip(src, &dst, 0);

[berak]

imho, somehow, you've hit a spot on the general concept here.

the gocv wrappers all go like this(pun intended):

type someclass {
     p pointer_to_some_CGO_wrapper_around_some_cpp_implementation
}
func( src1, src2, dst someclass) {
     (do some op on dst.p, but it won't get reassigned !)
}

so, actually, whatever dst.p points to, will get changed, neither the go instance, nor dst.p.
(and taking the address of the go one, won't mend it.
hard to explain, hard to propagate that kind of knowledge to actual users (that would be my problem with it))

somehow, returning dst, instead of taking it by a (invisible) reference, like it is done in python, would be a better idea. (too late, too change it for all of the core bindings ?)

imho, it's already a problem in the underlying opencv c++ code, for further mindbending fun, have a look here, it's turtles, all the way down

[willdurand]

somehow, returning dst, instead of taking it by a (invisible) reference, like it is done in python, would be a better idea. (too late, too change it for all of the core bindings ?)

I think returning values would be indeed better.

[berak]

right, yet it still works, like it is, now (also it is close to the c++ version, which the current docmentation heavily relies on)

[deadprogram]

There was a discussion about this at some point on slack or something like that. The question is, should we be more like the C++ API (the current way) or more like the Python API (return a new Mat in function that has a 'dest' that the dev needs to close).

I am still not pulled either way with great conviction, the C++ style seemed the best at the time, but we could decide to change the interface. Seems like doing so sooner would be best if we are going to do so.

[deadprogram]

As I recall it was @221bytes that I was discussing this with on the Golang Slack channel.

In any case, we can decide to follow one of 2 approaches here:

• continue using the dst Mat assigned pattern as currently implemented. It does make it more like the C++ code, so the C++ docs would match up, but is a little different than the typical Golang code.
• switch to returning a new gocv.Mat for any returned values, more like how the Python code handles. It makes it a little less of a match to the C++ docs, but is certainly a little more like what go programmers expect.

I don't like to break the API, but this conversation keeps coming up for good reason. Seems like it would be better to be a little more idiomatic for Go.

To use the example above:

src := ...

// dst is now return-value is all cases that there is a Mat that is modified.
dst := gocv.Flip(src, 0);

There is, however, a use case that is handled by OpenCV's C++ interface that this would not accommodate, which is when the src and dst are the same, what openCV calls "inplace". There are a number of OpenCV functions which allow this, for example dilate. This is rather inconsistent, as only some OpenCV functions support this.

I am starting to get the feeling we should probably just ignore the inplace return assignment option and always return new Mat values from any functions that have an output. This would eliminate an entire category for potential confusion for the consumers of this package.

Ideally, I would like to hear from a few more community members before revamping the current API. But so far everyone has been in favor of changing to a more idiomatic Go approach of returning new values.

[willdurand]

continue using the dst Mat assigned pattern as currently implemented. It does make it more like the C++ code, so the C++ docs would match up, but is a little different than the typical Golang code.

I'd be OK with this if we could add pointers for arguments that are modified.

I don't like to break the API, but this conversation keeps coming up for good reason. Seems like it would be better to be a little more idiomatic for Go.

The good thing is 1.0.0 has not been released yet, so we can still BC break for good reasons.

I am starting to get the feeling we should probably just ignore the inplace return assignment option and always return new Mat values from any functions that have an output. This would eliminate an entire category for potential confusion for the consumers of this package.

I like this proposal a lot! I believe a package like gocv should provide a uniform/Go-oriented API on top of opencv. The current package is already good but this suggestion would make it even better.

(my 2cents)

[deadprogram]

I changed the title of this to match the change I am proposing. @berak @221bytes anyone else have any thoughts on this change?

[221bytes]

I remember this talk, you said it was easier to stick to the C++ API for documentation and ease of implementation. Indeed, as a total newbie, it was for me easy to contribute (very small contribution though) to the project.
Except the reason, we wanna do it the gopher way, what are the other pros of refactoring now?

[willdurand]

Except the reason, we wanna do it the gopher way, what are the other pros of refactoring now?

see my initial issue description, mutation happens by accident.

[221bytes]

By accident ? I can't understand what you mean sorry

[willdurand]

By accident ? I can't understand what you mean sorry

Go passes variables by value (copy) not by reference to functions. In Gocv, we should not expect dst to be modified after having called gocv.Flip(src, dst, 0) since dst is passed by value. Yet, it works because Mat only attribute is a C pointer. This is very misleading.

[221bytes]

Hum, the name his dest and every functions as a nice comment associated with it. I can't see how someone can be misguided to be honest. I am not a super user and it was clear for me. Refactoring all the library only for this purpose sounds a bit overkill to me.
Ron took this decision at the beginning and it's working for us. Sticking to the c++ api is nice for documenting and for moving code from c++ to golang so for me we should keep the way it.
Please remember that I was a supporter of a more golang style at first ^^