After you or your users have uploaded image assets to Cloudinary, you can deliver them via dynamic URLs. You can include instructions in your dynamic URLs that tell Cloudinary to manipulate your assets using a set of transformation parameters. All manipulations are performed automatically in the cloud and your transformed assets are automatically optimized before they are routed through a fast CDN to the end user for optimal user experience.
For example, you can resize and crop, add overlay images, blur or pixelate faces, apply a large variety of special effects and filters, and apply settings to optimize your images and to deliver them responsively.
Cloudinary's Java SDK simplifies the generation of transformation URLs for easy embedding of assets in your Java application.
You can deliver your images using methods that generate image tags or via direct URL-building directives.
You can add images to your Java Enterprise Edition view using Cloudinary's
image tag, or using the
imageTag method of the core Java library. Both methods generate the full image resource URL based on the given transformation parameters and wraps it with an HTML image tag with the appropriate attributes:
For example, displaying the uploaded image with the sample public ID, while providing an alternate text:
<%@taglib uri="https://cloudinary.com/jsp/taglib" prefix="cl" %> ... <cl:image src="sample.jpg" alt="Sample Image"/> // Or using the core Java library: Cloudinary cloudinary = new Cloudinary(); //configured using an environment variable cloudinary.url().imageTag("sample.jpg", Cloudinary.asMap("alt","Sample Image"));
cloud_name is configured to be
demo, this tag is equivalent to:
You can use the
image tag or
imageTag method to show transformed versions of your uploaded images by adding transformation instructions. For example, displaying the 'sample' image resized to fill a 100x150 area:
<cl:image src="sample.jpg" width="100" height="150" crop="fill"/> // or cloudinary.url() .transformation(new Transformation().width(100).height(150).crop("fill")) .imageTag("sample.jpg");
This would generate the following HTML:
<img src='https://res.cloudinary.com/demo/image/upload/c_fill,h_150,w_100/sample.jpg' height='150' width='100'/>
Additionally, you can add other, non-transformation parameters to the
image tag such as the asset version, configuration parameters and HTML5 image tag attributes. Using the core Java library, pass any HTML5 image tag attributes directly to the map in the
imageTag method, and pass other non-transformation parameters to methods of the
versionparameter is added to the delivery URL as explained in Asset versions.
- Configuration parameters that you specify here override any that you have set globally.
- HTML5 image tag attributes (e.g., alt or class) are added to the resulting
<cl:image src="docs/casual" width="500" height="500" crop="fill" cloudName="demo" secure="true" version="1573726751" alt="Casual Jacket" /> // or cloudinary.url() .transformation(new Transformation().width(500).height(500).crop("fill")) .cloudName("demo") .secure(true) .version(1573726751) .imageTag("docs/casual", Cloudinary.asMap( "alt","Casual Jacket"));
is compiled to:
<img src="https://res.cloudinary.com/demo/image/upload/c_fill,h_500,w_500/v1573726751/docs/casual" height="500" alt="Casual Jacket">
In general, when using an SDK, you will probably take advantage of the SDK parameter names for improved readability and maintenance of your code. However, you can also optionally pass a raw transformation parameter, whose value is a literal URL transformation definition. Note that the string you pass as the raw transformation value will be appended as is (with no processing or validation) to the end of any other transformation parameters passed in the same component of the transformation chain.
Cloudinary supports powerful transformations. You can even combine multiple transformations together as part of a single transformation request, e.g. crop an image and add a border. In certain cases you may want to perform additional transformations on the result of the previous transformation request. To do that, you can use chained transformations.
To apply chained transformations in a transformation URL, you include multiple transformation components separated by '/'. Each transformation component is applied to the result of the previous one. When using the
image tag the first transformation's parameters are specified inline with the tag's attributes and additional transformations are specified using a
transformation tag inside a
<jsp:attribute name="transformation"> tag. When using the client library directly, the
transformation object has a method named
chain which allows chaining transformations.
The following example first crops the original image to a specific set of custom coordinates and then transforms the result so it fills a 130x100 rectangle:
The following example applies 4 chained transformations: custom cropping to 300x200, fill to 130x100, rotate by 20 degrees and then scale to 50%:
For more information on image transformations, see Apply common image transformations.
image tag or the
imageTag method generate an HTML image tag. In certain conditions, you might want to generate a transformation URL directly, without the containing image tag. You can do that by either using the
url tag or the
generate method. Here are few examples:
<cl:url src="sample.jpg" width="100" height="150" crop="fill"/> // "https://res.cloudinary.com/demo/image/upload/c_fill,h_150,w_100/sample.jpg"
cloudinary.url().resourceType("raw").generate("sample_spreadsheet.xls"); // "https://res.cloudinary.com/demo/raw/upload/sample_spreadsheet.xls"
cloudinary.url().transformation( new Transformation().width(100).height(150).crop("fill")).generate("sample.jpg"); // "https://res.cloudinary.com/demo/image/upload/c_fill,h_150,w_100/sample.jpg"
This section provides an overview and examples of the following commonly used image transformation features, along with links to more detailed documentation on these features:
- Resizing and cropping
- Converting to another image format
- Applying image effects and filters
- Adding text and image overlays
- Image optimizations
- Responsive image settings
Keep in mind that this section is only intended to introduce you to the basics of using image transformations with Java.
For comprehensive explanations of how to implement a wide variety of transformations, see Image transformations. For a full list of all supported image transformations and their usage, see the Transformation URL API Reference.
There are a variety of different ways to resize and/or crop your images, and to control the area of the image that is preserved during a crop.
The following example uses the
fill cropping method to generate and deliver an image that completely fills the requested 250x250 size while retaining the original aspect ratio. It uses face detection gravity to ensure that all the faces in the image are retained and centered when the image is cropped:
For details on all resizing and cropping options, see resizing and cropping images.
You can deliver any image uploaded to Cloudinary in essentially any image format. There are three main ways to convert and deliver in another format:
- Specifying the image's public ID with the desired extension.
- Explicitly set the desired format using the
- Use the
autofetch_format to instruct Cloudinary to deliver the image in the most optimized format for each browser that requests it.
Deliver a .jpg file in .gif format:
Let Cloudinary select the optimal format for each browser. For example, in Chrome, this image delivers in .webp format.
For more details see Image format support.
You can select from a large selection of image effects, enhancements, and filters to apply to your images. The available effects include a variety of color balance and level effects, tinting, blurring, pixelating, sharpening, automatic improvement effects, artistic filters, image and text overlays, distortion and shape changing effects, outlines, backgrounds, shadows, and more.
For example, the code below applies a cartoonify effect, rounding corners effect, and background color effect (and then scales the image down to a height of 300 pixels).
For more details on the available image effects and filters, see Applying image effects and filters.
You can add images and text as overlays on your main image. You can apply the same types of transformations on your overlay images as you can with any image and you can use gravity settings or x and y coordinates to control the location of the overlays. You can also apply a variety of transformations on text, such as color, font, size, rotation, and more.
For example, the code below overlays a couple's photo on a mug image. The overlay photo is cropped using face detection with adjusted color saturation and a vignette effect applied. The word love is added in a pink, fancy font and rotated to fit the design. A balloon graphic is also added. Additionally, the final image is cropped and the corners are rounded.
cloudinary.url().transformation(new Transformation() .width(400).height(250).gravity("south").crop("fill").chain() .overlay(new Layer().publicId("nice_couple")).width(1.3).height(1.3).gravity("faces").flags("region_relative").crop("crop").chain() .effect("saturation:50").chain() .effect("vignette").chain() .flags("layer_apply").width(100).radius("max").gravity("center").y(20).x(-20).crop("scale").chain() .overlay(new Layer().publicId("balloon")).height(55).chain() .effect("hue:-20").angle(5).chain() .flags("layer_apply").x(30).y(5).chain() .overlay(new TextLayer().fontFamily("Cookie").fontSize(40).fontWeight("bold").text("Love")).effect("colorize").color("#f08").chain() .angle(20).flags("layer_apply").x(-45).y(44).chain() .width(300).height(250).x(30).crop("crop").chain() .radius(60)).imageTag("coffee_cup.jpg");
By default, Cloudinary automatically performs certain optimizations on all transformed images. There are also a number of additional features that enable you to further optimize the images you use in your application. These include optimizations to image quality, format, and size, among others.
For example, you can use the
auto value for the
quality attributes to automatically deliver the image in the format and quality that minimize file size while meeting the required quality level. Below, these two parameters are applied, resulting in a 50% file size reduction (1.4 MB vs. 784 KB) with no visible change in quality.
For an in-depth review of the many ways you can optimize your images, see Image optimization.
Responsive web design is a method of designing websites to provide an optimal viewing experience to users, irrespective of the device, window size, orientation, or resolution used to view it. Ensuring that optimal experience means you should avoid sending high resolution images that get resized client-side, with significant bandwidth waste for users of small displays. Instead, you should always deliver the right size image for each device and screen size.
For example, you can ensure that each user receives images at the size and device pixel ratio (dpr) that fit their device using the
auto value for the
width attributes. The
auto value is replaced with actual values on the client side based on the actual browser settings and window width:
cloudinary.url().transformation(new Transformation().width("auto").dpr("auto").responsive("true"). crop("scale").responsive_placeholder("blank")).imageTag("sample.jpg");
Cloudinary offers several options for simplifying the complexity of delivering responsive images. For a detailed guide on how to implement these options, see Responsive images.