1# dominant_colours
2
3This is a tool for finding the dominant colours of an image.
4It prints their hex codes to the terminal, along with a preview of the colour (in terminals that support ANSI escape codes):
5
6![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)
7
8It's available both as a command-line tool and [as a web app](./webapp).
9
10
11
12## Installation
13
14You can download compiled binaries from the [GitHub releases](https://github.com/alexwlchan/dominant_colours/releases).
15
16Alternatively, you can install from source.
17You need Rust installed; I recommend using [Rustup].
18Then clone this repository and compile the code:
19
20```console
21$ git clone "https://github.com/alexwlchan/dominant_colours.git"
22$ cd dominant_colours
23$ cargo install --path .
24```
25
26[Rustup]: https://rustup.rs/
27
28
29
30## Usage examples
31
32Pass the path of an image you want to look at:
33
34```console
35$ dominant_colours /path/to/cats.jpg
36▇ #d0c6b2
37▇ #3f3336
38▇ #f3f2ee
39▇ #786356
40▇ #aa9781
41```
42
43By default, it finds (up to) five dominant colours.
44If you want more or less, pass the `--max-colours` flag.
45For example:
46
47```console
48$ dominant_colours /path/to/corgis.jpg --max-colours=3
49▇ #7c8442
50▇ #ccbe8f
51▇ #2d320e
52```
53
54The colours are printed as hex codes, with colour previews in your terminal.
55If you just want the hex codes and no colour preview, pass the `--no-palette` flag:
56
57```console
58$ dominant_colours /path/to/crustaceans.png --no-palette
59#e6401b
60#be5e36
61#734f48
62#d6c0bd
63#b1948f
64```
65
66This is useful if your terminal doesn't support ANSI escape codes, or you're passing the output to another tool.
67
68It currently supports JPEGs, PNGs, and GIFs (including animated GIFs).
69
70
71
72## Wrapper functions in other languages
73
74One 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.
75
76So far I've only done this from Python, but the option is there!
77I'll put any of these wrapper functions I write below (or add your own in a PR):
78
79<details>
80  <summary>Python</summary>
81
82```python
83import subprocess
84
85
86def dominant_colours(path, *, max_colours=5):
87    """
88    Get the dominant colours of an image.
89    
90    Returns the colours as RGB tuples of 0-255 values,
91    e.g. red is (255, 0, 0).
92    """
93    cmd = ["dominant_colours", path, f"--max-colours={max_colours}", "--no-palette"]
94    output = subprocess.check_output(cmd)
95
96    colours = []
97
98    for line in output.splitlines():
99        colours.append((
100            int(line[1:3], 16),
101            int(line[3:5], 16),
102            int(line[5:7], 16),
103        ))
104
105    return colours
106```
107
108</details>
109
110
111
112## Further reading
113
114-   I've written [an accompanying blog post](https://alexwlchan.net/2021/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.
115
116-   [Getting a tint colour from an image with Python and k-means](https://alexwlchan.net/2019/finding-tint-colours-with-k-means/) – a blog post I wrote in August 2019 explaining how to find dominant colours.
117
118    My original implementation was in Python.
119    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.
120
121-   [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.
122
123    The command-line tool has a lot of features, more than I need.
124    I wanted a very simple tool that does one thing, so I wrote dominant_colours as a wrapper around the library.
125
126-   [Drawing coloured squares/text in my terminal with Python](https://alexwlchan.net/2021/coloured-squares/) – a blog post I wrote in April 2021 explaining how to use ANSI escape codes to print arbitrary colours in a terminal.
127
128    I used the same escape codes to get the coloured output in this tool.
129
130
131
132## License
133
134MIT.