Clarify in documentation how input width/height and output width/height correlate

[mhulse]

Hello,

From the README:

smartcrop.crop(image, {width: 100, height: 100}).then(function(result){
  console.log(result);
});

Output:

{topCrop: {x: 300, y: 200, height: 200, width: 200}}

In terms of documentation and the above example, I think it would be nice to have a little explanation as to why the output's width/height values (200x200) are larger than the desired input's width/hieght (100x100 values).

Here's an example of desired input widths and heights and smartcrop's output widths and heights:

User-specified input WxH	Smartcrop output WxH	Output scaled to input width
2622x2660	1528x1550	2622x2660
2622x2660	1986x2014	2622x2659
2622x2660	2022x2051	2622x2660
2622x2660	2525x2561	2622x2659
2622x2660	3026x3072	2622x2662
2622x2660	3405x3454	2622x2660

I guess it just took me some exploration time to discover the correlation between the input and output dimensions. Clearly, and correct me if I am wrong, smartcrop is saying:

Based on your input image size, and desired crop area, the resulting relative crop area is (width) and (height) at coordinates (x) and (y). You must crop your image using smartcrop's output width, height, x, y, and then scale up or down to your desired width and height (using tool of choice, like ImageMagick or GraphicsMagick).

With that said, one issue I am running into is that the output numbers are not exact (as you can see above); maybe it should also be mentioned in the docs that if one wants an exact crop, they will have to account for rounding errors and use something like ImageMagick's ^:

....
-crop 3026x3072+100x200 \
-resize 2622x2660^ \
....

[jwagner]

Based on your input image size, and desired crop area, the resulting relative crop area is (width) and (height) at coordinates (x) and (y). You must crop your image using smartcrop's output width, height, x, y, and then scale up or down to your desired width and height (using tool of choice, like ImageMagick or GraphicsMagick).

This is correct. It seemed obvious to me but I guess it's not. I'll try to add some clarification in the next release. Thanks for sharing this.

[valerian]

Thanks @mhulse for your very helpful explanation, this was indeed not obvious at all, and this is the only place where I found some clarification.

However it's still not completely clear: does that mean that the width and height from the options are only there to provide an aspect ratio of the desired crop? Multiplying or dividing them does not seem to affect the result at all.

From experimenting it seems that the minScale and maxScale options, when they have their 1.0 default value, make the crop result always have either 100% of the width or 100% of the height of the original image.
Lowering them allows smartcrop to also try to return potentially smaller crop sizes.