@gselzer So far I like the document and it helps me understand the "gap" that SciJava Ops will fill in the image algorithm space. What I would like to see added to the document at some point is some text that helps soften the blow of the (from my perspective) unusual syntax of a SciJava Op call (i.e. ops.op("filter.gauss").arity2().input(Img, 3.0)). Specifically, I'm expecting people to really be thrown off on why they need to specify the input arity for their Op call. Some text that says "this is why we do this and why its best" would be great!

@elevans thank you for taking a look.

What I would like to see added to the document at some point is some text that helps soften the blow of the (from my perspective) unusual syntax of a SciJava Op call (i.e. ops.op("filter.gauss").arity2().input(Img, 3.0)). Specifically, I'm expecting people to really be thrown off on why they need to specify the input arity for their Op call.

Yeah, that's needed, although we might argue that it is better to put that discussion elsewhere. Is there not something like that in the Calling Ops page of the documentation?

Some text that says "this is why we do this and why its best" would be great!

I don't think I can write this well, having been an opponent of this change. @hinerm or @ctrueden I would really appreciate if one of you could write this section because as proponents of this change you may be able to better convince users that it is worthwhile.

What I would like to see added to the document at some point is some text that helps soften the blow of the (from my perspective) unusual syntax of a SciJava Op call (i.e. ops.op("filter.gauss").arity2().input(Img, 3.0)

I don't think I can write this well, having been an opponent of this change. @hinerm or @ctrueden I would really appreciate if one of you could write this section because as proponents of this change you may be able to better convince users that it is worthwhile.

You do not need to say ops.op.arity - you can write ops.binary. As I said here, separating arity and input type to two steps in the builder gives you an additive number of choices to make, and you never see more than [max arity] options at a time, while combining them in a single step gives you a multiplicative number of choices.

And as @ctrueden wrote, this API is Java-developer-focused (e.g. programming from an IDE). We can write convenience layers on top for python/scripting for users, as needed.

I vote against API-level documentation or explanation in this philosophy document.