{"id":27056237,"url":"https://github.com/MasterQ32/zig-qoi","last_synced_at":"2025-04-05T10:01:36.003Z","repository":{"id":38248146,"uuid":"431998572","full_name":"ikskuh/zig-qoi","owner":"ikskuh","description":"Quite OK Image format encoder/decoder written in Zig","archived":false,"fork":false,"pushed_at":"2025-03-11T11:17:22.000Z","size":2618,"stargazers_count":142,"open_issues_count":4,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-05T05:03:18.200Z","etag":null,"topics":["image-decoder","image-encoder","image-format","qoi","zig","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ikskuh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"MasterQ32"}},"created_at":"2021-11-25T23:08:00.000Z","updated_at":"2025-03-27T12:18:55.000Z","dependencies_parsed_at":"2023-11-13T22:27:28.607Z","dependency_job_id":"190e58c8-1d17-4cfd-b9c6-b39c54558c1b","html_url":"https://github.com/ikskuh/zig-qoi","commit_stats":{"total_commits":31,"total_committers":7,"mean_commits":4.428571428571429,"dds":0.4193548387096774,"last_synced_commit":"871d233a78ce6b7de849ba0c9dff473577d6323d"},"previous_names":["ikskuh/zig-qoi","masterq32/zig-qoi"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2Fzig-qoi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2Fzig-qoi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2Fzig-qoi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikskuh%2Fzig-qoi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikskuh","download_url":"https://codeload.github.com/ikskuh/zig-qoi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247318742,"owners_count":20919484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-decoder","image-encoder","image-format","qoi","zig","zig-package","ziglang"],"created_at":"2025-04-05T10:01:25.133Z","updated_at":"2025-04-05T10:01:35.996Z","avatar_url":"https://github.com/ikskuh.png","language":"Zig","readme":"# zig-qoi\n\nA implementation of the [_Quite OK Image Format_](https://qoiformat.org/) for Zig. This implementation conforms to the [Qoi specification](https://qoiformat.org/qoi-specification.pdf).\n\n![](design/logo.png)\n\n## API\n\nAdd `src/qoi.zig` to your Zig project as a package.\n\n```zig\npub const DecodeError = error{ OutOfMemory, InvalidData, EndOfStream };\npub const EncodeError = error{ OutOfMemory };\n\n// Simple API:\n\npub fn isQOI(bytes: []const u8) bool;\npub fn decodeBuffer(allocator: std.mem.Allocator, buffer: []const u8) DecodeError!Image;\npub fn decodeStream(allocator: std.mem.Allocator, reader: anytype) !Image;\n\npub fn encodeBuffer(allocator: std.mem.Allocator, image: ConstImage) EncodeError![]u8;\npub fn encodeStream(image: ConstImage, writer: anytype) !void;\n\n// Streaming API:\npub fn encoder(writer: anytype) Encoder(@TypeOf(writer));\npub fn Encoder(comptime Writer: type) type {\n   return struct {\n      writer: Writer,\n      pub fn reset(self: *Self) void;\n      pub fn flush(self: *Self) (EncodeError || Writer.Error)!void;\n      pub fn push(self: *Self, pixel: Color) (EncodeError || Writer.Error)!void;\n   };\n}\n\npub const ColorRun = struct {\n   color: Color,\n   length: usize,\n};\n\npub fn decoder(reader: anytype) Decoder(@TypeOf(reader));\npub fn Decoder(comptime Reader: type) type {\n   return struct {\n      reader: Reader,\n      pub fn fetch(self: *Self) Reader.Error!ColorRun;\n   };\n}\n```\n\n## Implementation Status\n\nEverything specified in https://github.com/phoboslab/qoi/issues/37 is implemented and accessible via the API.\n\n## Performance\n\nOn my machine (AMD Ryzen 7 3700U), i did a small benchmark with decoding `bench.zig`, which will decode `zero.qoi`:\n\n| Build Mode   | QOI Bytes   | Raw Bytes      | Encoding Time | Decoding Time |\n| ------------ | ----------- | -------------- | ------------- | ------------- |\n| Debug        | 75.024 byte | 1.048.576 byte | 14.439ms      | 7.061ms       |\n| ReleaseSmall | 75.024 byte | 1.048.576 byte | 1.888ms       | 1.499ms       |\n| ReleaseSafe  | 75.024 byte | 1.048.576 byte | 1.392ms       | 512.706us     |\n| ReleaseFast  | 75.024 byte | 1.048.576 byte | 1.186ms       | 456.762us     |\n\nThis means that this implementation is roughly able to decode ~2.1 GB/s raw texture data and is considered \"fast enough\" for now. If you find some performance improvements, feel free to PR it!\n\nRunning perf on the benchmark compiled with ReleaseFast showed that the implementation is quite optimal for the CPU, utilizing it to 100% and executing up to 3 instructions per cycle on my machine.\n\n```sh-console\n[felix@denkplatte-v2 zig-qoi]$ perf stat ./zig-out/bin/qoi-bench\nBenchmark [4067/4096] Encoding time for 1048576 =\u003e 75024 bytes: 1.019ms\nBenchmark [4067/4096] Decoding time for 75024 =\u003e 1048576 bytes: 419.223us\n\n Performance counter stats for './zig-out/bin/qoi-bench':\n\n          9.665,11 msec task-clock:u              #    0,997 CPUs utilized\n                 0      context-switches:u        #    0,000 K/sec\n                 0      cpu-migrations:u          #    0,000 K/sec\n            21.066      page-faults:u             #    0,002 M/sec\n    29.757.225.002      cycles:u                  #    3,079 GHz                      (83,33%)\n       317.453.390      stalled-cycles-frontend:u #    1,07% frontend cycles idle     (83,33%)\n       515.819.113      stalled-cycles-backend:u  #    1,73% backend cycles idle      (83,32%)\n    83.377.885.642      instructions:u            #    2,80  insn per cycle\n                                                  #    0,01  stalled cycles per insn  (83,36%)\n    18.947.655.057      branches:u                # 1960,417 M/sec                    (83,31%)\n       193.594.708      branch-misses:u           #    1,02% of all branches          (83,35%)\n\n       9,693303129 seconds time elapsed\n\n       9,553127000 seconds user\n       0,112001000 seconds sys\n```\n\nAlso, running the [benchmark dataset](https://qoiformat.org/benchmark/) of the original author, it yielded the [following data](data/benchmark.csv):\n\n```\nNumber of total images:             1351\nAverage PNG Compression:              18.57%\nAverage QOI Compression:              22.70%\nAverage Compression Rate (MB/s):     438.31 MB/s\nMinimal Compression Rate (MB/s):      27.06 MB/s\nMaximum Compression Rate (MB/s):    1390.15 MB/s\nAverage Decompression Rate (MB/s):  1128.46 MB/s\nMaximum Decompression Rate (MB/s):    39.77 MB/s\nMaximum Deompression Rate (MB/s):  13307.20 MB/s\n```\n\n[See also the original analysis on Google Docs](https://docs.google.com/spreadsheets/d/1guTm4A2TxFzxeB6MRWbCmfidJu3S2iv-S3OM_sOo_4Q/edit?usp=sharing)\n\n## Contribution\n\nRun the test suite like this:\n\n```sh-console\n[user@host zig-qoi]$ zig build test\nAll 5 tests passed.\n```\n\nRun the benchmark like this:\n\n```sh-console\n[user@host zig-qoi]$ zig build benchmark\nBenchmark [4096/4096] Encoding time for 1048576 =\u003e 67076 bytes: 16.649ms\nBenchmark [4095/4096] Decoding time for 67076 =\u003e 1048576 bytes: 5.681ms\n```\n\nTo run the benchmark for batch files, run this:\n\n```sh-console\n[user@host zig-qoi]$ zig build install \u0026\u0026 ./zig-out/bin/qoi-bench-files $(folder_a) $(folder_b) ...\nFile Name       Width   Height  Total Raw Bytes  Total PNG Bytes PNG Compression  Total QOI Bytes  QOI Compression  QOI to PNG          Decode Time (ns)  Encode Time (ns)\ndata/zero.png   512     512     1048576          80591           0.08             67076            0.06             0.8323013782501221  5628360           14499346\ntotal sum       0       0       1048576          80591           0.08             67076            0.06             0.8323013782501221  5628360           14499346\n```\n\nPass as many folders you like to the benchmarking tool. It will render a CSV file on the `stderr`.\n","funding_links":["https://github.com/sponsors/MasterQ32"],"categories":["Libraries"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMasterQ32%2Fzig-qoi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMasterQ32%2Fzig-qoi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMasterQ32%2Fzig-qoi/lists"}