1 | # sharp
|
2 |
|
3 | <img src="https://cdn.jsdelivr.net/gh/lovell/sharp@master/docs/image/sharp-logo.svg" width="160" height="160" alt="sharp logo" align="right">
|
4 |
|
5 | The typical use case for this high speed Node.js module
|
6 | is to convert large images in common formats to
|
7 | smaller, web-friendly JPEG, PNG and WebP images of varying dimensions.
|
8 |
|
9 | Resizing an image is typically 4x-5x faster than using the
|
10 | quickest ImageMagick and GraphicsMagick settings
|
11 | due to its use of [libvips](https://github.com/libvips/libvips).
|
12 |
|
13 | Colour spaces, embedded ICC profiles and alpha transparency channels are all handled correctly.
|
14 | Lanczos resampling ensures quality is not sacrificed for speed.
|
15 |
|
16 | As well as image resizing, operations such as
|
17 | rotation, extraction, compositing and gamma correction are available.
|
18 |
|
19 | Most modern macOS, Windows and Linux systems running Node.js v10+
|
20 | do not require any additional install or runtime dependencies.
|
21 |
|
22 | ## Examples
|
23 |
|
24 | ```sh
|
25 | npm install sharp
|
26 | ```
|
27 |
|
28 | ```javascript
|
29 | const sharp = require('sharp');
|
30 | ```
|
31 |
|
32 | ### Callback
|
33 |
|
34 | ```javascript
|
35 | sharp(inputBuffer)
|
36 | .resize(320, 240)
|
37 | .toFile('output.webp', (err, info) => { ... });
|
38 | ```
|
39 |
|
40 | ### Promise
|
41 |
|
42 | ```javascript
|
43 | sharp('input.jpg')
|
44 | .rotate()
|
45 | .resize(200)
|
46 | .toBuffer()
|
47 | .then( data => { ... })
|
48 | .catch( err => { ... });
|
49 | ```
|
50 |
|
51 | ### Async/await
|
52 |
|
53 | ```javascript
|
54 | const semiTransparentRedPng = await sharp({
|
55 | create: {
|
56 | width: 48,
|
57 | height: 48,
|
58 | channels: 4,
|
59 | background: { r: 255, g: 0, b: 0, alpha: 0.5 }
|
60 | }
|
61 | })
|
62 | .png()
|
63 | .toBuffer();
|
64 | ```
|
65 |
|
66 | ### Stream
|
67 |
|
68 | ```javascript
|
69 | const roundedCorners = Buffer.from(
|
70 | '<svg><rect x="0" y="0" width="200" height="200" rx="50" ry="50"/></svg>'
|
71 | );
|
72 |
|
73 | const roundedCornerResizer =
|
74 | sharp()
|
75 | .resize(200, 200)
|
76 | .composite([{
|
77 | input: roundedCorners,
|
78 | blend: 'dest-in'
|
79 | }])
|
80 | .png();
|
81 |
|
82 | readableStream
|
83 | .pipe(roundedCornerResizer)
|
84 | .pipe(writableStream);
|
85 | ```
|
86 |
|
87 | [![Test Coverage](https://coveralls.io/repos/lovell/sharp/badge.svg?branch=master)](https://coveralls.io/r/lovell/sharp?branch=master)
|
88 | [![N-API v3](https://img.shields.io/badge/N--API-v3-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api_version_matrix)
|
89 |
|
90 | ### Documentation
|
91 |
|
92 | Visit [sharp.pixelplumbing.com](https://sharp.pixelplumbing.com/) for complete
|
93 | [installation instructions](https://sharp.pixelplumbing.com/install),
|
94 | [API documentation](https://sharp.pixelplumbing.com/api-constructor),
|
95 | [benchmark tests](https://sharp.pixelplumbing.com/performance) and
|
96 | [changelog](https://sharp.pixelplumbing.com/changelog).
|
97 |
|
98 | ### Contributing
|
99 |
|
100 | A [guide for contributors](https://github.com/lovell/sharp/blob/master/.github/CONTRIBUTING.md)
|
101 | covers reporting bugs, requesting features and submitting code changes.
|
102 |
|
103 | ### Licensing
|
104 |
|
105 | Copyright 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Lovell Fuller and contributors.
|
106 |
|
107 | Licensed under the Apache License, Version 2.0 (the "License");
|
108 | you may not use this file except in compliance with the License.
|
109 | You may obtain a copy of the License at
|
110 | [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)
|
111 |
|
112 | Unless required by applicable law or agreed to in writing, software
|
113 | distributed under the License is distributed on an "AS IS" BASIS,
|
114 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
115 | See the License for the specific language governing permissions and
|
116 | limitations under the License.
|