REST API: Add batch image editing

[ajlende]

Moving over from ​WordPress/gutenberg#23369 since changes are now only in core.

This proposes a new API for image editing that should be more flexible and extensible than the existing API. The new API can take an array of modifiers that will be applied in the order they appear.

Trac ticket: https://core.trac.wordpress.org/ticket/52192

See: ​https://github.com/WordPress/gutenberg/pull/23369

This proposes a new API for image editing that should be more flexible and extensible than the existing API. The new API takes an array of modifiers that will be applied in the order they appear.

An example request body looks like this.

{{{json
{

"modifiers": [

{

"type": "crop",
"args": {

"left": 12.875,
"top": 0.125,
"width": 50,
"height": 50

}

},
{

"type": "rotate",
"args": {

"angle": 90

}

}

]

}
}}}

Crop values are as a percentage of the original image and rotation angle is in degrees clockwise.

The crop values need to be percentages because the image loaded on the frontend may not be a scaled version of the original image, so naturalWidth and naturalHeight cannot be trusted as the actual width and height of the original image.

The rotation value is in degrees to avoid rounding errors for the types of rotations that are most common like 90 degrees. Clockwise versus anticlockwise may be up for debate. When using degrees it seems more natural to me to rotate clockwise, but mathematically, when you've converted to radians, a positive value indicates an anticlockwise rotation.

Different front-end implementations may apply edits in a different order, so passing an array will allow them to use their edits as-is without converting to a fixed order.

One example in the wild that actually uses both orders in different contexts is ​BeFunky. To see the difference, try one of their demo images with a horizon in it so you have a line that you can pay attention to. Then use the 'straighten' option followed by a 'horizontal flip' to see that the angle of the horizon hasn't changed even though you flipped the image. This means that the flip happens before the rotation. If you use the 'rotate' option instead of 'straighten, the rotation happens before the flip.

The old API continues to work, but when supplying the modifiers option, the old crop and rotation options are ignored.

[TimothyBlynJacobs]

Thanks for the patch @ajlende!

[ajlende]

Yeah, and sorry for the delay on moving it here. It's been sitting in my queue of things to work on for quite a while and I've only finally gotten around to it again. You always seem to be more on top of things than I am, so thank you!

[prbot]

​TimothyBJacobs commented on ​PR #845:

Let's also move the deprecated modifiers to the end of the args description.

[prbot]

​ajlende commented on ​PR #845:

I know you had mentioned adding a new deprecated option, but I was weary of adding a non-standard key on the JSON Schema, so it seemed like just adding a notice to the description may be sufficient.

I can still go ahead and add that option if you still think it's needed—something like array( 'deprecated' => ( 'Use modifiers instead.' ) ) maybe rather than just a boolean.

And before we go ahead and merge this, I'd like @azaozz's opinion on updating it to use the args key which I had ​mentioned in the old PR, but hadn't changed until moving it here.

[prbot]

​TimothyBJacobs commented on ​PR #845:

Let's leave a formal deprecated syntax for another ticket.