#  `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](https://pdftl.readthedocs.io/en/latest/operations/modify_images.html)*

*Type: Operation*