Overview

Skill Level: Any

Prerequisites

The Image Converter (IC) is commonly used when you want dynamic image sizing for different page views (e.g., mobile device types), the same picture to display in different sizes (e.g., thumbnails and enlargements), or to convert image formats (e.g., converting a TIFF to a JPEG).

For example, you could use IC when you want to display images originating from your desktop site on your mobile site. For desktop sites, images are generally designed for fast connections and large browser display areas. IC allows you to transform these images so they work better with the layout and performance considerations of all your client devices, but without the need to create, maintain, store, and serve multiple versions of the same images.Customers subscribing to IC can perform image manipulations as clients request the images. Operations include resizing, cropping, and transcoding

Image Converter can be used with any of these image formats:

  • GIF
  • JPEG
  • PNG
  • TIFF

Step-by-step

  1. Using the Image Converter (IC)

    To use the Image Converter, you must append the IC commands to either an image’s URL or HTML <img> tag.

    Examples:

    URL

    URL command example

    HTML <img> tag

    <img> tag example

  2. Common elements of the Image Converter (IC): Command Order, Unit, Location, Dimension

    The IC reads commands sequentially from left to right, so you must ensure the order of your commands for accurate results.

    Use the following table to help determine the correct order of your commands:

    Command Type IC Commands Usage Considerations
    Measurement

    Define custom units in terms of pixels:

    unit

    The definitions you create with the unit command affect only the commands that follow it. Therefore, it is recommended that the unit command be the first command (if used).

    Pixels are the default unit of measurement. To use a different unit of measurement, you must define it with the unit command. The unit command defines a new measurement unit in terms of existing units.

    unit=<sizeunit>::<sizecurrent>

    Operations

    Manipulating an image:

    box

    composite

    composite-to

    crop

    downsize

    fit

    resize

    The order of operations commands is important.

    If you use the same operations command twice, each command is performed based on its order of appearance. As IC reads query strings sequentially from left to right, the left-most command would be performed first. The second command would then be performed based on the output of the first command.

    Output

    Change image format characteristics:

    background-color

    output-format

    output-quality

    It is recommended that output commands follow operations commands.

    If you repeat an output command, only the right-most command is performed.

    Some of the IC commands require values for location, dimensions, or both.

    • A location is given as a pair of x- and y-coordinates
    • Dimensions are given as a ratio of width to height
    • A rectangle is an example of a combination of dimensions and a location

    Use the following table to determine which IC commands use which values:

    Command Location Dimensions
    box Required Required
    composite Required Optional
    composite-to Required Optional
    crop Required Required
    downsize N/A Required
    fit N/A Required
    resize N/A Required

    Location

    Basic syntax: <x>,<y>

    The <x> and <y> parameters correspond to the image’s x- and y-zxis. They are used in the box, crop, composite, and composite-to commands:

    • In the box command, this is the upper-left corner of the box being drawn on the base image
    • In the crop command, this is the upper-left corner of the region being cropped.
    • In the composite and composite-to commands, this is the upper-left corner of the image being superimposed on the base image.

    Use the following table to see details about the ways to describe location:

    Value Description Example
    Basic Values
    <integer> A coordinate on the x- or y-axis given in pixels. Equivalent to <integer>px. 100, 120
    <integer><unit> A coordinate on the x- or y-axis given in units you’ve defined with the unit command. 3cm, 4cm
    w A variable that represents the width of the image. Can be used with modifiers to indicate a position along the x-axis. See Combination (Rectangle)
    h A variable that represents the height of the image. Can be used with modifiers to indicate a position along the y-axis. See Combination (Rectangle)
    Modifiers
    <decimal>x Use in front of a basic coordinate value to multiply it by the given decimal value. If using a decimal value that is less than 1, enter a 0 before the decimal point.

    0.1wv,0.25xh

    2x90px,3x1cm

    <integer>/<integer>x Use in front of a basic coordinate value to multiply it by the given fractional value.

    1/10xw,1/4xh

    1/10x90px,0.25xh

    Alignment Values

    *

    center

    Use in place of the x- or y-axis value to align the center of the rectangle or superimposed image with the center of the base image.

    *,0.25xh

    center,0.25xh

    left

    right

    Use in place of the x-axis value to align the left or right edge of the rectangle or superimposed image flush with the corresponding edge of the base image.

    left,0.25xh

    right,10

    top

    bottom

    Use in place of the y-axis value to align the top or bottom edge of the rectangle or superimposed image flush with the corresponding edge of the base image.

    0.25xw,top

    10,bottom

    left[<offset>]

    right[<offset>]

    top[<offset>]

    bottom[<offset>]

    Behaves similarly to the other alignment values but shifts the rectangle or superimposed image away from the edge by the offset amount specified.

    left[0.1xw],0.25xh

    right[1/10xw],10

    0.25xw,top[10]

    10,bottom[1/10xh]

    Dimension

    Basic syntax: <width>:<height>

    Dimensions can be used in the box, crop, downsize, fit, and resize commands. In the composite and composite-to commands, dimensions are used when indicating placement as a rectangle.

    Use the following table to see the available options for dimension values:

    Value Description Example
    Basic Values
    <integer> A position on the x- or y-axis given in pixels. Equivalent to <integer>px. 100:120
    <integer><unit> A position on the x- or y-axis given in units you’ve defined with the unit command. 3cm:4cm
    w A variable that represents width. Use alone to indicate that the width should not be altered. Use with a modifier to scale the width. w:300
    h A variable that represents height. Use alone to indicate that the height should not be altered. Use with a modifier to scale the height.

    300:h

    w:h

    Modifiers
    <decimal>x Use in front of a basic dimension value to multiply it by the given decimal value. If using a decimal value that is less than 1, enter a 0 before the decimal point.

    0.25xw:0.25xh

    1.2xw:1.3xh

    <integer>/<integer>x Use in front of a basic dimension value to multiply it by the given fractional value.

    1/4xw:1/4xh

    1/10xw:1/4xh

    Variable that Preserves Aspect Ratio
    * Use in place of a dimension value to preserve the aspect ratio relative to the other dimension value.

    *:120

    2in:*

    0.25xw:*

    Combination (Rectangles)

    Basic syntax: <width>:<height>;<x>,<y> (Where <width> and <height> are dimension parameters, and <x> and <y> are location parameters)

    A rectangle value is required for the box and crop commands and is optional for the composite and composite-to commands.

    • In the crop command, the dimensions indicate the size of the area of the image you want to keep. The location indicates the upper-left corner of the area you want to keep.
    • In the composite command, the dimensions indicate the size of the image you want to superimpose on the base image. The location indicates the upper-left corner of the image being superimposed on the base image.
  3. Available commands with the Image Converter (IC)

    The following table shows the available commands with the Akamai IC:

    Command Description Syntax Values
    background-color Sets the background color for transparent portions of images. background-color=<color>

    HTML color

    Hex color

    box Draws a rectangle on the image. box=<rectangle>|color[<color>]|
    fill|stroke[<linewidth>]

    If you omit an optional value, also omit the associated pipe (|) symbol.

    rectangle

    color

    fill

    linewidth

    composite

    composite-to

    Combines two images. Commonly used to apply a watermark to an image.

    The difference between these commands is which of the two images, the one in the IC command or the one in the base URL or image tag, is superimposed:

    • composite superimoses the image in the IC command to the base image
    • composite-to superimposes the base image onto the image in the IC command

    composite=<placement>|<image-URL>

    composite=<opacity>|<placement>|<image-URL>

    composite-to=<placement>|<image-URL>

    composite-to=<opacity>|<placement>|<image-URL>

    opacity

    placement

    image URL: With composite, the image URL is the URL of the top image. With composite-to, the image URL is the URL of the bottom image.

    crop Cuts out a section of an image crop=<dimensions>;<location>

    dimensions

    location

    downsize Scales, or resizes, the image to the dimensions you specify. However, if you enter a dimension that is larger than the original, the image’s dimension will not be changed. downsize=<width>:<height> dimensions
    fit Resize an image into the specified dimensions while maintaining aspect ratio.

    fit=inside|<dimensions>

    fit=around|<dimensions>

    inside

    around

    dimensions

    interpolation Indicates which algorithm to use when changing the size of an image. interpolation=<algorithm>

    bilinear

    bicubic

    nearest-neighbor

    progressive-bilinear

    progressive-bicubic

    lanczos-none

    output-format

    Renders the image in the specified format.

    The output formats available are GIF, JPEG, and PNG.

    output-format=<image-format>

    gif or image/gif

    jpeg, image/jpeg, jpg, or image/jpg

    png or image/png

    webp or image/webp

    jp2 or image/jpeg2000

    jpegxr or image/vnd.ms-photo

    output-quality For JPEG output, sets the desired quality of the output image. output-quality=<quality-value> integer from 1 to 100
    resize Scales, or resizes, the image to the dimensions you specify. resize=<width>:<height> dimensions
    unit Defines a new measurement unit in terms of existing units. unit=<sizeunit>::<sizecurrent>

    sizeunit is one or more integers followed by letters representing the unit of measurement

    sizecurrent is either pixels (default) or a unit of measurement you previously defined in your query string

Expected outcome

You are able to manipulate images through Akamai API commands appended to an image’s URL.

Join The Discussion

Your email address will not be published. Required fields are marked *