Install & Build

zigup 0.14.0-dev.2577+271452d22

Use zigimg in your project

As a submodule

pub fn build(b: *std.Build) void {    exe.root_module.addAnonymousModule("zigimg", .{ .root_source_file = b.path("zigimg.zig") });}

Through the package manager

zig fetch --save git+https://github.com/zigimg/zigimg.git

constzigimg_dependency=b.dependency("zigimg", .{    .target=target,    .optimize=optimize,});exe.root_module.addImport("zigimg",zigimg_dependency.module("zigimg"));

Test suite

zig build test

Supported image formats

BMP - Bitmap

GIF - Graphics Interchange Format

IFF - InterchangeFileFormat

PAM - Portable Arbitrary Map

PBM - Portable Bitmap format

PCX - ZSoft Picture Exchange format

PGM - Portable Graymap format

PNG - Portable Network Graphics

PPM - Portable Pixmap format

QOI - Quite OK Image Format

TGA - Truevision TGA format

Supported Pixel formats

User Guide

Design philosophy

Image vsImageUnmanaged

Read an image

From a file

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {vargpa=std.heap.GeneralPurposeAllocator(.{}){};defer_=gpa.deinit();constallocator=gpa.allocator();varimage=tryzigimg.Image.fromFilePath(allocator,"my_image.png");deferimage.deinit();// Do something with your image}

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {vargpa=std.heap.GeneralPurposeAllocator(.{}){};defer_=gpa.deinit();constallocator=gpa.allocator();varfile=trystd.fs.cwd().openFile(file_path, .{});deferfile.close();varimage=tryzigimg.Image.fromFile(allocator,file);deferimage.deinit();// Do something with your image}

From memory

conststd=@import("std");constzigimg=@import("zigimg");constimage_data=@embedFile("test.bmp");pubfnmain()!void {vargpa=std.heap.GeneralPurposeAllocator(.{}){};defer_=gpa.deinit();constallocator=gpa.allocator();constimage=tryzigimg.Image.fromMemory(allocator,image_data[0..]);deferimage.deinit();// Do something with your image}

Accessing pixel data

Accessing a specific format directly

pubfnexample()void {// [...]// Assuming you already have an image loadedconstfirst_pixel=image.pixels.rgb24[0];}

pubfnexample()void {// [...]// Assuming you already have an image loadedconstfirst_pixel=image.pixels.grayscale8Alpha[0];constgrayscale=first_pixel.value;constalpha=grayscale.alpha;}

pubfnexample()void {// [...]// Assuming you already have an image loadedconstfirst_color_palette=image.pixels.indexed8.palette[0];constfirst_pixel=image.pixels.indexed8.indices[0];}

Using the color iterator

pubfnexample()void {// [...]// Assuming you already have an image loadedconstcolor_it=image.iterator();while (color_it.next())|color| {// Do something with color    }}

Accessing animation frames

pubfnexample()void {// [...]// Assuming you already have an image loadedconstloop_count=image.animation.loop_count;for (image.animation.frames)|frame| {constrgb24_data=frame.pixels.rgb24;constframe_duration=frame.duration;    }}

Get raw bytes for texture transfer

pubfnexample()void {// [...]// Assuming you already have an image loadedconstimage_data=image.rawBytes();constrow_pitch=image.rowByteSize();constimage_byte_size=image.imageByteSize();}

Detect image format

From a file

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {constimage_format=tryzigimg.Image.detectFormatFromFilePath(allocator,"my_image.png");// Will print pngstd.log.debug("Image format: {}", .{image_format});}

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {varfile=trystd.fs.cwd().openFile("my_image.gif", .{});deferfile.close();constimage_format=tryzigimg.Image.detectFormatFromFile(allocator,file);// Will print gifstd.log.debug("Image format: {}", .{image_format});}

From memory

conststd=@import("std");constzigimg=@import("zigimg");constimage_data=@embedFile("test.bmp");pubfnmain()!void {constimage_format=tryzigimg.Image.detectFormatFromMemory(allocator,image_data[0..]);// Will print bmpstd.log.debug("Image format: {}", .{image_format});}

Write an image

Write to a file path

pubfnexample()!void {// [...]// Assuming you already have an image loadedtryimage.writeToFilePath("my_new_image.png", .{ .png= .{} });// Or with encoder optionstryimage.writeToFilePath("my_new_image.png", .{ .png= .{ .interlaced=true } });}

Write tostd.fs.File

pubfnexample()!void {// [...]// Assuming you already have an image loaded and the file already createdtryimage.writeToFile(file, .{ .bmp= .{} });}

Write to a memory buffer

pubfnexample()!void {// [...]// Assuming you already have an image loaded and the buffer already allocatedtryimage.writeToMemory(buffer[0..], .{ .tga= .{} });}

Create an image

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {vargpa=std.heap.GeneralPurposeAllocator(.{}){};defer_=gpa.deinit();constallocator=gpa.allocator();varimage=tryzigimg.Image.create(allocator,1920,1080,.rgba32);deferimage.deinit();// Do something with your image}

Interpret raw pixels

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {vargpa=std.heap.GeneralPurposeAllocator(.{}){};defer_=gpa.deinit();constallocator=gpa.allocator();constmy_raw_pixels=@embedData("raw_bgra32.bin");varimage=tryzigimg.Image.fromRawPixels(allocator,1920,1080,my_raw_pixels[0..],.bgra32);deferimage.deinit();// Do something with your image}

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {vargpa=std.heap.GeneralPurposeAllocator(.{}){};defer_=gpa.deinit();constallocator=gpa.allocator();constmy_raw_pixels=@embedData("raw_bgra32.bin");varimage=tryzigimg.ImageUnmanaged.fromRawPixelsOwned(1920,1080,my_raw_pixels[0..],.bgra32);// Do something with your image}

Use image format directly

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {vargpa=std.heap.GeneralPurposeAllocator(.{}){};defer_=gpa.deinit();constallocator=gpa.allocator();constimage_data=@embedFile("windows_rgba_v5.bmp");varstream_source=std.io.StreamSource{ .const_buffer=std.io.fixedBufferStream(image_data) };varbmp=zigimg.formats.bmp.BMP{};constpixels=trybmp.read(allocator,&stream_source);deferpixels.deinit(allocator);std.log.info("BMP info header: {}", .{bmp.info_header});}

info: BMP info header: src.formats.bmp.BitmapInfoHeader{ .v5 = src.formats.bmp.BitmapInfoHeaderV5{ .header_size = 124, .width = 240, .height = 160, .color_plane = 1, .bit_count = 32, .compression_method = src.formats.bmp.CompressionMethod.bitfields, .image_raw_size = 153600, .horizontal_resolution = 2835, .vertical_resolution = 2835, .palette_size = 0, .important_colors = 0, .red_mask = 16711680, .green_mask = 65280, .blue_mask = 255, .alpha_mask = 4278190080, .color_space = src.formats.bmp.BitmapColorSpace.srgb, .cie_end_points = src.formats.bmp.CieXyzTriple{ .red = src.formats.bmp.CieXyz{ ... }, .green = src.formats.bmp.CieXyz{ ... }, .blue = src.formats.bmp.CieXyz{ ... } }, .gamma_red = 0, .gamma_green = 0, .gamma_blue = 0, .intent = src.formats.bmp.BitmapIntent.graphics, .profile_data = 0, .profile_size = 0, .reserved = 0 } }

Convert between pixel formats

pubfnexample()!void {// [...]// Assuming you already have an image loadedtryimage.convert(.float32);}

PixelFormatConverter

pubfnexample(allocator:std.mem.Allocator)!void {constindexed2_pixels=tryzigimg.color.PixelStorage.init(allocator,.indexed2,4);deferindexed2_pixels.deinit(allocator);// [...] Setup your indexed2 pixel dataconstbgr24_pixels=tryzigimg.PixelFormatConverter.convert(allocator,&indexed2_pixels,.bgr24);deferbgr24_pixels.deinit(allocator);}

OctTreeQuantizer

pubfnexample(allocator:std.mem.Allocator)!void {constimage_data=@embedFile("windows_rgba_v5.bmp");varimage=tryzigimg.Image.fromMemory(allocator,image_data[0..]);deferimage.deinit();varquantizer=zigimg.OctTreeQuantizer.init(allocator);deferquantizer.deinit();varcolor_it=image.iterator();while (color_it.next())|pixel| {tryquantizer.addColor(pixel);    }varpalette_storage: [256]zigimg.color.Rgba32=undefined;constpalette=quantizer.makePalette(255,palette_storage[0..]);constpalette_index=tryquantizer.getPaletteIndex(zigimg.color.Rgba32.initRgba(110,0,0,255));}

Get a color from a HTML hex string

pubfnexample()!void {constrgb24=tryzigimg.color.Rgb24.fromHtmlHex("#123499");constrgba32=tryzigimg.color.Rgba32.fromHtmlHex("FF000045");constred_rgb24=tryzigimg.color.Rgb24.fromHtmlHex("#F00");constblue_rgba32=tryzigimg.clor.Rgba32.fromHtmlHex("#00FA");}

Predefined colors

conststd=@import("std");constzigimg=@import("zigimg");pubfnmain()!void {constred_float32=zigimg.Colors(zigimg.color.Colorf32).Red;constblue_rgb24=zigimg.Colors(zigimg.color.Rgb24).Blue;}

Color management & color space

Convert between linear and gamma-corrected color

pubfnexample(linear_color:zigimg.color.Colorf32) {constgamma_srgb=zigimg.color.sRGB.toGamma(linear_color);constgamma_bt709=zigimg.color.BT709.toGammaFast(linear_color);constlinear_srgb=zigimg.color.sRGB.toLinearFast(gamma_srgb);constlinear_bt709=zigimg.color.BT709.toLinear(gamma_bt609);}

Convert a single color to a different color space

pubfnexample(linear_color:zigimg.color.Colorf32)void {constxyz=zigimg.color.sRGB.toXYZ(linear_color);constlab_alpha=zigimg.color.sRGB.toLabAlpha(linear_color);constlch_ab=zigimg.color.sRGB.toLCHab(linear_color);constluv_alpha=zigimg.color.sRGB.toLuvAlpha(linear_color);constlch_uv=zigimg.color.sRGB.toLCHuv(linear_color);consthsluv=zigimg.color.sRGB.toHSLuv(linear_color);constoklab=zigimg.color.sRGB.toOklab(linear_color);constoklch=zigimg.color.sRGB.toOkLCh(linear_color);}

pubfnexample(oklab:zigimg.color.Oklab) {constlinear_srgb_clamped=zigimg.color.sRGB.fromOklab(oklab,.clamp);constlinear_srgb=zigimg.color.sRGB.fromOklab(oklab,.none);}

Convert a slice of color to a different color space

pubfnexampleInPlace(linear_srgb_image: []zigimg.color.Colorf32)void {constslice_lab_alpha=zigimg.color.sRGB.sliceToLabAlphaInPlace(linear_srgb_image);// Do your image manipulation in CIE L*a*b*// Convert back to linear sRGB_=zigimg.color.sRGB.sliceFromLabAlphaInPlace(slice_lab_alpha,.clamp);// or without clamping_=zigimg.color.sRGB.sliceFromLabAlphaInPlace(slice_lab_alpha,.none);}pubfnexampleCopy(allocator:std.mem.Allocator,linear_srgb_image: []constzigimg.color.Colorf32)![]zigimg.color.Colorf32 {constslice_oklab_alpha=tryzigimg.color.sRGB.sliceToOklabCopy(allocator,linear_srgb_image);// Do your image manipulatioon in Oklab// Convert back to linear sRGBreturntryzigimg.color.sRGB.sliceFromOklabCopy(allocator,slice_oklab_alpha,.clamp);// Or without clampingreturntryzigimg.color.sRGB.sliceFromOklabCopy(allocator,slice_oklab_alpha,.none);}

Convert between some cylindrical representation

pubfnexample()void {constlab=zigimg.color.CIELab{ .l=0.12, .a=-0.23, .b=0.56 };constluv_alpha=zigimg.color.CIELuvAlpha { .l=0.4, .u=0.5, .v=-0.2, .alpha=0.8 };constoklab=zigimg.color.Oklab{ .l=0.67, .a=0.1, .b=0.56 };constlch_ab=lab.toLCHab();constlch_uv_alpha=luv_alpha.toLCHuvAlpha();constoklch=oklab.toOkLCh();constresult_lab=lch_ab.toLab();constresult_luv_alpha=lch_uv_alpha.toLuvAlpha();constresult_oklab=oklch.toOklab();}

Convert color between RGB color spaces

pubfnexample(linear_color:zigimg.color.Colorf32)void {constpro_photo_color=zigimg.color.sRGB.convertColor(zigimg.color.ProPhotoRGB,linear_color);}

pubfnexample(linear_image: []zigimg.color.Colorf32)void {constadobe_image=zigimg.color.sRGB.convertColors(zigimg.color.AdobeRGB,linear_image);}

Predefined RGB color spaces

Predefined white points

Create your own RGB color space

fnmyColorSpaceToGamma(value:f32)f32 {returnstd.math.pow(f32,value,1.0/2.4);}fnmyColorSpaceToLinear(value:f32)f32 {returnstd.math.pow(f32,value,2.4);}pubfnexample()void {pubconstmy_color_space=zigimg.color.RgbColorspace.init(.{        .red= .{ .x=0.6400, .y=0.3300 },        .green= .{ .x=0.3000, .y=0.6000 },        .blue= .{ .x=0.1500, .y=0.0600 },        .white=zigimg.color.WhitePoints.D50,        .to_gamma=myColorSpaceToGamma,        .to_gamma_fast=myColorSpaceToGamma,        .to_linear=myColorSpaceToLinear,        .to_linear_fast=myColorSpaceToLinear,    });}