Operations and Filters

/**
 * Rotate image by specified angle or auto-orient using EXIF data
 * @param angle - Rotation angle in degrees (optional)
 * @param options - Rotation options (optional)
 * @returns Sharp instance for chaining
 */
rotate(angle?: number, options?: RotateOptions): Sharp;

/**
 * Auto-orient based on EXIF Orientation tag (alias for rotate())
 * @returns Sharp instance for chaining
 */
autoOrient(): Sharp;

interface RotateOptions {
  /** Background color for areas outside rotated image */
  background?: string | RGBA;
}

// Rotate by specific angle
await sharp('input.jpg')
  .rotate(90)
  .toFile('rotated-90.jpg');

// Rotate with custom background
await sharp('input.jpg')
  .rotate(45, { background: '#ff0000' })
  .toFile('rotated-45-red.jpg');

// Auto-orient using EXIF data
await sharp('input.jpg')
  .rotate()
  .toFile('oriented.jpg');

// Explicit auto-orient
await sharp('input.jpg')
  .autoOrient()
  .toFile('auto-oriented.jpg');

/**
 * Flip image vertically (about Y axis)
 * @param flip - Enable flip (defaults to true)
 * @returns Sharp instance for chaining
 */
flip(flip?: boolean): Sharp;

/**
 * Flop image horizontally (about X axis)
 * @param flop - Enable flop (defaults to true)
 * @returns Sharp instance for chaining
 */
flop(flop?: boolean): Sharp;

// Vertical flip
await sharp('input.jpg')
  .flip()
  .toFile('flipped.jpg');

// Horizontal flop
await sharp('input.jpg')
  .flop()
  .toFile('flopped.jpg');

// Both flip and flop
await sharp('input.jpg')
  .flip()
  .flop()
  .toFile('flipped-flopped.jpg');

/**
 * Apply affine transformation matrix
 * @param matrix - 2x2 transformation matrix or array of 4 numbers
 * @param options - Transformation options
 * @returns Sharp instance for chaining
 */
affine(matrix: [number, number, number, number] | Matrix2x2, options?: AffineOptions): Sharp;

type Matrix2x2 = [[number, number], [number, number]];

interface AffineOptions {
  /** Background color for new pixels */
  background?: string | object;
  /** Input horizontal offset */
  idx?: number;
  /** Input vertical offset */
  idy?: number;
  /** Output horizontal offset */
  odx?: number;
  /** Output vertical offset */
  ody?: number;
  /** Interpolation method */
  interpolator?: keyof Interpolators;
}

// Shear transformation
await sharp('input.jpg')
  .affine([1, 0.5, 0, 1])
  .toFile('sheared.jpg');

// Scale and rotate transformation
const angle = Math.PI / 4; // 45 degrees
const cos = Math.cos(angle);
const sin = Math.sin(angle);
await sharp('input.jpg')
  .affine([[cos, -sin], [sin, cos]], {
    background: 'white',
    interpolator: sharp.interpolators.bicubic
  })
  .toFile('transformed.jpg');

/**
 * Sharpen image with configurable parameters
 * @param options - Sharpening options
 * @returns Sharp instance for chaining
 */
sharpen(options?: SharpenOptions): Sharp;

interface SharpenOptions {
  /** Gaussian mask sigma (1 + radius / 2) */
  sigma: number;
  /** Sharpening level for flat areas */
  m1?: number;
  /** Sharpening level for jagged areas */
  m2?: number;
  /** Threshold between flat and jagged */
  x1?: number;
  /** Maximum brightening */
  y2?: number;
  /** Maximum darkening */
  y3?: number;
}

// Mild sharpening
await sharp('input.jpg')
  .sharpen()
  .toFile('sharpened-mild.jpg');

// Custom sharpening
await sharp('input.jpg')
  .sharpen({
    sigma: 1.5,
    m1: 1.2,
    m2: 2.5,
    x1: 3.0,
    y2: 15.0,
    y3: 25.0
  })
  .toFile('sharpened-custom.jpg');

