Tutorial for the Image API SDK

ShimmerCat Image Optimization comes as an API (Application Programming Interface), provided also as a SDK (Software Development Kit). The SDK simplifies using the image API by wrapping the request state machine. To optimize an image, all you need is a valid API token. Here we have created a tutorial on how to use it.

Check out the repo at https://gitlab.zunzun.se/public-items/toilmore-sdk/tree/develop/javascript

Prerequisites:

• Latest versions of npm and nodejs installed. Check here for installation

Installing

01. Create a directory

$ mkdir toilmore
$ cd toilmore

02. Execute the command npm install --save-dev @shimmercat/toilmore-sdk

This will create a directory which looks similar to:

../toilmore
├── node_modules
│   └── @shimmercat
│       └── toilmore-sdk
│           ├── index.js
│           ├── lib
│           │   ├── api_config.js
│           │   ├── http_requester.js
│           │   ├── stream_helpers.js
│           │   └── submit_machine.js
│           ├── package.json
│           └── README.md
└── package-lock.json

4 directories, 8 files

03. Next

$ cd node_modules/@shimmercat/toilmore-sdk/
$ npm link 
$ npm install . 
$ npm link '@shimmercat/toilmore-sdk'

04. Depending on the preferred API create a .js file to process any image that you want:

Make sure to provide a valid authentication token as the api_token.

Light API

$ vim light.js

import { LIGHT_API, Toilmore } from '@shimmercat/toilmore-sdk';
import fs from "fs";
import { Readable } from "stream";

let toilmore = new Toilmore(
    {
        'api_config': LIGHT_API, 

        'api_token': 'XXXXXXXXXXXXXXXXXXXXXXXXXXX',   // <-- Use a valid API token here.

        'domain': 'shimmercat.com'
    });


let adjustments = {
    "encoder": {
        "quality-measure": 'fsim-c',
        "qual-threshold": 90
    }
}

let force_processing = false;

let result_promise =  toilmore.optimize_with_precursor("costume.png", "webp0", force_processing,  adjustments);
result_promise.then((result) => {
    // `result` can contain a short status string or null if the image 
    // could not be optimized. 
    let w = fs.createWriteStream("./costume_light.webp");
    result.pipe(w);
});

Lux API

$ vim lux.js

import { LUX_API, Toilmore } from '@shimmercat/toilmore-sdk';
import fs from "fs";
import { Readable } from "stream";

let adjustments = {
    "encoder": {
        "quality-measure": "fsim-c",
        "qual-threshold": 90
    }
}

let toilmore = new Toilmore(
    {
        'api_config': LUX_API,

        'api_token': 'XXXXXXXXXXXXXXXXXXXXXXXXXX',   // <-- Use a valid API token here.

        'domain': 'shimmercat.com'
    });

let force_processing = false;

let result_promise =  toilmore.optimize_with_precursor("./costume.png", "webp0", force_processing, adjustments);
result_promise.then((result) => {
    // `result` can contain a short status string or null if the image
    // could not be optimized.
   
    let w = fs.createWriteStream("./costume_lux.webp");
    result.pipe(w);
});

05 Run the js. Before running the js you can also refer on how to configure the json file and what options are available.

$ node <file_name>.js 

Examples of different options values that can be used for each parameter type.

We are using as an example the image

1.How can I optimize an image in other formats (jpeg2000, avid, etc)

In the line provide the image format from the list [webp0, prjpg, pngzo, jp2o0, avifo0] you need to convert your image into just after the image, for example in here the my_image.jpg will be converted into webp0 format.

let result_promise =  toilmore.optimize_with_precursor("./my_image.jpg", "webp0");

List of transformed images with different image formats, qualityt: 90, algorithm: fsim-c and image width: original width

webp0: WebP

prjpg: Standard, JPEG image format

pngzo: PNG

jp2o0: JPEG2000

avifo0: AVIF image format

2. How can I scale an image to a specific width?

From the width list [2000, 1500, 1120, 750, 560, 375, 260, 180, 140, 90] select the width that is required and configure the line:

"scale-to-width": 90 

3. How can I use different quality measures, and thresholds?

From the quality list [90, 91, 92, 93, 94, 95, 96, 97, 98, 99] select the width that is required and configure the line:

"qual-threshold": 90

List of transformed images with different quality measures, image format: webp, algorithm: fsim-c and image width: original width

“qual-threshold”: 90

“qual-threshold”: 91

“qual-threshold”: 92

“qual-threshold”: 93

“qual-threshold”: 94

“qual-threshold”: 95

“qual-threshold”: 96

“qual-threshold”: 97

“qual-threshold”: 98

“qual-threshold”: 99

4. What are the options I can use to transform the image?

From the algorithm list [fsim-c, default, ssim, asymmetric-fsym-c, perceptual-sc] select the algorithm that is required and configure the line:

"quality-measure": 'fsim-c',

List of transformed images with different algorithms, image format: webp, quality: 90 and image width: original width

fsim-c

default

ssim

asymmetric-fsym-c

perceptual-sc