Add support for clipping/cutting out (#435)

[kleisauke]

Usage: overlayWith('overlayimage.png', { cutout: true } )

Only the API Docs and changelog needs to be updated. Test cases are included.

Thanks to @jcupitt for the help provided here.

[lovell]

I think dstHasAlpha will always be true as there's logic elsewhere to ensure the presence of an alpha channel.

[kleisauke]

You're right. https://github.com/lovell/sharp/blob/master/src/pipeline.cc#L448-L455

[lovell]

Fantastic, thank you for this Kleis. It's always a pleasure to see tests and I'm happy to update the docs etc. I've added a few comments inline.

[coveralls]

Coverage decreased (-0.2%) to 98.462% when pulling 6130f24 on kleisauke:feature-cutout into 4f3262c on lovell:master.

[coveralls]

Coverage decreased (-0.2%) to 98.462% when pulling 6130f24 on kleisauke:feature-cutout into 4f3262c on lovell:master.

[lovell]

Updates look great, thank you.

"What will be the best option? Will there be any difference in the image if we don't pre-multiply it?"

I think the best approach is to avoid premultiplying the image to be overlaid, assuming there are no other reasons for shouldPremultiplyAlpha being set to true, when using cutout.

This will avoid (a) a performance hit, (b) a source of rounding/clipping errors, and (c) potential light/dark artefacts at the "edges" of what was the discarded alpha channel.

[jcupitt]

A general Porter-Duff compose operator could solve this problem too. vips will need PD at some point.

[lovell]

@kleisauke Would you like to remove the premultiply logic here or would you prefer I take a look?

[kleisauke]

@lovell I already did that. See: pipeline.cc#L463-L464 and pipeline.cc#L698-L700.

[lovell]

@kleisauke You are absolutely correct - sorry I completely missed that. Thank you again for adding this very useful feature!

[kleisauke]

@lovell No problem! Thanks for merging the pull request! 👍