node-flif

Star this repo to increase the amount of FLIF in the world.

---

A Node wrapper for the FLIF CLI executable.

FLIF is a lossless image format designed with the web in mind. It has lots of great features. To learn more about the format go to FLIF.info.

This repository is for a Node.js module that wraps around a native executable for your platform. That executable performs the actions of encoding or decoding FLIF files. This wrapper allows you to pass in a javascript object containing your settings into a function that will create the commandline arguments for you and then run them against the executable CLI. It will also warn you if you pass in the wrong parameters or types of data.

---

node-flif is NOT meant for browsers

Since node-flif wraps around a native executable and references the file system, it cannot be ran in a browser.

If you would like to encode/decode flif files in a browser look into other projects like:

• Poly FLIF
• libflif.js

---

Supported Environments

• Windows - Node v1.0.0+ (Tested in v0.12.18 and it wouldn't work, works on 1.0.0-8.x.x)
• Linux/OSX - Node v8.0.0+ (Tested in 2.5.0, 3.3.1, 4.0.0, 4.8.4, 5.0.0, 6.0.0, 7.0.0, 7.10.1, none worked. Tested in Ubuntu 16 and OSX 10.11 on Node 8.0.0 and 8.4.0 and it worked.)

Why the difference between Node version on Win/*Nix:

Linux/OSX is using flif-wasm, it has a few known Windows-specific bugs however. So on Windows we are using a pre-built 32-Bit flif.exe file. Because flif-wasm relies on Node 8+, node-flif on those platforms requires that same version. Where as the Windows version does not have that requirement.

---

Basic usage

Here is the basic encode, decode, transcode usage. Detailed API below.

Install (requires Node/npm)

npm install --save node-flif

Asynchronous encode example:

var nodeFLIF = require('node-flif');
var path = require('path');
 
var encodeParams = {
    input: path.join(process.cwd(), 'your-file.png'),
    output: path.join(process.cwd(), 'new-file.flif')
};
nodeFLIF.encode(encodeParams, function (data) {
    console.log('Encode finished.');
    if (data) {
        console.log(data);
    }
});

Synchronous encode example:

var nodeFLIF = require('node-flif');
var path = require('path');
 
var encodeParams = {
    input: path.join(process.cwd(), 'your-file.png'),
    output: path.join(process.cwd(), 'new-file.flif'),
    async: false
};
 
var data = nodeFLIF.encode(encodeParams);
console.log('Encode finished');
if (data) {
    console.log(data);
}

Asynchronous decode example:

var nodeFLIF = require('node-flif');
var path = require('path');
 
var decodeParams = {
    input: path.join(process.cwd(), 'your-file.flif'),
    output: path.join(process.cwd(), 'new-file.png')
};
nodeFLIF.decode(decodeParams, function (data) {
    console.log('Decode finished.');
    if (data) {
        console.log(data);
    }
});

Synchronous decode example:

var nodeFLIF = require('node-flif');
var path = require('path');
 
var decodeParams = {
    input: path.join(process.cwd(), 'your-file.flif'),
    output: path.join(process.cwd(), 'new-file.png'),
    async: false
};
 
var data = nodeFLIF.decode(decodeParams);
console.log('Decode finished');
if (data) {
    console.log(data);
}

Asynchronous transcode example:

var nodeFLIF = require('node-flif');
var path = require('path');
 
var transcodeParams = {
    input: path.join(process.cwd(), 'your-file.flif'),
    output: path.join(process.cwd(), 'new-file.flif')
};
nodeFLIF.transcode(transcodeParams, function (data) {
    console.log('Transcode finished.');
    if (data) {
        console.log(data);
    }
});

Synchronous transcode example:

var nodeFLIF = require('node-flif');
var path = require('path');
 
var transcodeParams = {
    input: path.join(process.cwd(), 'your-file.flif'),
    output: path.join(process.cwd(), 'new-file.flif'),
    async: false
};
 
var data = nodeFLIF.transcode(transcodeParams);
console.log('Transcode finished');
if (data) {
    console.log(data);
}

In the above examples the variable of data should be undefined in normal use. It will only have a value if the flif executable returns text (likely a warning or error).

Additional API details below.

---

API

---

Encode

Convert your image to a FLIF.

var nodeFLIF = require('node-flif');
 
var encodeParams = {
    // Required encoding parameters
    input: ['/path/to/input-file.png'],  // String for one file or Array of input files for frames, Each must end in one of these: .png, .pnm, .ppm, .pgm, .pbm, .pam
    output: '/path/to/output-file.flif', // Must end in .flif
    // Common optional encoding parameters
    async: true,            // Set to false to run this as a synchronous encoding
    overwrite: false,       // Set to true to overwrite existing files on output (default is false)
    effort: 60,             // 0 = fast/poor compression, 100 = slowest/best? (default is 60)
    interlace: 'auto',      // true, false, or 'auto' (interlacing except on tiny images) (default is 'auto')
    encodeQuality: 100,     // 0-100, where 99 and below are lossy (default is 100)
    keepAlpha: false,       // Stores the original RGB data with 0 alpha (transparent) (default is false)
    crc: true,              // Set to false to skip verifying/adding CRC (default is true)
    keepMetaData: true,     // Set to false to strip EXIF/XMP metadata (default is true)
    keepColorProfile: true, // Set to false to strip ICC color profile (default is true)
    keepPalette: false,     // Set to true to keep the existing PNG pallete. (default is false)
    frameDelay: [100],      // Animation frame delay in ms. Array of number(s). (default is [100] which applies to all frames)
    // Advanced optional encoding parameters
    maxPaletteSize: 512,    // Max number of colors to store in a FLIF palette. PNG/GIF use 256. (FLIF default is 512)
    colorBuckets: 'auto',   // true, false, or 'auto' (default is 'auto')
    channelCompact: true,   // true or false (default is true)
    ycocg: true,            // false will disable YCoCg transform and use G(R-G)(B-G) (default is true)
    subtractGreen: true,    // false will disable YCoCg and SubtractGreen transform and use GRB (default is true)
    frameShape: true,       // false will disable Frame_Shape transform (default is true)
    maxFrameLookBack: 1,    // Max number of frames for Frame_Lookback (allows -1-256, default is 1)
    maniacRepeats: 2,       // MANIAC learning iterations; (default is 2)
    maniacThreshold: 64,    // MANIAC tree growth split threshold, in bits saved (default is 64)
    maniacDivisor: 30,      // MANIAC inner node count divisor (allows 1-268435455, default is 30)
    maniacMinSize: 50,      // MANIAC post-pruning threshold; (min allowed: 0, default is 50)
    chanceCutoff: 2,        // Minimum chance, 0-4096 (allows 1-128, default is 2)
    chanceAlpha: 19,        // Chance decay factor (allows 2-128, default is 19)
    adaptive: false,        // true will apply an adaptive lossy encoding, 2nd input image is saliency map (default is false)
    guess: {                // Pixel predictor for each plane (Y, Co, Cg, Alpha, Lookback)
        y: 'heuristically', // 'average', 'median gradient', 'median number', 'mixed', default is 'heuristically'
        co: 'heuristically',
        cg: 'heuristically',
        alpha: 'heuristically',
        lookback: 'heuristically'
    },
    alphaGuess: 'average',  // Predictor for invisible pixels (only if keepAlpha is false)
                            // `'average'`, `'median gradient'`, `'median neighbors'` (Default is to set keepAlpha to true)
    chromaSubsample: false  // true to write an incomplete 4:2:0 chroma subsampled lossy FLIF file (default is false)
};
 
// By default encode is asynchronous, and can accept an optional callback.
// If you set the async param to false and pass in a callback it will be ignored.
nodeFLIF.encode(encodeParams, function (data) {
    console.log('Encode finished.');
    if (data) {
        console.log(data);
    }
});

A note on keepPalette; by default, we read PNG images as 24-bit RGB or 32-bit RGBA. node-flif will automatically use a palette if the number of colors turns out to be low (doesn't matter if the original PNG is PNG8 or PNG24/32). The order the colors are stored in the FLIF palette is not related to the PNG8 palette order. By default it sorts on luma, the first component of YCoCg. The option keepPalette: true makes it read/write PNG8, and preserve the palette order. The FLIF format itself supports any palette order (though sorted on luma is slightly more compact to encode), and it supports more than 256 colors too. The main advantage of keepPalette: true is that you get full control over the palette order, and also a better memory footprint (because everything stays at 8-bit per pixel, no intermediate representation as 24-bit / 32-bit RGBA).

---

Decode

Convert your image from a FLIF.

var nodeFLIF = require('node-flif');
 
var decodeParams = {
    // Required decoding parameters
    input: '/path/to/input-file.flif',  // Must end in .flif
    output: '/path/to/output-file.png', // Must end in one of these: .png, .pnm, .ppm, .pgm, .pbm, .pam
    // Common optional decoding parameters
    async: true,            // Set to false to run this as a synchronous decoding
    overwrite: false,       // Set to true to overwrite existing files on output (default is false)
    decodeQuality: 100,     // 0-100 Lossy decode quality (default is 100)
    keepMetaData: true,     // Set to false to strip EXIF/XMP metadata (default is true)
    keepColorProfile: true, // Set to false to strip ICC color profile (default is true)
    // Advanced optional decoding parameters
    crc: true,              // Set to false to skip verifying/adding CRC (default is true)
    keepPalette: false,     // Set to true to keep the existing PNG pallete. (default is false)
    scale: 1,               // Lossy downscaled image at scale 1:N (2,4,8,16,32) (default 1)
    resize: {               // Lossy downscaled image to fit inside given Width/Height (default uses input dimensions)
        width: 200,
        height: 400
    },
    fit: {                  // Lossy downscaled image to exactly the given Width/Height (default uses input dimensions)
        width: 200,
        height: 400
    }
};
 
// By default encode is asynchronous, and can accept an optional callback.
// If you set the async param to false and pass in a callback it will be ignored.
nodeFLIF.decode(decodeParams, function (data) {
    console.log('Decode finished.');
    if (data) {
        console.log(data);
    }
});

---

Transcode

Create a new FLIF from an existing FLIF with new settings.

Accepts all the same parameters as Encode and Decode (combined).

var nodeFLIF = require('node-flif');
 
var transcodeParams = {
    // Required transcoding parameters
    input: '/path/to/input-file.flif',   // Must end in .flif
    output: '/path/to/output-file.flif', // Must end in .flif
    // All encoding and decoding parameters are accepted
};
 
// By default encode is asynchronous, and can accept an optional callback.
// If you set the async param to false and pass in a callback it will be ignored.
nodeFLIF.transcode(transcodeParams, function (data) {
    console.log('Transcode finished.');
    if (data) {
        console.log(data);
    }
});

---

Identify

Identify is a synchronous command that will return an object containing the name, dimensions, color, size, and interlace data about the image.

var nodeFLIF = require('node-flif');
 
var pizzaData = nodeFLIF.identify('./images/pizza.flif');
 
console.log(pizzaData);

The above snippet will console log out an object similar to this:

{
    file: 'images/pizza.flif',
    dimensions: '768x512',
    color: '8-bit RGB',
    interlace: 'interlaced',
    size: 475578
}

---

Executable Path

Returns a string of the internal path to the flif executable specific to your OS (win32/linux/darwin) and architecture (x86/x64).

Design rationale: It is assumed that there will be some people who just want a copy of the built executable for their system to use a CLI instead of using the Node wrapper.

var path = require('path');
var nodeFLIF = require('node-flif');
 
// 'executables\\win32\\flif.exe'
var internalFlifPath = nodeFLIF.executablePath;
 
// 'C:\\projects\\your-site\\node_modules\\node-flif\\executables\\win32\\flif.exe'
var flifFullPath = path.join(process.cwd(), 'node_modules', 'node-flif', nodeFLIF.executablePath);

---

Breakpoints

Gives you information about the breakpoints in an image to allow for truncating the file at different points. The breakpoints, or "truncation offsets", are for truncations at scales 1:8, 1:4, 1:2. This function runs synchronously. Non-interlaced flifs will return an empty object.

var nodeFLIF = require('node-flif');
 
var pizzaBreakpoints = nodeFLIF.breakpoints('./images/pizza.flif');
 
console.log(pizzaBreakpoints);

The above snippet will console log out an object similar to this:

{
    offsetStart: 11,
    eighth: 8080,
    fourth: 24900,
    half: 90422
}

For non-interlaced flifs, you will get an empty object back. You can also detect if an image is interlaced or not by using nodeFLIF.identify.

{}

---

Version

Returns the version of node-flif and the FLIF executable as an object.

var nodeFLIF = require('node-flif');
 
var nodeFLIFVersions = nodeFLIF.versions; // { nodeFLIF: '0.2.0', flif: '0.3.0' }
var nodeFLIFVersion = nodeFLIF.version.nodeFLIF; // '0.2.0'
var flifVersion = nodeFLIF.version.flif // '0.3.0'

Here is a table of each version of Node-FLIF and the corresponding version of FLIF that shipped with it.

node-flif	flif	flif-wasm
1.0.1	0.3.0	1.0.7
1.0.0	0.3.0	1.0.7
0.2.0	0.3.0	1.0.3
0.1.0	0.3.0	N/A

---

Documentation Table

Conversion	Parameter	Default	Type	Allowed	Description
Transcode	input	N/A	string	String must be a valid path ending in .flif	Path to location of FLIF file
Decode	input	N/A	string	String must be a valid path ending in .flif	Path to location of FLIF file
Encode	input	N/A	string or array of strings	Strings can be any valid path ending in one of these: .png, .pnm, .ppm, .pgm, .pbm, .pam	Array of input files for frames, or a single string that is the path to the file
Transcode	output	N/A	string	String must be a valid path ending in .flif	Path to the location of where the output file should be created
Decode	output	N/A	array of strings	Strings can be any valid path ending in one of these: .png, .pnm, .ppm, .pgm, .pbm, .pam	Path to the location of where the output file should be created
Encode	output	N/A	string	String must be a valid path ending in .flif	Path to the location of where the output file should be created
Transcode, Decode, Encode	async	true	boolean	true, false	Set to false to run as a synchronous encoding
Transcode, Decode, Encode	overwrite	false	boolean	true, false	Set to true to overwrite existing files on output
Transcode, Decode, Encode	crc	true	boolean	true, false	Set to false to skip verifying/adding CRC
Transcode, Decode, Encode	keepMetaData	true	boolean	true, false	Set to false to strip EXIF/XMP metadata
Transcode, Decode, Encode	keepColorProfile	true	boolean	true, false	Set to false to strip ICC color profile
Transcode, Decode, Encode	keepPalette	false	boolean	true, false	Set to true to keep the existing PNG pallete.
Transcode, Decode	scale	1	number	1, 2, 4, 8, 16, 32	Lossy downscaled image at scale 1:N
Transcode, Decode	resize	N/A	object	Object must contain the keys width and height, their pairs must be whole numbers greater than 0	Lossy downscaled image to fit inside given Width/Height
Transcode, Decode	fit	N/A	object	Object must contain the keys width and height, their pairs must be whole numbers greater than 0	Lossy downscaled image to fit exactly the given Width/Height
Transcode, Decode	decodeQuality	100	number	Min: 0, Max: 100	99 and below are lossy
Transcode, Encode	encodeQuality	100	number	Min: 0, Max: 100	99 and below are lossy
Transcode, Encode	effort	60	number	Min: 0, Max: 100	0 = fast/poor compression, 100 = slowest/best?
Transcode, Encode	interlace	'auto'	boolean, 'auto'	true, false, or 'auto'	Enable or disable interlacing. Auto will enable except on tiny images
Transcode, Encode	keepAlpha	false	boolean	true, false	Stores the original RGB data with 0 alpha (transparent)
Transcode, Encode	frameDelay	[100]	array of numbers	Numbers Min: 0, Numbers Max 60000. Amount of frames is limited by available memory, not a number	Animation frame delay in ms. Array of number(s). (default is [100] which applies to all frames)
Transcode, Encode	maxPaletteSize	512	number	Min: -32000, Max: 32000	Max number of colors to store in a FLIF palette. PNG/GIF use 256. FLIF default is 512. 0 will disable palette. Simple FLIF decoders (8-bit only) cannot palettes over 512.
Transcode, Encode	colorBuckets	'auto'	boolean, 'auto'	true, false, or 'auto'	Disable Color_Buckets transform
Transcode, Encode	channelCompact	true	boolean	true, false	Disable Channel_Compact transform
Transcode, Encode	ycocg	true	boolean	true, false	False will disable YCoCg transform and use G(R-G)(B-G)
Transcode, Encode	subtractGreen	true	boolean	true, false	False will disable YCoCg and SubtractGreen transform and use GRB
Transcode, Encode	frameShape	true	boolean	true, false	False will disable Frame_Shape transform
Transcode, Encode	maxFrameLookBack	1	number	Min: -1, Max: 256	Max number of frames for Frame_Lookback
Transcode, Encode	maniacRepeats	2	number	Min: 0, Max: 20	MANIAC learning iterations
Transcode, Encode	maniacThreshold	64	number	Min: 4, Max: 100000	MANIAC tree growth split threshold, in bits saved
Transcode, Encode	maniacDivisor	30	number	Min: 1, Max: 268435455	MANIAC inner node count divisor
Transcode, Encode	maniacMinSize	50	number	Min: 0, No Max	MANIAC post-pruning threshold
Transcode, Encode	chanceCutoff	2	number	Min: 1, Max: 128	Minimum chance, 0-4096
Transcode, Encode	chanceAlpha	19	number	Min: 2, Max: 128	Chance decay factor
Transcode, Encode	guess	{}	object	Object can contain any sub-parameter of y, co, cg, alpha, or lookback. All are optional.	Object containing the pixel predictors for each plane (Y, Co, Cg, Alpha, Lookback)
Transcode, Encode	guess.y	'heuristically'	string	'average', 'median gradient', 'median number', 'mixed', or 'heuristically'	Pixel predictor for Y
Transcode, Encode	guess.co	'heuristically'	string	'average', 'median gradient', 'median number', 'mixed', or 'heuristically'	Pixel predictor for Co
Transcode, Encode	guess.cg	'heuristically'	string	'average', 'median gradient', 'median number', 'mixed', or 'heuristically'	Pixel predictor for Cg
Transcode, Encode	guess.alpha	'heuristically'	string	'average', 'median gradient', 'median number', 'mixed', or 'heuristically'	Pixel predictor for Alpha
Transcode, Encode	guess.lookback	'heuristically'	string	'average', 'median gradient', 'median number', 'mixed', or 'heuristically'	Pixel predictor for Lookback
Transcode, Encode	alphaGuess	keepAlpha: true	string	'average', 'median gradient', 'median neighbors'	Predictor for invisible pixels (only if keepAlpha is false). Has no default, as default is to keep the original alpha values.
Transcode, Encode	chromaSubsample	false	boolean	true, false	True to write an incomplete 4:2:0 chroma subsampled lossy FLIF file
Encode	adaptive	N/A	string	String must be a valid path ending in one of these: .png, .pnm, .ppm, .pgm, .pbm, .pam	Uses image path as saliency map to apply an adaptive lossy encoding. Must use encodeQuality < 100 and only one input image

---

TO-DO List

• Add in more multi-arg tests for encode/decode/transcode
• Create automated end-to-end testing folder that verifies tests
• Add it to the npm registry when at v1.0.0.
• Wait for npm registry to allow for private emails or publishing without email verification