diff --git a/docs/api-constructor.md b/docs/api-constructor.md index 5bb9ea28..21ff2abf 100644 --- a/docs/api-constructor.md +++ b/docs/api-constructor.md @@ -4,30 +4,31 @@ ### Parameters -- `input` **([Buffer][1] \| [String][2])?** if present, can be +- `input` **([Buffer][1] \| [string][2])?** if present, can be a Buffer containing JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data, or a String containing the filesystem path to an JPEG, PNG, WebP, GIF, SVG or TIFF image file. JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data can be streamed into the object when not present. - `options` **[Object][3]?** if present, is an Object with optional attributes. - - `options.failOnError` **[Boolean][4]** by default halt processing and raise an error when loading invalid images. + - `options.failOnError` **[boolean][4]** by default halt processing and raise an error when loading invalid images. Set this flag to `false` if you'd rather apply a "best effort" to decode images, even if the data is corrupt or invalid. (optional, default `true`) - - `options.limitInputPixels` **([Number][5] \| [Boolean][4])** Do not process input images where the number of pixels + - `options.limitInputPixels` **([number][5] \| [boolean][4])** Do not process input images where the number of pixels (width x height) exceeds this limit. Assumes image dimensions contained in the input metadata can be trusted. An integral Number of pixels, zero or false to remove limit, true to use default limit of 268402689 (0x3FFF x 0x3FFF). (optional, default `268402689`) - - `options.sequentialRead` **[Boolean][4]** Set this to `true` to use sequential rather than random access where possible. + - `options.sequentialRead` **[boolean][4]** Set this to `true` to use sequential rather than random access where possible. This can reduce memory usage and might improve performance on some systems. (optional, default `false`) - - `options.density` **[Number][5]** number representing the DPI for vector images. (optional, default `72`) - - `options.pages` **[Number][5]** number of pages to extract for multi-page input (GIF, TIFF, PDF), use -1 for all pages. (optional, default `1`) - - `options.page` **[Number][5]** page number to start extracting from for multi-page input (GIF, TIFF, PDF), zero based. (optional, default `0`) + - `options.density` **[number][5]** number representing the DPI for vector images. (optional, default `72`) + - `options.pages` **[number][5]** number of pages to extract for multi-page input (GIF, TIFF, PDF), use -1 for all pages. (optional, default `1`) + - `options.page` **[number][5]** page number to start extracting from for multi-page input (GIF, TIFF, PDF), zero based. (optional, default `0`) + - `options.level` **[number][5]** level to extract from a multi-level input (OpenSlide), zero based. (optional, default `0`) - `options.raw` **[Object][3]?** describes raw pixel input image data. See `raw()` for pixel ordering. - - `options.raw.width` **[Number][5]?** - - `options.raw.height` **[Number][5]?** - - `options.raw.channels` **[Number][5]?** 1-4 + - `options.raw.width` **[number][5]?** + - `options.raw.height` **[number][5]?** + - `options.raw.channels` **[number][5]?** 1-4 - `options.create` **[Object][3]?** describes a new image to be created. - - `options.create.width` **[Number][5]?** - - `options.create.height` **[Number][5]?** - - `options.create.channels` **[Number][5]?** 3-4 - - `options.create.background` **([String][2] \| [Object][3])?** parsed by the [color][6] module to extract values for red, green, blue and alpha. + - `options.create.width` **[number][5]?** + - `options.create.height` **[number][5]?** + - `options.create.channels` **[number][5]?** 3-4 + - `options.create.background` **([string][2] \| [Object][3])?** parsed by the [color][6] module to extract values for red, green, blue and alpha. ### Examples diff --git a/docs/changelog.md b/docs/changelog.md index 27cf1b0b..0144af23 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -14,7 +14,8 @@ Requires libvips v8.9.1 [#2226](https://github.com/lovell/sharp/pull/2226) [@romaleev](https://github.com/romaleev) -* Expose `levels` metadata for multi-level images. +* Add `level` constructor option to use a specific level of a multi-level image. + Expose `levels` metadata for multi-level images. [#2222](https://github.com/lovell/sharp/issues/2222) ### v0.25.3 - 17th May 2020 diff --git a/lib/constructor.js b/lib/constructor.js index 0acf8243..3ec946c6 100644 --- a/lib/constructor.js +++ b/lib/constructor.js @@ -81,30 +81,31 @@ const debuglog = util.debuglog('sharp'); * .toBuffer() * .then( ... ); * - * @param {(Buffer|String)} [input] - if present, can be + * @param {(Buffer|string)} [input] - if present, can be * a Buffer containing JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data, or * a String containing the filesystem path to an JPEG, PNG, WebP, GIF, SVG or TIFF image file. * JPEG, PNG, WebP, GIF, SVG, TIFF or raw pixel image data can be streamed into the object when not present. * @param {Object} [options] - if present, is an Object with optional attributes. - * @param {Boolean} [options.failOnError=true] - by default halt processing and raise an error when loading invalid images. + * @param {boolean} [options.failOnError=true] - by default halt processing and raise an error when loading invalid images. * Set this flag to `false` if you'd rather apply a "best effort" to decode images, even if the data is corrupt or invalid. - * @param {Number|Boolean} [options.limitInputPixels=268402689] - Do not process input images where the number of pixels + * @param {number|boolean} [options.limitInputPixels=268402689] - Do not process input images where the number of pixels * (width x height) exceeds this limit. Assumes image dimensions contained in the input metadata can be trusted. * An integral Number of pixels, zero or false to remove limit, true to use default limit of 268402689 (0x3FFF x 0x3FFF). - * @param {Boolean} [options.sequentialRead=false] - Set this to `true` to use sequential rather than random access where possible. + * @param {boolean} [options.sequentialRead=false] - Set this to `true` to use sequential rather than random access where possible. * This can reduce memory usage and might improve performance on some systems. - * @param {Number} [options.density=72] - number representing the DPI for vector images. - * @param {Number} [options.pages=1] - number of pages to extract for multi-page input (GIF, TIFF, PDF), use -1 for all pages. - * @param {Number} [options.page=0] - page number to start extracting from for multi-page input (GIF, TIFF, PDF), zero based. + * @param {number} [options.density=72] - number representing the DPI for vector images. + * @param {number} [options.pages=1] - number of pages to extract for multi-page input (GIF, TIFF, PDF), use -1 for all pages. + * @param {number} [options.page=0] - page number to start extracting from for multi-page input (GIF, TIFF, PDF), zero based. + * @param {number} [options.level=0] - level to extract from a multi-level input (OpenSlide), zero based. * @param {Object} [options.raw] - describes raw pixel input image data. See `raw()` for pixel ordering. - * @param {Number} [options.raw.width] - * @param {Number} [options.raw.height] - * @param {Number} [options.raw.channels] - 1-4 + * @param {number} [options.raw.width] + * @param {number} [options.raw.height] + * @param {number} [options.raw.channels] - 1-4 * @param {Object} [options.create] - describes a new image to be created. - * @param {Number} [options.create.width] - * @param {Number} [options.create.height] - * @param {Number} [options.create.channels] - 3-4 - * @param {String|Object} [options.create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. + * @param {number} [options.create.width] + * @param {number} [options.create.height] + * @param {number} [options.create.channels] - 3-4 + * @param {string|Object} [options.create.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. * @returns {Sharp} * @throws {Error} Invalid parameters */ diff --git a/lib/input.js b/lib/input.js index 0abf64c3..cbad9e1a 100644 --- a/lib/input.js +++ b/lib/input.js @@ -113,6 +113,14 @@ function _createInputDescriptor (input, inputOptions, containerOptions) { throw is.invalidParameterError('page', 'integer between 0 and 100000', inputOptions.page); } } + // Multi-level input (OpenSlide) + if (is.defined(inputOptions.level)) { + if (is.integer(inputOptions.level) && is.inRange(inputOptions.level, 0, 256)) { + inputDescriptor.level = inputOptions.level; + } else { + throw is.invalidParameterError('level', 'integer between 0 and 256', inputOptions.level); + } + } // Create new image if (is.defined(inputOptions.create)) { if ( diff --git a/src/common.cc b/src/common.cc index e3f7f6d6..5f015c1a 100644 --- a/src/common.cc +++ b/src/common.cc @@ -88,6 +88,10 @@ namespace sharp { if (HasAttr(input, "page")) { descriptor->page = AttrAsUint32(input, "page"); } + // Multi-level input (OpenSlide) + if (HasAttr(input, "level")) { + descriptor->level = AttrAsUint32(input, "level"); + } // Create new image if (HasAttr(input, "createChannels")) { descriptor->createChannels = AttrAsUint32(input, "createChannels"); @@ -292,6 +296,9 @@ namespace sharp { option->set("n", descriptor->pages); option->set("page", descriptor->page); } + if (imageType == ImageType::OPENSLIDE) { + option->set("level", descriptor->level); + } image = VImage::new_from_buffer(descriptor->buffer, descriptor->bufferLength, nullptr, option); if (imageType == ImageType::SVG || imageType == ImageType::PDF || imageType == ImageType::MAGICK) { image = SetDensity(image, descriptor->density); @@ -341,6 +348,9 @@ namespace sharp { option->set("n", descriptor->pages); option->set("page", descriptor->page); } + if (imageType == ImageType::OPENSLIDE) { + option->set("level", descriptor->level); + } image = VImage::new_from_file(descriptor->file.data(), option); if (imageType == ImageType::SVG || imageType == ImageType::PDF || imageType == ImageType::MAGICK) { image = SetDensity(image, descriptor->density); diff --git a/src/common.h b/src/common.h index 9cb3a469..2d3ca0c9 100644 --- a/src/common.h +++ b/src/common.h @@ -57,6 +57,7 @@ namespace sharp { int rawHeight; int pages; int page; + int level; int createChannels; int createWidth; int createHeight; @@ -75,6 +76,7 @@ namespace sharp { rawHeight(0), pages(1), page(0), + level(0), createChannels(0), createWidth(0), createHeight(0), diff --git a/test/unit/io.js b/test/unit/io.js index 305f11c3..c5495be7 100644 --- a/test/unit/io.js +++ b/test/unit/io.js @@ -659,6 +659,19 @@ describe('Input/output', function () { sharp({ pages: '1' }); }, /Expected integer between -1 and 100000 for pages but received 1 of type string/); }); + it('Valid level property', function () { + sharp({ level: 1 }); + }); + it('Invalid level property (string) throws', function () { + assert.throws(function () { + sharp({ level: '1' }); + }, /Expected integer between 0 and 256 for level but received 1 of type string/); + }); + it('Invalid level property (negative) throws', function () { + assert.throws(function () { + sharp({ level: -1 }); + }, /Expected integer between 0 and 256 for level but received -1 of type number/); + }); }); describe('create new image', function () {