AIO Parameters

Refer this page to instruct AIO to resize/crop/merge the image based on the value provided in querystring.

Note: For demo purpose, we will be using www.n7.io domain as an example.

Prerequisite

1. You must have a domain configured on Nitrogen
2. You must have AIO enabled, please refer this article.

You can add the following query parameters in the image URL to scale the image based on width/height, to crop, to cut, to merge, or to serve original image without optimizing it:

Serve optimized version image (without any transformations)

Query Parameter: N/A

Description: Serves the optimized image with original dimensions of the image - without any resizing or modifications.

Example: https://www.n7.io/aio_examples/hopscotch.jpeg

Serve Original Image

Query Parameter: aio=noopt;

Description: This delivers the unoptimized original image, maintaining its original dimensions. This is useful when you want users to zoom in and see minute details.

Example:

This displays the original image:

https://www.n7.io/aio_examples/hopscotch.jpeg?aio=noopt;

Note: aio-noopt is an older way of using AIO operations and might be deprecated in the future. It's recommended to use aio= for all operations.

Serve Optimized Image in given format

Query Parameter: aio=f-<format>;

Description: This delivers the optimized version of image in given format.

Example:

This displays the optimized image in jpeg format:

https://www.n7.io/aio_examples/hopscotch.jpeg?aio=f-jpeg;

Notes:

• Available options for f are :
  • avif
  • webp
  • original image format e.g. here jpeg

Scale by Width

Query Parameter: aio=w-<number>;

Description: This resizes the image to the specified width while keeping the aspect ratio intact. This is typically used to display the same image with different widths on various pages.

Example: This resizes the image to a width of 200 pixels:
https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-200;

Note: aio-w-<number> is an older way of using AIO operations and might be deprecated in the future. It's recommended to use aio= for all operations.

Scale by Height

Query Parameter: aio=h-<number>;

Description: This resizes the image to the specified height while maintaining the aspect ratio. This is commonly used to display the same image with different heights on various pages.

Example: This resizes the image to a height of 200 pixels:
https://www.n7.io/aio_examples/hopscotch.jpeg?aio=h-200;

Note: aio-h-<number> is an older way of using AIO operations and might be deprecated in the future. It's recommended to use aio= for all operations.

Sharpen Images

Query Parameter: aio=sharp;

Description: This operation sharpens the image.

Example: https://www.n7.io/aio_examples/hopscotch.jpeg?aio=sharp;

Notes:

• Currently sharpening algorithm and amount being applied is default and not manageable through AIO query-parameter.

Blur Images

Query Parameter: aio=blur-<strength>;

Description: This operation blurs the image based on provided strength within range [0-100]. Where, 0 - No Blur & 100 - Maximum Blur

Example: https://aiotest.n7.io/shyaway/st021-balletslipper-front.webp?aio=blur-100;

Serve image for provided DPR value

Query Parameter: aio=dpr-<number>;

Description: This operation serves the image with dimensions based on the provided DPR value [1, 2]. Where, 1 - original dimensions & 2 - doubled dimensions.

Example: https://aiotest.n7.io/shyaway/st021-balletslipper-front.webp?aio=dpr-2;

Cut

Query Parameter: aio=w-<number>;h-<number>;cut,<optional-cut-parameters>;

Description: This documentation explains the various image cropping operations available in Nitrogen. All these operations currently only work with the "cut" operation type.

Example: Here image is cropped by given dimensions (by default from center)
https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-300;h-400;cut;

Cropping by Location

• Query Parameter: cut,top;
  This operation cuts a rectangular region from the top of the image. The size of the rectangle is determined by the provided width and height.

  • Example:
    This URL will return a 400x200 pixel image cropped from the top portion of the original image.
    https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-400;h-200;cut,top

• Query Parameter: cut,left;
  This operation cuts a square region from the left of the image. The size of the square is determined by the provided width and height.

  • Example:
    This URL will return a 400x400 pixel image cropped from the left of the original image.
    https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-400;h-200;cut,left

• Query Parameter: cut,top-left;
  This operation cuts a rectangular region from the top-left corner of the image. The size of the rectangle is determined by the provided width and height.

  • Example:
    This URL will return a 200x150 pixel image cropped from the top-left corner of the original image.
    https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-400;h-200;cut,top-left
• These directions are supported :
  • cut,left
  • cut,right
  • cut,top
  • cut,bottom
  • cut,center
    
    
  • cut,top-left
  • cut,top-right
  • cut,top-center
    
    
  • cut,bottom-left
  • cut,bottom-right
  • cut,bottom-right
    
    
  • cut,left-center
  • cut,right-center

Cropping by Custom Coordinates

