Command-line interface

python -m sandman ...

Common arguments

--help, -h

Print the help message for sandman or any subcommand of it.

--boring

Refrain from using terminal escapes to make certain text elements look like rainbow vomit.

Generating new colormaps

python -m sandman optimize ...

Basic subcommand arguments

--save=file

Save the output data as JSON in the given file, overwriting any previous content. If this option is not used, the output is printed to stdout.

--pool=number

Number of random colors in the pool from which colormap colors are chosen. If explicit colors are listed, this option does nothing.

--count=number

Maximum number of colors that should appear in each map. In general, including more colors in a map requires more effort to optimize, since each color in the map adds two degrees of freedom to the optimization problem.

--exact

By default, all permutations of color sequences of length 3 to count are attempted. This flag changes that behavior and limits the optimization to colormaps with exactly count colors.

--nproc=number

Number of processors to use during optimization. This code is “embarrasingly parallel,” meaning that different color permutations can be solved independently at the same time. concurrent.futures.ProcessPoolExecutor is used to parallelize the loop over color permutations. By default, only one processor is used.

--kind={sequential,diverging,cyclic}

Kind of colormap to generate. Sequential colormaps increase linearly in intensity, while diverging and cyclic maps are non-monotonic. Diverging maps will have an intensity peak in the middle. Cyclic maps have the same color and intensity at the two ends, making them ideal for plotting quantities like angles that naturally “wrap around.”

Advanced subcommand arguments

--lightdark=number

If maps appear too dark overall, this option can be used to boost the lightness across the map. The value should be an integer in the range [0, 100]. Keep in mind that lightness in the HSL space cannot exceed unity, though, so this argument, if used, should be small.

--saturate=number

Similarly, maps may appear washed-out or desaturated overall, so this option can be used to boost the overall saturation. The value should be an integer in the range [0, 100]. Keep in mind that saturation in the HSL space cannot exceed unity, though, so this argument, if used, should be small.

--lowval=number

Minimum value of perceived intensity; on a sequential map, this is the intensity at the far left edge of the map. The value should be an integer in the range [0, 100]. The default is 40.

--highval=number

Maximum value of perceived intensity; on a sequential map, this is the intensity at the far right edge of the map. The value should be an integer in the range [0, 100]. The default is 90.

Example

python -m sandman optimize --nproc=16 --kind=sequential --save=sequential.json --count=4 --exact --saturate=20 bf616a d08770 ebcb8b a3be8c 81a1c1 b48ead

Previewing colormaps

python -m sandman preview ...

Subcommand arguments

--rows=number

Number of rows of colormaps shown in the output image. The total height scales linearly with the number of rows. The default value is 10.

--cols=number

Number of columns of colormaps shown in the output image. The total width scales linearly with the number of columns. The default value is 2.

--save=file

Save the output image to the given file, overwriting any previous content. The image format corresponding to the file extension is used. If this option is not used, the image is shown in a window.

Example

python -m sandman preview sequential.json --rows=10 --cols=1

Simulating color vision deficiency

python -m sandman simulate ...

Subcommand arguments

--rows=number

Number of rows of colormaps shown in the output image. The total height scales linearly with the number of rows. The default value is 10.

--cols=number

Number of columns of colormaps shown in the output image. The total width scales linearly with the number of columns. The default value is 2.

--save=file

Save the output image to the given file, overwriting any previous content. The image format corresponding to the file extension is used. If this option is not used, the image is shown in a window.

--cvd={protanomaly,deuteranomaly,tritanomaly,achromatomaly}

Type of color vision deficiency (CVD) to apply to the colormap preview image.

Example

python -m sandman simulate sequential.json --rows=10 --cols=1 --cvd=protanomaly --severity=50