Curtail
Curtail is a pure JavaScript image manipulation tool.
Note: This documentation is for Curtail 3.0, the most recent version of Curtail which reflects some API changes.
Installation
To download Curtail through npm, simply use the following command:
$ npm install curtail
Curtail doesn't have a named export so you can import the specific modules you need or all of them like so:
import * as curtail from './node_modules/curtail/curtail.js';
Modules
The available modules within Curtail are:
-
Transform: The transform methods are used to change the image size, format, and other 'physical' properties.
- crop: Crops an image to a specified dimensions from a starting point.
- convert: Converts an image from one format to another.
- resize: Resizes an image with the option of keeping the aspect ratio.
-
Decorate: Contains methods that to add decorative features to images.
- pad: Adds a padding of your color around the image. It could also be thought of as a border.
Transform
The transform methods are used to change the image size, format, and other 'physical' properties.
Note: As loading of images is an asynchoronous action, all of Curtail's methods return a Promise which you can use either then
or await
as shown in the examples below.
crop
The crop method takes the path to an image, a crop start location, and the final dimensons of the image and returns the newly cropped version of the original image.
param | type | description | default |
---|
path | string | The path to the image to crop | |
x | number | The horizontal starting location of the crop | |
y | number | The vertical starting location of the crop | |
width | number | The width of the cropped image | |
height | number | The height of the cropped image | |
options | Object | | {} |
options.autoDownload | boolean | Indicates whether the image should download after the cropping is complete or not. | false |
options.crossOrigin | string | Sets the cross-origin property of images originating from external sources. | null |
Using Promise.then
:
curtail.crop('./path/to/image.png', 100, 100, 720, 480).then((newImage) => {
});
Using async/await
:
async function main() {
const newImage = curtail.crop('./path/to/image.png', 100, 100, 720, 480).catch((err) => console.log(err));
}
main();
convert
The convert method takes an image and converts it from one image format to another.
If you have a transparent image and convert it to a format that doesn't support transparency, the image will be placed on a white background.
param | type | description | default |
---|
path | string | The path to the image to crop | |
format | string | The new format for the image | |
options | Object | | {} |
options.autoDownload | boolean | Indicates whether the image should download after the cropping is complete or not. | false |
options.crossOrigin | string | Sets the cross-origin property of images originating from external sources. | null |
Using Promise.then
:
curtail.convert('./path/to/image.png', 'jpg').then((newImage) => {
});
Using async/await
:
async function main() {
const newImage = curtail.convert('./path/to/image.png', 'jpg').catch((err) => console.log(err));
}
main();
resize
The resize method takes an image and resizes it, maintaining its aspect ratio by default.
param | type | description | default |
---|
path | string | The path to the image to crop | |
format | string | Which dimension to resize, either width or height. Keep in mind that if you're preserving the aspect ratio, the other will resize accordingly | |
size | number | The new size to make the specified dimension | |
options | Object | | {} |
options.preserveAspectRatio | boolean | Indicates whether the width and height will resize together to preserve the aspect ratio of the image | true |
options.autoDownload | boolean | Indicates whether the image should download after the cropping is complete or not. | false |
options.crossOrigin | string | Sets the cross-origin property of images originating from external sources. | null |
Using Promise.then
:
curtail.resize('./path/to/image.png', 'width', 400).then((newImage) => {
});
Using async/await
:
async function main() {
const newImage = curtail.resize('./path/to/image.png', 'width', 400).catch((err) => console.log(err));
}
main();
Decorate
Contains methods to add decorative features to images.
pad
The pad method takes an image and adds the specified amount of padding to it.
param | type | description | default |
---|
path | string | The path to the image to crop | |
padding | number | The amount of padding to add to the image | |
options | Object | | {} |
options.paddingColor | string | The color that the padding will be. This value can be any valid CSS color value such as white or #FFFFFF | 'transparent' |
options.autoDownload | boolean | Indicates whether the image should download after the cropping is complete or not. | false |
options.crossOrigin | string | Sets the cross-origin property of images originating from external sources. | null |
Using Promise.then
:
curtail.pad('./path/to/image.png', 20, { paddingColor: 'blue' }).then((newImage) => {
});
Using async/await
:
async function main() {
const newImage = curtail.pad('./path/to/image.png', 20, { paddingColor: 'blue' }).catch((err) => console.log(err));
}
main();
License
MIT