ericmaciel/swift-png

decode, inspect, edit, and encode png images in pure swift

png
4.1.0

Swift PNG is a Foundation-less, cross-platform framework for decoding, inspecting, editing, and encoding PNG images. The framework is written in pure Swift, and will compile and provide consistent behavior on all Swift platforms. The library also comes with built-in file system support on linux, macOS, and Windows.

Swift PNG is available under the Mozilla Public License 2.0. The example programs are public domain and can be adapted freely.

tutorials and example programs

1. basic decoding (sources)
2. basic encoding (sources)
3. using indexed images (sources)
4. using iphone-optimized images (sources)
5. working with metadata (sources)
6. using in-memory images (sources)
7. online decoding (sources)
8. custom color targets (sources)

api reference

• PNG.PNG
• PNG.LZ77
• PNG.System

getting started

To use Swift PNG in a project, add this descriptor to the dependencies list in your Package.swift file:

.package(url: "https://github.com/kelvin13/swift-png", .exact("4.0.2")) 

basic usage

Decode an image:

import PNG 
func decode(png path:String) throws 
{
    guard let image:PNG.Data.Rectangular = try .decompress(path: path)
    else 
    {
        // failed to access file from file system
    }

    let rgba:[PNG.RGBA<UInt8>] = image.unpack(as: PNG.RGBA<UInt8>.self), 
        size:(x:Int, y:Int)    = image.size
    // ...
}

Encode an image:

func encode(png path:String, size:(x:Int, y:Int), pixels:[PNG.RGBA<UInt8>]) throws
{
    let image:PNG.Data.Rectangular = .init(packing: pixels, size: size, 
        layout: .init(format: .rgba8(palette: [], fill: nil)))
    try image.compress(path: path, level: 9)
}

features

• Powerful interfaces. Swift PNG’s expressive, strongly-typed APIs make working with PNG images easy for beginners and advanced users alike. If your code compiles, you’re already most of the way there. Power users can take advantage of custom indexing, manual decoding workflows, and user-defined color targets.

• Superior compression. Swift PNG supports minimum cost path-based DEFLATE optimization, which is why it offers four additional compression levels beyond what libpng supports. Swift PNG outperforms libpng at its highest compression setting by significant margins for almost all types of input images.

• Competitive performance. Swift PNG offers competitive performance compared to libpng. On appropriate CPU architectures, the Swift PNG encoder makes use of hardware-accelerated hash tables for even greater performance.

• Pure Swift, all the way down. Swift PNG is powered by its own, native Swift DEFLATE implementation. It depends only on other Foundation-less, pure-Swift libraries, and therefore does not need to link Foundation. This also means the core components of Swift PNG work on any platform that Swift itself works on, and that Swift PNG’s performance improves as the Swift compiler matures.

• Batteries included. Swift PNG comes with built-in color targets with support for premultiplied alpha. Convolution and deconvolution helper functions make implementing custom color targets a breeze.

  On MacOS and Linux, Swift PNG has built-in file system support, allowing you to compress or decompress an image, given a filepath, in a single function call. Other platforms can take advantage of Swift PNG’s protocol-oriented IO to implement their own data loading.

• First-class iPhone optimization support. Swift PNG requires no custom setup or third-party plugins to handle iPhone-optimized PNG images. iPhone-optimized images just work, on all platforms. Reproduce pngcrush’s output with bit width-aware alpha premultiplication, for seamless integration anywhere in your application stack.

• Comprehensive metadata support. Swift PNG can parse and validate all public PNG chunks, which are accessible as strongly-typed metadata records.

• Modern error handling. Swift PNG has a fully stateless and Swift-native error-handling system.

infrastructure

A list of build flags can be found here. Project automation scripts live in the utils/ directory, and are invoked as follows:

• utils/examples [-c/--configuration debug | release]

  Builds and runs the example programs in the examples/ directory. The --configuration argument specifies the Swift build mode to use.

• utils/benchmark [-t/--trials n0 n1 n2] [-s/--save] [-l/--load]

  Runs library performance and compression benchmarks, and generates a performance report.

  The --trials argument specifies the number of trials to run, for decompression, compression, and historical toolchain benchmarks, respectively. The --save argument makes this script store benchmark measurements in cache files; the --load argument makes this script use cached measurements instead of re-running the benchmarks.

• utils/generate-documentation [-l/--local]

  Generates documentation pages for the library using Entrapta. A Github action invokes this script and deploys the output to the Swift PNG API reference website on every commit.

The CI runs Swift PNG’s test suites with the following invocations:

swift run            PNGTests
swift run -c release PNGIntegrationTests
swift run -c release PNGCompressionTests

see also

• Swift JPEG