sic image cli

Convert images and perform image operations from the command-line.

sic (sic image cli) is a front-end for the image crate. Aside from image operations supplied by the image crate, a few additional helpful operations such as diff, are included. Operations provided by the imageproc crate can be enabled by compiling with the imageproc-ops feature. We intend to provide more extensive support for imageproc operations in a future release. sic supports operations on both static and animated images.

Installation

Install with cargo:

• run cargo install sic

Pre build binaries

• download from releases.

Build from source

• Setup rust and cargo (for example using rustup)
• Clone this repo: git clone https://github.com/foresterre/sic.git && cd sic
• Build a release: cargo build --release

sic is usually build against the latest stable Rust version, but may also work with older versions.

Using a package manager

brew tap tgotwig/sic
brew install tgotwig/sic/sic

brew tap tgotwig/linux-sic
brew install tgotwig/linux-sic/sic

emerge -av media-gfx/sic

Usage

Convert images

Convert an image from one format to another, for example from PNG to JPG.

• Command: sic --input <input> --output <output>
• Shorthand: sic -i <input> -o <output>
• Example: sic -i input.png -o output.jpg
  

If you want to explicitly set the image output format, you may do so by providing the --output-format <format> argument. Otherwise, sic will attempt to infer the format from the output file extension.

--help can be used to view a complete list of supported image output formats. Included are:

• AVIF, BMP, OpenExr, Farbfeld, GIF, ICO, JPEG, PNG, PNM (PAM, PBM, PGM and PPM), QOI TGA, TIFF and WebP.

The JPEG quality can optionally be set with --jpeg-encoding-quality <value>. The value should be in the range 1-100 (with default 80). Files which are formatted with a PNM format (with one subtype of PBM, PGM and PPM) use binary encoding (PNM P4, P5 and P6 respectively) by default. To use ascii encoding, you can provide the following flag: --pnm-encoding-ascii.

Convert or apply operations on a set of images

For the use case where you have a directory containing several (hundreds of) images which you like to convert to different format, or on which you perhaps want to apply certain image operations, sic provides built-in glob pattern matching. This mode can be used by providing the --glob-input and --glob-output options instead of --input and --output respectively.

Examples:

• To convert a directory of images from PNG to JPG, you can run sic with the following arguments:
  
  • sic --glob-input "*.png" --glob-output output_dir --output-format jpg"
• To convert all images with the jpg, jpeg and png extensions to BMP:
  • sic --glob-input "*.{jpg, jpeg, png}" --glob-output output_dir --output-format bmp
• To emboss all images in a folder (assuming it contains only supported image files and no folders):
  • sic --glob-input "*" --glob-output embossed_output --filter3x3 -1 -1 0 -1 1 1 0 1 1

