mini_vips

mini_vips packages the native libvips image operations used by discourse/discourse.

mini_vips requires libvips 8.13 or newer to be installed. Follow the libvips building and installation instructions before using it. Precompiled versions of mini_vips are available for glibc Linux and macOS on x86-64 and ARM64.

Usage

Add mini_vips to the application's Gemfile, then run bundle install:

gem "mini_vips"

Use MiniVips.executable to access the CLI executable:

require "mini_vips"

MiniVips.executable

Use MiniVips.asset_paths to access the files required by the CLI executable:

MiniVips.asset_paths

CLI

version

Print the linked libvips version.

$ mini_vips version
8.17.2

letter-avatar

Generate a square letter-avatar PNG, 360 by 360 pixels by default.

$ mini_vips letter-avatar A avatar.png --background-color C67D28

usage:
   letter-avatar letter out [--size pixels] [--letter-size pixels] [--background-color color]

where:
   letter             - Text displayed in the avatar
   out                - Output PNG path

options:
   background-color   - Six-character RGB background color
                        optional, default: 000000
   size               - Output width and height in pixels
                        optional, default: 360
                        min: 1, max: 4096
   letter-size        - Letter size in pixels
                        optional, default: 7/9 of size
                        min: 1, max: 4096

Letter avatars use the bundled Noto Sans font.

resize

Resize a supported image and select the output format from the output filename.

$ mini_vips resize avatar.png avatar-90.png --width 90 --height 90 --fit cover

usage:
   resize in out (--width pixels --height pixels | --scale ratio | --max-pixels pixels)
                 [--fit contain|cover] [--position center|top]
                 [--without-enlargement] [--quality 1..100]
                 [--colors count] [--strip-metadata]

where:
   in                    - Input image path
   out                   - Output image path

options:
   width                 - Bounding-box or cover width in pixels
   height                - Bounding-box or cover height in pixels
                          use together, min: 1, max: 65535
   scale                 - Proportional scale ratio
                          min: greater than 0, max: 100
   max-pixels            - Maximum output pixel area
                          min: 1; never enlarges the image
   fit                   - Fit within the dimensions or cover them exactly
                          optional, default: contain
   position              - Crop from the center or top when fit is cover
                          optional, default: center
   without-enlargement   - Keep an image within the requested dimensions at
                          its original size when it is already smaller
   quality               - Output encoder quality
                          optional, min: 1, max: 100; unavailable for GIF
   colors                - Maximum palette size for PNG or GIF output
                          optional, min: 2, max: 256; rounded down to the
                          nearest palette bit depth supported by the format
   strip-metadata        - Remove image metadata from the output

Supported inputs are JPEG, PNG, GIF, WebP, HEIF, JPEG XL, and SVG. Supported outputs are JPEG, PNG, GIF, WebP, HEIF/AVIF, and JPEG XL. Resize uses the first frame of animated inputs, applies image orientation, preserves transparency when the output format supports it, and sharpens only images produced with --fit cover.

dominant-color

Print a representative color as an uppercase six-character RGB value.

$ mini_vips dominant-color image.png
3A3730

usage:
   dominant-color in

where:
   in                 - Input image path

Supported inputs are JPEG, PNG, GIF, WebP, HEIF, and JPEG XL. Transparent pixels contribute black when calculating the color.

convert

Convert an SVG into an opaque PNG.

$ mini_vips convert image.svg image.png --max-pixels 40000000

usage:
   convert in out --max-pixels pixels

where:
   in                 - Input SVG path
   out                - Output PNG path

options:
   max-pixels         - Maximum output pixel area
                        required, min: 1

Currently, convert only supports SVG input and PNG output.

Exit status

The executable returns:

• 0 when the operation succeeds.
• 1 when image processing fails.
• 2 when the command or its arguments are invalid.

Errors are written to standard error.

Development

Install libvips and pkg-config first. Then set up the repository once by installing its Ruby development dependencies:

bundle install

Use the default task during development. It compiles the native helper, runs the tests, and checks Ruby formatting and style:

bundle exec rake

Build, install, and test the platform gem with:

bundle exec rake test:installed