zigimg/zigimg

Zig library for reading and writing different image formats

Zig Image library

This is a work in progress library to create, process, read and write different image formats with Zig programming language.

Install & Build

This library uses zig nominated 2024.3.0-mach. To install using zigup:

zigup 0.12.0-dev.3180+83e578a18

Use zigimg in your project

How to add to your project:

As a submodule

1. Clone this repository or add as a submodule
2. Add to your build.zig

exe.addAnonymousModule("zigimg", .{.source_file = .{ .path = "zigimg.zig" }});

Through the package manager

1. Example build.zig.zon file

.{
    .name = "app",
    .version = "0.0.0",
    .dependencies = .{
        .zigimg = .{
            .url = "https://github.com/zigimg/zigimg/archive/$REPLACE_WITH_WANTED_COMMIT$.tar.gz",
        },
    },
}

2. When it fails to build due to a mismatched hash, add the hash line to the dependency

.zigimg = .{
    .url = "https://github.com/zigimg/zigimg/archive/$REPLACE_WITH_WANTED_COMMIT$.tar.gz",
    .hash = "$REPLACE_WITH_HASH_FROM_BUILD_ERROR$",
},

Test suite

To run the test suite, checkout the test suite and run

1. Checkout zigimg
2. Go back one folder and checkout the test suite
3. Run the tests with zig build

zig build test

Supported image formats

Image Format	Read	Write
ANIM	❌	❌
BMP	✔️ (Partial)	✔️ (Partial)
GIF	✔️	❌
ICO	❌	❌
IILBM	❌	❌
JPEG	❌	❌
PAM	✔️	✔️
PBM	✔️	✔️
PCX	✔️	✔️
PGM	✔️ (Partial)	✔️ (Partial)
PNG	✔️	✔️ (Partial)
PPM	✔️ (Partial)	✔️ (Partial)
QOI	✔️	✔️
TGA	✔️	✔️
TIFF	❌	❌
XBM	❌	❌
XPM	❌	❌

BMP - Bitmap

• version 4 BMP
• version 5 BMP
• 24-bit RGB read & write
• 32-bit RGBA read & write
• Doesn't support any compression

GIF - Graphics Interchange Format

• Support GIF87a and GIF89a
• Support animated GIF with Netscape application extension for looping information
• Supported interlaced
• Supports tiled and layered images used to achieve pseudo true color and more.
• The plain text extension is not supported

PAM - Portable Arbitrary Map

Currently, this only supports a subset of PAMs where:

• The tuple type is official (see man 5 pam) or easily inferred (and by extension, depth is 4 or less)
• All the images in a sequence have the same dimensions and maxval (it is technically possible to support animations with different maxvals and tuple types as each AnimationFrame has its own PixelStorage, however, this is likely not expected by users of the library)
• Grayscale,
• Grayscale with alpha
• Rgb555
• Rgb24 and Rgba32
• Bgr24 and Bgra32
• Rgb48 and Rgba64

PBM - Portable Bitmap format

• Everything is supported

PCX - ZSoft Picture Exchange format

• Support monochrome, 4 color, 16 color and 256 color indexed images
• Support 24-bit RGB images

PGM - Portable Graymap format

• Support 8-bit and 16-bit grayscale images
• 16-bit ascii grayscale loading not tested

PNG - Portable Network Graphics

• Support all pixel formats supported by PNG (grayscale, grayscale+alpha, indexed, truecolor, truecolor with alpha) in 8-bit or 16-bit.
• Support the mininal chunks in order to decode the image.
• Not all images in Png Test Suite is covered but should be good enough for now.

PPM - Portable Pixmap format

• Support 24-bit RGB (8-bit per channel)
• Missing 48-bit RGB (16-bit per channel)

QOI - Quite OK Image Format

• Imported from https://github.com/MasterQ32/zig-qoi with blessing of the author

TGA - Truevision TGA format

• Supports uncompressed and compressed 8-bit grayscale, indexed with 16-bit and 24-bit colormap, truecolor with 16-bit(RGB555), 24-bit or 32-bit bit depth.
• Supports reading version 1 and version 2
• Supports writing version 2

zigimg's Issues

Write JPEG

Methods to draw on a Image

We should get inspiration from https://github.com/reneschulte/WriteableBitmapEx

Write and read APNG

Animated PNG should be trivial to support once PNG is complete, and is supported by almost all browsers

Read ANIM

https://en.wikipedia.org/wiki/ANIM

Image: Convert between pixel formats

In the Image struct or maybe in a separate struct

Write Netpbm

Write NetBPM PAM (P7) format

http://netpbm.sourceforge.net/doc/pam.html#layout

Read XBM

https://en.wikipedia.org/wiki/X_BitMap

Read 16-bit and more NetPBM formats properly

https://en.wikipedia.org/wiki/Netpbm#16-bit_extensions

Indexed pixel storage without alpha channel

PNG's indexed mode has alpha channel as an option. I think IndexedStorage should allow for Rgb32[] instead of a Rgba32[], to convey that info, instead of having to pass an argument to the png encoder in case we don't want an alpha channel.

Alternative: encoder checks each palette color to see if any one has transparency?

Write XPM

https://en.wikipedia.org/wiki/X_PixMap

ColorStorage name does not match component order

e. e. RgbColor is struct { B: BlueType, G: GreenType, R: RedType, ... }.

This is quite the footgun when e.g. loading the data into a texture. Is there a particular reason the components are reversed (at least with respect to graphics API conventions)? If there is, could the name of the ColorStorage at least be adjusted?

Finish BMP read support

Read all BMP formats missing in formats/bmp.zig