/**
 * Blur image using Gaussian convolution
 * @param sigma - Blur amount or blur options
 * @returns Sharp instance for chaining
 */
blur(sigma?: number | boolean | BlurOptions): Sharp;

interface BlurOptions {
  /** Gaussian mask sigma (0.3-1000) */
  sigma: number;
  /** Minimum amplitude for mask accuracy */
  minAmplitude?: number;
  /** Operation precision */
  precision?: 'integer' | 'float' | 'approximate';
}

// Mild blur
await sharp('input.jpg')
  .blur()
  .toFile('blurred-mild.jpg');

// Custom blur strength
await sharp('input.jpg')
  .blur(5.0)
  .toFile('blurred-medium.jpg');

// High-precision blur
await sharp('input.jpg')
  .blur({
    sigma: 3.0,
    precision: 'float'
  })
  .toFile('blurred-precise.jpg');

/**
 * Apply median filter for noise reduction
 * @param size - Filter mask size (defaults to 3)
 * @returns Sharp instance for chaining
 */
median(size?: number): Sharp;

// Noise reduction
await sharp('noisy-input.jpg')
  .median(5)
  .toFile('denoised.jpg');

/**
 * Expand foreground objects (morphological dilation)
 * @param width - Dilation width in pixels (defaults to 1)
 * @returns Sharp instance for chaining
 */
dilate(width?: number): Sharp;

/**
 * Shrink foreground objects (morphological erosion)
 * @param width - Erosion width in pixels (defaults to 1)
 * @returns Sharp instance for chaining
 */
erode(width?: number): Sharp;

// Expand white areas
await sharp('binary-input.png')
  .dilate(3)
  .toFile('dilated.png');

// Shrink white areas  
await sharp('binary-input.png')
  .erode(2)
  .toFile('eroded.png');

// Open operation (erode then dilate)
await sharp('binary-input.png')
  .erode(2)
  .dilate(2)
  .toFile('opened.png');

/**
 * Apply gamma correction
 * @param gamma - Input gamma value (1.0-3.0, defaults to 2.2)
 * @param gammaOut - Output gamma value (defaults to same as gamma)
 * @returns Sharp instance for chaining
 */
gamma(gamma?: number, gammaOut?: number): Sharp;

// Standard gamma correction
await sharp('input.jpg')
  .gamma(2.2)
  .toFile('gamma-corrected.jpg');

// Custom input/output gamma
await sharp('input.jpg')
  .gamma(1.8, 2.4)
  .toFile('custom-gamma.jpg');

/**
 * Produce negative of image
 * @param negate - Enable negation or options object
 * @returns Sharp instance for chaining
 */
negate(negate?: boolean | NegateOptions): Sharp;

interface NegateOptions {
  /** Whether to negate alpha channel */
  alpha?: boolean;
}

// Basic negative
await sharp('input.jpg')
  .negate()
  .toFile('negative.jpg');

// Negate without affecting alpha
await sharp('input.png')
  .negate({ alpha: false })
  .toFile('negative-preserve-alpha.png');

/**
 * Normalize image contrast
 * @param options - Normalization options
 * @returns Sharp instance for chaining
 */
normalise(options?: NormaliseOptions): Sharp;

// Alternative spelling
normalize(options?: NormaliseOptions): Sharp;

interface NormaliseOptions {
  /** Lower percentile for underexposure clipping */
  lower?: number;
  /** Upper percentile for overexposure clipping */
  upper?: number;
}

// Default normalization (1%-99%)
await sharp('low-contrast.jpg')
  .normalise()
  .toFile('normalized.jpg');

// Custom percentiles
await sharp('low-contrast.jpg')
  .normalize({
    lower: 2,
    upper: 98
  })
  .toFile('custom-normalized.jpg');

/**
 * Apply Contrast Limited Adaptive Histogram Equalization
 * @param options - CLAHE parameters
 * @returns Sharp instance for chaining
 */
clahe(options: ClaheOptions): Sharp;

