Preprocessing Filters
Introduction
Visionular's pre-processing filters have implemented functions such as denoising, sharpening, ROI detection, and conversion between HDR and SDR.
The pre-processing is implemented and invoked in the form of FFmpeg filters. When users use Visionular's FFmpeg, they can call Visionular's pre-processing filters just like calling FFmpeg’s built-in filters. For specific invocation methods, please refer to the following text.
wzoptimize
The wzoptimize filter implements functions such as sharpening, denoising, and enhancement which can improve the subjective quality of transcoding videos. The specific parameters are as follows:
| Parameter | Data Type {Value Range} | Default value | Description |
|---|---|---|---|
sharptype |
string {"0","1","2","3","4","5"} | 3 | Different values represent different sharpening methods: 0 and 2 represent sharpening with a 3x3 convolution kernel, 1 and 3 represent sharpening with a 5x5 convolution kernel, with 2 and 3 offering additional detail enhancement compared to 0 and 1. The value 4 represents CAS sharpening, and 5 represents sharpening that suppresses black and white edges. |
autoenh |
int {0,1,2,3} | 1 | Adaptively adjust the intensity of yenh, with uvenh following the adjustment of yenh. When autoenh is set to 1/2/3, the configurations of yenh and uvenh are ineffective. When autoenh takes the values 1, 2, or 3, it represents different adaptive sharpening strategies. When autoenh is set to 0, the adaptive sharpening intensity aenh_strength is ineffective. |
aenh_strength |
float {1.0~10.0} | 2.2 | The intensity of adaptive sharpening and it takes effect when autoenh > 0. The larger the value, the larger the generated yenh value. |
yenh |
float {0, or >=1.0} | 1.4 | Luminance sharpening intensity, 0 indicates disabled; only takes effect when autoenh is 0, otherwise it is automatically adjusted by aenh_strength. |
uvenh |
float {0, or >=1.0} | 1.0 | Chrominance sharpening intensity, 0 indicates disabled; only takes effect when autoenh is 0, otherwise it is automatically adjusted by aenh_strength. |
ymaxdiff |
int {0~128} | 0 | The maximum increasing value of sharpening amplitude, the smaller this value, the fewer white edges, and accordingly, the sharpening intensity will also be weakened. When autoenh is set to 0, the set value is the final value. If ymaxdiff is set to 0, it will default to 20. When autoenh is 1,2 or 3, ymaxdiff will adaptively select a value, and the set value is the maximum of the adaptive value. If ymaxdiff is set to 0, then ymaxdiff will adaptively reach a maximum of 100. If set to 20, then ymaxdiff will adaptively reach a maximum of 20. |
uvmaxdiff |
int {0~128} | 10 | The maximum increasing value of chroma sharpening amplitude, which will not adapt regardless of the value of autoenh. |
yenhmin |
float {0, or >=1.0} | 0 | Force the minimum sharpening intensity of yenh, 0.0 indicates disabled; only takes effect when autoenh is 1, 2 or 3. |
yEnhEps |
float {0~10.0} | 3.0 | The capability to suppress noise amplification during the sharpening process. The larger the value, the less noise is amplified by sharpening, but simultaneously, the detail enhancement capability is weakened. |
ydetail |
float {0~1.0} | 0 | Detail enhancement, 0.0 indicates disabled; takes effect when sharptype is 2 or 3. It is recommended to set it between 0.1 and 0.2. |
decay |
float {0~1.0} | 0 | Attenuate sharpening based on the magnitude of motion, meaning that sharpening is reduced during faster motion, while the ROI region is never weakened. It is disabled by default, and if enabled, a setting of 0.9 is recommended. |
yenhroi |
float {-1.0 or >=1.0} | -1.0 | The yenh value of the ROI region, when yenhroi is set to -1.0, the sharpening value of the ROI region is yenh. |
uvenhroi |
float {-1.0 or >=1.0} | -1.0 | The uvenh value of the ROI region, when uvenhroi is set to -1.0, the value of uvenhroi will be set to uvenh internally. |
yenhminroi |
float {-1.0 or >=1.0} | -1.0 | The yenhmin value of the ROI region, when yenhminroi is set to -1.0, the value of yenhminroi will be set to yenhmin internally. |
ymaxdiffroi |
int {-1 or 0~128} | -1 | The ymaxdiff value of the ROI region, when ymaxdiffroi is set to -1.0, the value of ymaxdiffroi will be set to ymaxdiff internally. |
uvmaxdiffroi |
int {-1 or 0~128} | -1 | The uvmaxdiff value of the ROI region, when uvmaxdiffroi is set to -1.0, the value of uvmaxdiffroi will be set to uvmaxdiff internally. |
ydetailroi |
float {-1.0 or 0~1.0} | -1.0 | The ydetail value of the ROI region, when ydetailroi is set to -1.0, the value of ydetailroi will be set to ydetail internally. |
smthtype |
string {"0","1"} | 1 | 0 and 1 represent different denoising methods, it is recommended to use the default value. |
ynslvl |
float {>=0} | 3.0 | Denoising strength for the luminance channel. |
uvnslvl |
float {>=0} | 0 | Denoising strength for the chrominance channel. |
ynslvlroi |
float {-1.0 or >=0} | -1.0 | The ynslvl value of the ROI region, when ynslvlroi is set to -1.0, the value of ynslvlroi will be set to ynslvl internally. |
uvnslvlroi |
float {-1.0 or >=0} | -1.0 | The uvnslvl value of the ROI region, when uvnslvlroi is set to -1.0, the value of uvnslvlroi will be set to uvnslvl internally. |
enhtype |
string {NULL,sim,sim1,sim2,simroi,sim1roi,sim2roi} | NULL | sim, sim1, and sim2 represent three enhancement models with different complexities and effects, ranging from high to low complexity. sim is suitable for image transcoding, sim1 can improve clarity to a certain extent, and sim2 mainly increases detail. simroi, sim1roi, and sim2roi indicate that only the ROI region is processed. |
weightfg |
float {0~1.0} | 1.0 | This setting takes effect when enhtype is set to sim, sim1, sim2, simroi, sim1roi, or sim2roi, indicating the weight of the ROI region enhancement when fused with the source. When weightfg is set to 1, the enhanced result is used entirely, and when weightfg is set to 0, no enhancement is applied. |
weightbg |
float {0~1.0} | 1.0 | This setting takes effect when enhtype is set to sim, sim1, sim2, indicating the weight of the non-ROI region enhancement when fused with the source. When weightbg is set to 1, the enhanced result is used entirely, and when weightbg is set to 0, no enhancement is applied. |
thrnum |
int {0~16} | 1 | The cpu thread number. |
Parameter example 1：
-vf wzoptimize=aenh_strength=2.5:ynslvl=1.0
Parameter example 2：
-vf wzoptimize=aenh_strength=2.8:decay=0.9:yenhmin=1.4:yenhminroi=2.0:smthtype=1:ynslvl=1.0:ynslvlroi=0:sharptype=3:uvenh=0:uvnslvl=0:enhtype=sim1:weightfg=0.7:weightbg=0.7:thrnum=4
wzaipreopt
wzaipreopt filter mainly supports face, human body, and text detection. The detection results are used in conjunction with the wzoptimize filter and encoder. The ROI detection results of wzaipreopt are transmitted to the wzoptimize filter and encoder through a shared memory within FFmpeg. wzoptimize filter can apply specific pre-processing methods and intensities to the ROI areas, and the encoder will protect different ROI areas with different intensities. The specific parameters are as follows:
| Parameter | Data Type {Value Range} | Default value | Description |
|---|---|---|---|
enhtype |
string {NULL,face,text,body} | NULL | The supported detection types currently include face, human body, and text detection. |
modpth |
string | NULL | The model path，when the model folder and FFmpeg are placed in the same directory, no additional settings are required. |
thrnum |
int {0~16} | 1 | The cpu thread number. |
track |
int {0,1} | 1 | Whether to enable tracking strategy when doing the detection. |
speed |
int {0~6} | 3 | The speed level for face, text, and human body detection: the larger the value, the slower the speed. |
text-per |
int {0~1000} | 100 | Text detection frame extraction interval. |
Parameter example:
-vf wzaipreopt=enhtype=face,wzaipreopt=enhtype=text,wzaipreopt=enhtype=body,wzoptimize=autoenh=0:yenh=1.5:yenhroi=2.0:ynslvl=1.0:ynslvlroi=2.0
wzhdr
Visionular's wzhdr preprocessing filter brings professional-grade dynamic range conversion to the video workflow. This powerful tool allows seamless transformation between HDR and SDR formats with precise control over brightness, color consistency, and processing speed.
Whether you need to convert HDR to SDR, translate between HLG and PQ formats, or simply adjust HDR brightness without changing formats, our solution delivers exceptional results.
Check out the parameter table below to learn more about customization options like peak brightness settings, color normalization, and performance optimization capabilities. The specific parameters are as follows:
| Parameter | Data Type {Value Range} | Default value | Description |
|---|---|---|---|
tonemap |
string {hdr2sdr, hlg2pq, pq2hlg, sdr2pq, sdr2hlg, hdr2hdr} |
NULL | Optional Parameters: NULL: No conversion or adjustment is performed. hdr2sdr: Convert HDR video to SDR format. hlg2pq: Convert HLG (Hybrid Log-Gamma) video to PQ (Perceptual Quantizer) format. pq2hlg: Convert PQ video to HLG format. sdr2pq: Converts SDR video to PQ format. sdr2hlg: Converts SDR video to HLG format. hdr2hdr: Adjust the brightness of HDR video without changing the format. |
peak |
int {0-10000} | 500 | Set the target display peak brightness. For MacBook, set to 500. For iPhone, set to 1000. |
norm_out |
bool {0,1} | 0 | Whether to enforce normalization (forcing the color space and transformation matrix to be consistent with the electro-optical transfer function). For example, if the input is: (COLORPRIM BT2020, COLOR TRANS BT709, COLOR COEFF BT709), setting this parameter will enforce the output to be: (COLOR PRIM BT709, COLOR TRANS BT709, COLOR COEFF BT709). It will also transform the data format accordingly to ensure that the input and output appear color-consistent. |
thread_num |
int {0~16} | 0 | Number of threads. If set to 0, all CPU cores will be enabled. |
lum_scale |
float {0~10.0} | 1.0 | Parameter for hdr2hdr, specifically used to adjust the brightness of HDR videos without converting the format. 0 or 1.0 indicates no brightness scaling. Less than 1.0 makes the video darker. Greater than 1.0 makes the video brighter. |
dark_ratio |
float {0-1.0} | 0.3 | Parameter for hdr2hdr, which generally does not need to be changed. |
Parameter examples:
convert hdr to sdr: ./ffmpeg -i input.mp4 -vf wzhdr=tonemap=hdr2sdr -pix_fmt yuv420p output.mp4
specify the HDR to SDR speed level: ./ffmpeg -i input.mp4 -vf wzhdr=tonemap=hdr2sdr:speed=0 -pix_fmt yuv420p output.mp4
yuv format: ./ffmpeg -colorspace bt2020nc -color_primaries bt2020 -color_trc smpte2084 -pix_fmt yuv420p10le -s 512x512 -i YUV10_512x512.I444P10.yuv -vf wzhdr=tonemap=hdr2sdr -pix_fmt yuv420p pq_512x512.yuv
hlg2pq: ./ffmpeg -i input.mp4 -vf wzhdr=tonemap=hlg2pq -pix_fmt yuv420p10le output.mp4
pq2hlg: ./ffmpeg -i input.mp4 -vf wzhdr=tonemap=pq2hlg -pix_fmt yuv420p10le output.mp4
sdr2pq: ./ffmpeg -i input.mp4 -vf wzhdr=tonemap=sdr2pq -pix_fmt yuv420p10le output.mp4
sdr2hlg: ./ffmpeg -i input.mp4 -vf wzhdr=tonemap=sdr2hlg -pix_fmt yuv420p10le output.mp4
lum_scale(lum_scale should be used in conjunction with hdr2hdr and cannot be used alone): ./ffmpeg -i input.mp4 -vf wzhdr=tonemap=hdr2hdr:lum_scale=0.5 output.mp4
Attention: When using the wzhdr filter, do not cascade it with the format filter or the scale filter, as both of these types of filters will change the format of the input source. If scaling is required, use the -s parameter, and specify the format using the -pix_fmt parameter as follows:
./ffmpeg -i input.mp4 -s 1280x720 -vf wzhdr=tonemap=hdr2sdr -pix_fmt yuv420p output.mp4