Finite Impulse Response Hilbert Transform (``firhilb``)
=======================================================

.. author   jgaeddert Joseph D. Gaeddert <joseph@liquidsdr.org>
.. date     January 1, 1975
.. location Boston, MA
.. header   /doc/firhilb/banner.png
.. keywords firhilb, Hilbert transform, real to complex, complex to real
.. api      firhilbf

The ``firhilbf`` object in liquid implements a finite impulse
response Hilbert transform which
converts between real and complex time series.
The interpolator takes a complex time series and produces real-valued
samples at twice the sample rate.
The decimator reverses the process by halving the sample rate of a
real-valued time series to a complex-valued one.

Typical trade-offs between filter length, side-lobe suppression, and
transition bandwidth apply.
The ``firhilbf`` object uses a half-band filter to implement the
transform as efficiently as possible.
While any filter length can be accepted, the ``firhilbf`` object
internally forces the length to be of the form :math:`n=4m+1`
to reduce the computational load.
A half-band filter of this length has :math:`2m` zeros and :math:`2m+1` non-zero
coefficients.
Of these non-zero coefficients, the center is exactly :math:`1` while the other :math:`2m`
are even symmetric, and therefore only :math:`m` computations are needed.

.. qplot:: series filter/firhilb.c
    :kwargs: {
        "figsize": [12,12],
        "format":
        {
            "xlabel" : "Time [samples]",
            "ylabel" : "Output (Complex)"
        },
        "plots" :
        [
            {
                "series":["x",{"color":"#800000"}],
                "ylabel":"Input (Real)"
            },
            {
                "series":
                [
                    ["y-real",{"color":"#008040"}],
                    ["y-imag",{"color":"#888888"}]
                ]
             },
             {
                "series": ["f0","X0", {"color":"#008040"}]
             }
        ]
        }
    :width: 75%
    :name: fig-firhilb
    :caption:
       ``firhilbf`` (Hilbert transform) decimator demonstration.
       The small signal at :math:`f=0.13` is due to aliasing as a result of
       imperfect image rejection.


A graphical example of the Hilbert decimator can be seen in
[fig-filter-firhilb]
where a real-valued input sinusoid is converted into a complex sinusoid
with half the number of samples.
An example code listing is given below.
Although ``firhilbf`` is a placeholder for both
decimation (real to complex) and
interpolation (complex to real),
separate objects should be used for each task.

.. code-block:: c

    #include <liquid/liquid.h>

    int main() {
        unsigned int m=5;           // filter semi-length
        float slsl=60.0f;           // filter sidelobe suppression level

        // create Hilbert transform objects
        firhilbf q0 = firhilbf_create(m,slsl);
        firhilbf q1 = firhilbf_create(m,slsl);

        float complex x;    // interpolator input
        float y[2];         // interpolator output
        float complex z;    // decimator output

        // ...

        // execute transforms
        firhilbf_interp_execute(q0, x, y);   // interpolator
        firhilbf_decim_execute(q1, y, &z);   // decimator

        // clean up allocated memory
        firhilbf_destroy(q0);
        firhilbf_destroy(q1);
    }


For more detailed examples on Hilbert transforms in liquid,
refer to the files
`examples/firhilb_decim_example.c` and
`examples/firhilb_interp_example.c`
located within the main liquid project directory.
_See also:_ `resamp2` ([section-filter-resamp2]),
FIR filter design ([section-filter-firdes]).


Interface
---------

Listed below is the full interface to the ``firhilb`` family of
objects.

.. api:: firhilb