Improve error messages for invalid resize parameters

Dependency version bumps and doc refresh
2025-12-19 07:15:08 +01:00 · 2017-01-05 22:16:59 +00:00
parent 4858ebe051
commit 70a3d4fb5e
15 changed files with 182 additions and 76 deletions
--- a/docs/api-channel.md
+++ b/docs/api-channel.md
@@ -1,6 +1,12 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# extractChannel
+### Table of Contents
+
+-   [extractChannel](#extractchannel)
+-   [joinChannel](#joinchannel)
+-   [bandbool](#bandbool)
+
+## extractChannel

 Extract a single channel from a multi-channel image.

@@ -23,7 +29,7 @@ sharp(input)

 Returns **Sharp** 

-# joinChannel
+## joinChannel

 Join one or more channels to the image.
 The meaning of the added channels depends on the output colourspace, set with `toColourspace()`.
@@ -46,7 +52,7 @@ For raw pixel input, the `options` object should contain a `raw` attribute, whic

 Returns **Sharp** 

-# bandbool
+## bandbool

 Perform a bitwise boolean operation on all input image channels (bands) to produce a single channel output image.

--- a/docs/api-colour.md
+++ b/docs/api-colour.md
@@ -1,6 +1,14 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# background
+### Table of Contents
+
+-   [background](#background)
+-   [greyscale](#greyscale)
+-   [grayscale](#grayscale)
+-   [toColourspace](#tocolourspace)
+-   [toColorspace](#tocolorspace)
+
+## background

 Set the background for the `embed`, `flatten` and `extend` operations.
 The default background is `{r: 0, g: 0, b: 0, alpha: 1}`, black without transparency.
@@ -18,7 +26,7 @@ The alpha value is a float between `0` (transparent) and `1` (opaque).

 Returns **Sharp** 

-# greyscale
+## greyscale

 Convert to 8-bit greyscale; 256 shades of grey.
 This is a linear operation. If the input image is in a non-linear colour space such as sRGB, use `gamma()` with `greyscale()` for the best results.
@@ -33,7 +41,7 @@ An alpha channel may be present, and will be unchanged by the operation.

 Returns **Sharp** 

-# grayscale
+## grayscale

 Alternative spelling of `greyscale`.

@@ -43,7 +51,7 @@ Alternative spelling of `greyscale`.

 Returns **Sharp** 

-# toColourspace
+## toColourspace

 Set the output colourspace.
 By default output image will be web-friendly sRGB, with additional channels interpreted as alpha channels.
@@ -57,7 +65,7 @@ By default output image will be web-friendly sRGB, with additional channels inte

 Returns **Sharp** 

-# toColorspace
+## toColorspace

 Alternative spelling of `toColourspace`.

--- a/docs/api-composite.md
+++ b/docs/api-composite.md
@@ -1,6 +1,10 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# overlayWith
+### Table of Contents
+
+-   [overlayWith](#overlaywith)
+
+## overlayWith

 Overlay (composite) an image over the processed (resized, extracted etc.) image.

--- a/docs/api-constructor.md
+++ b/docs/api-constructor.md
@@ -1,6 +1,13 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# Sharp
+### Table of Contents
+
+-   [Sharp](#sharp)
+    -   [format](#format)
+    -   [versions](#versions)
+-   [queue](#queue)
+
+## Sharp

 **Parameters**

@@ -43,7 +50,7 @@ readableStream.pipe(transformer).pipe(writableStream);

 Returns **[Sharp](#sharp)** 

-## format
+### format

 An Object containing nested boolean values representing the available input and output formats/methods.

@@ -55,7 +62,7 @@ console.log(sharp.format());

 Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

-## versions
+### versions

 An Object containing the version numbers of libvips and its dependencies.

@@ -65,7 +72,7 @@ An Object containing the version numbers of libvips and its dependencies.
 console.log(sharp.versions);
 ```

-# queue
+## queue

 An EventEmitter that emits a `change` event when a task is either:

--- a/docs/api-input.md
+++ b/docs/api-input.md
@@ -1,6 +1,13 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# clone
+### Table of Contents
+
+-   [clone](#clone)
+-   [metadata](#metadata)
+-   [limitInputPixels](#limitinputpixels)
+-   [sequentialRead](#sequentialread)
+
+## clone

 Take a "snapshot" of the Sharp instance, returning a new instance.
 Cloned instances inherit the input of their parent instance.
@@ -19,7 +26,7 @@ readableStream.pipe(pipeline);

 Returns **Sharp** 

-# metadata
+## metadata

 Fast access to image metadata without decoding any compressed image data.
 A Promises/A+ promise is returned when `callback` is not provided.
@@ -59,7 +66,7 @@ image

 Returns **([Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)> | Sharp)** 

-# limitInputPixels
+## limitInputPixels

 Do not process input images where the number of pixels (width _ height) exceeds this limit.
 Assumes image dimensions contained in the input metadata can be trusted.
@@ -74,7 +81,7 @@ The default limit is 268402689 (0x3FFF _ 0x3FFF) pixels.

 Returns **Sharp** 

-# sequentialRead
+## sequentialRead

 An advanced setting that switches the libvips access method to `VIPS_ACCESS_SEQUENTIAL`.
 This will reduce memory usage and can improve performance on some systems.
--- a/docs/api-operation.md
+++ b/docs/api-operation.md
@@ -1,6 +1,25 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# rotate
+### Table of Contents
+
+-   [rotate](#rotate)
+-   [extract](#extract)
+-   [flip](#flip)
+-   [flop](#flop)
+-   [sharpen](#sharpen)
+-   [blur](#blur)
+-   [extend](#extend)
+-   [flatten](#flatten)
+-   [trim](#trim)
+-   [gamma](#gamma)
+-   [negate](#negate)
+-   [normalise](#normalise)
+-   [normalize](#normalize)
+-   [convolve](#convolve)
+-   [threshold](#threshold)
+-   [boolean](#boolean)
+
+## rotate

 Rotate the output image by either an explicit angle
 or auto-orient based on the EXIF `Orientation` tag.
@@ -35,7 +54,7 @@ readableStream.pipe(pipeline);

 Returns **Sharp** 

-# extract
+## extract

 Extract a region of the image.

@@ -75,7 +94,7 @@ sharp(input)

 Returns **Sharp** 

-# flip
+## flip

 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.
@@ -86,7 +105,7 @@ The use of `flip` implies the removal of the EXIF `Orientation` tag, if any.

 Returns **Sharp** 

-# flop
+## flop

 Flop the image about the horizontal X axis. This always occurs after rotation, if any.
 The use of `flop` implies the removal of the EXIF `Orientation` tag, if any.
@@ -97,7 +116,7 @@ The use of `flop` implies the removal of the EXIF `Orientation` tag, if any.

 Returns **Sharp** 

-# sharpen
+## sharpen

 Sharpen the image.
 When used without parameters, performs a fast, mild sharpen of the output image.
@@ -115,7 +134,7 @@ Separate control over the level of sharpening in "flat" and "jagged" areas is av

 Returns **Sharp** 

-# blur
+## blur

 Blur the image.
 When used without parameters, performs a fast, mild blur of the output image.
@@ -130,7 +149,7 @@ When a `sigma` is provided, performs a slower, more accurate Gaussian blur.

 Returns **Sharp** 

-# extend
+## extend

 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.
@@ -159,7 +178,7 @@ sharp(input)

 Returns **Sharp** 

-# flatten
+## flatten

 Merge alpha transparency channel, if any, with `background`.

@@ -169,7 +188,7 @@ Merge alpha transparency channel, if any, with `background`.

 Returns **Sharp** 

-# trim
+## trim

 Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel.

@@ -182,7 +201,7 @@ Trim "boring" pixels from all edges that contain values within a percentage simi

 Returns **Sharp** 

-# gamma
+## gamma

 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`.
@@ -199,7 +218,7 @@ when applying a gamma correction.

 Returns **Sharp** 

-# negate
+## negate

 Produce the "negative" of the image.

@@ -209,7 +228,7 @@ Produce the "negative" of the image.

 Returns **Sharp** 

-# normalise
+## normalise

 Enhance output image contrast by stretching its luminance to cover the full dynamic range.

@@ -219,7 +238,7 @@ Enhance output image contrast by stretching its luminance to cover the full dyna

 Returns **Sharp** 

-# normalize
+## normalize

 Alternative spelling of normalise.

@@ -229,7 +248,7 @@ Alternative spelling of normalise.

 Returns **Sharp** 

-# convolve
+## convolve

 Convolve the image with the specified kernel.

@@ -262,7 +281,7 @@ sharp(input)

 Returns **Sharp** 

-# threshold
+## threshold

 Any pixel value greather than or equal to the threshold value will be set to 255, otherwise it will be set to 0.

@@ -278,7 +297,7 @@ Any pixel value greather than or equal to the threshold value will be set to 255

 Returns **Sharp** 

-# boolean
+## boolean

 Perform a bitwise boolean operation with operand image.

--- a/docs/api-output.md
+++ b/docs/api-output.md
@@ -1,6 +1,19 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# toFile
+### Table of Contents
+
+-   [toFile](#tofile)
+-   [toBuffer](#tobuffer)
+-   [withMetadata](#withmetadata)
+-   [jpeg](#jpeg)
+-   [png](#png)
+-   [webp](#webp)
+-   [tiff](#tiff)
+-   [raw](#raw)
+-   [toFormat](#toformat)
+-   [tile](#tile)
+
+## toFile

 Write output image data to a file.

@@ -21,7 +34,7 @@ A Promises/A+ promise is returned when `callback` is not provided.

 Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)>** when no callback is provided

-# toBuffer
+## toBuffer

 Write output to a Buffer.
 JPEG, PNG, WebP, and RAW output are supported.
@@ -40,7 +53,7 @@ By default, the format will match the input image, except GIF and SVG input whic

 Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;[Buffer](https://nodejs.org/api/buffer.html)>** when no callback is provided

-# withMetadata
+## withMetadata

 Include all metadata (EXIF, XMP, IPTC) from the input image in the output image.
 The default behaviour, when `withMetadata` is not used, is to strip all metadata and convert to the device-independent sRGB colour space.
@@ -56,7 +69,7 @@ This will also convert to and add a web-friendly sRGB ICC profile.

 Returns **Sharp** 

-# jpeg
+## jpeg

 Use these JPEG options for output image.

@@ -77,7 +90,7 @@ Use these JPEG options for output image.

 Returns **Sharp** 

-# png
+## png

 Use these PNG options for output image.

@@ -94,7 +107,7 @@ Use these PNG options for output image.

 Returns **Sharp** 

-# webp
+## webp

 Use these WebP options for output image.

@@ -109,7 +122,7 @@ Use these WebP options for output image.

 Returns **Sharp** 

-# tiff
+## tiff

 Use these TIFF options for output image.

@@ -124,13 +137,13 @@ Use these TIFF options for output image.

 Returns **Sharp** 

-# raw
+## raw

 Force output to be raw, uncompressed uint8 pixel data.

 Returns **Sharp** 

-# toFormat
+## toFormat

 Force output to a given format.

@@ -144,7 +157,7 @@ Force output to a given format.

 Returns **Sharp** 

-# tile
+## tile

 Use tile-based deep zoom (image pyramid) output.
 Set the format and options for tile images via the `toFormat`, `jpeg`, `png` or `webp` functions.
--- a/docs/api-resize.md
+++ b/docs/api-resize.md
@@ -1,6 +1,16 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# resize
+### Table of Contents
+
+-   [resize](#resize)
+-   [crop](#crop)
+-   [embed](#embed)
+-   [max](#max)
+-   [min](#min)
+-   [ignoreAspectRatio](#ignoreaspectratio)
+-   [withoutEnlargement](#withoutenlargement)
+
+## resize

 Resize image to `width` x `height`.
 By default, the resized image is centre cropped to the exact size specified.
@@ -52,7 +62,7 @@ sharp(inputBuffer)

 Returns **Sharp** 

-# crop
+## crop

 Crop the resized image to the exact size specified, the default behaviour.

@@ -87,7 +97,7 @@ readableStream.pipe(transformer).pipe(writableStream);

 Returns **Sharp** 

-# embed
+## embed

 Preserving aspect ratio, resize the image to the maximum `width` or `height` specified
 then embed on a background of the exact `width` and `height` specified.
@@ -114,7 +124,7 @@ sharp('input.gif')

 Returns **Sharp** 

-# max
+## max

 Preserving aspect ratio, resize the image to be as large as possible
 while ensuring its dimensions are less than or equal to the `width` and `height` specified.
@@ -137,7 +147,7 @@ sharp(inputBuffer)

 Returns **Sharp** 

-# min
+## min

 Preserving aspect ratio, resize the image to be as small as possible
 while ensuring its dimensions are greater than or equal to the `width` and `height` specified.
@@ -146,14 +156,14 @@ Both `width` and `height` must be provided via `resize` otherwise the behaviour

 Returns **Sharp** 

-# ignoreAspectRatio
+## ignoreAspectRatio

 Ignoring the aspect ratio of the input, stretch the image to
 the exact `width` and/or `height` provided via `resize`.

 Returns **Sharp** 

-# withoutEnlargement
+## withoutEnlargement

 Do not enlarge the output image if the input image width _or_ height are already less than the required dimensions.
 This is equivalent to GraphicsMagick's `>` geometry option:
--- a/docs/api-utility.md
+++ b/docs/api-utility.md
@@ -1,6 +1,13 @@
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

-# cache
+### Table of Contents
+
+-   [cache](#cache)
+-   [concurrency](#concurrency)
+-   [counters](#counters)
+-   [simd](#simd)
+
+## cache

 Gets, or when options are provided sets, the limits of _libvips'_ operation cache.
 Existing entries in the cache will be trimmed after any change in limits.
@@ -28,7 +35,7 @@ sharp.cache(false);

 Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

-# concurrency
+## concurrency

 Gets, or when a concurrency is provided sets,
 the number of threads _libvips'_ should create to process each image.
@@ -54,7 +61,7 @@ sharp.concurrency(0); // 4

 Returns **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** concurrency

-# counters
+## counters

 Provides access to internal task counters.

@@ -69,7 +76,7 @@ const counters = sharp.counters(); // { queue: 2, process: 4 }

 Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

-# simd
+## simd

 Get and set use of SIMD vector unit instructions.
 Requires libvips to have been compiled with liborc support.
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -4,6 +4,15 @@

 Requires libvips v8.4.2.

+#### v0.17.1 - TBD
+
+* Improve error messages for invalid parameters.
+  [@spikeon](https://github.com/spikeon)
+  [#644](https://github.com/lovell/sharp/pull/644)
+
+* Simplify expression for finding vips-cpp libdir.
+  [#656](https://github.com/lovell/sharp/pull/656)
+
 #### v0.17.0 - 11<sup>th</sup> December 2016

 * Drop support for versions of Node prior to v4.