You can do it easily using Cloudinary\u2019s Image Collage generation feature.<\/p>\n\n\n\n
![\"\"](\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/c_pad,b_auto:predominant,fl_preserve_transparency\/v1663762005\/docs\/collage\/blog\/food-collage.jpg\")
<\/figure>\n<\/div>\n\n\n\n![\"\"](\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/c_pad,b_auto:predominant,fl_preserve_transparency\/v1663762004\/docs\/collage\/blog\/landscape-collage.jpg\")
<\/figure>\n<\/div>\n<\/div>\n\n\n\n![\"\"](\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/c_pad,b_auto:predominant,fl_preserve_transparency\/v1663761994\/docs\/collage\/blog\/flow-collage.jpg\")
<\/figure>\n\n\n\nI\u2019m proud to have developed this exciting Cloudinary feature. In this post, I\u2019ll introduce you to this feature and explain how my team and I:<\/p>\n\n\n\n
- Built a simple, developer-friendly interface for creating customizable collages<\/li>
- Resolved the templating challenge by creating a flexible array representation to fit all needs<\/li>
- Considered several tradeoffs to resolve the gap challenge while satisfying desired collage properties, without compromising the resolution<\/li><\/ul>\n\n\n\n
Developer-friendly Interface<\/strong><\/h2>\n\n\n\n
<\/strong>Our goal in developing the ImageCollage generation feature was to empower Cloudinary users to choose collage dimensions, assets, spacing, and layout. Most of these parameters are represented easily by a json. But how could we determine the collage layout? This was our first challenge. <\/p>\n\n\n\nA grid layout was our first choice. We started with the following json representation:The first thing to tackle was how to represent collage generation easily. We would like to allow the user to choose the collage dimensions, assets, spacing and layout. Most of these parameters are represented easily by a json, but how to determine the collage layout?<\/p>\n\n\n\n
It was clear that `grid` should be the first one to develop. So we started with the following json representation:<\/p>\n\n\n
manifest_json={\n \"template\"<\/span>: \"grid\"<\/span>,\n \"width\"<\/span>: 500<\/span>,\n \"height\"<\/span>: 500<\/span>,\n \"columns\"<\/span>: 3<\/span>,\n \"rows\"<\/span>: 3<\/span>,\n \"spacing\"<\/span>: 2<\/span>,\n \"color\"<\/span>: \"white\"<\/span>,\n \"assetDefaults\"<\/span>: { \"kind\"<\/span>: \"upload\"<\/span>, \"crop\"<\/span>: \"fill\"<\/span>, \"gravity\"<\/span>: \"center\"<\/span> },\n \"assets\"<\/span>: [\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/tasmaniandevil\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/kangaroo\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/cassawary\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/echidna\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/koala\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/emu\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/platypus\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/wombat\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/australian-animals\/kokatoo\"<\/span>, \"gravity\"<\/span>: \"north\"<\/span> }\n ]\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nLet\u2019s dive into the parameters. <\/p>\n\n\n\n
The template parameter defines the collage layout. A grid requires the following dimensions to be defined:<\/p>\n\n\n\n
- Width<\/li>
- Height<\/li>
- Spacing between images<\/li><\/ul>\n\n\n\n
In addition, row and column counts should be defined to determine the number of images in the collage. This is achieved by setting the following parameters:<\/p>\n\n\n\n
- Width<\/li>
- Height<\/li>
- Spacing<\/li>
- Rows<\/li>
- Columns<\/li><\/ul>\n\n\n\n
The images that compose the collage are specified by the assets parameter, which is an array that should match the template size (rows x columns).
Next, we explored collage customization. <\/p>\n\n\n\nSetting the \u201ccolor\u201d parameter determines the color of the spacing between images. Options for personalizing assets include: <\/p>\n\n\n\n
- Setting defaults for all assets<\/strong> to control the resource delivery type (upload\/fetch\/restricted), crop, and gravity, defined by the \u201cassetDefaults\u201d parameter<\/li>
- Setting specific asset properties<\/strong> by specifying the desired \u2018kind\u2019, \u2018crop\u2019, and \u2018gravity\u2019 and thus allowing maximum flexibility in asset personalization<\/li><\/ul>\n\n\n\n
The manifest json above produces the following collage:<\/p>\n\n\n\n
![\"\"](\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/c_pad,b_auto:predominant,fl_preserve_transparency\/v1663746337\/docs\/collage\/blog\/australian-collage.jpg\")
<\/figure>\n\n\n\nThe challenge that remained was representing custom collage templates. Let\u2019s have a look at some template options:<\/p>\n\n\n\n
![\"\"](\"https:\/\/res.cloudinary.com\/cloudinary-marketing\/images\/w_302,h_594,c_scale\/f_auto,q_auto\/v1663712491\/Screen_Shot_2022-09-20_at_2.53.38_PM\/Screen_Shot_2022-09-20_at_2.53.38_PM.png?_i=AA\")
<\/figure>\n\n\n\nWe could use predefined templates using a string representation as we did for the grid layout, but we wanted to provide users with more template options. <\/p>\n\n\n\n
Assuming the whole collage is a 3×3 matrix, we merged cells to get the desired template. Each image is mapped to a single cell or multiple cells and represented by a color and a number.<\/p>\n\n\n\n
Let\u2019s see how this looks:<\/p>\n\n\n\n
![\"\"](\"https:\/\/res.cloudinary.com\/cloudinary-marketing\/images\/w_238,h_580,c_scale\/f_auto,q_auto\/v1663712492\/Screen_Shot_2022-09-20_at_2.54.05_PM\/Screen_Shot_2022-09-20_at_2.54.05_PM.png?_i=AA\")
<\/figure>\n\n\n\nNumbers are determined left to right, top to bottom.<\/p>\n\n\n\n
Removing the colors, we could now represent the collage template in a simple numeric array:<\/p>\n\n\n\n
![\"\"](\"https:\/\/cloudinary-marketing-res.cloudinary.com\/image\/upload\/v1663871482\/Screen_Shot_2022-09-22_at_11.30.18_AM.png\")
<\/figure>\n\n\n\nWant a different template configuration? No problem! Simply add more rows and columns to create your desired template.
<\/p>\n\n\n\nHere\u2019s the finalized manifest json for a custom template:<\/p>\n\n\n
manifest_json={\n \"template\"<\/span>: [[1<\/span>, 2<\/span>, 2<\/span>],\n [1<\/span>, 3<\/span>, 3<\/span>],\n [1<\/span>, 3<\/span>, 3<\/span>]],\n \"width\"<\/span>: 600<\/span>,\n \"height\"<\/span>: 400<\/span>,\n \"columns\"<\/span>: 3<\/span>,\n \"rows\"<\/span>: 3<\/span>,\n \"spacing\"<\/span>: 2<\/span>,\n \"color\"<\/span>: \"black\"<\/span>,\n \"assetDefaults\"<\/span>: { \"kind\"<\/span>: \"upload\"<\/span>, \"crop\"<\/span>: \"fill\"<\/span>, \"gravity\"<\/span>: \"auto\"<\/span>},\n \"assets\"<\/span>: [{ \"media\"<\/span>: \"docs\/collage\/blog\/dogs\/dog1\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/dogs\/dog2\"<\/span> },\n { \"media\"<\/span>: \"docs\/collage\/blog\/dogs\/dog3\"<\/span>}\n ]\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nAnd here\u2019s the collage it produces:<\/p>\n\n\n\n
![\"\"](\"https:\/\/res.cloudinary.com\/demo\/image\/upload\/c_pad,b_auto:predominant,fl_preserve_transparency\/v1663746336\/docs\/collage\/blog\/dogs-collage.jpg\")
<\/figure>\n\n\n\nValidating Input<\/strong><\/h2>\n\n\n\n
The next challenge we tackled was validating input. <\/p>\n\n\n\n
Looking at the examples above, it is clear that the only valid template options are a square or a rectangle. In addition, the image numbers should be consecutive, should not repeat themselves in different images, and should be ordered as I previously explained.<\/p>\n\n\n\n
Here are two examples of invalid inputs:<\/p>\n\n\n\n
![\"\"](\"https:\/\/res.cloudinary.com\/cloudinary-marketing\/images\/w_266,h_406,c_scale\/f_auto,q_auto\/v1663712490\/Screen_Shot_2022-09-20_at_2.54.30_PM\/Screen_Shot_2022-09-20_at_2.54.30_PM.png?_i=AA\")
<\/figure>\n\n\n\nThe first example is invalid because image 2 is not a rectangle or a square.<\/p>\n\n\n\n
The second example is invalid because there is a repeated number (2) and a jump in images numbering (5 instead of 4).<\/p>\n\n\n\n
Looking closely at the first example, the problem is that cells (0,1), (1,0), (1,1) don\u2019t create a square; they form an L-shaped structure. Any possible L structure is invalid even if it is rotated by 90, 180, or 270 degrees.<\/p>\n\n\n\n
Looking at the (2,1) cell in the second example, there is no adjacent horizontal or vertical cell with the same number (lonely cell), and the number already appears in a previous image in the template . Let\u2019s ignore the numbering consistency for now as this is easy to resolve.
After analyzing the input, validating the user input is easy: just search for \u201cL\u201d structures or lonely cells.<\/p>\n\n\n\nMind the Gap<\/strong><\/h2>\n\n\n\n
Last but not least, we tackled the challenge of collage layout dimensions. <\/p>\n\n\n\n
Let\u2019s look at another example. Let\u2019s assume we\u2019re creating a 1×3 grid collage of size 1000×1000. Dividing the total width in the images count, to get each image width, results in 1000\/3=333.333<\/p>\n\n\n\n
We\u2019re working in pixels, which must be integers. We had several options here:<\/p>\n\n\n\n
- Leave a gap at the end, the start, or divide the missing pixels per image. How should we handle it in custom templates?<\/li>
- Stretch the last image to fill the gap (consider the edge cases, e.g., 1×1000 grid)<\/li>
- Produce a collage with adjusted dimensions after ceiling\/flooring each image dimensions<\/li><\/ol>\n\n\n\n
Let\u2019s look at what Option 1 above might look like, where each blue section is a different image:<\/p>\n\n\n\n
![\"\"](\"https:\/\/res.cloudinary.com\/cloudinary-marketing\/images\/w_1024,h_226,c_scale\/f_auto,q_auto\/v1663712490\/pasted_image_0_5\/pasted_image_0_5.png?_i=AA\")
<\/figure>\n\n\n\nNot looking very nice, is it?<\/p>\n\n\n\n
Fortunately, we used existing Cloudinary capabilities to enhance the collage layout. <\/p>\n\n\n\n
We started by rounding up any floating point value per image, such that every image had integer dimensions. After creating the whole grid using Cloudinary\u2019s resize<\/a>, the collage is then downscaled to the desired dimensions. We thus filled the gap without losing resolution. (Note: Some resolution is, in fact, lost while ceiling each collage image, but this has a limited effect as 0 < diff < 1, while the alternative, upscaling the whole collage, may create a diff > 1.)
<\/p>\n\n\n\n
- Setting specific asset properties<\/strong> by specifying the desired \u2018kind\u2019, \u2018crop\u2019, and \u2018gravity\u2019 and thus allowing maximum flexibility in asset personalization<\/li><\/ul>\n\n\n\n
- Setting defaults for all assets<\/strong> to control the resource delivery type (upload\/fetch\/restricted), crop, and gravity, defined by the \u201cassetDefaults\u201d parameter<\/li>