Parameters for extract are ordered unintuitively

[papandreou]

The other day I spent a long time wondering why I couldn't get extract to do the right thing, only to find out that it wants top, left, width, height, whereas I intuitively put left, top, width, height. It works according to the documentation and all, but somehow I just assumed it would be X-Y-X-Y, and certainly not Y-X-X-Y.

I realize it'd be a hard thing to change, but I just wanted to check whether it's intentional? And if it's not, I move that extract is deprecated in favor of a differently named method that takes the parameters in the "correct" order ;). Mostly to save new users from the gotcha.

[lovell]

Hej Andreas,

The underlying vips_extract_area method accepts (left, top, width, height) so you are definitely not alone in thinking that, intuitively, the parameters should be in that order.

Perhaps the extract method could be modified to (also) accept a single Object parameter with left, top, width, height as keys?

@brandonaaron originally implemented the much-requested extract feature in 83b72a1 so also may have relevant comments or suggestions.

[papandreou]

Perhaps the extract method could be modified to (also) accept a single Object parameter with left, top, width, height as keys?

That could be a fair compromise, except that none of the methods with similar purposes take options objects (resize, rotate, crop etc.). That could be fixed, of course.

I'm mostly concerned with the long time effects of having the weirdly ordered extract around in any shape or form. As long as it's there and documented, I predict that users to waste time figuring it out. I still think deprecating it, undocumenting it, and introducing a new method (cut, shave, zoom, ...) would be the best long term solution. Or maybe crop can be overloaded to also support 4 numbers, if that's not in conflict with any future plans for that method.

[brandonaaron]

It seems really obvious after reading this that it should definitely be in that order. At the time I didn't think much of it. I just followed the example api laid out in this comment without really thinking about it.

Another potential name for a replacement is isolate. However, I wonder if a new method would be more confusing than just making the method take an object. I think I'd vote for just documenting the oddity of argument order and have it take an object.

[lovell]

Thank you both and sorry for not spotting this anomaly with extract sooner; API design is tricky.

In the current API, methods refer to both the what and the how. Switching to fewer methods (the what) that accept a related Object of parameters (the how) will more closely match libvips and should hopefully help expose more of its features. I realise this might make things inconsistent, at least in the short term.

Breaking API changes are also under discussion at #241 - please do get involved there too.

[papandreou]

Added support for the options object over at #308 as that seems to be the pragmatic solution. Closing this issue.