mirror of
https://github.com/lovell/sharp.git
synced 2025-12-19 15:25:07 +01:00
File extend, extract and trim ops under 'resize' #1135
Should make them easier to find in the docs
This commit is contained in:
Lovell Fuller
111
lib/operation.js
111
lib/operation.js
@@ -43,53 +43,6 @@ function rotate (angle) {
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract a region of the image.
|
||||
*
|
||||
* - Use `extract` before `resize` for pre-resize extraction.
|
||||
* - Use `extract` after `resize` for post-resize extraction.
|
||||
* - Use `extract` before and after for both.
|
||||
*
|
||||
* @example
|
||||
* sharp(input)
|
||||
* .extract({ left: left, top: top, width: width, height: height })
|
||||
* .toFile(output, function(err) {
|
||||
* // Extract a region of the input image, saving in the same format.
|
||||
* });
|
||||
* @example
|
||||
* sharp(input)
|
||||
* .extract({ left: leftOffsetPre, top: topOffsetPre, width: widthPre, height: heightPre })
|
||||
* .resize(width, height)
|
||||
* .extract({ left: leftOffsetPost, top: topOffsetPost, width: widthPost, height: heightPost })
|
||||
* .toFile(output, function(err) {
|
||||
* // Extract a region, resize, then extract from the resized image
|
||||
* });
|
||||
*
|
||||
* @param {Object} options
|
||||
* @param {Number} options.left - zero-indexed offset from left edge
|
||||
* @param {Number} options.top - zero-indexed offset from top edge
|
||||
* @param {Number} options.width - dimension of extracted image
|
||||
* @param {Number} options.height - dimension of extracted image
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function extract (options) {
|
||||
const suffix = this.options.width === -1 && this.options.height === -1 ? 'Pre' : 'Post';
|
||||
['left', 'top', 'width', 'height'].forEach(function (name) {
|
||||
const value = options[name];
|
||||
if (is.integer(value) && value >= 0) {
|
||||
this.options[name + (name === 'left' || name === 'top' ? 'Offset' : '') + suffix] = value;
|
||||
} else {
|
||||
throw new Error('Non-integer value for ' + name + ' of ' + value);
|
||||
}
|
||||
}, this);
|
||||
// Ensure existing rotation occurs before pre-resize extraction
|
||||
if (suffix === 'Pre' && ((this.options.angle % 360) !== 0 || this.options.useExifOrientation === true)) {
|
||||
this.options.rotateBeforePreExtract = true;
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Flip the image about the vertical Y axis. This always occurs after rotation, if any.
|
||||
* The use of `flip` implies the removal of the EXIF `Orientation` tag, if any.
|
||||
@@ -200,50 +153,6 @@ function blur (sigma) {
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extends/pads the edges of the image with the colour provided to the `background` method.
|
||||
* This operation will always occur after resizing and extraction, if any.
|
||||
*
|
||||
* @example
|
||||
* // Resize to 140 pixels wide, then add 10 transparent pixels
|
||||
* // to the top, left and right edges and 20 to the bottom edge
|
||||
* sharp(input)
|
||||
* .resize(140)
|
||||
* .background({r: 0, g: 0, b: 0, alpha: 0})
|
||||
* .extend({top: 10, bottom: 20, left: 10, right: 10})
|
||||
* ...
|
||||
*
|
||||
* @param {(Number|Object)} extend - single pixel count to add to all edges or an Object with per-edge counts
|
||||
* @param {Number} [extend.top]
|
||||
* @param {Number} [extend.left]
|
||||
* @param {Number} [extend.bottom]
|
||||
* @param {Number} [extend.right]
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function extend (extend) {
|
||||
if (is.integer(extend) && extend > 0) {
|
||||
this.options.extendTop = extend;
|
||||
this.options.extendBottom = extend;
|
||||
this.options.extendLeft = extend;
|
||||
this.options.extendRight = extend;
|
||||
} else if (
|
||||
is.object(extend) &&
|
||||
is.integer(extend.top) && extend.top >= 0 &&
|
||||
is.integer(extend.bottom) && extend.bottom >= 0 &&
|
||||
is.integer(extend.left) && extend.left >= 0 &&
|
||||
is.integer(extend.right) && extend.right >= 0
|
||||
) {
|
||||
this.options.extendTop = extend.top;
|
||||
this.options.extendBottom = extend.bottom;
|
||||
this.options.extendLeft = extend.left;
|
||||
this.options.extendRight = extend.right;
|
||||
} else {
|
||||
throw new Error('Invalid edge extension ' + extend);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge alpha transparency channel, if any, with `background`.
|
||||
* @param {Boolean} [flatten=true]
|
||||
@@ -254,23 +163,6 @@ function flatten (flatten) {
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel.
|
||||
* @param {Number} [tolerance=10] value between 1 and 99 representing the percentage similarity.
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function trim (tolerance) {
|
||||
if (!is.defined(tolerance)) {
|
||||
this.options.trimTolerance = 10;
|
||||
} else if (is.integer(tolerance) && is.inRange(tolerance, 1, 99)) {
|
||||
this.options.trimTolerance = tolerance;
|
||||
} else {
|
||||
throw new Error('Invalid trim tolerance (1 to 99) ' + tolerance);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of `1/gamma`
|
||||
* then increasing the encoding (brighten) post-resize at a factor of `gamma`.
|
||||
@@ -460,15 +352,12 @@ function linear (a, b) {
|
||||
module.exports = function (Sharp) {
|
||||
[
|
||||
rotate,
|
||||
extract,
|
||||
flip,
|
||||
flop,
|
||||
sharpen,
|
||||
median,
|
||||
blur,
|
||||
extend,
|
||||
flatten,
|
||||
trim,
|
||||
gamma,
|
||||
negate,
|
||||
normalise,
|
||||
|
||||
113
lib/resize.js
113
lib/resize.js
@@ -265,6 +265,114 @@ function withoutEnlargement (withoutEnlargement) {
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extends/pads the edges of the image with the colour provided to the `background` method.
|
||||
* This operation will always occur after resizing and extraction, if any.
|
||||
*
|
||||
* @example
|
||||
* // Resize to 140 pixels wide, then add 10 transparent pixels
|
||||
* // to the top, left and right edges and 20 to the bottom edge
|
||||
* sharp(input)
|
||||
* .resize(140)
|
||||
* .background({r: 0, g: 0, b: 0, alpha: 0})
|
||||
* .extend({top: 10, bottom: 20, left: 10, right: 10})
|
||||
* ...
|
||||
*
|
||||
* @param {(Number|Object)} extend - single pixel count to add to all edges or an Object with per-edge counts
|
||||
* @param {Number} [extend.top]
|
||||
* @param {Number} [extend.left]
|
||||
* @param {Number} [extend.bottom]
|
||||
* @param {Number} [extend.right]
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function extend (extend) {
|
||||
if (is.integer(extend) && extend > 0) {
|
||||
this.options.extendTop = extend;
|
||||
this.options.extendBottom = extend;
|
||||
this.options.extendLeft = extend;
|
||||
this.options.extendRight = extend;
|
||||
} else if (
|
||||
is.object(extend) &&
|
||||
is.integer(extend.top) && extend.top >= 0 &&
|
||||
is.integer(extend.bottom) && extend.bottom >= 0 &&
|
||||
is.integer(extend.left) && extend.left >= 0 &&
|
||||
is.integer(extend.right) && extend.right >= 0
|
||||
) {
|
||||
this.options.extendTop = extend.top;
|
||||
this.options.extendBottom = extend.bottom;
|
||||
this.options.extendLeft = extend.left;
|
||||
this.options.extendRight = extend.right;
|
||||
} else {
|
||||
throw new Error('Invalid edge extension ' + extend);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Extract a region of the image.
|
||||
*
|
||||
* - Use `extract` before `resize` for pre-resize extraction.
|
||||
* - Use `extract` after `resize` for post-resize extraction.
|
||||
* - Use `extract` before and after for both.
|
||||
*
|
||||
* @example
|
||||
* sharp(input)
|
||||
* .extract({ left: left, top: top, width: width, height: height })
|
||||
* .toFile(output, function(err) {
|
||||
* // Extract a region of the input image, saving in the same format.
|
||||
* });
|
||||
* @example
|
||||
* sharp(input)
|
||||
* .extract({ left: leftOffsetPre, top: topOffsetPre, width: widthPre, height: heightPre })
|
||||
* .resize(width, height)
|
||||
* .extract({ left: leftOffsetPost, top: topOffsetPost, width: widthPost, height: heightPost })
|
||||
* .toFile(output, function(err) {
|
||||
* // Extract a region, resize, then extract from the resized image
|
||||
* });
|
||||
*
|
||||
* @param {Object} options
|
||||
* @param {Number} options.left - zero-indexed offset from left edge
|
||||
* @param {Number} options.top - zero-indexed offset from top edge
|
||||
* @param {Number} options.width - dimension of extracted image
|
||||
* @param {Number} options.height - dimension of extracted image
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function extract (options) {
|
||||
const suffix = this.options.width === -1 && this.options.height === -1 ? 'Pre' : 'Post';
|
||||
['left', 'top', 'width', 'height'].forEach(function (name) {
|
||||
const value = options[name];
|
||||
if (is.integer(value) && value >= 0) {
|
||||
this.options[name + (name === 'left' || name === 'top' ? 'Offset' : '') + suffix] = value;
|
||||
} else {
|
||||
throw new Error('Non-integer value for ' + name + ' of ' + value);
|
||||
}
|
||||
}, this);
|
||||
// Ensure existing rotation occurs before pre-resize extraction
|
||||
if (suffix === 'Pre' && ((this.options.angle % 360) !== 0 || this.options.useExifOrientation === true)) {
|
||||
this.options.rotateBeforePreExtract = true;
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel.
|
||||
* @param {Number} [tolerance=10] value between 1 and 99 representing the percentage similarity.
|
||||
* @returns {Sharp}
|
||||
* @throws {Error} Invalid parameters
|
||||
*/
|
||||
function trim (tolerance) {
|
||||
if (!is.defined(tolerance)) {
|
||||
this.options.trimTolerance = 10;
|
||||
} else if (is.integer(tolerance) && is.inRange(tolerance, 1, 99)) {
|
||||
this.options.trimTolerance = tolerance;
|
||||
} else {
|
||||
throw new Error('Invalid trim tolerance (1 to 99) ' + tolerance);
|
||||
}
|
||||
return this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Decorate the Sharp prototype with resize-related functions.
|
||||
* @private
|
||||
@@ -277,7 +385,10 @@ module.exports = function (Sharp) {
|
||||
max,
|
||||
min,
|
||||
ignoreAspectRatio,
|
||||
withoutEnlargement
|
||||
withoutEnlargement,
|
||||
extend,
|
||||
extract,
|
||||
trim
|
||||
].forEach(function (f) {
|
||||
Sharp.prototype[f.name] = f;
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user