Doc update and changelog entry for #3461

docs/api-operation.md

@@ -265,6 +265,31 @@ await sharp(rgbaInput)
 ```
 
 
+## unflatten
+Ensure the image has an alpha channel
+with all white pixel values made fully transparent.
+
+Existing alpha channel values for non-white pixels remain unchanged.
+
+This feature is experimental and the API may change.
+
+
+**Since**: 0.32.1  
+**Example**  
+```js
+await sharp(rgbInput)
+  .unflatten()
+  .toBuffer();
+```
+**Example**  
+```js
+await sharp(rgbInput)
+  .threshold(128, { grayscale: false }) // converter bright pixels to white
+  .unflatten()
+  .toBuffer();
+```
+
+
 ## gamma
 Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of `1/gamma`
 then increasing the encoding (brighten) post-resize at a factor of `gamma`.

docs/changelog.md

@@ -6,6 +6,10 @@ Requires libvips v8.14.2
 
 ### v0.32.1 - TBD
 
+* Add experimental `unflatten` operation.
+  [#3461](https://github.com/lovell/sharp/pull/3461)
+  [@antonmarsden](https://github.com/antonmarsden)
+
 * Ensure use of `flip` operation forces random access read (regression in 0.32.0).
   [#3600](https://github.com/lovell/sharp/issues/3600)
 

lib/index.d.ts

@@ -428,11 +428,11 @@ declare namespace sharp {
         flatten(flatten?: boolean | FlattenOptions): Sharp;
 
         /**
-         * Unflatten - add an alpha channel to the image if required, and make white pixels fully transparent. Alpha for non-white pixels will be unchanged/opaque.
-         * @param unflatten true to enable and false to disable (defaults to true)
+         * Ensure the image has an alpha channel with all white pixel values made fully transparent.
+         * Existing alpha channel values for non-white pixels remain unchanged.
          * @returns A sharp instance that can be used to chain operations
          */
-        unflatten(unflatten?: boolean): Sharp;
+        unflatten(): Sharp;
 
         /**
          * Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of 1/gamma then increasing the encoding (brighten) post-resize at a factor of gamma.

lib/operation.js

@@ -406,7 +406,14 @@ function flatten (options) {
 }
 
 /**
- * Unflatten - add an alpha channel to the image if required, and make white pixels fully transparent. Alpha for non-white pixels will be unchanged/opaque.
+ * Ensure the image has an alpha channel
+ * with all white pixel values made fully transparent.
+ *
+ * Existing alpha channel values for non-white pixels remain unchanged.
+ *
+ * This feature is experimental and the API may change.
+ *
+ * @since 0.32.1
  *
  * @example
  * await sharp(rgbInput)
@@ -419,8 +426,8 @@ function flatten (options) {
  *   .unflatten()
  *   .toBuffer();
  */
-function unflatten (options) {
-  this.options.unflatten = is.bool(options) ? options : true;
+function unflatten () {
+  this.options.unflatten = true;
   return this;
 }
 

test/unit/unflatten.js

@@ -1,10 +1,11 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
 'use strict';
 
 const sharp = require('../../');
 const fixtures = require('../fixtures');
 
-// const assert = require('assert');
-
 describe('Unflatten', function () {
   it('unflatten white background', function (done) {
     sharp(fixtures.inputPng).unflatten()
@@ -21,17 +22,10 @@ describe('Unflatten', function () {
       });
   });
   it('unflatten using threshold', function (done) {
-    sharp(fixtures.inputPngPalette).unflatten(true).threshold(128, { grayscale: false })
+    sharp(fixtures.inputPngPalette).unflatten().threshold(128, { grayscale: false })
       .toBuffer(function (err, data) {
         if (err) throw err;
         fixtures.assertSimilar(fixtures.expected('unflatten-swiss.png'), data, { threshold: 1 }, done);
       });
   });
-  it('no unflatten', function (done) {
-    sharp(fixtures.inputPng).unflatten(false)
-      .toBuffer(function (err, data) {
-        if (err) throw err;
-        fixtures.assertSimilar(fixtures.inputPng, data, { threshold: 0 }, done);
-      });
-  });
 });