1mNAME0m colorsnap - snap colors in an image to reference colors 1mSYNOPSIS0m # basic plain-text report of snapped color proportions bin/colorsnap -file img/mickey.png # run 4 threads (spawns child processes, see below) bin/colorsnap -file img/mickey.png -fork 4 # very brief report of snapped color proportions bin/colorsnap -file img/mickey.png -brief # resize the input image proportionately to 150 pixels before snapping bin/colorsnap -file img/mickey.png -resizew 150 # deltaE (using dE00) cutoff for snapping (if this is not set, closest reference color will be chosen) bin/colorsnap -file img/mickey.png -delta_e_max 25 # when using -delta_e_max, any colors that weren't snapped can be masked bin/colorsnap -file img/mickey.png -delta_e_max 25 -snap_mask 255,255,255,0 # change deltaE model (cie74, cie94, cmc94, cie00) bin/colorsnap -file img/mickey.png -delta_e_model cie94 # exclude reference colors to snap to using regular expression bin/colorsnap -file img/mickey.png -delta_e_max 25 -rxfail "white|black" # include reference colors to snap to using regular expression (all others excluded) bin/colorsnap -file img/mickey.png -delta_e_max 25 -rxpass "red|green|blue" # include snapped output file (PNG), written to same directory as input file bin/colorsnap -file img/mickey.png -snap # snapped output file uses average colors instead of reference bin/colorsnap -file img/mickey.png -snap -snap_method average # any colors in the input image matching the mask, possibily within delta_e_mask will not be touched bin/colorsnap -file img/mickey.png -snap -delta_e_max 25 -mask 255,255,255 -delta_e_mask 10 # any transparent colors in the input image can be skipped, masked or snapped bin/colorsnap -file img/mickey.png -snap -delta_e_max 25 -if_transparency skip # when using if_transparency=mask, provide the mask color bin/colorsnap -file img/mickey.png -snap -delta_e_max 25 -if_transparency mask -transparency_mask 255,255,255,0 # include stacked bar plot of colors bin/colorsnap ... -bars # include stacked bar plot of colors of a given width and height bin/colorsnap ... -bars -barw 100 -barh 5 # make the stacked bar plot ordered by size bin/colorsnap ... -bars -ordered # debug while running bin/colorsnap ... -debug # specify configuration file (default etc/colorsnap.conf) bin/colorsnap ... -conf myconfig.conf # dump configuration and exit bin/colorsnap -cdump # help and usage bin/colorsnap -help bin/colorsnap -man 1mDESCRIPTION0m Snaps colors in an image to a set of reference colors. Optionally, generate a color-snapped image and a histogram of snapped color values. 1mOUTPUT0m 1mConfiguration0m See "etc/colorsnap.conf" for default settings. The configuration file is needed to define the reference colors to snap to. All other parameters may be defined (and overwritten) on the command line. If you define "delta_e_max" in the configuration file, to undefine it on the command line use <-delta_e_max -1>. This will snap to the closest color without a maximum color difference cutoff. 1mColor Difference Models0m Four common color difference models are supported: CIE74, CIE94, CMC94, CIE00. Default is CIE00, which is the most accurate but also slowest. CIE94 is almost as good as CIE00 and quite a bit faster. If you're happy with the performance of "colorsnap", use CIE00 otherwise CIE94. See . 1mColor snap report0m Each reference is reported with number of pixel in image snapped to it, fraction of pixels in image snapped to it, and number of pixels normalize to the largest number of pixels snapped to a reference. > bin/colorsnap -file img/traffic.png img/traffic.png 162690 3084 0.019 dred rgb 119 11 11 n 188 0.061 0.001 0.103 *** img/traffic.png 162690 3084 0.019 green rgb 89 218 91 n 1827 0.592 0.011 1.000 ****************************** img/traffic.png 162690 3084 0.019 lred rgb 246 47 39 n 553 0.179 0.003 0.303 ********* img/traffic.png 162690 3084 0.019 orange rgb 255 147 73 n 516 0.167 0.003 0.282 ******** For example, the output above is the report for the img/traffic.png image snapped to the four traffic reference colors. The image has 162,690 pixels of which 3,084 (1.9%) were snapped to colors (delta_e_max = 25). We see 188, 1827, 553 and 516 pixels stapped to the dark red, green light red and orange, respectively. These represent 6.1%, 59.2%, 17.9% and 16.7% of snapped pixels and 0.1%, 1.1%, 0.3% and 0.3% of all pixels in the image. The last field is the number of pixels normalized to the most frequently snapped color -- here this is green thus, for example 10.3% of pixels are dark red relative to how many are green (188/1827). The *'s show a graphical encoding of the number of pixels. 1mBrief color snap report0m If you just want to get down to business and only need the number of pixels snapped to a given color, use "-brief". Note that colors here are in alphabetical order. > bin/colorsnap -file img/traffic.png -brief # file dred_pix dred_fraction green_pix green_fraction lred_pix lred_fraction orange_pix orange_fraction img/traffic.png 188 0.061 1827 0.592 553 0.179 516 0.167 1mReference color report0m If you use "-debug", then you'll see a report about the reference colors as well as the deltaE's for all pairwise comparisons between reference colors. > bin/colorsnap -file img/traffic.png -delta_e_max 25 refrence green rgb 89 218 91 lch 77.9 79.0 139.7 refrence lred rgb 246 47 39 lch 53.8 89.7 36.7 refrence orange rgb 255 147 73 lch 71.3 65.4 57.7 refrence dred rgb 119 11 11 lch 24.3 53.8 36.0 deltae dred green 118.4 4.7 ok deltae dred lred 46.5 1.9 ok deltae dred orange 53.3 2.1 ok deltae green lred 134.4 5.4 ok deltae green orange 95.5 3.8 ok deltae lred orange 41.0 1.6 ok The deltaE comparisons show the color difference (e.g. 118.4 for dred vs green) as well as the difference expressed in multiples of "delta_e_max". If this multiple is >1 then "ok" appears. Be wary of having reference colors that are too close to one another -- the snapping in these cases may be unreliable. 1mSnapped image0m If you use the "-snap" flag, you also get an image of the same size as the input but with its colors replaced by the reference they snapped to. The snapped file will be written to the same direcdtory as the input file name with the strong "snap" in the filename. For example, img/mickey.snap.png. 1mStacked bar image of snapped color proportions0m If you use the "-bars" flag, you get a small stacked bar plot of the fraction of colors in the image snapped to each bar. If you use "-bars -ordered" then the bars will be ordered by size. The stacked bar image will be written to the same directory as the input file with the string "bars" in the filename. For example, img/mickey.bars.png. 1mReference colors0m Look in "etc/" for a few color reference lists: gretag.srgb.conf traffic.conf new.york.subway.conf paris.subway.conf london.subway.conf tokyo.subway.conf Colors can be defined in r,g,b or RGB hex format. When using hex format, do not include the # (see "new.york.subway.conf"). You can exclude colors from being considered using "-rxfail". This is most useful if you've added black and white to your list, but don't want to use them. bin/colorsnap ... -rxfail "white|black" Alternatively, you can use only specific colors that match "-rxpass". When using this flag, any colors whose names do not match this regular expression will not be used. bin/colorsnap ... -rxfail "orange|red|purple|blue" 1mMulti-threading0m By using "-fork N" you can spawn N child processes that each analyze a portion of the image. The children communicate to the parent process by way of a temporary cache file which is written to "fork_tmp_dir" which you can set using "-fork_tmp_dir DIR". By default this is the current directory. The cache files are named "colorsnap.RANDOM_STRING.CHILD_IDX.dat" and are deleted immediately after the script ends. To get the forking to work with Windows, the children also write to a .semaphore file, which is deleted as they are killed. If the compiled binary for Windows doesn't work with "-fork" and you want to fork, install Strawberry perl and run the script by invoking Perl perl bin\colorsnap ... Otherwise do not use -fork on Windows. 1mHISTORY0m * 31 Jan 2021 v0.22 v0.2 + added various delta E functions (delta_e_model = cie74, cie94, cmc94, cie00) + masking can now include nearby colors + added if_transparency, snap_mask, transparency_mask + other updates to config syntax + fixed Windows 10 compilation * 6 Jan 2019 v0.03 + forks children for speedup (-fork N) + reports average of colors snapped to a reference * 29 Dec 2018 v0.02 + modified command line flag names + added ability to have mask with transparency + added -rxfail and -rxpass flags to exclude/include colors by name * 28 Dec 2018 v0.01 1mAUTHOR0m Martin Krzywinski 1mCONTACT0m Martin Krzywinski Genome Sciences Center BC Cancer Research Center 100-570 W 7th Ave Vancouver BC V5Z 4S6 mkweb.bcgsc.ca martink@bcgsc.ca