Skip to content

Commit f92540f

Browse files
lovelllovell
committed
Nest format-specific constructor params (deprecate at top-level)
- `subifd` -> `tiff.subifd` - `level` -> `openSlide.level` - `pdfBackground` -> `pdf.background`
1 parent 8c53d49 commit f92540f

File tree

8 files changed

+169
-75
lines changed

8 files changed

+169
-75
lines changed

‎docs/src/content/docs/api-constructor.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,6 @@ where the overall height is the `pageHeight` multiplied by the number of `pages`
4444
| [options.ignoreIcc] | <code>number</code> | <code>false</code> | should the embedded ICC profile, if any, be ignored. |
4545
| [options.pages] | <code>number</code> | <code>1</code> | Number of pages to extract for multi-page input (GIF, WebP, TIFF), use -1 for all pages. |
4646
| [options.page] | <code>number</code> | <code>0</code> | Page number to start extracting from for multi-page input (GIF, WebP, TIFF), zero based. |
47-
| [options.subifd] | <code>number</code> | <code>-1</code> | subIFD (Sub Image File Directory) to extract for OME-TIFF, defaults to main image. |
48-
| [options.level] | <code>number</code> | <code>0</code> | level to extract from a multi-level input (OpenSlide), zero based. |
49-
| [options.pdfBackground] | <code>string</code> \| <code>Object</code> | | Background colour to use when PDF is partially transparent. Parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick. |
50-
| [options.jp2Oneshot] | <code>boolean</code> | <code>false</code> | Set to `true` to decode tiled JPEG 2000 images in a single operation, improving compatibility. |
5147
| [options.animated] | <code>boolean</code> | <code>false</code> | Set to `true` to read all frames/pages of an animated image (GIF, WebP, TIFF), equivalent of setting `pages` to `-1`. |
5248
| [options.raw] | <code>Object</code> | | describes raw pixel input image data. See `raw()` for pixel ordering. |
5349
| [options.raw.width] | <code>number</code> | | integral number of pixels wide. |
@@ -82,6 +78,14 @@ where the overall height is the `pageHeight` multiplied by the number of `pages`
8278
| [options.join.background] | <code>string</code> \| <code>Object</code> | | parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. |
8379
| [options.join.halign] | <code>string</code> | <code>&quot;&#x27;left&#x27;&quot;</code> | horizontal alignment style for images joined horizontally (`'left'`, `'centre'`, `'center'`, `'right'`). |
8480
| [options.join.valign] | <code>string</code> | <code>&quot;&#x27;top&#x27;&quot;</code> | vertical alignment style for images joined vertically (`'top'`, `'centre'`, `'center'`, `'bottom'`). |
81+
| [options.tiff] | <code>Object</code> | | Describes TIFF specific options. |
82+
| [options.tiff.subifd] | <code>number</code> | <code>-1</code> | Sub Image File Directory to extract for OME-TIFF, defaults to main image. |
83+
| [options.pdf] | <code>Object</code> | | Describes PDF specific options. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick. |
84+
| [options.pdf.background] | <code>string</code> \| <code>Object</code> | | Background colour to use when PDF is partially transparent. Parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. |
85+
| [options.openSlide] | <code>Object</code> | | Describes OpenSlide specific options. Requires the use of a globally-installed libvips compiled with support for OpenSlide. |
86+
| [options.openSlide.level] | <code>number</code> | <code>0</code> | Level to extract from a multi-level input, zero based. |
87+
| [options.jp2] | <code>Object</code> | | Describes JPEG 2000 specific options. Requires the use of a globally-installed libvips compiled with support for OpenJPEG. |
88+
| [options.jp2.oneshot] | <code>boolean</code> | <code>false</code> | Set to `true` to decode tiled JPEG 2000 images in a single operation, improving compatibility. |
8589

