Control keys and ranges

set_controls develops one photo. The assistant calls it, and so does an agent connected over MCP. See Assistant tools.

Arguments

Argument	Type	Description
`photograph`	string	Which photo the call is about. Required.
`layer`	string or null	Which layer, by name. Null is the base render.
`adjustments`	array or null	The controls to set, as a key and a value.
`curves`	array or null	The tone curves to redraw.
`style`	string or null	The style to grade from.
`white_balance`	object or null	The light to balance for, as an alternative to `tmp` and `tnt`.

Rules

A value is absolute. A control the call leaves out keeps the value it has.
A value outside the range is refused. Fotometis does not clamp it.
Fotometis checks the whole call before it writes any part of it.
A call that sets tmp and white_balance together is refused. The two say the same thing.
A control of the photo reaches the photo whichever layer the call names.
hdr.headroom is off at 0, and its smallest setting above that is 1. A value between 0 and 1 is refused.
tmp with no value set is the reading of the camera, not 6500.
The three profiled corrections in optics rest at 100, which is the full correction of the profile.

Crop arithmetic

A value is a number, or arithmetic in a string that works out to a number. The arithmetic takes +, -, *, /, and brackets, over numbers and three names. Precedence is ordinary. A string longer than 120 characters is refused, and so is a string that is not arithmetic.

Name	What it holds
`ratio`	The width of the photo over its height, after any quarter turn.
`w`	The width of the crop, as this call leaves it.
`h`	The height of the crop, as this call leaves it.

crop.w is a fraction of the width and crop.h is a fraction of the height, so matched fractions keep the shape of the frame. The fraction that makes a square is a different number on every photo, and 1/ratio is a square on all of them.

A shape A wide by B tall is (A/B)/ratio as the width at full height, or (B/A)*ratio as the height at full width.

The four crop values settle in the order crop.w, crop.h, crop.x, crop.y. A position works out against the size that the same call sets.

Call	Result
`crop.w` `"1/ratio"`	A square, at the full height.
`crop.h` `"(9/16)*ratio"`	16:9, at the full width.
`crop.w` `"(4/5)/ratio"`	4:5 upright, at the full height.
`crop.w` `"0.6/ratio"` with `crop.h` `"0.6"`	A square at 60% of the frame.
`crop.h` `"0.8"` with `crop.w` `"h/ratio"`	The same square, read back from the height.
`crop.w` `"w/2"`	Half the width it has now.
`crop.x` `"(1 - w)/2"`	Centered across.
`crop.y` `"(1 - h)/2"`	Centered down.
`crop.x` `"0.31 - w/3"`	The subject at 0.31, on the left third.
`crop.y` `"0.38 - 2*h/3"`	The horizon at 0.38, on the lower third.

Controls

Each group below gives the wire key, the name in the tool sidebar, the range, and the default.

Style

Group style. The controls belong to the layer.

Key	Control	Range	Default
`sty.amt`	Amount	0 to 100	100

White Balance

Group wb. The controls belong to the layer.

Key	Control	Range	Default
`tmp`	Temperature	2000 to 50000	6500
`tnt`	Tint	-150 to 150	0

Tone

Group tone. The controls belong to the layer.

Key	Control	Range
`ev`	Exposure	-5 to 5
`con`	Contrast	-100 to 100
`hi`	Highlights	-100 to 100
`sh`	Shadows	-100 to 100
`wh`	Whites	-100 to 100
`bl`	Blacks	-100 to 100

Response

Group resp. The controls belong to the layer.

Key	Control	Range	Default
`resp.toe`	Toe	0 to 100	0
`resp.shoulder`	Shoulder	0 to 100	0

Local Contrast

Group lc. The controls belong to the layer.

Key	Control	Range
`lc.fine`	Fine	-100 to 100
`lc.medium`	Medium	-100 to 100
`lc.coarse`	Coarse	-100 to 100

Color

Group color. The controls belong to the layer.

Key	Control	Range	Default
`vib`	Vibrance	-100 to 100	0
`sat`	Saturation	-100 to 100	0

Color Grading

Group grade. The controls belong to the layer.

