/*
 * Copyright (c) 2020, Alliance for Open Media. All rights reserved
 *
 * This source code is subject to the terms of the BSD 2 Clause License and
 * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
 * was not distributed with this source code in the LICENSE file, you can
 * obtain it at www.aomedia.org/license/software. 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 www.aomedia.org/license/patent.
 */

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].