image

Kind	ffi-c
Capabilities	ffi file
Categories	graphics image ffi
Keywords	image png jpeg graphics stb

Image loading and manipulation for Kit using stb_image

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_image.c`	C FFI wrapper (compiles stb_image implementations)
`c/kit_image.h`	C header for FFI wrapper
`c/stb_image.h`	stb_image v2.30 (bundled, header-only)
`c/stb_image_write.h`	stbimagewrite v1.16 (bundled, header-only)
`examples/basic.kit`	Basic image loading and saving example
`examples/drawing.kit`	Drawing primitives example
`examples/filters.kit`	Image filters example (grayscale, invert, brightness)
`kit.toml`	Package manifest with metadata and dependencies
`src/image.kit`	kit-image: Image loading and manipulation
`tests/image.test.kit`	Tests for image operations

Dependencies

No Kit package dependencies.

Installation

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

No external library installation is required -- stbimage and stbimage_write are bundled with this package.

Usage

import Kit.Image as Image

main = fn =>
  # Create a 200x200 RGBA image
  img = Image.create 200 200 |> Result.unwrap

  # Fill with a solid color
  Image.fill img Image.cyan

  # Draw a red rectangle
  Image.draw-rect img 20 20 160 160 Image.red

  # Draw a rectangle outline
  Image.draw-rect-outline img 10 10 180 180 Image.white

  # Set individual pixels
  Image.set-pixel? img 100 100 (Image.rgb 128 0 255)

  # Get a pixel color
  match Image.get-pixel img 100 100
    | Some color -> println "Pixel: ${Image.color-to-hex color}"
    | None -> println "Out of bounds"

  # Apply filters (in-place)
  Image.grayscale img
  Image.brightness img 30

  # Save to file
  Image.save-png img "output.png" |> Result.unwrap

  # Free image memory
  Image.free img

main

Supported Formats

Format	Load	Save
PNG	Yes	Yes
JPEG	Yes	Yes
BMP	Yes	Yes
TGA	Yes	Yes
GIF	Yes	--
PSD	Yes	--
HDR	Yes	--
PIC	Yes	--

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./basic

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

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.

Local Installation

To install this package locally for development:

kit install

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

License

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

stb_image is released under the MIT License / Public Domain.

Exported Functions & Types

`ImageError`

Image error type with specific variants for different failure modes.

Variants

ImageLoadError {message}

ImageSaveError {message}

ImageProcessError {message}

`rgba`

Create a color from RGBA values.

Parameters:

- r - Red component (0-255)
- g - Green component (0-255)
- b - Blue component (0-255)
- a - Alpha/transparency component (0-255, where 255 is fully opaque)

Returns: Color record with the specified RGBA values

Byte -> Byte -> Byte -> Byte -> Color

semi-transparent-red = rgba 255 0 0 128

`rgb`

Create a color from RGB values with full opacity.

The alpha channel is automatically set to 255 (fully opaque).

Parameters:

- r - Red component (0-255)
- g - Green component (0-255)
- b - Blue component (0-255)

Returns: Color record with the specified RGB values and alpha=255

Byte -> Byte -> Byte -> Color

purple = rgb 128 0 128

`white`

White color (255, 255, 255).

Color

`black`

Black color (0, 0, 0).

Color

`red`

Red color (255, 0, 0).

Color

`green`

Green color (0, 255, 0).

Color

`blue`

Blue color (0, 0, 255).

Color

`yellow`

Yellow color (255, 255, 0).

Color

`cyan`

Cyan color (0, 255, 255).

Color

`magenta`

Magenta color (255, 0, 255).

Color

`transparent`

Transparent color (0, 0, 0, 0).

Color

`load`

Load image from file.

NonEmptyString -> Result Image ImageError

`load-with-channels`

Load image with specific number of channels.

NonEmptyString -> ImageChannels -> Result Image ImageError

`load-rgb`

Load as RGB (3 channels).

NonEmptyString -> Result Image ImageError

`load-rgba`

Load as RGBA (4 channels).

NonEmptyString -> Result Image ImageError

`load-grayscale`

Load as grayscale (1 channel).

NonEmptyString -> Result Image ImageError

`free`

Free image memory.

Image -> Void

`create`

Create a new blank image.

PositiveInt -> PositiveInt -> Result Image ImageError

`create-with-channels`

Create with specific number of channels.

PositiveInt -> PositiveInt -> ImageChannels -> Result Image ImageError

`copy`

Copy an image.

Image -> Result Image ImageError

`width`

Get image width.

Image -> Int

`height`

Get image height.

Image -> Int

`channels`

Get image channels.

Image -> Int

`data-ptr`

Get raw data pointer for bulk pixel operations.

Image -> Ptr

`in-bounds?`

Check if coordinates are in bounds.

Image -> Int -> Int -> Bool

`get-pixel`

Get pixel color at (x, y).

Image -> Int -> Int -> Option Color

`set-pixel?`

Set pixel color at (x, y). Returns true if successful.

Image -> Int -> Int -> Color -> Bool

`fill`

Fill entire image with color.

Image -> Color -> Void

`save-png`

Save as PNG.

Image -> NonEmptyString -> Result () ImageError

`save-jpg`

Save as JPEG with quality (1-100).

Image -> NonEmptyString -> PositiveInt -> Result () ImageError

`save-jpeg`

Save as JPEG with default quality (90).

Image -> NonEmptyString -> Result () ImageError

`save-bmp`

Save as BMP.

Image -> NonEmptyString -> Result () ImageError

`save-tga`

Save as TGA.

Image -> NonEmptyString -> Result () ImageError

`resize`

Resize image.

Image -> PositiveInt -> PositiveInt -> Result Image ImageError

`scale`

Scale image by factor.

Image -> PositiveFloat -> Result Image ImageError

`flip-vertical`

Flip image vertically (in place).

Image -> Void

`flip-horizontal`

Flip image horizontally (in place).

Image -> Void

`draw-rect`

Draw a filled rectangle.

Image -> Int -> Int -> Int -> Int -> Color -> Void

`draw-line-h`

Draw a horizontal line.

Image -> Int -> Int -> Int -> Color -> Void

`draw-line-v`

Draw a vertical line.

Image -> Int -> Int -> Int -> Color -> Void

`draw-rect-outline`

Draw rectangle outline.

Image -> Int -> Int -> Int -> Int -> Color -> Void

`average-color`

Get average color of entire image.

Image -> Color

`invert`

Invert colors.

Image -> Void

`grayscale`

Convert to grayscale.

Image -> Void

`brightness`

Adjust brightness (-255 to 255).

Image -> Int -> Void

`info`

Print image info.

Image -> Void

`color-to-hex`

Color to hex string.

Color -> String

`hex-to-color`

Parse hex color string.

String -> Option Color