tensors/imagekit

imagekit

A general-purpose image processing library for Ballerina — the Ballerina equivalent of Python's Pillow.

Wraps Java's javax.imageio and java.awt via Ballerina–Java interop with zero external Maven dependencies.

Supported formats: PNG · JPEG · BMP · GIF

Features

Installation

Add the dependency to your Ballerina.toml:

[[dependency]]
org     = "tensors"
name    = "imagekit"
version = "0.1.0"

Full package documentation is available on Ballerina Central.

Quick Start

import tensors/imagekit;
import ballerina/io;

public function main() returns error? {
    // Read metadata
    imagekit:ImageInfo info = check imagekit:getInfo("photo.png");
    io:println(info.width.toString() + "x" + info.height.toString() + " " + info.format);

    // Crop
    check imagekit:crop("photo.png", top = 20, bottom = 20, left = 10, right = 10);

    // Resize to exact dimensions
    check imagekit:resize("photo.png", 1920, 1080);

    // Resize preserving aspect ratio
    check imagekit:resizeToFit("photo.png", 800, 600);

    // Rotate 90° clockwise
    check imagekit:rotate("photo.png", 90);

    // Mirror
    check imagekit:flipHorizontal("photo.png");
    check imagekit:flipVertical("photo.png");

    // Grayscale
    check imagekit:toGrayscale("photo.png");

    // Convert format (writes a new file)
    check imagekit:convert("photo.png", "photo.jpg", "JPEG");

    // Create thumbnail (fits within 200×200, aspect ratio preserved)
    check imagekit:thumbnail("photo.png", "thumb.png", 200, 200);
}

Examples

Comparison with Pillow

Building from Source

Prerequisites

• Ballerina Swan Lake 2201.x or later
• Java 17+ JDK
• Gradle 7+

Build

# 1. Build the Java native layer
cd native && gradle build && cd ..

# 2. Build the Ballerina package
bal build

# 3. Run tests
bal test

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

License

Copyright 2026 Tensors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See the full license text in LICENSE.