Squirrel Abstract Imaging Library

The missing fast imaging library for humans (not for machines).

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

SAIL is a high-quality cross-platform image decoding library providing rich APIs, from one-liners to complex use cases with custom I/O sources. It supports loading and saving static, animated, and multi-paged images along with metadata 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

• Thread-safe C, C++, and Python interfaces
• Versatile APIs: junior, advanced, deep diver, and technical diver
• Input/output: files, memory, custom I/O streams (see custom-io.c)
• Load by file extensions, paths, and magic numbers
• Format-specific tuning options (e.g., PNG filters) and read-only properties (e.g. RAW properties, video length etc.). See FORMATS
• Metadata support: text comments, EXIF, ICC profiles
• Access to image properties without decoding pixels (probing)
• Access to source image properties (source encoding, etc.)
• Preserve original pixel formats when saving
• Extensible codec architecture demonstrated by Intel [*]

* 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.

20+ image formats

Image format	Operations	Dependencies
AVIF	RW	libavif
GIF	RW	giflib
HEIF	RW	libheif, libheif-plugin-x265
JPEG	RW	libjpeg-turbo
JPEG 2000	RW	openjpeg
JPEG XL	RW	libjxl
PNG	RW	libpng
SVG	R	resvg/nanosvg
TIFF	RW	libtiff
WEBP	RW	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

• Python: PyPI - pip install sailpy
• 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().

Python:

import sailpy

image = sailpy.Image.from_file(path)

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

# View documentation
# python -m sailpy --readme

# Run image viewer example
# pip install PySide6
# python -m sailpy.examples.12_image_viewer

See also FAQ for more information.

Command-line utility

SAIL comes with a powerful command-line utility sail for image conversion, composition, and manipulation. Convert between formats, extract frames from animations, resize images, and fine-tune codec-specific options.

# Extract frame from video at specific timestamp and convert with PNG UP filter
sail convert video.mp4 frame.png --load-tuning video-seek-time=5000 --save-tuning png-filter=up

# Resize image to 800x600 with Lanczos scaling
sail resize photo.jpg 800x600 resized.jpg -m lanczos

Programming languages

Programming language: C11
Bindings: C++11, Python 3.10+

Competitors

• FreeImage
• DevIL
• SDL_Image
• stb_image
• Boost.GIL
• gdk-pixbuf
• imlib2
• CImg
• WIC (Windows only)

Differences from other image decoding libraries

• Easily extensible with new image format plugins
• Intuitive API with well-defined abstractions: images, palettes, pixels, etc.
• Access to source pixel data (supported by most codecs)
• Access to image properties without decoding pixel data (probing)

Have questions or issues?

Opening a GitHub issue is the preferred method for communication and problem resolution.

See FAQ for more information.

Architecture overview

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

SAIL codecs

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

Every codec is accompanied by a codec info (description) file, which is a plain text file. It describes the codec's capabilities: supported pixel formats for loading and output, compression types, 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 for decoding and encoding images. End users implementing C applications work with libsail.

libsail-manip

libsail-manip is a collection of image manipulation functions, such as pixel format conversion.

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 recommended for C++ applications due to its simplified interface.

Building

See BUILDING.

Philosophy

SAIL's philosophy is modularization and simplicity.

Image codecs are designed as standalone dynamically loaded files. Future improvements will be implemented as separate libraries, allowing users to choose which components to use (i.e., link against) and which to exclude.

Support

If you like the project, please consider starring the repository.

Author

Dzmitry Baryshau

License

Released under the MIT license.

Copyright (c) 2020-2026 Dmitry Baryshev

The MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.