Vapoursynth GrainFactory3

From wiki.selur.net
Jump to navigation Jump to search

GrainFactory3 generates film-like grain with separate strength, size and sharpness for dark, mid-tone and bright areas, blended by brightness. It was written by Didée for AviSynth and comes to Hybrid from the old havsfunc.

Filtering → Vapoursynth → Add Grain

GrainFactory3 controls in Hybrid
GrainFactory3 controls in Hybrid

What it does

Three grain layers are generated, each at a reduced or enlarged resolution given by its Size and resized back with a bicubic kernel whose sharpness comes from the Sharpness value. Luma masks with two soft transition zones decide where each layer applies. The grain is added to luma only; chroma stays untouched. Optionally the grain is averaged over time and an extra fine layer is added on top.

Requirements

  • A grain plugin (vs-noise on all platforms, AddGrain on Linux/macOS) and an Expr implementation; works on all platforms.

Settings

Control Parameter Range / values Hybrid default Meaning
Dark: Strength / Sharpness / Size g1str, g1shrp, g1size 0 – 1000 / 0 – 100 / 0.5 – 4 7.0 / 60 / 1.5 Grain of the dark areas.
Mid: Strength / Sharpness / Size g2str, g2shrp, g2size 0 – 1000 / 0 – 100 / 0.5 – 4 5.0 / 66 / 1.2 Grain of the mid-tones.
Bright: Strength / Sharpness / Size g3str, g3shrp, g3size 0 – 1000 / 0 – 100 / 0.5 – 4 3.0 / 80 / 0.9 Grain of the bright areas.
Temp average temp_avg 0 – 100 % 0 Temporal averaging of the grain; needs scene change detection.
On top grain ontop_grain 0 – 1000 0 Strength of an extra fine grain layer.
Dark->Midtone zone (Start/End) th1, th2 0 – 255 24 / 56 Brightness range (8-bit scale) where dark grain fades into mid-tone grain.
Midtone->Bright zone (Start/End) th3, th4 0 – 255 128 / 160 Brightness range (8-bit scale) where mid-tone grain fades into bright grain.
Seed seed −1 – 1000 −1 0 or higher selects a repeatable grain sequence.
Tools: expr – akarin, cranexpr, std – Expr implementation.
Tools: grain – noise, grain (Linux/macOS) – Grain plugin.
Tools: scd – scd, misc (Windows), std, mv scd Scene change detection; only with Temp average above 0.

Example

Default settings on a 10-bit YUV 4:2:0 source (640x356):

# adding grain using GrainFactory3
clip = addGrain.GrainFactory3(clip, tools={'expr': 'akarin', 'scd': 'scd', 'grain': 'noise'})

How Hybrid calls it

  • Works on integer YUV clips.
  • Only values that differ from the script defaults are written, plus the tools.
  • A Sharpness value is disabled while its Size is 1.0, because the layer is then not resized.
  • The zone thresholds are scaled by the script to the bit depth; the grain strengths are scaled by the grain plugin.
  • Hybrid does not check the order of the zones; keep Start below End and the dark zone below the bright zone (equal Dark->Midtone Start and End values cause an error).
  • GrainFactory3 also offers the common options (Masked, ApplyOnlyTo, Merge, OnRegion, Gimmick).

Background

GrainFactory3

Didée's GrainFactory3 is a classic AviSynth script for film-like grain. Its defaults give the dark areas the strongest and coarsest grain and the bright areas the weakest and finest. The VapourSynth version was part of havsfunc; current havsfunc no longer documents it, so Hybrid keeps its own copy.

Sources