Skip to content

imgeng/imageengine-helpers

Repository files navigation

A tiny set of helpers and TS types for building ImageEngine query URLs for your distribution.

These set of utilities only make sense if you want to use an object to declare your directives for when retrieving assets from an ImageEngine distribution.

Install it with:

npm install @imageengine/imageengine-helpers

View on npm

Types:

export type IEFormat =
    "png"  |
    "gif"  |
    "jpg"  |
    "bmp"  |
    "webp" |
    "jp2"  |
    "svg"  |
    "mp4"  |
    "jxr"  |
    "avif" 
    "jxl"  ;


export type IEFit =
    "stretch"   |
    "box"       |
    "letterbox" |
    "cropbox"   |
    "outside"   ;


export interface IEDirectives {
    width?: number;                // the intrinsic width of the final image 
    height?: number;               // the intrinsic height of the final image
    auto_width_fallback?: number;  // if WURFL device detection should be tried with a
                                   // fallback value in case it fails

    scale_to_screen_width?: number;          // 0-100 float
    crop?: [number, number, number, number]; // [width, height, left, top]

    format?: IEFormat;  // the output format
    fit?: IEFit;        // the image fit in relation to the provided width/height

    compression?: number; // 0-100
    sharpness?: number;   // 0-100
    rotate?: number;      // -360-360

    inline?: true;                 // convert image to dataURL
    keep_meta?: true;              // keep EXIF image data
    no_optimization?: true;        // don't apply IE optimizations
    force_download?: true;
    max_device_pixel_ratio: 2.1;   // 1-4 float
};

For instance:

import { build_IE_url, build_IE_directives, build_IE_query_string } from "imageengine-helpers";

let directives: IEDirectives = {
    width: 400,
    height: 200,
    fit: "cropbox", 
    compression: 10,
    inline: true,
    format: "png",
    force_download: true,
    max_device_pixel_ratio: 2.1
};

let source_url: string = "https://my_ie_distribution.imgeng.io/path/to_asset1.jpg";

let final_url: string = build_IE_url(source_url, directives);

/*
"https://my_ie_distribution.imgeng.io/path/to_asset1.jpg?imgeng=/w_400/h_200/m_cropbox/cmpr_10/in_true/f_png/dl_true"
*/

let directives_string: string = build_IE_directives(directives);

/*
"/w_400/h_200/m_cropbox/cmpr_10/in_true/f_png/dl_true"
*/

let query_string: string = build_IE_query_string(directives);

/*
"?imgeng=/w_400/h_200/m_cropbox/cmpr_10/in_true/f_png/dl_true"
*/