description for "crop" directive in ngx_http_image_filter_module's document is not correct

[Homutov Vladimir]

On Mon, Oct 29, 2012 at 12:28:47PM +0400, Homutov Vladimir wrote:
> On Mon, Oct 29, 2012 at 11:47:02AM +0800, chen cw wrote:
> > Hi,
> >     we think the description for  "crop" directive in
> > ngx_http_image_filter_module's document is not correct, or at least not
> > clear. It says "proportionally reduces an image to the size of the largest
> > side". we have tested and now believes it should be  not "the largest
> > side", but "the smallest side".
> >
>
> Hi!
>
> The 'largest side' is related to the arguments of the 'crop'
> directive, not the source image size.
>
> With this in mind, the description is correct.
>
> For example,
>
> command 'crop 600x50' for source image 640x480 will:
>
> 1) proportionally reduce largest (600 - horizontal) side: 640->600
> 2) crops extraneous edges by another side - vertical: 480->50
>
> the result is that image got reduced horizontally a bit (proportionally)
> and cropped by vertical side (50 center pixels left).
>
> command 'crop 600x50' for 480x640 image will give 480x50:
>
> 1) proportionally reduce horizontal side (no actions, 480 < 600
> requested)
> 2) leave 50 center pixels on another side
>
> command 'crop 50x600' for 640x480 image will give 50x480:
>
> 1) largest side is 600 (vertical), no actions (requested 600 < 480
> actual)
> 2) another side is cropped to 50 pixels.

actually, things are a bit more complicated:

what is important, it is the correlation between width/height ratio
of the source image and the desired size.

The 'largest side' phrase is misleading, as ratios are
compared, not sizes; thus largest ratio is important, not side.

The effect is that crop chooses dimension (width or height) to be
resized to reach the best fit of source image in the destination frame.

if the source image has w/h ratio less than requested frame, it will be
proportionally resized up to new width and extra height will be cut.

if the source image has w/h ratio greater than or equal to requested frame, it
will be proportionally resized to the new height and extra width will be cut.

Example:

#    source image:640x480    (w/h = 1.333)
image_filter crop 320 250; # (w/h = 1.28)

since 1.33 > 1.28, source image is resized up to desired height
first (333x250) and then extra width cut (320x250).