• cut,custom:
  This operation allows you to specify the exact location and size of the cropped region. You provide the width and height as usual, but additionally specify the starting x and y coordinates (defaults to 0,0) from which the cropping should begin.
  • Example:
    This URL will return a 300x300 pixel image cropped from the original image, starting 300 pixels from the right and 50 pixels down from the top-left corner.
    https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-400;h-200;cut,custom,x-300,y-50;
    

Cropping by face

• cut,face / cut,part:
  These operations attempt to intelligently crop a region of the image that might contain a face or other significant element.
  It uses a static default of 50% for X (horizontal center) and 20% for Y (20% down from the top).

  • Example: This URL will return a 400x200 pixel image automatically cropped based on static defaults.
    https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-400;h-200;cut,face;

Smart Crop

• smart,prominent:
  This operation crops the image focusing the most important part of the image using AI/ML methods.

  • Example: This URL will return a 400x200 pixel image automatically cropped to keep the portion with faces in focus.
    https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-400;h-200;smart,prominent;

Smart crop for body parts

• Query Parameter: aio=w-100;h-100;smart,<body-part>;

• Description: This operation crops the image for the given part of body using AI.

• Example: https://dasset.manyavar.com/image/41227ee6-6b48-44b2-af53-8897bd82f476/KFN146_324-Yellow.3538_24-08-2024-20-00?aio=w-1244;h-900;smart,body

  Available values :

  • body
  • face
  • head
  • legs
  • nape
  • torso
  • stomach
  • prominent
  • prominent.body
  • prominent.head
  • prominent.legs
  • prominent.nape
  • prominent.torso
  • prominent.stomach

Swatch

Query Parameter: aio=w-100;h-100;smart,swatch;

Description: This feature intelligently selects the swatch of fabric for the given dimensions using AI.

Example: For this image, we can get the swatch as following : https://dasset.manyavar.com/image/cb6ecc4f-1e81-45ef-8f69-ae8088205c11/KFN075_322-Wine.5489_25-08-2024-16-28?aio=w-100;h-100;smart,swatch

Crop

Query Parameter: aio=w-<number>;h-<number>;crop;

Description: This operation resizes the image to the specified width (w) and height (h) while maintaining the original aspect ratio. If the original image proportions don't match the requested dimensions, it will be cropped to fit the new size.

Example: This resizes the image to 200 pixels wide and 200 pixels high, maintaining the aspect ratio and cropping any excess if necessary:
https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-200;h-200;crop;

Important notes for all cut and crop operations

• All cropping operations currently only work with the "cut" operation type.
• For custom cropping (cut,custom), ensure the provided x and y coordinates stay within the image boundaries (0 < x,y < source_width, source_height).

Debug feature for all cut and crop operations

Query Parameter: explain;

• explain: This operation is for debugging purposes only and does not modify the image. It displays a rectangle on the original image to visualize the sample area that would be affected by a specific "cut" operation.

Example: https://www.n7.io/aio_examples/hopscotch.jpeg?aio=w-300;h-400;cut;explain;
This URL shows the original image with a rectangle indicating the area that would be cropped by the cut operation.

Combine Images

Query Parameter: aio=append,image=(url=https://www.n7.io/aio_examples/buywow.jpg);

Description: This operation allows you to combine multiple images into a single image.
Currently following values are supported : - d=h (default): Images are appended horizontally (side-by-side). - d=v (not yet supported): Images would be appended vertically (top-to-bottom).

Example: This combines the image1 with another image2 by placing them side-by-side
https://www.n7.io/aio_examples/hopscotch.jpeg?aio=append,image=(d=h,url=https://www.n7.io/aio_examples/buywow.jpg);

Understanding the aio parameter in Nitrogen with multiple operations

The aio parameter in Nitrogen allows you to manipulate images on the fly using various operations. Here's a breakdown of its components: - This keyword initiates the use of the aio parameter. - All configuration details for image manipulation are included after the = sign.

Example:

https://www.n7.io/aio_examples/hopscotch.jpeg?aio=append,image=(d=h,url=https://www.n7.io/aio_examples/buywow.jpg?aio=w-200;h-350;cut,top-center;);w-900;h-350;sharp;

Separators

• ; separates multiple operations within a single aio parameter.

aio=w-500;h-300;crop;  // Resize to 500x300 and then crop

• , separates details within a single operation.

cut,top-center;  // crop the image from top-center

Operation Details

• append,image indicates that multiple images need to be combined.
  Here it will resize buywow.jpg for given dimensions, and crop it by given direction and horizontally append it to hopscotch.jpeg

https://www.n7.io/aio_examples/hopscotch.jpeg?aio=append,image=(d=h,url=https://www.n7.io/aio_examples/buywow.jpg?aio=w-200;h-350;cut,top-center;)

• w-value specifies the desired width for the image.
  Here it will resize the final merged image to 900px width

aio=w-900;

• h-value specifies the desired height for the image.
  Here it will resize the final merged image to 350px height

aio=h-350;

• sharp sharpens the image.
  Here it will sharpen the final merged image