Skip to content

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.

Available AIO paramters

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; OR noopt=true

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;

Notes:

  • Images served with this setting might still be cached by Nitrogen.
  • noopt=true is an older method and might be removed in future updates. It's recommended to use the newer aio=noopt method for all AIO operations.

Image Operations

This documentation explains the various image operations available in Nitrogen.

Scale by Width

Query Parameter: aio=w-<number>; OR 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 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>; OR 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 is an older way of using AIO operations and might be deprecated in the future. It's recommended to use aio= for all operations.

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.

  • 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.

  • 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.

  • 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-center

    • 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.

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. They use a static default of 50% for X (horizontal center) and 20% for Y (20% down from the top).

Debug feature

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.

Important Notes

  • 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).

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;

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.

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);

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.

Understanding the aio Parameter in Nitrogen

The aio parameter in Nitrogen allows you to manipulate images on the fly using various operations. Here's a breakdown of its components:

1. aio=

  • 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);w-500;h-300;crop;

2. Separators

  • ; separates multiple operations within a single aio parameter.
aio=w-500;h-300;cut;  // Resize and crop
  • , separates details within a single operation.
aio=append,image=(d=h,url=https://www.n7.io/aio_examples/buywow.jpg);  // Append image horizontally

3. Operation Details

  • w-value specifies the desired width for the image.
aio=w-400;  // Resize to 400px width
  • h-value specifies the desired height for the image.
aio=h-300;  // Resize to 300px height
  • crop resizes the image to the provided dimensions and then crops it (currently, only center cropping is available).
aio=w-250;h-250;crop;  // Resize to 250x250 and crop
  • cut crops the image from the center with the provided dimensions (currently, only center cutting is available).
aio=w-350;h-200;cut;  // Resize to 350x200 by cutting from center
  • append,image indicates that multiple images need to be combined.
aio=append,image=(d=h,url=https://www.n7.io/aio_examples/buywow.jpg);  // Append another image horizontally

  • d=h (optional) specifies the direction for appending images:

    • d=h (default): Images are appended horizontally (side-by-side).
    • d=v (not yet supported): Images would be appended vertically (top-to-bottom).

  • url=path_value provides the URL of the image to be appended.

This example resizes two images (assumed to be already fetched) to 200px wide and 100px high, combines them horizontally, and then crops the final combined image to 500px wide and 300px high