Current file types supported: PDF, PNG, JPEG, GIF
Calipers was built to provide a method of determining the dimensions of an image or PDF much faster and less resource-intensive than shelling-out to ImageMagick. At Lob we must validate image and PDF sizes during the lifecyle of an API request. The simplest way to do this is to shell-out to ImageMagick to identify the type and size of a file. For high-traffic servers, this becomes a major bottleneck due to the innefficiency of shelling-out.
Calipers remains performant because it avoids spawning child processes and it doesn't read entire files into memory. Instead, it intelligently reads only parts of the files that are necessary to determine the type and the dimensions of the file.
Calipers uses a plugin architecture to allow users to include support for only the specific file types they need to measure. This helps avoid wasting CPU cycles measuring file types that an application doesn't support, and ensures users must only install dependencies that are absolutely needed (e.g. Poppler for PDF support).
To use Calipers, you must install the core library and at least one plugin. For example, for PNG support:
npm install --save calipers calipers-png
Here is a list of officially supported plugins:
† The Poppler library C++ interface is required for PDF support. You must install Poppler before running
npm install calipers-pdf.
To install Poppler on Mac OS X using Homebrew:
brew install poppler
To install Poppler on Ubuntu:
apt-get install pkg-configapt-get install libpoppler-cpp-dev
To install Calipers, use NPM:
npm install calipers
Calipers must be initialized by calling the required function with supported file types passed in. Use the plugin name's suffix (everything after the first "-") as an argument.
// Initializes Calipers with support for calipers-png, calipers-jpeg, calipers-pdf.var calipers = 'png' 'jpeg' 'pdf';
Calipers exposes a single function,
measure, once initialized.
Measures the file at the given path.
filePath- The path of the file.
callback- called when the file has been measured
err- An Error is thrown for unsupported file types or corrupt files.
result- Contains keys
typeis a string representing the file type (e.g.
pagesis an array of objects with keys
height. For image files,
pagesalways has 1 element and
heightare the integer pixel dimensions. For PDF
heightare floating-point PostScript Point dimensions.
var calipers = 'png' 'pdf';// You can use a callback:calipers;// Or you can use promises:calipers;
More information coming soon.
As with all benchmarks, take these with a grain of salt. You can run the benchmarks on your own hardware:
These benchmarks are running 500 iterations of each method on the 123x456 PDF, PNG, and JPEG with a concurrency setting of 50. They were run on a Mid-2014 13" MacBook Pro with a 2.6 GHz Intel Core i5.
The easiest and most helpful way to contribute is to find a file that Calipers incorrectly measures, and submit an issue or PR with the file.
More information coming soon.
Inspired by netroy's image-size library: https://github.com/netroy/image-size