Key	Control	Range	Default
`grade.shadows.hue`	Shadow Hue	0 to 360	0
`grade.shadows.sat`	Shadow Saturation	0 to 100	0
`grade.midtones.hue`	Midtone Hue	0 to 360	0
`grade.midtones.sat`	Midtone Saturation	0 to 100	0
`grade.highlights.hue`	Highlight Hue	0 to 360	0
`grade.highlights.sat`	Highlight Saturation	0 to 100	0
`grade.global.hue`	Global Hue	0 to 360	0
`grade.global.sat`	Global Saturation	0 to 100	0
`grade.balance`	Balance	-100 to 100	0
`grade.blending`	Blending	0 to 100	50

Color Mixer

Group hsl. The controls belong to the layer.

Eight bands, each with a hue, a saturation, and a luminance. Every one runs -100 to 100, with 0 as the default.

Band	Hue	Saturation	Luminance
Red	`hsl.red.h`	`hsl.red.s`	`hsl.red.l`
Orange	`hsl.orange.h`	`hsl.orange.s`	`hsl.orange.l`
Yellow	`hsl.yellow.h`	`hsl.yellow.s`	`hsl.yellow.l`
Green	`hsl.green.h`	`hsl.green.s`	`hsl.green.l`
Aqua	`hsl.aqua.h`	`hsl.aqua.s`	`hsl.aqua.l`
Blue	`hsl.blue.h`	`hsl.blue.s`	`hsl.blue.l`
Purple	`hsl.purple.h`	`hsl.purple.s`	`hsl.purple.l`
Magenta	`hsl.magenta.h`	`hsl.magenta.s`	`hsl.magenta.l`

Effects

Group fx. The controls belong to the layer.

Key	Control	Range	Default
`grain.amount`	Grain	0 to 100	0
`grain.size`	Grain Size	0 to 100	50
`grain.roughness`	Grain Roughness	0 to 100	50
`hal.amount`	Halation	0 to 100	0
`hal.threshold`	Halation Threshold	0 to 100	70
`hal.radius`	Halation Radius	0 to 100	50

Vignette

Group vig. The controls belong to the photo.

Key	Control	Range	Default
`vig.amount`	Amount	-100 to 100	0
`vig.midpoint`	Midpoint	0 to 100	50
`vig.roundness`	Roundness	-100 to 100	0
`vig.feather`	Feather	0 to 100	50

Noise Reduction

Group nr. The controls belong to the photo.

Key	Control	Range	Default
`nr.lum`	Luminance	0 to 100	0
`nr.detail`	Detail	0 to 100	50
`nr.color`	Color	0 to 100	0

Sharpening

Group sharp. The controls belong to the photo.

Key	Control	Range	Default
`sharp.amount`	Amount	0 to 100	0
`sharp.px`	Radius	0.5 to 3	1
`sharp.mask`	Masking	0 to 100	0

Optics

Group optics. The controls belong to the photo.

Key	Control	Range	Default
`optics.distortion`	Distortion	0 to 100	100
`optics.falloff`	Light Falloff	0 to 100	100
`optics.ca`	Chromatic Aberration	0 to 100	100
`optics.defringe`	Defringe	0 to 100	0

Geometry

Group geo. The controls belong to the photo.

Key	Control	Range	Default
`crop.x`	Crop Left	0 to 1	0
`crop.y`	Crop Top	0 to 1	0
`crop.w`	Crop Width	0 to 1	1
`crop.h`	Crop Height	0 to 1	1
`geo.angle`	Angle	-45 to 45	0
`geo.turn`	Rotate	0 to 3	0
`geo.flipH`	Flip Horizontal	0 to 1	0
`geo.flipV`	Flip Vertical	0 to 1	0
`geo.vertical`	Vertical	-100 to 100	0
`geo.horizontal`	Horizontal	-100 to 100	0
`geo.aspect`	Aspect	-100 to 100	0

Dynamic Range

Group hdr. The controls belong to the photo.

Key	Control	Range	Default
`hdr.headroom`	HDR Headroom	0 to 4	0

Styles

style takes one of these names.

Color: neutral, standard, portrait, cinema, chroma, reversal, terrain, autumn, golden, frost, night, bleach, faded, pastel.

Monochrome: monochrome, silver, ortho, platinum, sepia.

neutral applies no style. sty.amt sets how much of the style is mixed in.