| /* | |
| * Copyright (c) 2021, Alliance for Open Media. All rights reserved | |
| * | |
| * This source code is subject to the terms of the BSD 3-Clause Clear License and the | |
| * Alliance for Open Media Patent License 1.0. If the BSD 3-Clause Clear License was | |
| * not distributed with this source code in the LICENSE file, you can obtain it | |
| * at aomedia.org/license/software-license/bsd-3-c-c/. If the Alliance for Open Media Patent | |
| * License 1.0 was not distributed with this source code in the PATENTS file, you | |
| * can obtain it at aomedia.org/license/patent-license/. | |
| */ | |
| The Lanczos resampling library and utilities are developed by Google | |
| initially and contributed to the Alliance for open Media for experiments | |
| related to super-resolution and Adaptive Streaming use cases. | |
| For questions and technical support, please contact debargha@google.com | |
| LIBRARY | |
| ####### | |
| The main library source and header files are: | |
| lanczos_resample.c | |
| lanczos_resample.h | |
| UTILITIES | |
| ######### | |
| Two utilities are provided to resample y4m and yuv videos respectively: | |
| lanczos_resample_y4m (built using source lanczos_resample_y4m.c) | |
| lanczos_resample_y4m (built using source lanczos_resample_yuv.c) | |
| Another utility simply returns the filter parameters for a given | |
| resampling configuration: | |
| lanczos_resample_filter (built using source lanczos_resample_filter.c) | |
| lanczos_resample_y4m | |
| -------------------- | |
| The usage of lanczos_resample_y4m is: | |
| lanczos_resample_y4m | |
| [<Options>] | |
| <y4m_input> | |
| <num_frames> | |
| <horz_resampling_config> | |
| <vert_resampling_config> | |
| <y4m_output> | |
| [<outwidth>x<outheight>] | |
| Notes: | |
| <Options> are optional switches prefixed by '-' as follows: | |
| -bit:<n> - providing bits for filter taps | |
| [default: 14] | |
| -ieb:<n> - providing intermediate extra bits of | |
| prec between horz and vert filtering | |
| clamped to maximum of (15 - bitdepth) | |
| [default: 2] | |
| -ext:<ext_type> - providing the extension type | |
| <ext_type> is one of: | |
| 'r' or 'rep' (Repeat) | |
| 's' or 'sym' (Symmetric) | |
| 'f' or 'ref' (Reflect/Mirror-whole) | |
| 'g' or 'gra' (Grafient preserving) | |
| [default: 'r'] | |
| -win:<win_type> - providing the windowing function type | |
| <win_type> is one of: | |
| 'lanczos' (Repeat) | |
| 'lanczos_dil' (Symmetric) | |
| 'gaussian' (Gaussian) | |
| 'gengaussian' (Generalized Gaussian) | |
| 'cosine' (Cosine) | |
| 'hamming (Hamming) | |
| 'blackman (Blackman) | |
| 'kaiser (Kaiser) | |
| [default: 'lanczos'] | |
| <y4m_input> is the input video in Y4M format | |
| <y4m_output> is the output video in Y4M format | |
| <num_frames> is number of frames to be processed | |
| <horz_resampling_config> and <vert_resampling_config> | |
| are of the form: | |
| <p>:<q>:<Lanczos_a>[:<x0>] where: | |
| <p>/<q> gives the resampling ratio. | |
| <Lanczos_a> is Lanczos parameter. | |
| <x0> is the optional initial offset | |
| [default: centered] | |
| If used, it can be a number in (-1, 1), | |
| or 'c' meaning centered. | |
| which is a shortcut for x0 = (q-p)/(2p) | |
| or 'd' meaning co-sited chroma with centered | |
| luma for use only on sub-sampled chroma, | |
| which is a shortcut for x0 = (q-p)/(4p) | |
| The field can be prefixed by 'i' meaning | |
| using the inverse of the number provided, | |
| If it is desired to provide different config parameters | |
| for luma and chroma, the <Lanczos_a> and <x0> fields | |
| could be optionally converted to a pair of | |
| comma-separated parameters as follows: | |
| <p>:<q>:<Lanczos_al>,<lanczos_ac>[:<x0l>,<x0c>] | |
| where <Lanczos_al> and <lanczos_ac> are | |
| luma and chroma lanczos parameters | |
| <x0l> and <x0c> are | |
| luma and chroma initial offsets | |
| <outwidth>x<outheight> is output video dimensions | |
| only needed in case of upsampling | |
| Resampling config of 1:1:1:0 horizontally or vertically | |
| is regarded as a no-op in that direction | |
| Example usages: | |
| 1a. Downsample 10 frames from Boat_1920x1080_60fps_10bit_420.y4m by | |
| ratio 3/2 horizontally and 4/3 vertically with Lanczos parameter | |
| 6 for both and centered sampling. | |
| lanczos_resample_y4m Boat_1920x1080_60fps_10bit_420.y4m 10 \ | |
| 2:3:6 3:4:6 /tmp/down.y4m | |
| 1b. Reverse the process in 1a. That is, upsample 10 frames from | |
| /tmp/boat.y4m by ratio 3/2 horizontally and 4/3 vertically with | |
| Lanczos parameter 6 for both and centered sampling. The output | |
| dimension desired is specified to be 1920x1080. | |
| lanczos_resample_y4m /tmp/down.y4m 10 3:2:6 4:3:6 /tmp/downup.y4m 1920x1080 | |
| 2a. Similar to 1a, except using left-aligned sampling | |
| lanczos_resample_y4m Boat_1920x1080_60fps_10bit_420.y4m 10 \ | |
| 2:3:6:0 3:4:6:0 /tmp/down.y4m | |
| 2b. Reversing the process in 2a. | |
| lanczos_resample_y4m /tmp/down.y4m 10 3:2:6:0 4:3:6:0 /tmp/downup.y4m \ | |
| 1920x1080 | |
| 3a. Similar to 1a, except using a specified initial offset of 0.125 horizontally | |
| and center aligned sampling vertically | |
| lanczos_resample_y4m Boat_1920x1080_60fps_10bit_420.y4m 10 \ | |
| 2:3:6:0.125 3:4:6 /tmp/down.y4m | |
| 3b. Reversing the process in 3a. | |
| lanczos_resample_y4m /tmp/down.y4m 10 3:2:6:i0.125 4:3:6 /tmp/downup.y4m \ | |
| 1920x1080 | |
| 4a. Similar to 3a, except using symmetric border extension instead of default | |
| repeat. | |
| lanczos_resample_y4m -ext:sym Boat_1920x1080_60fps_10bit_420.y4m 10 \ | |
| 2:3:6:0.125 3:4:6:c /tmp/down.y4m | |
| 4b. Reversing the process in 4a. | |
| lanczos_resample_y4m -ext:sym /tmp/down.y4m 10 3:2:6:i0.125 4:3:6:c \ | |
| /tmp/downup.y4m 1920x1080 | |
| 5a. Downsample 10 frames from Boat_1920x1080_60fps_10bit_420.y4m by | |
| ratio 3/2 horizontally and vertically with Lanczos parameter | |
| 6 for both, centered sampling for luma, co-sited chroma horizontally | |
| and centered chroma vertically. Note this is the most common use | |
| case encountered in practice. | |
| lanczos_resample_y4m Boat_1920x1080_60fps_10bit_420.y4m 10 \ | |
| 2:3:6:c,d 2:3:6 /tmp/down.y4m | |
| 5b. Reversing the process in 5a. | |
| lanczos_resample_y4m /tmp/down.y4m 10 3:2:6:ic,id 3:2:6 \ | |
| /tmp/downup.y4m 1920x1080 | |
| 6a. Similar to 5a except using symmetric border extension, 12-bit | |
| filters, 3 bit intermediate extra precision, and hamming windowing. | |
| lanczos_resample_y4m -ext:sym -bit:12 -ieb:3 -win:hamming \ | |
| Boat_1920x1080_60fps_10bit_420.y4m 10 \ | |
| 2:3:6:c,d 2:3:6 /tmp/down.y4m | |
| 6b. Reversing the process in 6a. | |
| lanczos_resample_y4m -ext:sym -bit:12 -ieb:3 -win:hamming \ | |
| /tmp/down.y4m 10 3:2:6:ic,id 3:2:6 \ | |
| /tmp/downup.y4m 1920x1080 | |
| lanczos_resample_yuv | |
| -------------------- | |
| The usage of lanczos_resample_yuv is similar but with two extra | |
| arguments to specify the input format: | |
| lanczos_resample_yuv | |
| [<Options>] | |
| <yuv_input> | |
| <width>x<height> | |
| <pix_format> | |
| <num_frames> | |
| <horz_resampling_config> | |
| <vert_resampling_config> | |
| <yuv_output> | |
| [<outwidth>x<outheight>] | |
| Notes: | |
| <yuv_input> is the input video in raw YUV format | |
| <yuv_output> is the output video in raw YUV format | |
| <width>x<height> is input video dimensions. | |
| <pix_format> is one of { yuv420p, yuv420p10, yuv420p12, | |
| yuv422p, yuv422p10, yuv422p12, | |
| yuv444p, yuv444p10, yuv444p12 } | |
| All other parameters are the same as the ones used for | |
| lanczos_resample_y4m described above. | |
| lanczos_resample_filter | |
| ----------------------- | |
| Utility to show the filter parameters used for both luma and chroma. | |
| The usage of lanczos_resample_filter is: | |
| lanczos_resample_filter | |
| [<Options>] | |
| <resampling_config> | |
| Notes: | |
| <resampling_config> is in the same format as one specified | |
| in lanczos_resample_y4m above for <horz_resampling_config> | |
| or <vert_resampling_config>. | |
| Example usages: | |
| 7a. lanczos_resample_filter -bit:14 2:3:6 | |
| (shows 14-bit a = 6 filter for 2/3 resampling, x0 = centered) | |
| 7b. lanczos_resample_filter -bit:12 1:2:5:0.125 | |
| (shows 12-bit a = 5 filter for 1/2 resampling, x0 = 0.125) | |
| 7c. lanczos_resample_filter -bit:12 1:2:5:c,d 12 | |
| (shows 12-bit a = 5 filter for 1/2 resampling, | |
| x0 = centered for luma, co-sited for chroma) | |
| 7d. lanczos_resample_filter -bit:12 3:2:6:i0.125 12 | |
| (shows 12-bit a = 5 filter for 3/2 resampling, x0 = inverse of 0.125) | |
| SCRIPTS | |
| ####### | |
| In addition to these utilities, two convenience scripts are provided: | |
| lanczos_downup.sh | |
| lanczos_downcompup.sh | |
| They can be invoked from the build directory directly after a build that | |
| produces lanczos_resample_y4m, aomenc and aomdec applications. | |
| lanczos_downup.sh | |
| ----------------- | |
| The script lanczos_downup.sh resamples a video with specified parameters | |
| and then reverses the process using two lanczos_resample_y4m commands. | |
| The usage for the script is: | |
| Usage: | |
| lanczos_downup.sh [<Options>] | |
| <input_y4m> | |
| <num_frames> | |
| <horz_resampling_config> | |
| <vert_resampling_config> | |
| <downup_y4m> | |
| [<down_y4m>] | |
| Notes: | |
| <Options> are optional switches similar to what is used by | |
| lanczos_resample_y4m utility | |
| <y4m_input> is input y4m video | |
| <num_frames> is number of frames to process | |
| <horz_resampling_config> and <vert_resampling_config> are in format: | |
| <p>:<q>:<Lanczos_a_str>[:<x0>] | |
| similar to what is used by lanczos_resample_y4m utility, with the | |
| enhancement that for <Lanczos_a_str> optionally | |
| two '^'-separated strings for 'a' could be provided instead | |
| of one for down and up-sampling operations respectively if different. | |
| Note each string separated by '^' could have two values for luma | |
| and chroma separated by ','. | |
| So <Lanczos_a_str> could be of the form: | |
| <a_luma_down>,<a_chroma_down>^<a_luma_up>,<a_chroma_up> | |
| if down and up operations use different parameters, or | |
| <a_luma_down>,<a_chroma_down> | |
| if down and up operations use the same parameters. | |
| <downup_y4m> is the output y4m video. | |
| <down_y4m> provides the intermediate resampled file as an | |
| optional parameter. If skipped the intermediate resampled | |
| file is deleted. | |
| Example usages: | |
| 8. Similar to combined use cases 1a and 1b above including both | |
| down and inverse up steps. | |
| 8a. From build directory run: | |
| /path/to/script/lanczos_downup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:6 3:4:6 /tmp/downup.y4m | |
| [Here the intermediate resampled files is not stored] | |
| 8b. From build directory run: | |
| /path/to/script/lanczos_downup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:6 3:4:6 /tmp/downup.y4m \ | |
| /tmp/down.y4m | |
| [Here the intermediate resampled file is stored in /tmp/down.y4m] | |
| 8c. From build directory run: | |
| /path/to/script/lanczos_downup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:8^4 3:4:8^4 /tmp/downup.y4m | |
| [Here Lanczos parameters 8 and 4 are used for down and upscaling | |
| respectively] | |
| 8d. From build directory run: | |
| /path/to/script/lanczos_downup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:6,4^6,4:c,d 3:4:6,4^6,4 /tmp/downup.y4m | |
| [Here Lanczos parameters 6 and 4 are used for luma and chroma | |
| respectively for both down and upscaling. Further centered | |
| luma and co-sited chroma are used horizontally, while centered | |
| luma and chroma sampling are used vertically.] | |
| lanczos_downcompup.sh | |
| --------------------- | |
| The script lanczos_downcompup.sh resamples a video with specified parameters | |
| using lanczos_resample_y4m, then comprsses and decompresses using aomenc and | |
| aomdec respectively, and finally reverse resamples the decompressed video to | |
| the source resolution using another lanczos_resample_y4m command. | |
| The usage for the script is: | |
| Usage: | |
| lanczos_downcompup.sh [<Options>] | |
| <input_y4m> | |
| <num_frames> | |
| <horz_resampling_config> | |
| <vert_resampling_config> | |
| <cq_level>[:<cpu_used>] | |
| <downcompup_y4m> | |
| [[<down_y4m>]:[<downcomp_bit>]:[<downcomp_y4m]] | |
| Notes: | |
| <Options> are optional switches similar to what is used by | |
| lanczos_resample_y4m utility | |
| <y4m_input> is input y4m video | |
| <num_frames> is number of frames to process | |
| <horz_resampling_config> and <vert_resampling_config> are in format: | |
| <p>:<q>:<Lanczos_a_str>[:<x0>] | |
| similar to what is used by lanczos_resample_y4m utility, with the | |
| enhancement that for <Lanczos_a_str> optionally | |
| two '^'-separated strings for 'a' could be provided instead | |
| of one for down and up-sampling operations respectively if different. | |
| Note each string separated by '^' could have two values for luma | |
| and chroma separated by ','. | |
| So <Lanczos_a_str> could be of the form: | |
| <a_luma_down>,<a_chroma_down>^<a_luma_up>,<a_chroma_up> | |
| if down and up operations use different parameters, or | |
| <a_luma_down>,<a_chroma_down> | |
| if down and up operations use the same parameters. | |
| <cq_level>[:<cpu_used>] provides the cq_level parameter of | |
| compression along with an optional cpu_used parameter. | |
| <downcompup_y4m> is the output y4m video. | |
| The last param [[<down_y4m>]:[<downcomp_bit>]:[<downcomp_y4m]] | |
| provides names of intermediate files where: | |
| <down_y4m> is the resampled source | |
| <downcomp_bit> is the compressed resampled bitstream | |
| <downcomp_y4m> is the reconstructed bitstream. | |
| This parameter string is entirely optional. | |
| Besides if provided, each of <down_y4m>, <downcomp_bit> and | |
| <downcomp_y4m> are optional by themselves where each can be | |
| either provided or empty. If empty the corresponding | |
| intermediate file is deleted. | |
| Example usages: | |
| 9. Similar to use cases 8 above with a compression step in between. | |
| 9a. From build directory run: | |
| /path/to/script/lanczos_downcompup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:6 3:4:6 40:5 /tmp/downup.y4m | |
| [Here no intermediate files are stored. | |
| Compression is at cq_level 40 and cpu_used=5] | |
| 9b. From build directory run: | |
| /path/to/script/lanczos_downcompup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:6 3:4:6 40:5 /tmp/downup.y4m \ | |
| /tmp/down.y4m::/tmp/downrec.y4m | |
| [Here the resampled source and its compressed reconstruction are | |
| stoted in /tmp/down.y4m and /tmp/downrec.y4m respectively. | |
| Compression is at cq_level 40 and cpu_used=5]. | |
| 9c. From build directory run: | |
| /path/to/script/lanczos_downcompup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:6 3:4:6 40:5 /tmp/downup.y4m \ | |
| /tmp/down.y4m:/tmp/down.bit:/tmp/downrec.y4m | |
| [Here the resampled source, its compressed bitstream, and the | |
| conpressed reconstruction are stoted in /tmp/down.y4m, | |
| /tmp/downcomp.bit and /tmp/downrec.y4m respectively. | |
| Compression is at cq_level 40 and cpu_used=5]. | |
| 9d. From build directory run: | |
| /path/to/script/lanczos_downcompup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:8^4 3:4:8^4 40:5 /tmp/downup.y4m | |
| [Here Lanczos parameters 8 and 4 are used for down and upscaling | |
| respectively. | |
| Compression is at cq_level 40 and cpu_used=5]. | |
| 9e. From build directory run: | |
| /path/to/script/lanczos_downcompup.sh Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:6,4^6,4:c,d 3:4:6,4^6,4 40:5 /tmp/downup.y4m | |
| [Here Lanczos parameters 6 and 4 are used for luma and chroma | |
| respectively for both down and upscaling. Further centered | |
| luma sampling and co-sited chroma sampling are respectively used | |
| in the horizontal direction, while centered sampling is used for | |
| both luma and chroma vertically. | |
| Compression is at cq_level 40 and cpu_used=5]. | |
| 9f. From build directory run: | |
| /path/to/script/lanczos_downcompup.sh -win:kaiser \ | |
| Boat_1920x1080_60fps_10bit_420.y4m \ | |
| 10 2:3:5:c,d 3:4:5 40:5 /tmp/downup.y4m | |
| [Here Lanczos parameter 5 is used for luma and chroma both | |
| horizontally and vertically, Further, centered luma | |
| sampling and co-sited chroma sampling are used respectively | |
| in the horizontal direction, while centered sampling is used | |
| for both luma and chroma vertically. | |
| Compression is at cq_level 40 and cpu_used=5]. |