Image-client-api NPM

Image Client API

Standard library (~5K GZIP) for generating canonical URL's for consuming images at Wix, it generates the URL parameters for optimal image downloads.

Features

Maintaining pixel perfect images
Ensuring minimum download latency, maximum performance and maximum quality
Optimizing images for Retina displays
Fetching .webp images where applicable (browser support)
Handling image sharpening when needed
Optimizing image upscaling (Wix machine learning) when needed

Example

import imageSDK from 'image-client-api';

const img = new Image();

img.src = imageSDK.getScaleToFillImageUrl('some-image.jpg', 1200, 800, 640, 480, { quality: 90 });

Installation

You have 2 options:

Install package

You can install the package via npm/yarn

> npm install -s image-client-api

> yarn add image-client-api

You can install the package via npm/yarn

> npm install -s image-client-api --registry http://npm.dev.wixpress.com/

> yarn add image-client-api --registry http://npm.dev.wixpress.com/

The default UMD modules can be found in dist/.

If you want CommonJS only modules you can find them under dist/cjs/.

Include script

Include the following tag in your document:

<script src="https://static.parastorage.com/services/image-client-api/<version>/imageClientSDK.js"></script>

Make sure to replace <version> with the version you need.

If your server is provisioned by Chef you'll be provided with the correct URL.

Usage

import imageSDK from 'image-client-api';

const imageSDK = require('image-client-api');

define(['image-client-api'], function (imageSDK) { ... });

const imageSDK = window.imageClientSDK;

API

Method	Description
getScaleToFitImageURL()	Scales the designated image to fit in the given target width and height while retaining the original proportions.
getScaleToFillImageURL()	Scales the designated image with the exact given target width and height while retaining the original proportions. If the required proportions are different than the original, the image may be cropped to fill the provided width and height, so that only part of the original image might be visible. The position pointing to the place from which to crop the image, if needed, is set by default to the vertical and horizontal center of the image or set to the focalPoint x,y values if presented.
getCropImageURL()	Crops the designated image based on the supplied coordinates, starting at the x, y pixel coordinates, along with the width and height options. The image might be scaled according to the target dimensions.

Methods

getScaleToFillImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    targetWidth,
    targetHeight,
    options
)

name	description	type
relativeUrl	the original image uri	string
sourceWidth	the original image width	number
sourceHeight	the original image height	number
targetWidth	target container width	number
targetHeight	target container height	number
options	additional image settings [optional]	object

{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   name: 'hello kitty',
   quality: 80,
   upscaleMethod: 'classic',
   watermark: '3856-9876-76890-xzxz',
   isSEOBot: true
}

key	valid values	default	type
filters.blur	0-100	-	number (%)
unsharpMask.amount	0-10	0.66	float
unsharpMask.radius	0.1-500	1.0	float
unsharpMask.amount	0-255	0.01	float
name	any string	''	string
quality	5-90	80	number
upscaleMethod	'auto', 'classic', 'super'	'auto'	string
watermark	watermark manifest id	-	string
isSEOBot	true or false	false	boolean

returns image url [string]

getScaleToFillImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    targetWidth,
    targetHeight,
    options
)

name	description	type
relativeUrl	the original image uri	string
sourceWidth	the original image width	number
sourceHeight	the original image height	number
targetWidth	target container width	number
targetHeight	target container height	number
options	additional image settings [optional]	object

{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   focalPoint: {
      x: 50,
      y: 50
   },
   name: 'hello kitty',
   quality: 80, 
   upscaleMethod: 'classic'
   watermark: '3856-9876-76890-xzxz',
   isSEOBot: true
}

key	valid values	default	type
filters.blur	0-100	-	number (%)
unsharpMask.amount	0-10	0.66	float
unsharpMask.radius	0.1-500	1.0	float
unsharpMask.amount	0-255	0.01	float
focalPoint.x	0-100	-	number (%)
focalPoint.y	0-100	-	number (%)
name	any string	''	string
quality	5-90	80	number
upscaleMethod	'auto', 'classic', 'super'	'auto'	string
watermark	watermark manifest id	-	string
isSEOBot	true or false	false	boolean

returns image url [string]

getCropImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    cropX,
    cropY,
    cropWidth,
    cropHeight,
    targetWidth,
    targetHeight,
    options
)

name	description	type
relativeUrl	the original image uri	string
sourceWidth	the original image width	number
sourceHeight	the original image height	number
cropX	the X pixel coordinate to start cropping from	number
cropY	the Y pixel coordinate to start cropping from	number
cropWidth	the width constraint	number
cropHeight	the height constraint	number
targetWidth	target container width	number
targetHeight	target container height	number
options	additional image settings [optional]	object

{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   focalPoint: {
      x: 50,
      y: 50
   },
   name: 'hello kitty',
   quality: 80, 
   upscaleMethod: 'classic',
   watermark: '3856-9876-76890-xzxz',
   isSEBot: true
}

key	valid values	default	type
filters.blur	0-100	-	number (%)
unsharpMask.amount	0-10	0.66	float
unsharpMask.radius	0.1-500	1.0	float
unsharpMask.amount	0-255	0.01	float
name	any string	''	string
quality	5-90	80	number
upscaleMethod	'auto', 'classic', 'super'	'auto'	string
watermark	watermark manifest id	-	string
isSEOBot	true or false	false	boolean

returns image url [string]

Image Client API

Features

Example

Installation

Install package

In public (as open-source, dist only)

At Wix (with source)

Include script

Usage

ES6 module

CommonJS

AMD

Gobal

API

Methods

getScaleToFitImageUrl

arguments

options

returns

getScaleToFillImageURL

arguments

options

returns

getCropImageURL

arguments

options

returns