Squirrel Abstract Image Library

The missing fast and easy-to-use image decoding library for humans (not for machines).

Target Audience • Features • Image Formats • Getting Started • FAQ

SAIL is a format-agnostic cross-platform image decoding library providing rich APIs, from one-liners to complex use cases with custom I/O sources. It enables a client to load and save static, animated, multi-paged images along with their meta data and ICC profiles. :sailboat:

Target audience

Image viewers
Game developers
Anyone who needs to load or save images in different image formats with a clean and comprehensive API

Features overview

[x] Easy-to-use thread-safe C and C++ interfaces
[x] Versatile APIs: junior, advanced, deep diver, and technical diver
[x] Input/output: files, memory, custom I/O streams
[x] Load by file suffixes, paths, and magic numbers
[x] Save pixels as close as possible to the source
[x] Codec-specific tuning options like PNG filters. See FORMATS
[x] Meta data support: text comments, EXIF, ICC profiles
[x] Access to the image properties w/o decoding pixels (probing)
[x] Access to the source image properties
[x] Adding or updating image codecs with ease demonstrated by Intel [*]
[x] The best MIME icons in the computer industry :smile:

* One day Intel demonstrated the advantages of their IPP technology in speeding up decoding JPEG and JPEG 2000 images with the help of ksquirrel-libs, the predecessor of SAIL.

Features NOT provided

[ ] Image editing capabilities (filtering, distortion, scaling, etc.)
[ ] Color space conversion functions
[ ] Color management functions (applying ICC profiles etc.)
[ ] EXIF rotation

Supported image formats

N	Image format	Operations	Dependencies
1	APNG	R	libpng+APNG patch
2	AVIF	R	libavif
3	BMP	R
4	GIF	R	giflib
..	...
6	JPEG	RW	libjpeg-turbo
7	JPEG 2000	R	jasper
8	JPEG XL	R	libjxl
9	PCX	R
10	PNG	RW	libpng
..	...
12	PSD	R
13	QOI	RW
14	SVG	R	resvg
15	TGA	R
16	TIFF	RW	libtiff
..	...
18	WEBP	R	libwebp
..	...

See the full list here. Work to add more image formats is ongoing.

Benchmarks

Time to load and output default pixels (without explicit conversion) was measured. See BENCHMARKS.

Preferred installation method

Windows: Conan, vcpkg
macOS: brew, Conan, vcpkg
Linux: native packages if available, Conan, vcpkg

See BUILDING.

APIs overview

SAIL provides four levels of APIs, depending on your needs. Let's have a quick look at the junior level.

C:

struct sail_image *image;

SAIL_TRY(sail_load_from_file(path, &image));

/*
 * Handle the image pixels here.
 * Use image->width, image->height, image->bytes_per_line,
 * image->pixel_format, and image->pixels for that.
 *
 * In particular, you can convert it to a different pixel format with functions
 * from libsail-manip. With sail_convert_image(), for example.
 */

sail_destroy_image(image);

C++:

sail::image image(path);

// Handle the image and its pixels here.
// Use image.width(), image.height(), image.bytes_per_line(),
// image.pixel_format(), and image.pixels() for that.
//
// In particular, you can convert it to a different pixel format with image::convert().

It's pretty easy, isn't it? :smile: See also FAQ.

Programming languages

Programming language: C11
Bindings: C++11

Competitors

Differences from other image decoding libraries

Easily extensible with new image format plugins
Easy-to-use API providing expected business entities - images, palettes, pixels etc.
Access to source pixel data (supported by the most codecs)
Access to the image properties w/o decoding pixel data (probing)

Have questions or issues?

Opening a GitHub issue is the preferred way of communicating and solving problems.

See FAQ for more.

Architecture overview

SAIL is written in pure C11 w/o using any third-party libraries (except for codecs). It also provides bindings to C++.

SAIL codecs

SAIL codecs is the deepest level. This is a set of standalone, dynamically loaded codecs (SO on Linux and DLL on Windows). They implement actual decoding and encoding capabilities. End-users never work with codecs directly. They always use abstract, high-level APIs in libsail for that.

Every codec is accompanied with a so called codec info (description) file which is just a plain text file. It describes what the codec can actually do: what pixel formats it can load and output, what compression types it supports, and more.

By default, SAIL loads codecs on demand. To preload them, use sail_init_with_flags(SAIL_FLAG_PRELOAD_CODECS).

libsail-common

libsail-common holds common data types (images, pixel formats, I/O abstractions etc.) and a small set of functions shared between SAIL codecs and the high-level APIs in libsail.

libsail

libsail is a feature-rich, high-level API. It provides comprehensive and lightweight interfaces to decode and encode images. End-users implementing C applications always work with libsail.

libsail-manip

libsail-manip is a collection of image manipulation functions. For example, conversion functions from one pixel format to another.

libsail-c++

libsail-c++ is a C++ binding to libsail. End-users implementing C++ applications may choose between libsail and libsail-c++. Using libsail-c++ is always recommended, as it's much more simple to use in C++ applications.

Building