{"id":25340936,"url":"https://github.com/ivordir/okolors","last_synced_at":"2025-08-15T15:17:55.988Z","repository":{"id":155186845,"uuid":"631411501","full_name":"Ivordir/Okolors","owner":"Ivordir","description":"Generate a color palette from an image using k-means clustering in the Oklab color space.","archived":false,"fork":false,"pushed_at":"2024-07-04T06:34:37.000Z","size":162587,"stargazers_count":45,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T19:07:01.412Z","etag":null,"topics":["kmeans","oklab","palette","palette-generation","theme"],"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/Ivordir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2023-04-23T00:03:20.000Z","updated_at":"2025-01-21T04:03:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"3c4c37a9-ddf8-4c09-b042-6ecedd8cf3db","html_url":"https://github.com/Ivordir/Okolors","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ivordir%2FOkolors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ivordir%2FOkolors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ivordir%2FOkolors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ivordir%2FOkolors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ivordir","download_url":"https://codeload.github.com/Ivordir/Okolors/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238805869,"owners_count":19533618,"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":["kmeans","oklab","palette","palette-generation","theme"],"created_at":"2025-02-14T08:17:47.831Z","updated_at":"2025-02-14T08:17:48.500Z","avatar_url":"https://github.com/Ivordir.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Okolors\n\nOkolors generates high quality color palettes from an image for your theming needs.\nIt does this by converting the image's pixels to the\n[Oklab](https://bottosson.github.io/posts/oklab/) color space\nand then performing [k-means](https://en.wikipedia.org/wiki/K-means_clustering) clustering.\nBy using a proper color space for color difference and a more accurate clustering algorithm,\nthis helps to ensure that the generated palette is truly representative of the input image.\n\nOne of the main intended use cases for Okolors is to generate colors for a theme based off a wallpaper.\nIn line with this goal, the Okolors also supports printing the final average colors in multiple Okhsl lightness levels.\nFor example, you can specify a low lightness level for background colors\nand a high lightness for foreground text in order to achieve a certain contrast ratio.\nThe [Okhsl](https://bottosson.github.io/posts/colorpicker/) color space is ideal for this,\nbecause as the lightness is changed, Okhsl preserves the hue and saturation of the color\n(better than other color spaces like HSL).\n\nOkolors supports jpeg, png, gif, webp, and qoi images by default.\nPrecompiled binaries are available on [Github](https://github.com/Ivordir/Okolors/releases).\n\nIf you are looking for the Okolors library, see the crates.io page or the documentation:\n\n[![Crate](https://badgen.net/crates/v/okolors)](https://crates.io/crates/okolors)\n[![Docs](https://docs.rs/okolors/badge.svg)](https://docs.rs/okolors)\n\n# Examples\n\n## CLI Flags\n\nLet's use the following photo for the examples below.\n\n![Jewel Changi Airport Waterfall](docs/img/Jewel%20Changi.jpg)\n\nRunning Okolors for this image with the default options gives the following sRGB hex values.\n\n```bash\n\u003e okolors 'Jewel Changi.jpg'\n010202 041215 08343A DCE1E5 246673 C27E63 4A2D25 8B739B\n```\n\nIf your terminal supports true color,\nthen you can use `-o swatch` to see blocks of the output colors.\n\n```bash\n\u003e okolors 'Jewel Changi.jpg' -o swatch\n```\n\n![](docs/cli/swatch1.svg)\n\nLet's get these colors in additional lightness levels using `-l`.\n\n```bash\n\u003e okolors 'Jewel Changi.jpg' -l 10,30,50,70 -o swatch\n```\n\n![](docs/cli/swatch2.svg)\n\nIf we're providing our own lightness levels, maybe we want to cluster the colors by hue and saturation only.\nLet's set the lightness weight to `0` using `-w`.\n\n```bash\n\u003e okolors 'Jewel Changi.jpg' -w 0 -l 10,30,50,70 -o swatch\n```\n\n![](docs/cli/swatch3.svg)\n\nThat ended up bringing out an additional pinkish color but also merged white and black into a gray.\nSo, use this at your own discretion!\n\nIf some of the colors still seem quite similar, then you can reduce/set the number of colors through `-k`.\n\n```bash\n\u003e okolors 'Jewel Changi.jpg' -k 6 -w 0 -l 10,30,50,70 -o swatch\n```\n\n![](docs/cli/swatch4.svg)\n\nTo see all the other command line options, pass `-h` for a summary or `--help` for detailed explanations.\n\n## Images\n\nHere are some more examples of Okolors in action. The only CLI flag used was `-s l`.\n\n### Louvre\n![Louvre](docs/img/Louvre.jpg)\n![Louvre Palette](docs/palette/Louvre.svg)\n\n### Hokkaido\n![Hokkaido](docs/img/Hokkaido.jpg)\n![Hokkaido Palette](docs/palette/Hokkaido.svg)\n\n### Český Krumlov\n![Český Krumlov](docs/img/Cesky%20Krumlov.jpg)\n![Český Krumlov Palette](docs/palette/Cesky%20Krumlov.svg)\n\n### Lake Mendota\n![Lake Mendota](docs/img/Lake%20Mendota.jpg)\n![Lake Mendota Palette](docs/palette/Lake%20Mendota.svg)\n\n# Performance\n\nOkolors is designed with performance in mind and should give fast results for even very large images.\nThis is despite using k-means which is more accurate but slower than something like median cut quantization.\nBelow are the palette generation times as reported by the `--verbose` flag.\nThe only other flag used was `-t 4` to use 4 threads.\n\n| Image               | Width | Height | Unique Colors | Time (ms) |\n| ------------------- | -----:| ------:| -------------:| ---------:|\n| Louvre              | 6056  | 4000   | 616101        | 63        |\n| Hokkaido            | 6000  | 4000   | 576339        | 57        |\n| Jewel Changi        | 6000  | 4000   | 400788        | 48        |\n| Český Krumlov       | 4608  | 3456   | 743552        | 51        |\n| Lake Mendota        | 3839  | 5758   | 467802        | 55        |\n| Louvre (25%)        | 1514  | 1000   | 238332        | 18        |\n| Hokkaido (25%)      | 1500  | 1000   | 262207        | 18        |\n| Jewel Changi (25%)  | 1500  | 1000   | 147678        | 11        |\n| Český Krumlov (25%) | 1152  | 864    | 294989        | 20        |\n| Lake Mendota (25%)  | 960   | 1440   | 264149        | 18        |\n\nOftentimes, especially for large images, loading and decoding the image takes longer than it does for Okolors to generate the palette!\n\n# References\n\n- [kmeans-colors](https://github.com/okaneco/kmeans-colors/) served as the original inspiration for Okolors.\n  If you want to perform other k-means related operations on images or prefer the CIELAB colorspace, then check it out!\n- The awesome [palette](https://github.com/Ogeon/palette) library is used for all color conversions.\n\n# License\n\nOkolors (binary and library) is licensed under either\n- the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) (see [LICENSE-APACHE](LICENSE-APACHE))\n- the [MIT](http://opensource.org/licenses/MIT) license (see [LICENSE-MIT](LICENSE-MIT))\n\nat your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivordir%2Fokolors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivordir%2Fokolors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivordir%2Fokolors/lists"}