Add read PCX support

Thanks to https://github.com/MasterQ32 to allow me to merge and adapt his PCX code: https://github.com/MasterQ32/zig-gamedev-lib/blob/master/src/pcx.zig

Read ICO

Windows Icon file format

https://en.wikipedia.org/wiki/ICO_(file_format)

Write TIFF

Read TGA

Write ICO

Windows Icon file format

https://en.wikipedia.org/wiki/ICO_(file_format)

Create common color formats and functions to convert inbetween

Create color structs for:

• CIEL*a*b*
• CMYK
• sRGB
• XYZ

Add functions to convert inbetween those formats

Write retro console GFX format

https://www.romhacking.net/documents/21/

Smaller palettes

In PNG, a palette can be "incomplete" (have less than 256 colors). Right now there is no way of knowing if the palette is full, we should find a way to know that. I guess it could involved resizing the slice using the allocator once we know the palette is filled, so that the .len field reflects this.

Write BMP support

Write TGA

Does not work in the latest version of zig

InStream does not exist in std.io anymore

Use zig standard library deflate implementation

With ziglang/zig#6277 merged there is no need for a separate deflate implementation.

Write PNG

Remove usage of StreamSource to support targets without a filesystem

std.io.StreamSource is a tagged union, defined as so:

const std = @import("../std.zig");
const io = std.io;

pub const StreamSource = union(enum) {
    buffer: io.FixedBufferStream([]u8),
    const_buffer: io.FixedBufferStream([]const u8),
    file: std.fs.File,
};

On targets that don't have a filesystem (for example, WASM in the browser), this prevents zigimg from being used, giving the user a compile time error saying (paraphrased), "std.os.fd_t is not defined".

I worked around this in my personal fork by swapping the implementation from std with a version that uses dynamic dispatch instead of a static union. You can see that here. This is an issue and not a pull request because the workaround only supports loading from memory, and I'm not sure that it's the right way to go.

Another solution might be changing std to void out the file variant on systems that don't have a filesystem.

Read TIFF

Add function to convert colors based on ICC profiles

See: https://en.wikipedia.org/wiki/ICC_profile

Related: #34

Write XBM

https://en.wikipedia.org/wiki/X_BitMap

Add read PNG support

Support the whole PNG test suite: http://www.schaik.com/pngsuite/

Add SDL test program

This is to ensure that we can use zigimg to load them to a SDL_Surface

Write ILBM

Format used on Amiga
https://en.wikipedia.org/wiki/ILBM

Read NetBPM PAM (P7) format

http://netpbm.sourceforge.net/doc/pam.html#layout

Deferred image manipulation

One of the most important (and difficult) feature of an image library is deferred image manipulation.

Basically not loading the image pixels in memory. For example if I do the following:

mybg = image.load_reference("huge_background.jpg")
mybg.set_pixels(0, 0, 100, 10, Color.red)

// at this point, in memory we should only have a small data structure referring the image file + a 1000 pixel buffer of red pixels
mybg.commit()
// only here we update the pixels we need to update, some image format will require loading the whole data, but many don't

Apple API does it with NSImage (proxy) and NSBitmapRepresentation (actual pixels):

https://developer.apple.com/documentation/appkit/nsimage

https://developer.apple.com/documentation/appkit/nsbitmapimagerep

Write PCX

Add read NetBMP format support

Thanks to @MasterQ32 to allow me to merge and adapt https://github.com/MasterQ32/zig-gamedev-lib/blob/master/src/netbpm.zig

File access is unbuffered

Loading or writing images from/to files uses unbuffered IO. This is extremely slow, resulting in ~5s write times for a 1080p PPM on my machine, compared to milliseconds when writing to memory and then writing that buffer to the file.
Even writing to /dev/null is slow, taking ~500ms compared to ~35ms for writeToMemory.

Read XPM

https://en.wikipedia.org/wiki/X_PixMap

Read retro console GFX formats

See https://www.romhacking.net/documents/21/ for more info

Write ANIM

https://en.wikipedia.org/wiki/ANIM

Add OpenGL test program

This is to make sure that you can use zigimg to read textures

Add read JPEG support

Write GIF

Bindings from other languages

Is this repo restricted to pure Zig implementations or would a wrapper around existing C/C++ libraries also be acceptable? I feel like some formats such as JXL may be too complex to reimplement in a reasonable amount of time, however, they'd be incredibly useful to have a consistent API to these other image formats in Zig.

If someone were to later reimplement the format in Zig, it could take the place of the C wrapper given it was stable and feature complete

Add read GIF support

• Allow to read each indidual frame of animation

Make Color use f32 interally

the generic Color should store its components as f32, or maybe even a SIMD f128 register

Png reader makes a lot of allocations

I only looked at Png reader so I can't speak of other readers. For example reading basn2c08.png from the test suite makes 12 allocations. If I use 24bit RGB image of 1082x1017 size it makes 63 allocations. How is this acceptable? Won't it significantly impact the performance?

I once wrote a png reader in DLang. It always decoded an image from any format into RGBA buffer but, in most cases, it only made one allocation for that final buffer. The only case where it needed to make one additional allocation was if image was interlaced, because I needed another buffer to deinterlace pixels.

Reading PNG fails with invalid enum value

The image that errors out

The failure is on line 691 of src/formats/png.zig. Modifying it so that it logs the filter values before converting them gives me this:

debug: filter_type: 1
debug: filter_type: 0
debug: filter_type: 0
debug: filter_type: 254

Read ILBM

Format used on Amiga
https://en.wikipedia.org/wiki/ILBM