ps_add_adjustment_layer
Idempotent
Add a non-destructive adjustment layer for tonal and color edits—Curves, Levels, Hue/Saturation, and more—above the active layer.
Instructions
Create a non-destructive adjustment layer above the active layer — hoisted out of the active layer's group by default even though Photoshop's own Mk-AdjL placement rule would otherwise nest it INSIDE that group (pass into_active_group:true to keep that native nesting). Supports the full real-Photoshop tonal/color surface: Curves (with S-curve presets), Levels, Hue/Saturation, Brightness/Contrast, Black & White (with optional tint), Color Balance, Photo Filter (preset or custom color), Vibrance, Channel Mixer, Selective Color, Gradient Map (preset), Exposure (stops + offset + gamma), Color Lookup (3DLUT presets or custom file path), and Invert. Values are editable, maskable, and removable. This is the canonical entry point for tonal/color adjustments — EXCEPT global tone/color on raw-sourced documents, which starts with a Camera Raw develop pass when a camera-raw develop tool is registered (see ps_open_document's is_raw_source); the old destructive bake tools (auto_levels / auto_contrast / desaturate / invert) were removed on 2026-05-31 — if you genuinely need a pixel bake, follow this call with ps_merge (mode=visible). Optionally clips the adjustment to only affect the layer directly below it. If a selection is active at call time, the new layer is automatically masked by it (toggle with mask_from_selection / mask_inverted). For destructive ops that don't have an adjustment-layer equivalent in Photoshop (Shadows/Highlights — single-pass shadow/highlight recovery), use ps_apply_adjustment (type=shadows_highlights) which auto-duplicates the active layer to keep the original intact. Returns context (the new adjustment layer becomes active) plus parent_path — the actual containing-group chain, so placement is never silent.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hue | No | For type=hue_saturation. Hue shift in degrees (-180 to 180). | |
| name | No | Optional name for the new adjustment layer. | |
| type | Yes | Adjustment kind. | |
| gamma | No | For type=levels. Midpoint gamma. | |
| bw_reds | No | For type=black_and_white. Red-channel lightness mapping (-200 to 300). PS default 40. | |
| bw_tint | No | For type=black_and_white. If true, applies a single-color tint over the grayscale conversion (split-toning effect). Pair with bw_tint_hue + bw_tint_saturation. | |
| bw_blues | No | For type=black_and_white. Blue-channel mapping (-200 to 300). PS default 20. | |
| bw_cyans | No | For type=black_and_white. Cyan-channel mapping (-200 to 300). PS default 60. | |
| contrast | No | For type=brightness_contrast. Contrast (-100 to 100). | |
| gm_stops | No | For type=gradient_map. Custom color stops overriding gm_preset — each {red,green,blue (0-255), location (0-100 shadows→highlights), midpoint (5-95, default 50)}. At least 2; sorted by location. E.g. a blue→orange stylized grade: [{red:20,green:40,blue:120,location:0},{red:250,green:150,blue:50,location:100}]. | |
| bw_greens | No | For type=black_and_white. Green-channel mapping (-200 to 300). PS default 40. | |
| exp_gamma | No | For type=exposure. Gamma correction (0.01 to 9.99). PS default 1.0 (identity). Values <1 brighten midtones; >1 darken them. | |
| gm_dither | No | For type=gradient_map. Apply dithering to reduce banding. | |
| gm_preset | No | For type=gradient_map. Preset gradient. "black_to_white" is the canonical tonal B&W via gradient. "sepia" is a warm vintage tone. "tint" maps black→tint_color→white using gm_tint_color_hex. For arbitrary color mappings pass gm_stops instead (overrides the preset). | black_to_white |
| lightness | No | For type=hue_saturation. Lightness (-100 to 100). | |
| pf_preset | No | For type=photo_filter. Named filter preset. If set, takes precedence over pf_color_hex. Common picks: warming_85 (warm portraits), cooling_80 (cool down skies), sepia (vintage), warming_lba / cooling_lbb (subtle classic film), underwater. | |
| sc_colors | No | For type=selective_color. Nested per-color-family CMYK shifts. Each family is an object {cyan, magenta, yellow, black} with values -100 to 100. Omitted families default to zero. Families: reds, yellows, greens, cyans, blues, magentas, whites, neutrals, blacks. | |
| sc_method | No | For type=selective_color. "relative" scales adjustments by the existing color amount (subtle, the PS default). "absolute" applies fixed CMYK shifts (more aggressive). | relative |
| thr_level | No | For type=threshold. Threshold luminance (1-255). PS default 128. Pixels brighter than the threshold become white; darker become black. | |
| brightness | No | For type=brightness_contrast. Brightness (-100 to 100). | |
| bw_yellows | No | For type=black_and_white. Yellow-channel mapping (-200 to 300). PS default 60. | |
| exp_offset | No | For type=exposure. Offset shift (-0.5 to +0.5). PS default 0. Shifts the black point — most useful for paired with negative exposure for moody/crushed-shadow looks. | |
| gm_reverse | No | For type=gradient_map. Reverse the gradient direction. | |
| pf_density | No | For type=photo_filter. Filter strength (1-100). PS default 25. | |
| pos_levels | No | For type=posterize. Number of tonal levels per channel (2-255). PS default 4. Lower values yield a more graphic / illustration look (2-4); higher values are gentler. | |
| saturation | No | For type=hue_saturation. Master saturation (-100 to 100). Note: vibrance has its own vib_saturation param. | |
| black_point | No | For type=levels. Input black (0-255). | |
| bw_magentas | No | For type=black_and_white. Magenta-channel mapping (-200 to 300). PS default 80. | |
| bw_tint_hue | No | For type=black_and_white when bw_tint=true. Tint hue in degrees (-180 to 180). Default 220 (cool blue). | |
| cl_lut_name | No | For type=color_lookup. The LUT file name as Photoshop sees it. Common built-in 3DLUT presets: "3Strip.look", "Bleach Bypass.look", "Candlelight.CUBE", "Crisp_Warm.look", "Crisp_Winter.look", "DropBlues.3DL", "EdgyAmber.3DL", "FoggyNight.3DL", "FuturisticBleak.3DL", "Horror Blue.3DL", "LateSunset.3DL", "Moonlight.3DL", "NightFromDay.CUBE", "Soft_Warming.look", "TealMagentaGold.look", "TealOrangePlusContrast.3DL". For custom files, pass the absolute path. | |
| cl_lut_type | No | For type=color_lookup. Which LUT slot to load into. Default 3dlut covers .cube / .3dl / .look files (the photographer-typical case). abstract and device_link are for color-management workflows. | 3dlut |
| cm_b_from_b | No | For type=channel_mixer. Blue-from-Blue weight. PS default 100. | |
| cm_b_from_g | No | For type=channel_mixer. Blue-from-Green weight. | |
| cm_b_from_r | No | For type=channel_mixer. Blue-from-Red weight. | |
| cm_g_from_b | No | For type=channel_mixer. Green-from-Blue weight. | |
| cm_g_from_g | No | For type=channel_mixer. Green-from-Green weight. PS default 100. | |
| cm_g_from_r | No | For type=channel_mixer. Green-from-Red weight. | |
| cm_r_from_b | No | For type=channel_mixer. Red-from-Blue weight. Default 0. | |
| cm_r_from_g | No | For type=channel_mixer. Red-from-Green weight. Default 0. | |
| cm_r_from_r | No | For type=channel_mixer with cm_monochrome=false. Red-from-Red weight. PS default 100 (identity). | |
| white_point | No | For type=levels. Input white (0-255). | |
| exp_exposure | No | For type=exposure. Exposure shift in STOPS (-20 to +20). PS default 0. Photographer-feeling tonal control — 1 stop ≈ 2× linear brightness. | |
| pf_color_hex | No | For type=photo_filter. Custom filter color as a hex string like "#EC8A00". Only used when pf_preset is not set. | |
| vib_vibrance | No | For type=vibrance. Vibrance (-100 to 100). Saturation boost that protects skin tones and already-saturated colors. Gentler than hue_saturation.saturation. | |
| clip_to_below | No | If true, the adjustment only affects the layer directly below. | |
| cm_b_constant | No | For type=channel_mixer. Constant added to Blue output. | |
| cm_g_constant | No | For type=channel_mixer. Constant added to Green output. | |
| cm_monochrome | No | For type=channel_mixer. If true, output is single gray channel and only cm_gray_* params apply. If false, the per-output cm_{r,g,b}_from_* and cm_{r,g,b}_constant params apply for RGB→RGB remix. | |
| cm_r_constant | No | For type=channel_mixer. Constant added to Red output. | |
| curves_preset | No | For type=curves only. Default sCurveMedium. | sCurveMedium |
| mask_inverted | No | Only meaningful when mask_from_selection is true AND there is an active selection. If true, the resulting mask is inverted — so the adjustment affects EVERYTHING OUTSIDE the selection rather than inside. Common idiom: "I selected the sky but want to adjust everything else." Defaults to false. | |
| cm_gray_from_b | No | For type=channel_mixer with cm_monochrome=true. Blue contribution to gray. PS default 20. | |
| cm_gray_from_g | No | For type=channel_mixer with cm_monochrome=true. Green contribution to gray. PS default 40. | |
| cm_gray_from_r | No | For type=channel_mixer with cm_monochrome=true. Red contribution to gray (-200 to 200). PS default 40. | |
| vib_saturation | No | For type=vibrance. Master saturation override (-100 to 100). Affects all colors equally. | |
| cm_gray_constant | No | For type=channel_mixer with cm_monochrome=true. Constant added to gray output. | |
| gm_tint_color_hex | No | For type=gradient_map with gm_preset=tint. Mid-tone tint color as a hex string like "#5588CC". Only used when gm_preset=tint. | #5588CC |
| into_active_group | No | Photoshop's Mk-AdjL descriptor carries no placement target, so with a GROUP active it would natively nest the new layer INSIDE that group. Default false hoists the new layer back out so it lands above the active layer/group as a sibling, matching this tool's documented placement. Pass true to keep the new layer nested inside the active group instead. | |
| bw_tint_saturation | No | For type=black_and_white when bw_tint=true. Tint saturation (0 to 100). Default 25. | |
| cb_shadows_cyan_red | No | For type=color_balance. Shadows: cyan↔red shift (-100 cyan to +100 red). Default 0. | |
| mask_from_selection | No | If true (default) and there is an active selection at the time of this call, the new adjustment layer is automatically masked by that selection. If false, any existing selection is dropped first and the new layer is unmasked (full canvas). Photoshop's native Mk-with-active-selection behavior does the masking; this flag makes it explicit and toggleable. | |
| cb_midtones_cyan_red | No | For type=color_balance. Midtones: cyan↔red shift. | |
| cb_highlights_cyan_red | No | For type=color_balance. Highlights: cyan↔red shift. | |
| cb_preserve_luminosity | No | For type=color_balance. Preserve luminosity while shifting color. Default true (matches the PS dialog default). | |
| cb_shadows_yellow_blue | No | For type=color_balance. Shadows: yellow↔blue shift (-100 yellow to +100 blue). | |
| pf_preserve_luminosity | No | For type=photo_filter. Preserve luminosity. Default true. | |
| cb_midtones_yellow_blue | No | For type=color_balance. Midtones: yellow↔blue shift. | |
| cb_shadows_magenta_green | No | For type=color_balance. Shadows: magenta↔green shift (-100 magenta to +100 green). | |
| cb_highlights_yellow_blue | No | For type=color_balance. Highlights: yellow↔blue shift. | |
| cb_midtones_magenta_green | No | For type=color_balance. Midtones: magenta↔green shift. | |
| cb_highlights_magenta_green | No | For type=color_balance. Highlights: magenta↔green shift. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| clipped | No | ||
| context | No | ||
| created | No | ||
| hoisted | No | True when the new layer had to be moved back out of the previously-active group to honor into_active_group:false (the default). False when it landed correctly on its own, or when the move-back itself failed — check the layer tree if this matters and hoisted is false. | |
| clipError | No | ||
| layerKind | No | ||
| layerName | No | ||
| kindMatches | No | ||
| parent_path | No | The containing-group name chain (outermost first), empty array at the document root. | |
| mask_applied | No | ||
| had_selection | No | ||
| mask_inverted | No | ||
| customValuesApplied | No | ||
| raw_develop_pending | No | Advisory, present only when the active document was opened from a raw source this session and no Camera Raw develop pass has run yet. Nothing failed — the layer was created. Global tone/color on raw sources normally starts with the camera-raw develop pass; ignore if the user prescribed this exact layer or the file was already developed elsewhere. | |
| mask_inversion_error | No |