-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs: switch to well-maintained jsdoc2md for JSDoc parsing
- Loading branch information
Showing
13 changed files
with
933 additions
and
1,287 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,145 +1,126 @@ | ||
| <!-- Generated by documentation.js. Update this documentation by updating the source code. --> | ||
|
|
||
| ## removeAlpha | ||
|
|
||
| Remove alpha channel, if any. This is a no-op if the image does not have an alpha channel. | ||
|
|
||
| See also [flatten][1]. | ||
| See also [flatten](/api-operation#flatten). | ||
|
|
||
| ### Examples | ||
|
|
||
| ```javascript | ||
| **Example** | ||
| ```js | ||
| sharp('rgba.png') | ||
| .removeAlpha() | ||
| .toFile('rgb.png', function(err, info) { | ||
| // rgb.png is a 3 channel image without an alpha channel | ||
| }); | ||
| ``` | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| ## ensureAlpha | ||
|
|
||
| Ensure the output image has an alpha transparency channel. | ||
| If missing, the added alpha channel will have the specified | ||
| transparency level, defaulting to fully-opaque (1). | ||
| This is a no-op if the image already has an alpha channel. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `alpha` **[number][2]** alpha transparency level (0=fully-transparent, 1=fully-opaque) (optional, default `1`) | ||
| **Throws**: | ||
|
|
||
| - <code>Error</code> Invalid alpha transparency level | ||
|
|
||
| ### Examples | ||
| **Since**: 0.21.2 | ||
|
|
||
| ```javascript | ||
| | Param | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | [alpha] | <code>number</code> | <code>1</code> | alpha transparency level (0=fully-transparent, 1=fully-opaque) | | ||
|
|
||
| **Example** | ||
| ```js | ||
| // rgba.png will be a 4 channel image with a fully-opaque alpha channel | ||
| await sharp('rgb.jpg') | ||
| .ensureAlpha() | ||
| .toFile('rgba.png') | ||
| ``` | ||
|
|
||
| ```javascript | ||
| **Example** | ||
| ```js | ||
| // rgba is a 4 channel image with a fully-transparent alpha channel | ||
| const rgba = await sharp(rgb) | ||
| .ensureAlpha(0) | ||
| .toBuffer(); | ||
| ``` | ||
|
|
||
| * Throws **[Error][3]** Invalid alpha transparency level | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| **Meta** | ||
|
|
||
| * **since**: 0.21.2 | ||
|
|
||
| ## extractChannel | ||
|
|
||
| Extract a single channel from a multi-channel image. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `channel` **([number][2] | [string][4])** zero-indexed channel/band number to extract, or `red`, `green`, `blue` or `alpha`. | ||
| **Throws**: | ||
|
|
||
| - <code>Error</code> Invalid channel | ||
|
|
||
|
|
||
| ### Examples | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | channel | <code>number</code> \| <code>string</code> | zero-indexed channel/band number to extract, or `red`, `green`, `blue` or `alpha`. | | ||
|
|
||
| ```javascript | ||
| **Example** | ||
| ```js | ||
| // green.jpg is a greyscale image containing the green channel of the input | ||
| await sharp(input) | ||
| .extractChannel('green') | ||
| .toFile('green.jpg'); | ||
| ``` | ||
|
|
||
| ```javascript | ||
| **Example** | ||
| ```js | ||
| // red1 is the red value of the first pixel, red2 the second pixel etc. | ||
| const [red1, red2, ...] = await sharp(input) | ||
| .extractChannel(0) | ||
| .raw() | ||
| .toBuffer(); | ||
| ``` | ||
|
|
||
| * Throws **[Error][3]** Invalid channel | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| ## joinChannel | ||
|
|
||
| Join one or more channels to the image. | ||
| The meaning of the added channels depends on the output colourspace, set with `toColourspace()`. | ||
| By default the output image will be web-friendly sRGB, with additional channels interpreted as alpha channels. | ||
| Channel ordering follows vips convention: | ||
|
|
||
| * sRGB: 0: Red, 1: Green, 2: Blue, 3: Alpha. | ||
| * CMYK: 0: Magenta, 1: Cyan, 2: Yellow, 3: Black, 4: Alpha. | ||
| - sRGB: 0: Red, 1: Green, 2: Blue, 3: Alpha. | ||
| - CMYK: 0: Magenta, 1: Cyan, 2: Yellow, 3: Black, 4: Alpha. | ||
|
|
||
| Buffers may be any of the image formats supported by sharp. | ||
| For raw pixel input, the `options` object should contain a `raw` attribute, which follows the format of the attribute of the same name in the `sharp()` constructor. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `images` **([Array][5]<([string][4] | [Buffer][6])> | [string][4] | [Buffer][6])** one or more images (file paths, Buffers). | ||
| * `options` **[Object][7]** image options, see `sharp()` constructor. | ||
| **Throws**: | ||
|
|
||
| <!----> | ||
| - <code>Error</code> Invalid parameters | ||
|
|
||
| * Throws **[Error][3]** Invalid parameters | ||
|
|
||
| Returns **Sharp**  | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | images | <code>Array.<(string\|Buffer)></code> \| <code>string</code> \| <code>Buffer</code> | one or more images (file paths, Buffers). | | ||
| | options | <code>Object</code> | image options, see `sharp()` constructor. | | ||
|
|
||
|
|
||
| ## bandbool | ||
|
|
||
| ## bandbool | ||
| Perform a bitwise boolean operation on all input image channels (bands) to produce a single channel output image. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `boolOp` **[string][4]** one of `and`, `or` or `eor` to perform that bitwise operation, like the C logic operators `&`, `|` and `^` respectively. | ||
| **Throws**: | ||
|
|
||
| - <code>Error</code> Invalid parameters | ||
|
|
||
| ### Examples | ||
|
|
||
| ```javascript | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | boolOp | <code>string</code> | one of `and`, `or` or `eor` to perform that bitwise operation, like the C logic operators `&`, `|` and `^` respectively. | | ||
|
|
||
| **Example** | ||
| ```js | ||
| sharp('3-channel-rgb-input.png') | ||
| .bandbool(sharp.bool.and) | ||
| .toFile('1-channel-output.png', function (err, info) { | ||
| // The output will be a single channel image where each pixel `P = R & G & B`. | ||
| // If `I(1,1) = [247, 170, 14] = [0b11110111, 0b10101010, 0b00001111]` | ||
| // then `O(1,1) = 0b11110111 & 0b10101010 & 0b00001111 = 0b00000010 = 2`. | ||
| }); | ||
| ``` | ||
|
|
||
| * Throws **[Error][3]** Invalid parameters | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| [1]: /api-operation#flatten | ||
|
|
||
| [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number | ||
|
|
||
| [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error | ||
|
|
||
| [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String | ||
|
|
||
| [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array | ||
|
|
||
| [6]: https://nodejs.org/api/buffer.html | ||
|
|
||
| [7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,150 +1,132 @@ | ||
| <!-- Generated by documentation.js. Update this documentation by updating the source code. --> | ||
|
|
||
| ## tint | ||
|
|
||
| Tint the image using the provided chroma while preserving the image luminance. | ||
| An alpha channel may be present and will be unchanged by the operation. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `rgb` **([string][1] | [Object][2])** parsed by the [color][3] module to extract chroma values. | ||
| **Throws**: | ||
|
|
||
| - <code>Error</code> Invalid parameter | ||
|
|
||
|
|
||
| ### Examples | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | rgb | <code>string</code> \| <code>Object</code> | parsed by the [color](https://www.npmjs.org/package/color) module to extract chroma values. | | ||
|
|
||
| ```javascript | ||
| **Example** | ||
| ```js | ||
| const output = await sharp(input) | ||
| .tint({ r: 255, g: 240, b: 16 }) | ||
| .toBuffer(); | ||
| ``` | ||
|
|
||
| * Throws **[Error][4]** Invalid parameter | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| ## 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. | ||
| By default the output image will be web-friendly sRGB and contain three (identical) color channels. | ||
| This may be overridden by other sharp operations such as `toColourspace('b-w')`, | ||
| which will produce an output image containing one color channel. | ||
| An alpha channel may be present, and will be unchanged by the operation. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `greyscale` **[Boolean][5]** (optional, default `true`) | ||
|
|
||
| ### Examples | ||
| | Param | Type | Default | | ||
| | --- | --- | --- | | ||
| | [greyscale] | <code>Boolean</code> | <code>true</code> | | ||
|
|
||
| ```javascript | ||
| **Example** | ||
| ```js | ||
| const output = await sharp(input).greyscale().toBuffer(); | ||
| ``` | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| ## grayscale | ||
|
|
||
| Alternative spelling of `greyscale`. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `grayscale` **[Boolean][5]** (optional, default `true`) | ||
|
|
||
| Returns **Sharp**  | ||
| | Param | Type | Default | | ||
| | --- | --- | --- | | ||
| | [grayscale] | <code>Boolean</code> | <code>true</code> | | ||
|
|
||
| ## pipelineColourspace | ||
|
|
||
|
|
||
| ## pipelineColourspace | ||
| Set the pipeline colourspace. | ||
|
|
||
| The input image will be converted to the provided colourspace at the start of the pipeline. | ||
| All operations will use this colourspace before converting to the output colourspace, as defined by [toColourspace][6]. | ||
| All operations will use this colourspace before converting to the output colourspace, as defined by [toColourspace](#toColourspace). | ||
|
|
||
| This feature is experimental and has not yet been fully-tested with all operations. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `colourspace` **[string][1]?** pipeline colourspace e.g. `rgb16`, `scrgb`, `lab`, `grey16` [...][7] | ||
| **Throws**: | ||
|
|
||
| - <code>Error</code> Invalid parameters | ||
|
|
||
| **Since**: 0.29.0 | ||
|
|
||
| ### Examples | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | [colourspace] | <code>string</code> | pipeline colourspace e.g. `rgb16`, `scrgb`, `lab`, `grey16` [...](https://github.com/libvips/libvips/blob/41cff4e9d0838498487a00623462204eb10ee5b8/libvips/iofuncs/enumtypes.c#L774) | | ||
|
|
||
| ```javascript | ||
| **Example** | ||
| ```js | ||
| // Run pipeline in 16 bits per channel RGB while converting final result to 8 bits per channel sRGB. | ||
| await sharp(input) | ||
| .pipelineColourspace('rgb16') | ||
| .toColourspace('srgb') | ||
| .toFile('16bpc-pipeline-to-8bpc-output.png') | ||
| ``` | ||
|
|
||
| * Throws **[Error][4]** Invalid parameters | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| **Meta** | ||
|
|
||
| * **since**: 0.29.0 | ||
|
|
||
| ## pipelineColorspace | ||
|
|
||
| Alternative spelling of `pipelineColourspace`. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `colorspace` **[string][1]?** pipeline colorspace. | ||
| **Throws**: | ||
|
|
||
| <!----> | ||
| - <code>Error</code> Invalid parameters | ||
|
|
||
| * Throws **[Error][4]** Invalid parameters | ||
|
|
||
| Returns **Sharp**  | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | [colorspace] | <code>string</code> | pipeline colorspace. | | ||
|
|
||
|
|
||
| ## toColourspace | ||
|
|
||
| ## toColourspace | ||
| Set the output colourspace. | ||
| By default output image will be web-friendly sRGB, with additional channels interpreted as alpha channels. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `colourspace` **[string][1]?** output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...][8] | ||
| **Throws**: | ||
|
|
||
| - <code>Error</code> Invalid parameters | ||
|
|
||
| ### Examples | ||
|
|
||
| ```javascript | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | [colourspace] | <code>string</code> | output colourspace e.g. `srgb`, `rgb`, `cmyk`, `lab`, `b-w` [...](https://github.com/libvips/libvips/blob/3c0bfdf74ce1dc37a6429bed47fa76f16e2cd70a/libvips/iofuncs/enumtypes.c#L777-L794) | | ||
|
|
||
| **Example** | ||
| ```js | ||
| // Output 16 bits per pixel RGB | ||
| await sharp(input) | ||
| .toColourspace('rgb16') | ||
| .toFile('16-bpp.png') | ||
| ``` | ||
|
|
||
| * Throws **[Error][4]** Invalid parameters | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| ## toColorspace | ||
|
|
||
| Alternative spelling of `toColourspace`. | ||
|
|
||
| ### Parameters | ||
|
|
||
| * `colorspace` **[string][1]?** output colorspace. | ||
|
|
||
| <!----> | ||
|
|
||
| * Throws **[Error][4]** Invalid parameters | ||
|
|
||
| Returns **Sharp**  | ||
|
|
||
| [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String | ||
|
|
||
| [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object | ||
|
|
||
| [3]: https://www.npmjs.org/package/color | ||
|
|
||
| [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error | ||
|
|
||
| [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean | ||
| **Throws**: | ||
|
|
||
| [6]: #tocolourspace | ||
| - <code>Error</code> Invalid parameters | ||
|
|
||
| [7]: https://github.com/libvips/libvips/blob/41cff4e9d0838498487a00623462204eb10ee5b8/libvips/iofuncs/enumtypes.c#L774 | ||
|
|
||
| [8]: https://github.com/libvips/libvips/blob/3c0bfdf74ce1dc37a6429bed47fa76f16e2cd70a/libvips/iofuncs/enumtypes.c#L777-L794 | ||
| | Param | Type | Description | | ||
| | --- | --- | --- | | ||
| | [colorspace] | <code>string</code> | output colorspace. | |
Oops, something went wrong.