{"id":13580052,"url":"https://github.com/Lymphatus/libcaesium","last_synced_at":"2025-04-06T00:30:47.978Z","repository":{"id":46605387,"uuid":"72835733","full_name":"Lymphatus/libcaesium","owner":"Lymphatus","description":"The Caesium compression library written in Rust (with a C interface)","archived":false,"fork":false,"pushed_at":"2025-03-14T21:26:36.000Z","size":12094,"stargazers_count":143,"open_issues_count":1,"forks_count":26,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-28T19:58:47.678Z","etag":null,"topics":["compression","image-compression","jpeg","optimization","png","rust","webp"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lymphatus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2016-11-04T10:01:12.000Z","updated_at":"2025-03-26T16:51:37.000Z","dependencies_parsed_at":"2024-01-25T19:27:24.504Z","dependency_job_id":"e1514d5f-18c8-439c-a5a2-54f1cd920600","html_url":"https://github.com/Lymphatus/libcaesium","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lymphatus%2Flibcaesium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lymphatus%2Flibcaesium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lymphatus%2Flibcaesium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lymphatus%2Flibcaesium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lymphatus","download_url":"https://codeload.github.com/Lymphatus/libcaesium/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419597,"owners_count":20936009,"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":["compression","image-compression","jpeg","optimization","png","rust","webp"],"created_at":"2024-08-01T15:01:46.600Z","updated_at":"2025-04-06T00:30:42.946Z","avatar_url":"https://github.com/Lymphatus.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# libcaesium [![Rust](https://github.com/Lymphatus/libcaesium/actions/workflows/rust.yml/badge.svg)](https://github.com/Lymphatus/libcaesium/actions/workflows/rust.yml)\n\nLibcaesium is a simple library performing JPEG, PNG, WebP and GIF (experimental) compression/optimization written in Rust, with a C interface.\\\n**IMPORTANT**: starting from v0.6.0 the library is written in Rust and no longer in C. There's a C interface, but it's not backward compatible with the \u003c0.6.0.\n\n## Usage in Rust\nLibcaesium exposes two functions, auto-detecting the input file type\n### Based on quality values\n```Rust\npub fn compress(\n    input_path: String,\n    output_path: String,\n    parameters: \u0026CSParameters\n) -\u003e Result\u003c(), Box\u003cdyn Error\u003e\u003e\n```\n#### Parameters\n- `input_path` - input file path (full filename)\n- `output_path` - output file path (full filename)\n- `parameters` - options struct, containing compression parameters (see below)\n\n### Based on output size\n```Rust\npub fn compress_to_size(\n    input_path: String,\n    output_path: String,\n    parameters: \u0026CSParameters,\n    max_output_size: usize,\n) -\u003e Result\u003c(), Box\u003cdyn Error\u003e\u003e\n```\n#### Parameters\n- `input_path` - input file path (full filename)\n- `output_path` - output file path (full filename)\n- `parameters` - options struct, containing compression parameters (see below)\n- `max_output_size` - the maximum output size, in bytes\n\nThis function will attempt to compress the given file *below* the desired size. It will never exceed it. The function \nwill start looping until the best size under the desired is achieved. The function has a 2% tolerance for the output size.\nAll quality value set to the parameters will be ignored and overwritten during the compression.\n\nNOTE: The output folder where the file is compressed **must** exist.\n### Compression options\nLibcaesium supports a few compression parameters for each file it supports.\nThey are defined into a top level struct containing each supported file parameters, as follows:\n```Rust\npub struct CSParameters {\n    pub jpeg: jpeg::Parameters,\n    pub png: png::Parameters,\n    pub gif: gif::Parameters,\n    pub webp: webp::Parameters,\n    pub tiff: tiff::Parameters,\n    pub keep_metadata: bool,\n    pub optimize: bool,\n    pub width: u32,\n    pub height: u32,\n}\n```\nEach file type has its own options, but the last two are generic:\n- `keep_metadata`: will keep metadata information for any supported type. JPEG and PNG supported. Default `false`.\n- `optimize`: forces optimization, when available. With this option enabled the compression will be lossless. JPEG, PNG and WebP supported. Default `false`.\n- `width`: Resizes the image to the given width. If this value is `0` and the height value is also `0`, no resizing will be done. If this is `0` and height is `\u003e 0`, the image will be scaled based on height keeping the aspect ratio. Default `0`.\n- `height`: Resizes the image to the given height. If this value is `0` and the width value is also `0`, no resizing will be done. If this is `0` and width is `\u003e 0`, the image will be scaled based on width keeping the aspect ratio. Default `0`.\n\n#### jpeg\n```Rust\npub struct Parameters {\n    pub quality: u32,\n    pub chroma_subsampling: jpeg::ChromaSubsampling\n}\n```\n- `quality`: in a range from 1 to 100, the quality of the resulting image. Default `80`.\n- `chroma_subsampling`: [chroma subsampling](https://en.wikipedia.org/wiki/Chroma_subsampling) to apply during compression. Default `Auto`.\n\n#### png\n```Rust\npub struct Parameters {\n    pub quality: u32,\n    pub force_zopfli: bool,\n    pub optimization_level: u32\n}\n```\n- `quality`: in a range from 0 to 100, the quality of the resulting image. Default `80`.\n- `force_zopfli`: if `optimization` is `true` and this option is also `true`, will use zopfli algorithm for compression, resulting in a smaller image, but it may take minutes to finish the process. Default `false`.\n- `optimization_level`: if `optimization` is `true` will set the level of oxipng optimization, from 1 to 6. Default `3`.\n\n#### gif\nGIF support is experimental, has many know issues and does not support optimization. Expect bugs (especially on Windows).\n```Rust\npub struct Parameters {\n    pub quality: u32,\n}\n```\n- `quality`: in a range from 0 to 100, the quality of the resulting image. If the optimization flag is `true`, the level is set to `100`. Default: `80`.\n\n#### webp\nWebP's compression is tricky. The format is already well optimized and using the `optimize` flag will probably result in a bigger image.\n```Rust\npub struct Parameters {\n    pub quality: u32,\n}\n```\n- `quality`: in a range from 0 to 100, the quality of the resulting image. If the optimization flag is `true`, this option will be ignored. Default: `60`.\n\n#### tiff\nSupported TIFF compression is only lossless. The supported algorithms are: Lzw, Deflate, Packbits, Uncompressed.\n```Rust\npub struct Parameters {\n    pub algorithm: TiffCompression,\n    pub deflate_level: DeflateLevel,\n}\n```\n- `deflate_level`: can be one of `Fast`, `Balanced`, `Best`.\n\n_________________\n\n## Usage in C\nLibcaesium exposes two C functions, auto-detecting the input file type:\n### Based on quality values\n```Rust\npub unsafe extern \"C\" fn c_compress(\n    input_path: *const c_char,\n    output_path: *const c_char,\n    params: CCSParameters\n) -\u003e CCSResult\n```\n#### Parameters\n- `input_path` - input file path (full filename)\n- `output_path` - output file path (full filename)\n- `parameters` - options struct, containing compression parameters (see below)\n#### Return\nA `CCSResult` struct\n```Rust\n#[repr(C)]\npub struct CCSResult {\n    pub success: bool,\n    pub error_message: *const c_char,\n}\n```\nIf `success` is `true` the compression process ended successfully and `error_message` will be empty.  \nOn failure, the `error_message` will be filled with a string containing a brief explanation of the error.\n\n### Based on output size\n```Rust\npub unsafe extern \"C\" fn c_compress_to_size(\n    input_path: *const c_char,\n    output_path: *const c_char,\n    params: CCSParameters,\n    max_output_size: usize,\n) -\u003e CCSResult\n```\n#### Parameters\n- `input_path` - input file path (full filename)\n- `output_path` - output file path (full filename)\n- `parameters` - options struct, containing compression parameters (see below)\n- `max_output_size` - the maximum output size, in bytes\n#### Return\nA `CCSResult` struct\n```Rust\n#[repr(C)]\npub struct CCSResult {\n    pub success: bool,\n    pub error_message: *const c_char,\n}\n```\nIf `success` is `true` the compression process ended successfully and `error_message` will be empty.  \nOn failure, the `error_message` will be filled with a string containing a brief explanation of the error.\n\n### Compression options\nThe C options struct is slightly different from the Rust one:\n```Rust\n#[repr(C)]\npub struct CCSParameters {\n    pub keep_metadata: bool,\n    pub jpeg_quality: u32,\n    pub jpeg_chroma_subsampling: u32,\n    pub png_quality: u32,\n    pub png_optimization_level: u32,\n    pub png_force_zopfli: bool,\n    pub gif_quality: u32,\n    pub webp_quality: u32,\n    pub tiff_compression: u32,\n    pub tiff_deflate_level: u32,\n    pub optimize: bool,\n    pub width: u32,\n    pub height: u32,\n}\n```\nThe option description is the same as the Rust counterpart.\nValid values for `jpeg_chroma_subsampling` are [444, 422, 420, 411]. Any other value will be ignored and will be used the default option.\nValid values for `tiff_compression` are [0 (Uncompressed), 1 (Lzw), 2 (Deflate), 3 (Packbits)]. Any other value will be ignored and `0` will be used.\nValid values for `tiff_deflate_level` are [3 (Fast), 6 (Balanced), 9 (Best)]. Any other value will be ignored and `Best` will be used.\n\n## Download\nBinaries not available. Please refer to the compilation section below.\n\n## Compilation and Installation\nCompilation is available for all supported platforms: Windows, macOS and Linux.\n\n```\ncargo build --release\n```\nNote: if you don't use the `--release` flag, the PNG optimizations can take a very long time to complete, especially using the zopfli algorithm.\n\nThe result will be a dynamic library usable by external applications through its C interface.\n\n## Compression vs Optimization\nJPEG is a lossy format: that means you will always lose some information after each compression. So, compressing a file with\n100 quality for 10 times will result in an always different image, even though you can't really see the difference.\nLibcaesium also supports optimization, by setting the _quality_ to 0. This performs a lossless process, resulting in the same image,\nbut with a smaller size (10-12% usually).  \nGIF optimization is possible, but currently not supported.\nWebP's optimization is also possible, but it will probably result in a bigger output file as it's well suited to losslessly convert from PNG or JPEG.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLymphatus%2Flibcaesium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLymphatus%2Flibcaesium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLymphatus%2Flibcaesium/lists"}