8690
**Example**
8791
```js

‎docs/src/content/docs/changelog.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Requires libvips v8.17.0
1212

1313
* Add "Magic Kernel Sharp" (no relation) to resizing kernels.
1414

15+
* Deprecate top-level, format-specific constructor parameters, e.g. `subifd` becomes `tiff.subifd`.
16+
1517
* Expose `keepDuplicateFrames` GIF output parameter.
1618

1719
* Expose JPEG 2000 `oneshot` decoder option.

‎lib/constructor.js

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -153,10 +153,6 @@ const debuglog = util.debuglog('sharp');
153153
* @param {number} [options.ignoreIcc=false] - should the embedded ICC profile, if any, be ignored.
154154
* @param {number} [options.pages=1] - Number of pages to extract for multi-page input (GIF, WebP, TIFF), use -1 for all pages.
155155
* @param {number} [options.page=0] - Page number to start extracting from for multi-page input (GIF, WebP, TIFF), zero based.
156-
* @param {number} [options.subifd=-1] - subIFD (Sub Image File Directory) to extract for OME-TIFF, defaults to main image.
157-
* @param {number} [options.level=0] - level to extract from a multi-level input (OpenSlide), zero based.
158-
* @param {string|Object} [options.pdfBackground] - Background colour to use when PDF is partially transparent. Parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick.
159-
* @param {boolean} [options.jp2Oneshot=false] - Set to `true` to decode tiled JPEG 2000 images in a single operation, improving compatibility.
160156
* @param {boolean} [options.animated=false] - Set to `true` to read all frames/pages of an animated image (GIF, WebP, TIFF), equivalent of setting `pages` to `-1`.
161157
* @param {Object} [options.raw] - describes raw pixel input image data. See `raw()` for pixel ordering.
162158
* @param {number} [options.raw.width] - integral number of pixels wide.
@@ -192,7 +188,14 @@ const debuglog = util.debuglog('sharp');
192188
* @param {string|Object} [options.join.background] - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
193189
* @param {string} [options.join.halign='left'] - horizontal alignment style for images joined horizontally (`'left'`, `'centre'`, `'center'`, `'right'`).
194190
* @param {string} [options.join.valign='top'] - vertical alignment style for images joined vertically (`'top'`, `'centre'`, `'center'`, `'bottom'`).
195-
*
191+
* @param {Object} [options.tiff] - Describes TIFF specific options.
192+
* @param {number} [options.tiff.subifd=-1] - Sub Image File Directory to extract for OME-TIFF, defaults to main image.
193+
* @param {Object} [options.pdf] - Describes PDF specific options. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick.
194+
* @param {string|Object} [options.pdf.background] - Background colour to use when PDF is partially transparent. Parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
195+
* @param {Object} [options.openSlide] - Describes OpenSlide specific options. Requires the use of a globally-installed libvips compiled with support for OpenSlide.
196+
* @param {number} [options.openSlide.level=0] - Level to extract from a multi-level input, zero based.
197+
* @param {Object} [options.jp2] - Describes JPEG 2000 specific options. Requires the use of a globally-installed libvips compiled with support for OpenJPEG.
198+
* @param {boolean} [options.jp2.oneshot=false] - Set to `true` to decode tiled JPEG 2000 images in a single operation, improving compatibility.
196199
* @returns {Sharp}
197200
* @throws {Error} Invalid parameters
198201
*/

‎lib/index.d.ts

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1003,14 +1003,20 @@ declare namespace sharp {
10031003
pages?: number | undefined;
10041004
/** Page number to start extracting from for multi-page input (GIF, TIFF, PDF), zero based. (optional, default 0) */
10051005
page?: number | undefined;
1006-
/** subIFD (Sub Image File Directory) to extract for OME-TIFF, defaults to main image. (optional, default -1) */
1006+
/** TIFF specific input options */
1007+
tiff?: TiffInputOptions | undefined;
1008+
/** PDF specific input options */
1009+
pdf?: PdfInputOptions | undefined;
1010+
/** OpenSlide specific input options */
1011+
openSlide?: OpenSlideInputOptions | undefined;
1012+
/** JPEG 2000 specific input options */
1013+
jp2?: Jp2InputOptions | undefined;
1014+
/** Deprecated: use tiff.subifd instead */
10071015
subifd?: number | undefined;
1008-
/** Level to extract from a multi-level input (OpenSlide), zero based. (optional, default 0) */
1009-
level?: number | undefined;
1010-
/** Background colour to use when PDF is partially transparent. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick. */
1016+
/** Deprecated: use pdf.background instead */
10111017
pdfBackground?: Colour | Color | undefined;
1012-
/** Set to `true` to load JPEG 2000 images using [oneshot mode](https://github.com/libvips/libvips/issues/4205) */
1013-
jp2Oneshot?: boolean | undefined;
1018+
/** Deprecated: use openSlide.level instead */
1019+
level?: number | undefined;
10141020
/** Set to `true` to read all frames/pages of an animated image (equivalent of setting `pages` to `-1`). (optional, default false) */
10151021
animated?: boolean | undefined;
10161022
/** Describes raw pixel input image data. See raw() for pixel ordering. */
@@ -1116,6 +1122,26 @@ declare namespace sharp {
11161122
valign?: VerticalAlignment | undefined;
11171123
}
11181124

1125+
interface TiffInputOptions {
1126+
/** Sub Image File Directory to extract, defaults to main image. Use -1 for all subifds. */
1127+
subifd?: number | undefined;
1128+
}
1129+
1130+
interface PdfInputOptions {
1131+
/** Background colour to use when PDF is partially transparent. Requires the use of a globally-installed libvips compiled with support for PDFium, Poppler, ImageMagick or GraphicsMagick. */
1132+
background?: Colour | Color | undefined;
1133+
}
1134+
1135+
interface OpenSlideInputOptions {
1136+
/** Level to extract from a multi-level input, zero based. (optional, default 0) */
1137+
level?: number | undefined;
1138+
}
1139+
1140+
interface Jp2InputOptions {
1141+
/** Set to `true` to load JPEG 2000 images using [oneshot mode](https://github.com/libvips/libvips/issues/4205) */
1142+
oneshot?: boolean | undefined;
1143+
}
1144+
11191145
interface ExifDir {
11201146
[k: string]: string;
11211147
}

‎lib/input.js

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -230,32 +230,49 @@ function _createInputDescriptor (input, inputOptions, containerOptions) {
230230
throw is.invalidParameterError('page', 'integer between 0 and 100000', inputOptions.page);
231231
}
232232
}
233-
// Multi-level input (OpenSlide)
234-
if (is.defined(inputOptions.level)) {
233+
// OpenSlide specific options
234+
if (is.object(inputOptions.openSlide) && is.defined(inputOptions.openSlide.level)) {
235+
if (is.integer(inputOptions.openSlide.level) && is.inRange(inputOptions.openSlide.level, 0, 256)) {
236+
inputDescriptor.level = inputOptions.openSlide.level;
237+
} else {
238+
throw is.invalidParameterError('openSlide.level', 'integer between 0 and 256', inputOptions.openSlide.level);
239+
}
240+
} else if (is.defined(inputOptions.level)) {
241+
// Deprecated
235242
if (is.integer(inputOptions.level) && is.inRange(inputOptions.level, 0, 256)) {
236243
inputDescriptor.level = inputOptions.level;
237244
} else {
238245
throw is.invalidParameterError('level', 'integer between 0 and 256', inputOptions.level);
239246
}
240247
}
241-
// Sub Image File Directory (TIFF)
242-
if (is.defined(inputOptions.subifd)) {
248+
// TIFF specific options
249+
if (is.object(inputOptions.tiff) && is.defined(inputOptions.tiff.subifd)) {
250+
if (is.integer(inputOptions.tiff.subifd) && is.inRange(inputOptions.tiff.subifd, -1, 100000)) {
251+
inputDescriptor.subifd = inputOptions.tiff.subifd;
252+
} else {
253+
throw is.invalidParameterError('tiff.subifd', 'integer between -1 and 100000', inputOptions.tiff.subifd);
254+
}
255+
} else if (is.defined(inputOptions.subifd)) {
256+
// Deprecated
243257
if (is.integer(inputOptions.subifd) && is.inRange(inputOptions.subifd, -1, 100000)) {
244258
inputDescriptor.subifd = inputOptions.subifd;
245259
} else {
246260
throw is.invalidParameterError('subifd', 'integer between -1 and 100000', inputOptions.subifd);
247261
}
248262
}
249-
// PDF background colour
250-
if (is.defined(inputOptions.pdfBackground)) {
263+
// PDF specific options
264+
if (is.object(inputOptions.pdf) && is.defined(inputOptions.pdf.background)) {
265+
inputDescriptor.pdfBackground = this._getBackgroundColourOption(inputOptions.pdf.background);
266+
} else if (is.defined(inputOptions.pdfBackground)) {
267+
// Deprecated
251268
inputDescriptor.pdfBackground = this._getBackgroundColourOption(inputOptions.pdfBackground);
252269
}
253-
// JP2 oneshot
254-
if (is.defined(inputOptions.jp2Oneshot)) {
255-
if (is.bool(inputOptions.jp2Oneshot)) {
256-
inputDescriptor.jp2Oneshot = inputOptions.jp2Oneshot;
270+
// JPEG 2000 specific options
271+
if (is.object(inputOptions.jp2) && is.defined(inputOptions.jp2.oneshot)) {
272+
if (is.bool(inputOptions.jp2.oneshot)) {
273+
inputDescriptor.jp2Oneshot = inputOptions.jp2.oneshot;
257274
} else {
258-
throw is.invalidParameterError('jp2Oneshot', 'boolean', inputOptions.jp2Oneshot);
275+
throw is.invalidParameterError('jp2.oneshot', 'boolean', inputOptions.jp2.oneshot);
259276
}
260277
}
261278
// Create new image

‎test/types/sharp.test-d.ts

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -435,9 +435,6 @@ sharp('input.jpg').clahe({ width: 10, height: 10, maxSlope: 5 }).toFile('outfile
435435
// Support `unlimited` input option
436436
sharp('input.png', { unlimited: true }).resize(320, 240).toFile('outfile.png');
437437

438-
// Support `subifd` input option for tiffs
439-
sharp('input.tiff', { subifd: 3 }).resize(320, 240).toFile('outfile.png');
440-
441438
// Support creating with noise
442439
sharp({
443440
create: {
@@ -720,13 +717,19 @@ sharp(input).composite([
720717
}
721718
])
722719

720+
// Support format-specific input options
723721
const colour: sharp.Colour = '#fff';
724722
const color: sharp.Color = '#fff';
725-
sharp({ pdfBackground: colour });
726-
sharp({ pdfBackground: color });
727-
728-
sharp({ jp2Oneshot: true });
729-
sharp({ jp2Oneshot: false });
723+
sharp({ pdf: { background: colour } });
724+
sharp({ pdf: { background: color } });
725+
sharp({ pdfBackground: colour }); // Deprecated
726+
sharp({ pdfBackground: color }); // Deprecated
727+
sharp({ tiff: { subifd: 3 } });
728+
sharp({ subifd: 3 }); // Deprecated
729+
sharp({ openSlide: { level: 0 } });
730+
sharp({ level: 0 }); // Deprecated
731+
sharp({ jp2: { oneshot: true } });
732+
sharp({ jp2: { oneshot: false } });
730733

731734
sharp({ autoOrient: true });
732735
sharp({ autoOrient: false });

‎test/unit/io.js

Lines changed: 77 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -867,52 +867,91 @@ describe('Input/output', function () {
867867
sharp({ pages: '1' });
868868
}, /Expected integer between -1 and 100000 for pages but received 1 of type string/);
869869
});
870-
it('Valid level property', function () {
870+
it('Valid openSlide.level property', function () {
871+
sharp({ openSlide: { level: 1 } });
871872
sharp({ level: 1 });
872873
});
873-
it('Invalid level property (string) throws', function () {
874-
assert.throws(function () {
875-
sharp({ level: '1' });
876-
}, /Expected integer between 0 and 256 for level but received 1 of type string/);
877-
});
878-
it('Invalid level property (negative) throws', function () {
879-
assert.throws(function () {
880-
sharp({ level: -1 });
881-
}, /Expected integer between 0 and 256 for level but received -1 of type number/);
882-
});
883-
it('Valid subifd property', function () {
874+
it('Invalid openSlide.level property (string) throws', function () {
875+
assert.throws(
876+
() => sharp({ openSlide: { level: '1' } }),
877+
/Expected integer between 0 and 256 for openSlide.level but received 1 of type string/
878+
);
879+
assert.throws(
880+
() => sharp({ level: '1' }),
881+
/Expected integer between 0 and 256 for level but received 1 of type string/
882+
);
883+
});
884+
it('Invalid openSlide.level property (negative) throws', function () {
885+
assert.throws(
886+
() => sharp({ openSlide: { level: -1 } }),
887+
/Expected integer between 0 and 256 for openSlide\.level but received -1 of type number/
888+
);
889+
assert.throws(
890+
() => sharp({ level: -1 }),
891+
/Expected integer between 0 and 256 for level but received -1 of type number/
892+
);
893+
});
894+
it('Valid tiff.subifd property', function () {
895+
sharp({ tiff: { subifd: 1 } });
884896
sharp({ subifd: 1 });
885897
});
886-
it('Invalid subifd property (string) throws', function () {
887-
assert.throws(function () {
888-
sharp({ subifd: '1' });
889-
}, /Expected integer between -1 and 100000 for subifd but received 1 of type string/);
890-
});
891-
it('Invalid subifd property (float) throws', function () {
892-
assert.throws(function () {
893-
sharp({ subifd: 1.2 });
894-
}, /Expected integer between -1 and 100000 for subifd but received 1.2 of type number/);
895-
});
896-
it('Valid pdfBackground property (string)', function () {
898+
it('Invalid tiff.subifd property (string) throws', function () {
899+
assert.throws(
900+
() => sharp({ tiff: { subifd: '1' } }),
901+
/Expected integer between -1 and 100000 for tiff\.subifd but received 1 of type string/
902+
);
903+
assert.throws(
904+
() => sharp({ subifd: '1' }),
905+
/Expected integer between -1 and 100000 for subifd but received 1 of type string/
906+
);
907+
});
908+
it('Invalid tiff.subifd property (float) throws', function () {
909+
assert.throws(
910+
() => sharp({ tiff: { subifd: 1.2 } }),
911+
/Expected integer between -1 and 100000 for tiff\.subifd but received 1.2 of type number/
912+
);
913+
assert.throws(
914+
() => sharp({ subifd: 1.2 }),
915+
/Expected integer between -1 and 100000 for subifd but received 1.2 of type number/
916+
);
917+
});
918+
it('Valid pdf.background property (string)', function () {
919+
sharp({ pdf: { background: '#00ff00' } });
897920
sharp({ pdfBackground: '#00ff00' });
898921
});
899-
it('Valid pdfBackground property (object)', function () {
922+
it('Valid pdf.background property (object)', function () {
923+
sharp({ pdf: { background: { r: 0, g: 255, b: 0 } } });
900924
sharp({ pdfBackground: { r: 0, g: 255, b: 0 } });
901925
});
902-
it('Invalid pdfBackground property (string) throws', function () {
903-
assert.throws(function () {
904-
sharp({ pdfBackground: '00ff00' });
905-
}, /Unable to parse color from string/);
906-
});
907-
it('Invalid pdfBackground property (number) throws', function () {
908-
assert.throws(function () {
909-
sharp({ pdfBackground: 255 });
910-
}, /Expected object or string for background/);
911-
});
912-
it('Invalid pdfBackground property (object)', function () {
913-
assert.throws(function () {
914-
sharp({ pdfBackground: { red: 0, green: 255, blue: 0 } });
915-
}, /Unable to parse color from object/);
926+
it('Invalid pdf.background property (string) throws', function () {
927+
assert.throws(
928+
() => sharp({ pdf: { background: '00ff00' } }),
929+
/Unable to parse color from string/
930+
);
931+
assert.throws(
932+
() => sharp({ pdfBackground: '00ff00' }),
933+
/Unable to parse color from string/
934+
);
935+
});
936+
it('Invalid pdf.background property (number) throws', function () {
937+
assert.throws(
938+
() => sharp({ pdf: { background: 255 } }),
939+
/Expected object or string for background/
940+
);
941+
assert.throws(
942+
() => sharp({ pdf: { background: 255 } }),
943+
/Expected object or string for background/
944+
);
945+
});
946+
it('Invalid pdf.background property (object)', function () {
947+
assert.throws(
948+
() => sharp({ pdf: { background: { red: 0, green: 255, blue: 0 } } }),
949+
/Unable to parse color from object/
950+
);
951+
assert.throws(
952+
() => sharp({ pdfBackground: { red: 0, green: 255, blue: 0 } }),
953+
/Unable to parse color from object/
954+
);
916955
});
917956
});
918957

‎test/unit/jp2.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -117,14 +117,14 @@ describe('JP2 output', () => {
117117

118118
it('valid JP2 oneshot value does not throw error', () => {
119119
assert.doesNotThrow(
120-
() => sharp(fixtures.inputJp2TileParts, { jp2Oneshot: true })
120+
() => sharp({ jp2: { oneshot: true } })
121121
);
122122
});
123123

124124
it('invalid JP2 oneshot value throws error', () => {
125125
assert.throws(
126-
() => sharp(fixtures.inputJp2TileParts, { jp2Oneshot: 'fail' }),
127-
/Expected boolean for jp2Oneshot but received fail of type string/
126+
() => sharp({ jp2: { oneshot: 'fail' } }),
127+
/Expected boolean for jp2.oneshot but received fail of type string/
128128
);
129129
});
130130
});

0 commit comments

Comments
 (0)