{"id":19858728,"url":"https://github.com/alexwlchan/dominant_colours","last_synced_at":"2026-01-16T09:54:36.934Z","repository":{"id":37042290,"uuid":"432113519","full_name":"alexwlchan/dominant_colours","owner":"alexwlchan","description":"A CLI tool to find the dominant colours in an image 🎨","archived":false,"fork":false,"pushed_at":"2025-04-14T18:34:37.000Z","size":10865,"stargazers_count":99,"open_issues_count":8,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-14T19:40:29.863Z","etag":null,"topics":["dominant-colors","kmeans","kmeans-colors","rust"],"latest_commit_sha":null,"homepage":"https://dominant-colours.glitch.me","language":"Rust","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/alexwlchan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2021-11-26T08:58:04.000Z","updated_at":"2025-04-14T18:34:35.000Z","dependencies_parsed_at":"2024-05-17T07:48:06.692Z","dependency_job_id":"e56257c3-b3c2-445c-8b3f-341baaba70c3","html_url":"https://github.com/alexwlchan/dominant_colours","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwlchan%2Fdominant_colours","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwlchan%2Fdominant_colours/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwlchan%2Fdominant_colours/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwlchan%2Fdominant_colours/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexwlchan","download_url":"https://codeload.github.com/alexwlchan/dominant_colours/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251972475,"owners_count":21673612,"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":["dominant-colors","kmeans","kmeans-colors","rust"],"created_at":"2024-11-12T14:24:20.137Z","updated_at":"2026-01-16T09:54:36.922Z","avatar_url":"https://github.com/alexwlchan.png","language":"Rust","funding_links":[],"categories":["Unknown"],"sub_categories":[],"readme":"# dominant_colours\n\nThis is a tool for finding the dominant colours of an image.\nIt prints their hex codes to the terminal, along with a preview of the colour (in terminals that support ANSI escape codes):\n\n![Left: a photo of a red and white lighthouse set against a blue sky. Right: the terminal output of three invocations of 'dominant_colours' against 'lighthouse.jpg', with hex colours printed to the terminal.](screenshot.png)\n\nIt's available both as a command-line tool and [as a web app](./webapp).\n\n\n\n## Installation\n\nYou can download compiled binaries from the [GitHub releases](https://github.com/alexwlchan/dominant_colours/releases).\n\nAlternatively, you can install from source.\nYou need Rust installed; I recommend using [Rustup].\nThen clone this repository and compile the code:\n\n```console\n$ git clone \"https://github.com/alexwlchan/dominant_colours.git\"\n$ cd dominant_colours\n$ cargo install --path .\n```\n\n[Rustup]: https://rustup.rs/\n\n\n\n## Usage examples\n\nPass the path of an image you want to look at:\n\n```console\n$ dominant_colours /path/to/cats.jpg\n▇ #d0c6b2\n▇ #3f3336\n▇ #f3f2ee\n▇ #786356\n▇ #aa9781\n```\n\nBy default, it finds (up to) five dominant colours.\nIf you want more or less, pass the `--max-colours` flag.\nFor example:\n\n```console\n$ dominant_colours /path/to/corgis.jpg --max-colours=3\n▇ #7c8442\n▇ #ccbe8f\n▇ #2d320e\n```\n\nThe colours are printed as hex codes, with colour previews in your terminal.\nIf you just want the hex codes and no colour preview, pass the `--no-palette` flag:\n\n```console\n$ dominant_colours /path/to/crustaceans.png --no-palette\n#e6401b\n#be5e36\n#734f48\n#d6c0bd\n#b1948f\n```\n\nThis is useful if your terminal doesn't support ANSI escape codes, or you're passing the output to another tool.\n\nIt currently supports JPEGs, PNGs, and GIFs (including animated GIFs).\n\n\n\n## Wrapper functions in other languages\n\nOne of the reasons I wrote `dominant_colours` as a standalone binary was to allow me to write all the fiddly colour logic once, and then I can call it with thin wrapper functions from other languages.\n\nSo far I've only done this from Python, but the option is there!\nI'll put any of these wrapper functions I write below (or add your own in a PR):\n\n\u003cdetails\u003e\n  \u003csummary\u003ePython\u003c/summary\u003e\n\n```python\nimport subprocess\n\n\ndef dominant_colours(path, *, max_colours=5):\n    \"\"\"\n    Get the dominant colours of an image.\n    \n    Returns the colours as RGB tuples of 0-255 values,\n    e.g. red is (255, 0, 0).\n    \"\"\"\n    cmd = [\"dominant_colours\", path, f\"--max-colours={max_colours}\", \"--no-palette\"]\n    output = subprocess.check_output(cmd)\n\n    colours = []\n\n    for line in output.splitlines():\n        colours.append((\n            int(line[1:3], 16),\n            int(line[3:5], 16),\n            int(line[5:7], 16),\n        ))\n\n    return colours\n```\n\n\u003c/details\u003e\n\n\n\n## Further reading\n\n-   I've written [an accompanying blog post](https://alexwlchan.net/2021/11/dominant-colours/) that talks more about the motivation behind the tool, a high-level overview of how it works, and why I chose to write it in Rust.\n\n-   [Getting a tint colour from an image with Python and k-means](https://alexwlchan.net/2019/08/finding-tint-colours-with-k-means/) – a blog post I wrote in August 2019 explaining how to find dominant colours.\n\n    My original implementation was in Python.\n    I've replaced it with a standalone Rust tool so I can easily share it across multiple projects, and because Rust is noticeably faster for this sort of thing.\n\n-   [Collyn O'Kane's kmeans-colors project](https://github.com/okaneco/kmeans-colors) – a Rust command-line tool and library for finding the average colours in an image using k-means.\n\n    The command-line tool has a lot of features, more than I need.\n    I wanted a very simple tool that does one thing, so I wrote dominant_colours as a wrapper around the library.\n\n-   [Drawing coloured squares/text in my terminal with Python](https://alexwlchan.net/2021/04/coloured-squares/) – a blog post I wrote in April 2021 explaining how to use ANSI escape codes to print arbitrary colours in a terminal.\n\n    I used the same escape codes to get the coloured output in this tool.\n\n\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwlchan%2Fdominant_colours","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexwlchan%2Fdominant_colours","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwlchan%2Fdominant_colours/lists"}