SQIP - a pluggable image converter with vector support

SQIP is a flexible, and a little bit different image processor. It is available as node API and CLI.

By combining plugins you can use it for several purposes:

• Create super-tiny image previews to improve your websites lazy loading experience
• Do art by converting images into abstract representations of themselves
• Quickly convert, resize or optimize a set of pixel or vector images
• More? Ideas, contributions and community plugins are very welcome

Table of contents

• Examples
• Requirements
• Node
• CLI
• Config
• Plugins
• Bundler Integrations
• Background & research
• Credits
• Contributing
• License

Examples

Check out the interactive demo to compare all plugins and configurations side by side.

Requirements

• Node.js >= 20 (https://nodejs.org/en/)
• 64-bit OS (Not all plugins, see below)

<details> <summary> <strong>Non-64bit operating systems requirements</strong> </summary>

The most common plugin sqip-plugin-primitive is packed with a 64bit executable for all 3 major operating systems. Users with non 32-bit operating system or those who simply want to use the latest and greatest verison of primitive need:

• Golang (https://golang.org/doc/install)
• Primitive (https://github.com/fogleman/primitive) (go get -u github.com/fogleman/primitive)

After installing Primitive, you may also need to add the path to the Primitive binary file.

For macOS

It would generally look something like

/Users/myMacbook/go/bin

To do this on a Mac, type: sudo vim /etc/paths into your terminal, and add the path to your Primitive binary file, but be sure to add the full path, /Users/<username>/go/bin and not ~/go/bin.

For PC

Using the command line (https://www.windows-commandline.com/set-path-command-line) Using a GUI (https://www.computerhope.com/issues/ch000549.htm)

</details>

Node

CLI see here

Installation

You need the core plugin sqip plus all the plugins you want to use like sqip-plugin-primtive, sqip-plugin-svgo and more.

For example:

npm install sqip sqip-plugin-primitive sqip-plugin-svgo sqip-plugin-data-uri

Hint: SQIP is plugin based, you might want to install more plugins later on. See Plugins section.

Migrating from v0? See the Migration Guide.

Usage

SQIP is async.

try {
  const result = await sqip({ ...options })
  console.log(result)
} catch (err) {
  console.error(err)
}

// or

sqip({ ...options })
  .then((result) => console.log(result))
  .catch((error) => console.error(error))

If you passed a single image to process, SQIP will return the following result object:

{
  content: Buffer.from('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 188">...</svg>'),
  metadata: {
    originalWidth: 1024,
    originalHeight: 640,
    palette: {
      Vibrant: Vibrant.Swatch,
      DarkVibrant: Vibrant.Swatch,
      LightVibrant: Vibrant.Swatch,
      Muted: Vibrant.Swatch,
      DarkMuted: Vibrant.Swatch,
      LightMuted: Vibrant.Swatch
    },
    width: 300,
    height: 188,
    type: 'svg',
    // These will be added by sqip-plugin-data-uri
    dataURI: "data:image/svg+xml,...",
    dataURIBase64: 'data:image/svg+xml;base64,...'
  }
}

Documentation for all 6 colors from the palette: Vibrant.Swatch

Plugins might add their own meta data

Multiple input images will result in an array of result objects.

Process folder with default settings

import { sqip } from 'sqip'
import { resolve } from 'path'
;(async () => {
  try {
    // Process whole folder with default settings
    const folderResults = await sqip({
      input: resolve(__dirname, 'images/originals'),
      output: resolve(__dirname, 'images/previews')
    })
    console.log(folderResults)
  } catch (err) {
    console.log('Something went wrong generating the SQIP previews')
    console.error(err)
  }
})()

Use custom plugin config

This will run:

• Primitive with custom settings
• SVGO with default settings

;(async () => {
  const pluginResults = await sqip({
    input: resolve(__dirname, 'images/originals'),
    output: resolve(__dirname, 'images/previews'),
    plugins: [
      {
        name: 'sqip-plugin-primitive',
        options: {
          numberOfPrimitives: 8,
          mode: 0
        }
      },
      'sqip-plugin-svgo'
    ]
  })
  console.log(pluginResults)
})()

For further configuration options see here

CLI

Installation

npm install -g sqip-cli

Usage examples

Using the help efficently

Make sure to specify plugins when using --help to see the available plugin options.

sqip -h -p primitive -p blur -p svgo

<details> <summary>Result:</summary>

sqip CLI

  Usage: sqip --input [path]

  "SQIP" (pronounced skwɪb like the non-magical folk of magical descent) is a
  SVG-based LQIP technique - https://github.com/technopagan/sqip

Options

  -h, --help string                           Show help
  --version string                            Show version number
  -p, --plugins string[]                      One or more plugins. E.g. "-p
                                              primitive blur"
  -i, --input string
  -o, --output string                         Define the path of the resulting
                                              file. By default SQIP will guess
                                              the output file name.
  -w, --width number                          Width of the resulting file.
                                              Negative values and 0 will fall
                                              back to original image width.
  --silent                                    Supress all output
  --parseable-output                          Ensure the output is parseable.
                                              Will suppress the preview images
                                              and the table borders.
  --print                                     Print resulting svg to stdout.
  -n, --primitive-numberOfPrimitives number   The number of primitive shapes to
                                              use to build the SQIP SVG
  -m, --primitive-mode number                 The style of primitives to use:
                                              0=combo, 1=triangle, 2=rect,
                                              3=ellipse, 4=circle,
                                              5=rotatedrect, 6=beziers,
                                              7=rotatedellipse, 8=polygon
  -b, --blur-blur number                      Set the blur value. If you pass a
                                              number, it will be converted to
                                              px for css blur. It will also set
                                              the stdDeviation for the legacy
                                              SVG blur.

Examples

  Output input.jpg image as SQIP
  $ sqip --input /path/to/input.jpg

  Save input.jpg as result.svg with 25 shapes and no blur
  $ sqip -i input.jpg -n 25 -b 0 -o result.svg

</details>

Process single file

$ sqip -i __tests__/fixtures/beach.jpg
Processing: __tests__/fixtures/beach.jpg
[Preview image (iTerm2 users only)]
┌───────────────┬────────────────┬───────┬────────┬──────┐
│ originalWidth │ originalHeight │ width │ height │ type │
├───────────────┼────────────────┼───────┼────────┼──────┤
│ 1024          │ 640            │ 300   │ 188    │ svg  │
└───────────────┴────────────────┴───────┴────────┴──────┘
┌─────────┬─────────────┬──────────────┬─────────┬───────────┬────────────┐
│ Vibrant │ DarkVibrant │ LightVibrant │ Muted   │ DarkMuted │ LightMuted │
├─────────┼─────────────┼──────────────┼─────────┼───────────┼────────────┤
│ #dd852f │ #be4e0c     │ #f2b17a      │ #5c8fa4 │ #694e35   │ #cfc8b7    │
└─────────┴─────────────┴──────────────┴─────────┴───────────┴────────────┘

Process multiple files via glob and use custom plugin config

sqip -p primitive -p blur -p svgo \
-i "demo/*.jpg" \
-b 6

For further configuration options see here

Config

The configuration consists of three parts. A required input, an optional output path and a configuration of plugins to be applied on the images.

input - required

Input file or directory. Supports feature rich globbing via micromatch.

CLI usage: -i/--input

output

If set, the output will be written to the given file or directory.

Otherwise, results will be output to CLI

CLI usage: -o/--output

width

Set the width of the resulting image. Negative values and 0 will fall back to the original image width.

CLI usage: -w/--width

plugins

Default: `['primitive', 'blur', 'svgo', 'data-uri']