Image Duotone Effect Processor

Build a Node.js application that applies duotone color effects to images based on their luminance values.

Overview

Create a command-line tool that processes image files by applying a two-tone color gradient effect. The tool should map pixel brightness to a gradient between two specified colors, creating artistic duotone images commonly used in modern web design.

Requirements

Input Processing

The application should accept:

• An input image file path
• A highlight color (hex format, e.g., "#ffffff")
• A shadow color (hex format, e.g., "#663399")
• An optional opacity value (0-100, default: 100)
• An output file path

Duotone Effect

The duotone transformation should:

• Analyze each pixel's luminance using the relative luminance formula
• Map the luminance to a position in a gradient between shadow and highlight colors
• Apply the gradient color to the pixel
• Support optional opacity blending with the original image

Output

The tool should:

• Save the processed image to the specified output path
• Preserve the original image dimensions
• Support common image formats (JPEG, PNG, WebP)

Implementation Guidelines

• Use appropriate image processing libraries available in the npm ecosystem
• Handle errors gracefully (invalid file paths, unsupported formats, invalid colors)
• Provide clear feedback during processing

Dependencies { .dependencies }

gatsby-plugin-sharp { .dependency }

Provides image processing and transformation capabilities with duotone effect support.

Test Cases

Basic duotone application { .test }

@test

Given an input image with path test-images/sample.jpg, apply duotone with highlight #ffffff and shadow #663399, then save to output/duotone-basic.jpg. The output should exist and have valid image data.

Custom opacity duotone { .test }

@test

Given an input image with path test-images/sample.jpg, apply duotone with highlight #f00e2e, shadow #192550, and opacity 50, then save to output/duotone-opacity.jpg. The output should exist and show blending with the original image.

Multiple format support { .test }

@test

Process the same source image to three different output formats: JPEG, PNG, and WebP. All outputs should exist and be valid images with the duotone effect applied.

Invalid color handling { .test }

@test

Attempting to apply duotone with an invalid hex color (e.g., #gggggg) should throw an error with a clear message about the invalid color format.

API

/**
 * Applies a duotone effect to an image file
 *
 * @param {Object} options - Configuration options
 * @param {string} options.inputPath - Path to the input image
 * @param {string} options.outputPath - Path for the output image
 * @param {string} options.highlight - Highlight color in hex format (e.g., "#ffffff")
 * @param {string} options.shadow - Shadow color in hex format (e.g., "#663399")
 * @param {number} [options.opacity=100] - Opacity for blending (0-100)
 * @returns {Promise<void>}
 * @throws {Error} If file paths are invalid or colors are malformed
 */
async function applyDuotone(options) {
  // Implementation
}

module.exports = { applyDuotone };

Implementation

@generates