Graduated ND filter transition calculator

Invalid meters, inverted sky and land readings, and out-of-range horizons fail with invalid_input and are not billed.

How sky and foreground EV become a GND strength

A graduated ND filter is specified in photographic stops, which are the same units as exposure value. Values under half a stop collapse to zero and the label no filter, because a one-stop slab would over-darken a nearly balanced scene. Values above five clamp to a five-stop recommendation and add a short note that stacking or exposure blending will serve better than a single slab. If a spot meter (or the camera in spot mode) reports sky_ev of fifteen for the bright sky and foreground_ev of twelve for the darker land, the scene holds three stops of contrast: delta_stops equals sky_ev minus foreground_ev. That three-stop gap is exactly what a 0.9 hard or soft GND is sold to remove. Optional keep_stops lets you leave a little natural contrast so the sky does not look as dark as the grass; needed_stops is then delta_stops minus keep_stops. The engine rounds needed_stops to the nearest integer in the closed set zero through five, which matches the commercial ladder ND2, ND4, ND8, ND16, and ND32 (optical densities 0.3, 0.6, 0.9, 1.2, and 1.5). The dark portion transmits one over two to the power of recommended_stops, so a three-stop GND passes 12.5 percent of the skylight. remaining_contrast_stops is the scene contrast left after that recommended slab. None of this invents a meter reading: if the sky is actually darker than the land the request is rejected, because a sky-weighted graduate would make the imbalance worse rather than better.

Hard, soft, and reverse transitions on the horizon

Set horizon_type to flat for a seascape, lake, or prairie with a straight line; the calculator answers with a hard-edge style and a nominal ten percent band centered on the horizon so the fade does not smear into trees or water. Set horizon_type to irregular for mountains, forests, or a broken skyline; the answer is a soft-edge style with a fifty percent band so the gradient can hide behind peaks instead of drawing a visible stripe across them. Set horizon_type to sunset when the sun sits on the horizon and the brightest band is a strip rather than the zenith; the answer is a reverse graduate that stays clear below the horizon, is darkest on the horizon line, and fades toward the top over about thirty percent of the frame. horizon_percent is measured from the bottom of the frame (zero at the bottom edge, one hundred at the top) and defaults to fifty. Optional filter_height_mm overrides the 100 millimetre default so a 75 millimetre or 150 millimetre holder reports start, end, and width in its own units.

Input contract, failures, and where the numbers are used

Optional output keys that do not apply, such as the stacking note when contrast is within five stops, are omitted rather than set to null. POST JSON with required finite sky_ev and foreground_ev in the interval from minus twenty to thirty, and horizon_type set to the string flat, irregular, or sunset. Optional horizon_percent must lie in zero to one hundred inclusive, optional keep_stops in zero to ten, and optional filter_height_mm in twenty to two hundred. Aliases such as ev_sky, fg_ev, style, and filter_mm are accepted so worksheets and typed forms reuse the same contract. On success the body echoes the inputs, then reports delta_stops, needed_stops, recommended_stops, optical_density, nd_factor, nd_label, gnd_label, transition_style, the start, end, center, and width of the fade in both percent and millimetres, remaining_contrast_stops, transmission and transmission_percent of the dark half, and a filter_needed flag. A formula string and the method tag graduated_nd_transition make API clients self-describing. Missing meters, non-finite numbers, an inverted sky that is darker than the land, an unknown horizon_type, or out-of-range percents fail with invalid_input naming the field. Those failures do not consume prepaid balance. Pair this endpoint with your own holder marks or live-view overlay if you need a drawing; the capability only computes stops and placement and never touches image bytes.