interface ClaheOptions {
  /** Region width for local histogram */
  width: number;
  /** Region height for local histogram */
  height: number;
  /** Maximum contrast amplification (0-100) */
  maxSlope?: number;
}

// Enhance local contrast
await sharp('low-contrast.jpg')
  .clahe({
    width: 64,
    height: 64,
    maxSlope: 3
  })
  .toFile('clahe-enhanced.jpg');

/**
 * Apply linear formula: a * input + b
 * @param a - Multiplier (defaults to 1.0)
 * @param b - Offset (defaults to 0.0)
 * @returns Sharp instance for chaining
 */
linear(a?: number | number[], b?: number | number[]): Sharp;

// Increase brightness
await sharp('input.jpg')
  .linear(1.0, 50)
  .toFile('brighter.jpg');

// Increase contrast
await sharp('input.jpg')
  .linear(1.5, 0)
  .toFile('higher-contrast.jpg');

// Per-channel adjustment
await sharp('input.jpg')
  .linear([1.2, 1.0, 0.8], [10, -5, 20])
  .toFile('channel-adjusted.jpg');

/**
 * Modulate image brightness, saturation, hue, and lightness
 * @param options - Modulation parameters
 * @returns Sharp instance for chaining
 */
modulate(options?: ModulateOptions): Sharp;

interface ModulateOptions {
  /** Brightness multiplier */
  brightness?: number;
  /** Saturation multiplier */
  saturation?: number;
  /** Hue rotation in degrees */
  hue?: number;
  /** Lightness adjustment */
  lightness?: number;
}

// Increase brightness and saturation
await sharp('input.jpg')
  .modulate({
    brightness: 1.2,
    saturation: 1.3
  })
  .toFile('enhanced.jpg');

// Hue shift
await sharp('input.jpg')
  .modulate({
    hue: 45
  })
  .toFile('hue-shifted.jpg');

// Combined adjustments
await sharp('input.jpg')
  .modulate({
    brightness: 1.1,
    saturation: 0.9,
    hue: -15,
    lightness: 5
  })
  .toFile('color-graded.jpg');

/**
 * Apply custom convolution kernel
 * @param kernel - Convolution kernel definition
 * @returns Sharp instance for chaining
 */
convolve(kernel: Kernel): Sharp;

interface Kernel {
  /** Kernel width in pixels */
  width: number;
  /** Kernel height in pixels */
  height: number;
  /** Kernel values array (length: width * height) */
  kernel: number[];
  /** Kernel scale (defaults to sum of kernel values) */
  scale?: number;
  /** Kernel offset (defaults to 0) */
  offset?: number;
}

// Edge detection kernel
await sharp('input.jpg')
  .convolve({
    width: 3,
    height: 3,
    kernel: [
      -1, -1, -1,
      -1,  8, -1,
      -1, -1, -1
    ]
  })
  .toFile('edges.jpg');

/**
 * Apply threshold to create binary image
 * @param threshold - Threshold value (0-255, defaults to 128)
 * @param options - Threshold options
 * @returns Sharp instance for chaining
 */
threshold(threshold?: number, options?: ThresholdOptions): Sharp;

interface ThresholdOptions {
  /** Convert to single channel greyscale */
  greyscale?: boolean;
  /** Alternative spelling of greyscale */
  grayscale?: boolean;
}

/**
 * Recombine image channels using matrix
 * @param matrix - 3x3 or 4x4 recombination matrix
 * @returns Sharp instance for chaining
 */
recomb(matrix: Matrix3x3 | Matrix4x4): Sharp;

type Matrix3x3 = [[number, number, number], [number, number, number], [number, number, number]];
type Matrix4x4 = [[number, number, number, number], [number, number, number, number], [number, number, number, number], [number, number, number, number]];

// Custom color mixing
await sharp('input.jpg')
  .recomb([
    [0.3588, 0.7044, 0.1368],
    [0.2990, 0.5870, 0.1140],
    [0.2392, 0.4696, 0.0912]
  ])
  .toFile('custom-mixed.jpg');