vips

Kind	ffi-c
Capabilities	ffi
Categories	graphics ffi
Keywords	vips image processing resize thumbnail

libvips fast image processing library bindings for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_vips.c`	C FFI wrapper
`c/kit_vips.h`	C header for FFI wrapper
`examples/basic.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and native dependencies
`src/vips.kit`	Kit Vips - fast image processing library bindings
`tests/vips.test.kit`	Tests for vips

Dependencies

No Kit package dependencies.

This package links against the native libvips, glib-2.0, and gobject-2.0 libraries.

Installation

kit add gitlab.com/kit-lang/packages/kit-vips.git

System Requirements

Install libvips before building or running packages that import Kit.VIPS.

Platform	Command
macOS	`brew install vips`
Ubuntu	`sudo apt install libvips-dev`
Fedora	`sudo dnf install vips-devel`

Usage

import Kit.VIPS as vips

main = fn =>
  match vips.init
    | Err e -> println ("Failed to init libvips: " ++ e)
    | Ok _ ->
      println ("libvips version: " ++ vips.version)

      match vips.load "photo.png"
        | Err e -> println ("Load error: " ++ e)
        | Ok img ->
          println ("Size: " ++ (show (vips.get-width img)) ++ "x" ++ (show (vips.get-height img)))
          println ("Bands: " ++ (show (vips.get-bands img)))

          # Resize to 50%
          match vips.resize img 0.5
            | Err e -> println ("Resize error: " ++ e)
            | Ok resized ->
              match vips.save resized "photo-half.png"
                | Ok _ -> println "Saved resized image"
                | Err e -> println ("Save error: " ++ e)
              vips.free resized

          # Generate a thumbnail from the original file
          match vips.thumbnail "photo.png" 100
            | Err e -> println ("Thumbnail error: " ++ e)
            | Ok thumb ->
              match vips.save thumb "photo-thumb.png"
                | Ok _ -> println "Saved thumbnail"
                | Err e -> println ("Save error: " ++ e)
              vips.free thumb

          vips.free img
      vips.shutdown

main

Use vips.free for every image handle returned by load, thumbnail, or image operations such as resize, crop, invert, blur, and sharpen.

API Overview

Area	Functions
Lifecycle	`init`, `shutdown`, `version`
File I/O	`load`, `save`
Image info	`get-width`, `get-height`, `get-bands`
Geometry	`thumbnail`, `resize`, `crop`, `rotate`, `flip-horizontal`, `flip-vertical`
Filters	`invert`, `blur`, `sharpen`, `to-grayscale`
Memory	`free`

Image format support depends on the libvips build installed on the system. Common builds support PNG, JPEG, TIFF, WebP, HEIF, GIF, and SVG.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi,file-read,file-write

Compile examples to a native binary:

kit build examples/basic.kit -o /tmp/kit-vips-basic --allow=ffi,file-read,file-write
/tmp/kit-vips-basic

The basic example looks for /tmp/kit-cairo-test.png and writes processed images to /tmp/kit-vips-*.png. If the input image is missing, it prints libvips load errors and exits cleanly.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Checking Interpreter and Compiler Parity

Run the package examples through the interpreter, compiler, executable, and output comparison:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Native Binding Notes

The Kit API in src/vips.kit calls a small C wrapper in c/kit_vips.c. The package manifest declares the native requirements and links vips, glib-2.0, and gobject-2.0.

During package development, examples/basic.kit imports ../src/vips.kit directly so changes can be tested without reinstalling the package. Installed consumers should import Kit.VIPS.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/vips/, making it available for import as Kit.VIPS in other projects.

License

This package is released under the MIT License - see LICENSE for details.

libvips is released under the LGPL 2.1 License.

Exported Functions & Types

`init`

Initialize libvips. Must be called before any other operations.

Returns:

Result Unit String

`shutdown`

Shut down libvips and release global resources.

Unit

`load`

Load an image from a file.

Parameters:

Returns:

NonEmptyString -> Result Ptr String

`save`

Save an image to a file. Format is determined by file extension.

Parameters:

Returns:

Ptr -> NonEmptyString -> Result Unit String

Get the libvips version string.

Returns:

String