A few things worth noticing: 1) We use quotation marks (") around the input argument, so our shell won't expand the glob pattern to a list of files. 2) When using glob mode, our output (--glob-output) should be a folder instead of a file. 3) We need to explicitly state the output format with --output-format, unless we work with a known extension we want to keep.

Output images are placed in the output folder using the directory structure mirrored from the first common directory of all input files. If output directories do not exist, they will be created.

Image operations

In sic, you can manipulate images using image operations. Image operations can be used directly from the CLI, or through sic's image script.

NB: Operations are applied in a left-to-right order and are generally not commutative. This may be especially surprising when applying image operation via CLI options and flags.

📜 image script

Use this method by using the --apply-operations "<operations>" (shorthand: -x) cli argument and providing statements which tell sic what operations should be applied on the image, for example:
sic -i input.jpg -o output.jpg --apply-operations "flip-horizontal; blur 10; resize 250 250"
When more than one image operation is provided, the separator ; should be used to separate each operation statement.

✏️ CLI ops

Use this method by providing cli image operation arguments, such as --blur and --crop, directly.
If we use the cli operations method the previously shown example becomes:
sic -i input.png -o output.jpg --flip-horizontal --blur 10 --resize 250 250

Available image operations

^1 The syntax in the table applies to image script, but can also be used as a reference when using image operations via CLI arguments
^2 draw-text is only available when compiled with imageproc-ops feature

Image operation modifiers

For some operations, their behaviour can be adapted by setting an operation modifier. These modifiers can be overwritten and they can also be reset (to their default behaviour).

legend:

<byte>: an 8 bit unsigned integer (positive number in range 0-255
<uint>: a 32 bit unsigned integer (positive number)
<int>: a 32 bit signed integer (positive or negative number)
<fp>: a 32 bit floating-point number (real number)
<fp9x>: 9 succeeding 32 bit floating-point numbers
<path>: a qualified path to an image reachable from your current platform (the path should be surrounded by quotation marks, i.e. " or ')
<string>: a valid unicode string

<nv:coord>: a named value representing a coordinate (top left is (0, 0)), with syntax coord(<uint>, <uint>)
<nv:rgba>: a named value representing an RGBA color, with syntax: rgba(<byte>, <byte>, <byte>, <byte>)
<nv:size>: a named value representing a font size, with syntax: size(<fp>)
<nv:font>: a named value representing a (TrueType) font file location, with syntax: font(<path>)

Examples

blur example:
sic -i in.png -o out.png --apply-operations "blur 1.3;"
or
sic -i in.png -o out.png --blur 1.3

brighten example:
sic -i in.png -o out.png --apply-operations "brighten 2;"
or
sic -i in.png -o out.png --brighten 2

contrast example:
sic -i in.png -o out.png --apply-operations "contrast 0.7;"
or
sic -i in.png -o out.png --contrast 0.7

crop example:
sic -i in.png -o out.png --apply-operations "crop 0 0 10 10;"
or
sic -i in.png -o out.png --crop 0 0 10 10

diff example:
sic -i a.png -o diff_between_a_and_b.png --apply-operations "diff 'b.png'"
or
sic -i a.png -o diff_between_a_and_b.png --diff b.png

a	b	output

With an animated image:

a	b	output

draw-text example (requires build feature imageproc-ops):
sic -i in.png -o out.png --apply-operations "draw-text '<3' coord(10, 2) rgba(255, 0, 0, 255) size(14) font('./Lato-Regular.ttf')"
or
sic -i in.png -o out.png --draw-text "<3" "coord(10, 2)" "rgba(255, 0, 0, 255)" "size(14)" "font('Lato-Regular.ttf')"

input	output

filter3x3 example:
sic -i in.png -o out.png --apply-operations "filter3x3 -1 -1 0 -1 0 1 0 1 1"
or
sic -i in.png -o out.png --filter3x3 -1 -1 0 -1 0 1 0 1 1

flip horizontal example:
sic -i in.png -o out.png --apply-operations "flip-horizontal"
or
sic -i in.png -o out.png --flip-horizontal

flip vertical example:
sic -i in.png -o out.png --apply-operations "flip-vertical"
or
sic -i in.png -o out.png --flip-vertical

gray scale example:
sic -i in.png -o out.png --apply-operations "grayscale"
or
sic -i in.png -o out.png --grayscale

horizontal gradient example:
sic -i in.png -o out.png --apply-operations "horizontal-gradient rgba(255, 0, 0, 255) rgba(0, 0, 255, 255)"
or
sic -i in.png -o out.png --horizontal-gradient "rgba(255, 0, 0, 255)" "rgba(0, 0, 255, 255)"

hue rotate example:
sic -i in.png -o out.png --apply-operations "hue-rotate -90"
or
sic -i in.png -o out.png --hue-rotate -90

invert example:
sic -i in.png -o out.png --apply-operations "invert"
or
sic -i in.png -o out.png --invert

overlay example:
sic -i in.png -o out.png --apply-operations "overlay 'image.png' 10 10"
or
sic -i in.png -o out.png --overlay "image.png" 10 10

resize example:
sic -i in.png -o out.png --apply-operations "resize 100 100"
or
sic -i in.png -o out.png --resize 100 100

resize with preserve aspect ratio example:
sic -i in.png -o out.png --apply-operations "set preserve-aspect-ratio true; resize 100 100"
or
sic -i in.png -o out.png --preserve-aspect-ratio true --resize 100 100

resize with custom sampling filter (default is 'lanczos3') example:
sic -i in.png -o out.png --apply-operations "set sampling-filter triangle; resize 100 100"
or
sic -i in.png -o out.png --sampling-filter triangle --resize 100 100

rotate 90 degree example:
sic -i in.png -o out.png --apply-operations "rotate90"
or
sic -i in.png -o out.png --rotate90

rotate 180 degree example:
sic -i in.png -o out.png --apply-operations "rotate180"
or
sic -i in.png -o out.png --rotate180

rotate 270 degree example:
sic -i in.png -o out.png --apply-operations "rotate270"
or
sic -i in.png -o out.png --rotate270

threshold example:
sic -i in.png -o out.png --apply-operations "threshold"
or
sic -i in.png -o out.png --threshold

unsharpen example:
sic -i in.png -o out.png --apply-operations "unsharpen -0.7 1"
or
sic -i in.png -o out.png --unsharpen -0.7 1

vertical gradient example:
sic -i in.png -o out.png --apply-operations "vertical-gradient rgba(255, 0, 0, 255) rgba(0, 0, 255, 255)"
or
sic -i in.png -o out.png --vertical-gradient "rgba(255, 0, 0, 255)" "rgba(0, 0, 255, 255)"

example with multiple image operations which are applied from left-to-right:
sic -i in.png -o out.png --apply-operations "rotate180; flip-horizontal; set sampling-filter nearest; resize 75 80; hue-rotate 75"
or
sic -i in.png -o out.png --rotate180 --flip-horizontal --sampling-filter nearest --resize 75 80 --hue-rotate 75

Other resources on image operations

For additional information on available options and flags, run sic --help.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Suggestions, Questions, Bugs

Feel free to open an issue 📬 if you have a suggestion, a question or found a bug =).

🎸 🎺 🎻 🎷