opencv

Kind	ffi-c
Capabilities	ffi
Categories	graphics ffi
Keywords	opencv vision image processing detection

OpenCV computer vision 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_opencv.cpp`	C++ FFI wrapper around OpenCV
`c/kit_opencv.h`	C header for the FFI wrapper
`examples/basic.kit`	Basic drawing and image-processing example
`examples/phase1.kit`	Pixel, array, transform, bitwise, and arithmetic example
`kit.toml`	Package manifest with metadata, capabilities, and native build settings
`src/opencv.kit`	Kit OpenCV API bindings
`tests/opencv.test.kit`	Tests for exported OpenCV functions

Dependencies

No Kit package dependencies.

This package requires OpenCV 4 and pkg-config for native builds.

Platform	Install command
macOS	`brew install opencv pkg-config`
Ubuntu	`sudo apt install libopencv-dev pkg-config`
Fedora	`sudo dnf install opencv-devel pkgconf-pkg-config`

Installation

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

The package requires the ffi capability because it calls OpenCV through a native C++ shim.

Usage

import Kit.OpenCV as OpenCV

main = fn =>
  println ("OpenCV version: " ++ OpenCV.version)

  # Create a blank image and draw on it
  match OpenCV.create 400 300 3
    | Err e -> println ("Create error: " ++ e)
    | Ok img ->
      OpenCV.draw-rectangle img 50 50 200 150 255 0 0 2
      OpenCV.draw-circle img 300 150 60 0 0 255 -1
      OpenCV.draw-line img 50 250 350 250 0 255 0 2
      OpenCV.draw-text img "Hello, OpenCV!" 80 30 0.8 255 255 255

      match OpenCV.save img "/tmp/kit-opencv-drawing.png"
        | Ok _ -> println "Saved drawing"
        | Err e -> println ("Save error: " ++ e)

      # Edge detection pipeline
      match OpenCV.to-grayscale img
        | Ok gray ->
          match OpenCV.canny gray 50.0 150.0
            | Ok edges ->
              match OpenCV.save edges "/tmp/kit-opencv-edges.png"
                | Ok _ -> println "Saved edges"
                | Err e -> println ("Save error: " ++ e)
              OpenCV.free edges
            | Err e -> println ("Canny error: " ++ e)
          OpenCV.free gray
        | Err e -> println ("Grayscale error: " ++ e)

      OpenCV.free img

main

Development

Running Examples

Run the basic example with the interpreter:

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

Run the phase 1 example with the interpreter:

kit run examples/phase1.kit --allow=ffi

Compile an example to a native binary:

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

The basic example writes images to /tmp/kit-opencv-drawing.png, /tmp/kit-opencv-edges.png, and /tmp/kit-opencv-blurred.png.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running Parity

Run interpreter/compiler parity checks for the examples:

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

Parity writes timestamped *-results.txt files in the package root. They are generated artifacts and are removed by kit task clean.

Running kit dev

Run the standard development workflow:

kit dev --no-spinner

This will:

Build the native libkit_opencv wrapper
Format and check Kit source files
Type check examples
Run tests with coverage

Native Build Details

The native wrapper is built from c/kit_opencv.cpp using the custom build command in kit.toml:

c++ -shared -fPIC -std=c++17 ${package_dir}/c/kit_opencv.cpp -o ${output} $(pkg-config --cflags --libs opencv4)

Kit consumers link the wrapper as kit_opencv, while the wrapper itself links to OpenCV through pkg-config. After changing kit.toml, src/opencv.kit, or the native wrapper sources, run kit install so examples that import Kit.OpenCV use the refreshed package cache under ~/.kit/packages/@kit/opencv/.

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/opencv/, builds libkit_opencv.dylib on macOS, and makes the package available for import as Kit.OpenCV in other projects.

License

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

OpenCV is released under the Apache 2.0 License.

Exported Functions & Types

`load`

Load an image from a file.

Parameters:

Returns:

String -> Result Ptr String

`save`

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

Parameters:

Returns:

Ptr -> NonEmptyString -> Result Unit String

`free`

Free an image and release its resources.

Parameters:

Ptr -> Unit

`width`

Get the width of an image in pixels.

Parameters:

Returns:

Ptr -> Int

`height`

Get the height of an image in pixels.

Parameters:

Returns:

Ptr -> Int

`channels`

Get the number of channels in an image.

Parameters:

Returns:

Ptr -> Int

`create`

Create a blank image filled with black.

Parameters:

Returns:

Int -> Int -> Int -> Result Ptr String

`clone`

Deep copy an image.

Parameters:

Returns:

Ptr -> Result Ptr String

`to-grayscale`

Convert an image to grayscale.

Parameters:

Returns:

Ptr -> Result Ptr String

`to-rgb`

Convert an image from BGR to RGB color order.

Parameters:

Returns:

Ptr -> Result Ptr String

`resize`

Resize an image to the given dimensions.

Parameters:

Returns:

Ptr -> Int -> Int -> Result Ptr String

`blur`

Apply Gaussian blur to an image.

Parameters:

Returns:

Ptr -> Int -> Result Ptr String

`threshold`

Apply binary threshold to an image. Auto-converts to grayscale if needed.

Parameters:

Returns:

Ptr -> Float -> Float -> Result Ptr String

`canny`

Detect edges using the Canny algorithm. Auto-converts to grayscale if needed.

Parameters:

Returns:

Ptr -> Float -> Float -> Result Ptr String

`sobel`

Compute Sobel derivatives. Auto-converts to grayscale if needed.

Parameters:

Returns:

Ptr -> Int -> Int -> Result Ptr String

`erode`

Apply morphological erosion to an image.

Parameters:

Returns:

Ptr -> Int -> Result Ptr String

`dilate`

Apply morphological dilation to an image.

Parameters:

Returns:

Ptr -> Int -> Result Ptr String

`draw-line`

Draw a line on an image (mutates in place).

Parameters:

Ptr -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Unit

`draw-rectangle`

Draw a rectangle on an image (mutates in place).

Parameters:

Ptr -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Unit

`draw-circle`

Draw a circle on an image (mutates in place).

Parameters:

Ptr -> Int -> Int -> Int -> Int -> Int -> Int -> Int -> Unit

`draw-text`

Draw text on an image (mutates in place).

Parameters:

Ptr -> String -> Int -> Int -> Float -> Int -> Int -> Int -> Unit

`named-window`

Create a named display window.

Parameters:

String -> Unit

`show`

Show an image in a named window.

Parameters:

NonEmptyString -> Ptr -> Unit

`wait-key`

Wait for a keypress. Returns the key code.

Parameters:

Returns:

Int -> Int

`destroy-all-windows`

Close all display windows.

Unit

`version`

Get the OpenCV version string.

Returns:

String

`get-pixel`

Get a single pixel channel value.

Parameters:

Returns:

Ptr -> Int -> Int -> Int -> Float

`set-pixel`

Set a single pixel channel value (mutates in place).

Parameters:

Ptr -> Int -> Int -> Int -> Float -> Unit

`get-pixel-bgr`

Get BGR pixel values as a record.

Parameters:

Returns:

Ptr -> Int -> Int -> {b: Float, g: Float, r: Float}

`set-pixel-bgr`

Set BGR pixel values (mutates in place).

Parameters:

Ptr -> Int -> Int -> Int -> Int -> Int -> Unit

`copy`

Deep copy an image (alias for clone).

Parameters:

Returns:

Ptr -> Result Ptr String

`fill`

Fill an image with a BGR color (mutates in place).

Parameters:

Ptr -> Int -> Int -> Int -> Unit

`set-zero`

Clear an image to black (mutates in place).

Parameters:

Ptr -> Unit

`convert-scale`

Scale and shift pixel values. Output = src * scale + shift.

Parameters:

Returns:

Ptr -> Float -> Float -> Result Ptr String

`flip`

Flip an image along an axis.

Parameters:

Returns:

Ptr -> Int -> Result Ptr String

`transpose`

Transpose an image (swap rows and columns).

Parameters:

Returns:

Ptr -> Result Ptr String

`bitwise-and`

Per-element bitwise AND of two images.

Parameters:

Returns:

Ptr -> Ptr -> Result Ptr String

`bitwise-or`

Per-element bitwise OR of two images.

Parameters:

Returns:

Ptr -> Ptr -> Result Ptr String

`bitwise-xor`

Per-element bitwise XOR of two images.

Parameters:

Returns:

Ptr -> Ptr -> Result Ptr String

`bitwise-not`

Per-element bitwise NOT (invert) of an image.

Parameters:

Returns:

Ptr -> Result Ptr String

`add`

Per-element addition of two images (saturating).

Parameters:

Returns:

Ptr -> Ptr -> Result Ptr String

`subtract`

Per-element subtraction of two images (saturating).

Parameters:

Returns:

Ptr -> Ptr -> Result Ptr String

`add-weighted`

Alpha-blend two images. Output = src1 * alpha + src2 * beta + gamma.

Parameters:

Returns:

Ptr -> Float -> Ptr -> Float -> Float -> Result Ptr String

`abs-diff`

Per-element absolute difference of two images.

Parameters:

Returns:

Ptr -> Ptr -> Result Ptr String