modify_images

Apply in-place image pixel modifications and effects

Usage

pdftl <input> modify_images <specs>(pipeline) output <file> [threads=<n>] [quality=<q>]

Details

Processes bitmap page image assets using an ordered sequence of parallelized point and kernel transformations.

Arguments:

  • <specs>(...): The page specification selection followed immediately by parenthesized pipeline instructions separated by semicolons. Example: 1-5(contrast=1.3; sharpen=true)

  • threads=<n>: Explicit parallel execution worker thread limit count.

  • quality=<q>: Output JPEG stream lossy compression value (1-100). Default: 75

Available Image Modifiers:

Image modifier

Syntax

Short description

Auto Contrast

autocontrast=<bool>

Maximizes image contrast automatically by scaling image histogram bounds.

Gaussian Blur

blur=<float>

Blurs details smoothly using a floating-point radius calculation.

Brightness Adjustment

brightness=<float>

Linearly scales overall image exposure levels.

Contrast Adjustment

contrast=<float>

Scales image contrast boundaries around a gray midpoint.

Despeckle Noise

despeckle=<bool>

Applies a 3x3 median filter to eliminate salt-and-pepper noise.

Gamma Correction

gamma=<float>

Applies power-law tone adjustment to modify midtones.

Hue Rotation

hue=<float>

Rotates the color hue spectrum wheel.

Invert Channels

invert=<bool>

Creates a negative effect by flipping color channels.

N-Point Levels Curve

levels=<list[float]>

Maps image tones using an n-point piecewise linear percentage curve.

Lightness Blend

lightness=<float>

Adjusts color luminance parameters via an HSL shift.

Posterization

posterize=<int>

Reduces discrete color variations to specific bit depth counts.

Saturation Adjustment

saturation=<float>

Controls color intensity levels.

Edge Sharpening

sharpen=<bool>

Applies a standard 3x3 convolution kernel enhancement pass.

Solarize Highlights

solarize=<int>

Inverts pixel intensities lying above a given cutoff percentage.

Binarize Threshold

threshold=<int>

Converts an image into strict 1-bit monochrome artwork.

Unsharp Masking

unsharp_mask=<float>

Sharpens fine edge details via a local unsharp radius subtractor.

Image modifier details

autocontrast: Auto Contrast

  • autocontrast=<bool>

  • Maximizes image contrast automatically by scaling image histogram bounds.

Argument enabled (boolean): Pass ‘true’ to apply auto-contrast or ‘false’ to bypass.

blur: Gaussian Blur

  • blur=<float>

  • Blurs details smoothly using a floating-point radius calculation.

Argument radius (float): The blur radius in pixels (e.g., 2.0).

brightness: Brightness Adjustment

  • brightness=<float>

  • Linearly scales overall image exposure levels.

Argument factor (float): Multiplier where 1.0 is the original image, < 1.0 darkens the image, and > 1.0 brightens it.

contrast: Contrast Adjustment

  • contrast=<float>

  • Scales image contrast boundaries around a gray midpoint.

Argument factor (float): Multiplier where 1.0 is original, < 1.0 reduces contrast (flatter), and > 1.0 increases contrast (punchier).

despeckle: Despeckle Noise

  • despeckle=<bool>

  • Applies a 3x3 median filter to eliminate salt-and-pepper noise.

Argument enabled (boolean): Pass ‘true’ to apply the filter or ‘false’ to bypass.

gamma: Gamma Correction

  • gamma=<float>

  • Applies power-law tone adjustment to modify midtones.

Argument exponent (float): Gamma value where 1.0 is original, < 1.0 lightens midtones, and > 1.0 darkens midtones.

hue: Hue Rotation

  • hue=<float>

  • Rotates the color hue spectrum wheel.

Argument degrees (float): The angle of rotation in degrees, ranging from -180.0 to 180.0.

invert: Invert Channels

  • invert=<bool>

  • Creates a negative effect by flipping color channels.

Argument enabled (boolean): Pass ‘true’ to apply the inversion or ‘false’ to leave the image unchanged.

levels: N-Point Levels Curve

  • levels=<list[float]>

  • Maps image tones using an n-point piecewise linear percentage curve.

Argument points (list of percentages): A comma-separated list of nodes to define the curve (e.g., ‘0,50,100’).

lightness: Lightness Blend

  • lightness=<float>

  • Adjusts color luminance parameters via an HSL shift.

Argument factor (float): Multiplier where 1.0 is original, < 1.0 darkens towards black, and > 1.0 lightens towards white.

posterize: Posterization

  • posterize=<int>

  • Reduces discrete color variations to specific bit depth counts.

Argument bits (integer): The number of bits to keep per color channel, ranging from 1 to 8.

saturation: Saturation Adjustment

  • saturation=<float>

  • Controls color intensity levels.

Argument factor (float): Multiplier where 1.0 is original, > 1.0 increases vibrancy, and 0.0 results in a completely grayscale image.

sharpen: Edge Sharpening

  • sharpen=<bool>

  • Applies a standard 3x3 convolution kernel enhancement pass.

Argument enabled (boolean): Pass ‘true’ to apply sharpening or ‘false’ to bypass.

solarize: Solarize Highlights

  • solarize=<int>

  • Inverts pixel intensities lying above a given cutoff percentage.

Argument threshold_pct (integer): The threshold percentage from 0 to 100 where inversion begins.

threshold: Binarize Threshold

  • threshold=<int>

  • Converts an image into strict 1-bit monochrome artwork.

Argument threshold_pct (integer): The threshold percentage (0-100) where pixels above become white and below become black.

unsharp_mask: Unsharp Masking

  • unsharp_mask=<float>

  • Sharpens fine edge details via a local unsharp radius subtractor.

Argument radius (float): The sharpening radius size in pixels (e.g., 2.0).

Examples

Boost contrast and sharpen page image assets for pages 1 through 5.

pdftl in.pdf modify_images '1-5(contrast=1.3; sharpen=true)' output out.pdf

Tags: in_place, images, modification

Source: pdftl.operations.modify_images

Read online: https://pdftl.readthedocs.io/en/latest/operations/modify_images.html

Type: Operation