Shear API and background colour

caprica Member Posts: 9
edited November 2023 in Developer APIs

I want to use the shear effect on images.

First, I resize and pad a source image, specifying a black background for the padded area. It ends up with a letterbox effect, which is exactly what I want.

Second, I apply a shear like (30, 0).

In the resulting image, where the pixels have been moved along their axis, that area is filled with black pixels. However, I need those pixels, and only those pixels, to be transparent.

If I remove the black background from the first padded image, I do get transparent pixels in the sheared result, but it also has transparent pixels in the padded area which I do not want - I only want transparent pixels where the pixels have moved due to the shear.

Can I achieve this?

This is a fragment of my transform chain:

new CloudinaryImage('sourceImage')


.reshape(shear("0", "30.0"))

This (really poor!) image illustrates crudely what I mean. I'm using red here instead of black just to differentiate the padding from the shearing.

The red areas are the padded areas from the initial resize, I want to keep this. The black areas are the fill caused by the shear moving the pixels. I want those black areas to be transparent.

If I replace my shear with a distort, everything works as expected. I would however prefer to use shear as it is a lot simpler than calculating the distortion rectangle each time.



  • johnr
    johnr Member Posts: 7

    hi @caprica, can you share the URL from your test?

    The `distort` effect will not make the background transparent, it will give a white background instead. I would like to clarify if you meant a white background?

    I've done some testing on my own and this is the result I got.

    If this is what you need, you only need to remove the .background(color('black')) from your code.

  • caprica
    caprica Member Posts: 9

    If I remove the background colour black function, then the area where the image was padded becomes transparent, and I don't want that. I want the image resized and letterboxed with the black padding.

    In your image, the space above and below the image is solid white, I need that to be transparent.

    In my code, replacing shear with distort *does* give me exactly the result I want. Fair enough it might be the case that it's not making the pixels transparent like you say, maybe it's the size/shape of the resultant image that's different or something.

    I'll prepare some URLs and come back. I would still very much prefer to use shear because it's much simpler to work out.

  • caprica
    caprica Member Posts: 9
    edited November 2023

    First image, resized, padded, with black letter-boxing.

    Second image, shear applied, with unwanted black fill:

    Third image, if I remove the .background(color('black')) it is no longer letter-boxed, and indeed the background is now transparent, but this is not what I want:

    Fourth image, adding the black background back, and then applying distort:

    In this latter image, the background may look white, but it is in fact transparent as can be seen here:

    So this last image is the effect I want, but ideally I'd like to use shear as specifying a simple shear angle is trivial compared with having to calculate all of the corner offsets dynamically.

    Final image, just to show it all in one place, middle image is shear, last image is distort:

  • johnr
    johnr Member Posts: 7

    Can you please check if this is the transformation you need?


    Here is what I did:

    • I uploaded a transparent image blank-transparent that will serve as my transparent canvas.
    • Overlayed the image with `public_id: sample` - l_cld-sample,bo_40px_solid_black,w_540/e_shear:0.0:30.0/fl_layer_apply. Added a 40px black border to add the letter-box effect.
    • resized the `blank-transparent` canvas c_crop,w_500,h_750 to match the width of the overlayed image.

    Let me know if this works for you.

  • caprica
    caprica Member Posts: 9

    I really appreciate your efforts, thank you.

    I think my fundamental issue though, is why shear doesn't seem to work like distortion. Shear can detect and fill with black, or whatever other background the image has, *including* transparency, so why can I not tell it to forego this background colour detection and be specific about filling transparency instead.

    I guess the answer is it's not supported, so the why is moot.

    I could maybe use your transform pipeline, but then I lose the automatic padding (which may or may not be required at all, or may be variable, depending on the source image), which then means I have to do more manual calculations and write more code to determine if and how I need to apply the border.

    So at the moment, I think distort is actually the closest to what I need.

    But again, really appreciate your suggestions.

  • Cloudinary Team
    Cloudinary Team Administrator, Cloudinary Staff Posts: 135 admin

    Hi there,

    I'm glad John was able to help, even if it's not your ideal workflow.

    I just wanted to throw out one more idea, if you decide to work with shear, using an overlay. We have some advanced transformation techniques - user-defined variables, arithmetic expressions, and conditional transformations that might be helpful for you. I only bring it up because i see that you have a concern over the manual calculations you would need to do in following John's workflow. The idea is that if you set up your variables and expressions correctly, you wouldn't have to do the calculations. If you are interested, you can find the relevant documentation here:

    If you have any questions at all, do not hesitate to ask.

    Kind regards,


    Helpful Links For You
    💬 Share questions, connect with other users in our Cloudinary Community forums and Discord server!
    🧑‍🎓 Join our Cloudinary Academy for free courses, workshops and other educational resources.
    📄 Read our documentation for in-depth details on Cloudinary product features and capabilities
    📰 Check out the Cloudinary blog for the latest company news and insights