Add withDensity to set density in EXIF metadata #4496

Author: lovell

docs/src/content/docs/api-output.md

@@ -149,6 +149,30 @@ const base64String = data.toBase64();
 ```
 
 
+## withDensity
+> withDensity(density) ⇒ <code>Sharp</code>
+
+Set output density (DPI) in EXIF metadata.
+
+
+**Throws**:
+
+- <code>Error</code> Invalid parameters
+
+**Since**: 0.35.0  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| density | <code>number</code> | Number of pixels per inch (DPI). |
+
+**Example**  
+```js
+const data = await sharp(input)
+  .withDensity(96)
+  .toBuffer();
+```
+
+
 ## keepExif
 > keepExif() ⇒ <code>Sharp</code>
 

docs/src/content/docs/changelog/v0.35.0.md

@@ -50,4 +50,7 @@ slug: changelog/v0.35.0
 * Add image Media Type (MIME Type) to metadata response.
   [#4492](https://github.com/lovell/sharp/issues/4492)
 
+* Add `withDensity` to set output density in EXIF metadata.
+  [#4496](https://github.com/lovell/sharp/issues/4496)
+
 * Add WebP `exact` option for control over transparent pixel colour values.

lib/index.d.ts

@@ -685,6 +685,14 @@ declare namespace sharp {
          */
         toUint8Array(): Promise<{ data: Uint8Array; info: OutputInfo }>;
 
+        /**
+         * Set output density (DPI) in EXIF metadata.
+         * @param density Density in dots per inch (DPI).
+         * @returns A sharp instance that can be used to chain operations
+         * @throws {Error} Invalid parameters
+         */
+        withDensity(density: number): Sharp;
+
         /**
          * Keep all EXIF metadata from the input image in the output image.
          * EXIF metadata is unsupported for TIFF output.

lib/output.js

@@ -199,6 +199,29 @@ function toUint8Array () {
   return this._pipeline(null, stack);
 }
 
+/**
+ * Set output density (DPI) in EXIF metadata.
+ *
+ * @since 0.35.0
+ *
+ * @example
+ * const data = await sharp(input)
+ *   .withDensity(96)
+ *   .toBuffer();
+ *
+ * @param {number} density Number of pixels per inch (DPI).
+ * @returns {Sharp}
+ * @throws {Error} Invalid parameters
+ */
+function withDensity (density) {
+  if (is.number(density) && density > 0) {
+    this.options.withMetadataDensity = density;
+  } else {
+    throw is.invalidParameterError('density', 'positive number', density);
+  }
+  return this.keepExif();
+}
+
 /**
  * Keep all EXIF metadata from the input image in the output image.
  *
@@ -1712,6 +1735,7 @@ module.exports = (Sharp) => {
     toFile,
     toBuffer,
     toUint8Array,
+    withDensity,
     keepExif,
     withExif,
     withExifMerge,

test/types/sharp.test-d.ts

@@ -53,6 +53,8 @@ sharp('input.png')
     // output.png is an image containing input.png along with all metadata(EXIF, ICC, XMP, IPTC) from input.png
   })
 
+sharp(input).withDensity(300);
+
 sharp('input.jpg')
   .resize(300, 200)
   .toFile('output.jpg', (err: Error) => {

test/unit/metadata.js

@@ -875,7 +875,7 @@ describe('Image metadata', () => {
     assert.strictEqual(parsedExif.Photo.ExposureTime, 0.2);
   });
 
-  it('Set density of JPEG', async () => {
+  it('withMetadata - set density of JPEG', async () => {
     const data = await sharp({ create })
       .withMetadata({
         density: 300
@@ -887,7 +887,7 @@ describe('Image metadata', () => {
     assert.strictEqual(density, 300);
   });
 
-  it('Set density of PNG', async () => {
+  it('withMetadata - set density of PNG', async () => {
     const data = await sharp({ create })
       .withMetadata({
         density: 96
@@ -899,6 +899,26 @@ describe('Image metadata', () => {
     assert.strictEqual(density, 96);
   });
 
+  it('withDensity - set density of JPEG', async () => {
+    const data = await sharp({ create })
+      .withDensity(300)
+      .jpeg()
+      .toBuffer();
+
+    const { density } = await sharp(data).metadata();
+    assert.strictEqual(density, 300);
+  });
+
+  it('withDensity - set density of PNG', async () => {
+    const data = await sharp({ create })
+      .withDensity(96)
+      .png()
+      .toBuffer();
+
+    const { density } = await sharp(data).metadata();
+    assert.strictEqual(density, 96);
+  });
+
   it('chromaSubsampling 4:4:4:4 CMYK JPEG', () => sharp(fixtures.inputJpgWithCmykProfile)
       .metadata()
       .then((metadata) => {
@@ -1369,5 +1389,17 @@ describe('Image metadata', () => {
         /Expected boolean for attach but received 1 of type number/
       );
     });
+    it('withDensity missing density', () => {
+      assert.throws(
+        () => sharp().withDensity(),
+        /Expected positive number for density but received undefined of type undefined/
+      );
+    });
+    it('withDensity invalid density', () => {
+      assert.throws(
+        () => sharp().withDensity('invalid'),
+        /Expected positive number for density but received invalid of type string/
+      );
+    });
   });
 });