Update and refactor /transformations/image.py

[rsedykh]

Honestly, I don't like that we have to mirror URL API in the lib. Isn't there a more elegant way?

If not (or not now), let's reorder it to mirror the URL API structure better.

Changes/comments:

• [x] ImageFormat: add avif, preserve
• [x] CropAlignment: syntax is more than this; see https://uploadcare.com/docs/transformations/image/resize-crop/#operation-crop
• [ ] ScaleCropMode is more of a SmartCropMode (except for the center, which is mentioned in CropAlignment)
• [x] I'm not a dev, but why there're three gif2video functions instead of passing all params in one?

New stuff since the last update:

• [x] Text overlay (https://uploadcare.com/docs/transformations/image/overlay/#overlay-text)

• [x] Color overlay (https://uploadcare.com/docs/transformations/image/overlay/#overlay-solid)

• [x] Strip meta (https://uploadcare.com/docs/transformations/image/compression/#meta-information-control)

• [x] Radius crop (https://uploadcare.com/docs/transformations/image/resize-crop/#operation-border-radius)

• [x] Zoom (https://uploadcare.com/docs/transformations/image/resize-crop/#operation-zoom-objects)

• [x] SVG stuff (https://uploadcare.com/docs/transformations/image/svg/)

• [x] And Face detection (https://uploadcare.com/docs/intelligence/face-detection/) is missing entirely, maybe because it returns JSON, like some other non-transformative ops (https://uploadcare.com/docs/cdn-operations/#inline, https://uploadcare.com/docs/intelligence/color-recognition/, https://uploadcare.com/docs/cdn-operations/#file-information).

[evgkirov]

From https://uploadcare.com/docs/transformations/image/compression/#operation-format:

Alternatively, you can use the -/format/ operation to convert an image to one of the following formats:

But there's no avif listed in this section.

[KamillaGarifullina]

But there's no avif listed in this section.

This option is not available because it cannot be done that way.

[evgkirov]

CropAlignment: syntax is more than this; see https://uploadcare.com/docs/transformations/image/resize-crop/#operation-crop

Alignment is actually ok, you can set arbitrary position like this:

ImageTransformation().crop(
    width=640,
    height=480, 
    offset_x=50,
    offset_y="20%"
)

However, I can't see a way to "Crop by ratio" using ImageTransformation

[KamillaGarifullina]

However, I can't see a way to "Crop by ratio" using ImageTransformation

Here https://uploadcare.com/docs/transformations/image/resize-crop/#operation-crop-aspect-ratio is described how to make a ratio crop. Is this suitable for your task?

[evgkirov]

Yes.

But I've meant is that it's not supported by the library (yet!)

[evgkirov]

Isn't there a more elegant way?

It is the more elegant way. This provides a nice pythonic interface to set image effects.

The downside is that yes, it must be kept in sync with the URL API.

[evgkirov]

• [x] Don't forget about the docs

[evgkirov]

I wanted to update https://pyuploadcare.readthedocs.io/en/latest/core_api.html with the information about the added methods and... as it turns out,ImageTransformation is completely undocumented there.

I don't think it makes sense to write that part of the documentation by hand now. It should be automatically generated from the source code.

I think it's beyond the scope of this particular issue.

[rsedykh]

Let's document the existence of this feature and explain where to look for details.

[evgkirov]

explain where to look for details

You mean the source code for now?

[rsedykh]

You mean the source code for now?

Yes. And link to the /docs.