{"id":13430886,"url":"https://github.com/berndporr/iir1","last_synced_at":"2025-04-13T14:08:03.963Z","repository":{"id":3142090,"uuid":"4171255","full_name":"berndporr/iir1","owner":"berndporr","description":"DSP IIR realtime filter library written in C++","archived":false,"fork":false,"pushed_at":"2024-12-18T22:33:15.000Z","size":13501,"stargazers_count":684,"open_issues_count":1,"forks_count":145,"subscribers_count":29,"default_branch":"master","last_synced_at":"2025-04-13T14:07:56.922Z","etag":null,"topics":["bandpass","bandpass-filter","bandstop","bandstop-filter","c-plus-plus","filter","filter-plugin","filtering-library","filters","highpass","highpass-filter","iir","linux","lowpass","lowpass-filter","osx","sample-realtime-filtering","signal-processing","ubuntu","windows"],"latest_commit_sha":null,"homepage":"http://berndporr.github.io/iir1/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/berndporr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-04-29T00:04:15.000Z","updated_at":"2025-04-09T11:30:37.000Z","dependencies_parsed_at":"2024-01-31T09:03:46.257Z","dependency_job_id":"62c22cd7-2734-4a98-b5af-5827cfbc5036","html_url":"https://github.com/berndporr/iir1","commit_stats":{"total_commits":337,"total_committers":18,"mean_commits":18.72222222222222,"dds":0.1483679525222552,"last_synced_commit":"9ef2a04ac3a44a8762b6a209c18e3bdb00394e5b"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berndporr%2Fiir1","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berndporr%2Fiir1/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berndporr%2Fiir1/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berndporr%2Fiir1/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/berndporr","download_url":"https://codeload.github.com/berndporr/iir1/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724634,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bandpass","bandpass-filter","bandstop","bandstop-filter","c-plus-plus","filter","filter-plugin","filtering-library","filters","highpass","highpass-filter","iir","linux","lowpass","lowpass-filter","osx","sample-realtime-filtering","signal-processing","ubuntu","windows"],"created_at":"2024-07-31T02:00:58.714Z","updated_at":"2025-04-13T14:08:03.932Z","avatar_url":"https://github.com/berndporr.png","language":"C++","funding_links":[],"categories":["C++","DSP","Data processing"],"sub_categories":["DSP and Filtering"],"readme":"# DSP IIR Realtime C++ filter library\n\n![alt tag](title.png)\n\n - High performance\n - Realtime sample in - sample out processing\n - Butterworth, RBJ, Chebychev filters\n - Lowpass, highpass, bandpass and bandstop filters\n - Template based header-only filter functions\n - Cross platform: Linux, Windows and Mac\n\nAn infinite impulse response (IIR) filter library for\nLinux, Mac OSX and Windows\nwhich implements Butterworth, RBJ, Chebychev filters\nand can easily import coefficients generated by Python (scipy).\n\nThe filter processes the data sample by sample for realtime\nprocessing.\n\nIt uses templates to allocate the required memory so that\nit can run without any malloc / new commands.\nMemory is allocated at compile time\nso that there is never the risk of memory leaks.\n\nAll realtime filter code is in the header files which guarantees\nefficient integration into the main program and the compiler\ncan optimise both filter code and main program at the same time.\n\n## C++ code\nAdd the following include statement to your code:\n```\n#include \"Iir.h\"\n```\n\nThe general coding approach is that first the filter is\ninstantiated specifying its order, then the\nparameters are set with the function `setup` and\nthen it's ready to be used for sample by sample realtime filtering.\n\n### Instantiating the filter\nThe idea is to allocate the memory of the\nfilter at compile time with a template argument to avoid any new\ncommands. This prevents memory leaks and can be optimised at compile\ntime. The `order` provided to the template (for example here for a\nlowpass filter):\n```\nIir::Butterworth::LowPass\u003corder\u003e f;\n```\nis used as the default order by the `setup` command below\nbut can be overridden by a lower order if required.\n\n### Setting the filter parameters: `setup`\nAll filters are available as lowpass, highpass, bandpass and bandstop/notch\nfilters. Butterworth / Chebyshev offer also low/high/band-shelves with\nspecified passband gain and 0dB gain in the stopband.\n\nThe frequencies can either be analogue ones against the sampling rate\nor normalised ones between 0..1/2 where 1/2 is the Nyquist frequency. Note\nthat normalised frequencies are simply f = F/Fs and are in units of 1/samples.\nInternally the library uses normalised frequencies and the setup commands\nsimply divide by the sampling rate if given. Choose between:\n 1. `setup`: sampling rate and the analogue cutoff frequencies\n 2. `setupN`: normalised frequencies in 1/samples between f = 0..1/2 where 1/2 = Nyquist.\n\nBy default `setup` uses the order supplied by the template argument but\ncan be overridden by lower filter orders.\n\nSee the header files in `\\iir` or the documentation for the arguments\nof the `setup` commands.\n\nThe examples below are for lowpass filters:\n\n1. Butterworth -- `Butterworth.h`\nStandard filter suitable for most applications. Monotonic response.\n```\nconst int order = 4; // 4th order (=2 biquads)\nIir::Butterworth::LowPass\u003corder\u003e f;\nconst float samplingrate = 1000; // Hz\nconst float cutoff_frequency = 5; // Hz\nf.setup (samplingrate, cutoff_frequency);\n```\nor specify a normalised frequency between 0..1/2:\n```\nf.setupN(norm_cutoff_frequency);\n```\n\n2. Chebyshev Type I -- `ChebyshevI.h`\nWith permissible passband ripple in dB.\n```\nIir::ChebyshevI::LowPass\u003corder\u003e f;\nconst float passband_ripple_in_db = 5;\nf.setup (samplingrate,\n         cutoff_frequency,\n         passband_ripple_in_dB);\n```\nor specify a normalised frequency between 0..1/2:\n```\nf.setupN(norm_cutoff_frequency,passband_ripple_in_dB);\n```\n\n\n3. Chebyshev Type II -- `ChebyshevII.h`\nWith worst permissible stopband rejection in dB.\n```\nIir::ChebyshevII::LowPass\u003corder\u003e f;\ndouble stopband_ripple_in_dB = 20;\nf.setup (samplingrate,\n         cutoff_frequency,\n         stopband_ripple_in_dB);\n```\nor specify a normalised frequency between 0..1/2:\n```\nf.setupN(norm_cutoff_frequency,stopband_ripple_in_dB);\n```\n\n4. RBJ -- `RBJ.h`\n2nd order filters with cutoff and Q factor.\n```\nIir::RBJ::LowPass f;\nconst float cutoff_frequency = 100;\nconst float Q_factor = 5;\nf.setup (samplingrate, cutoff_frequency, Q_factor);\n```\nor specify a normalised frequency between 0..1/2:\n```\nf.setupN(norm_cutoff_frequency, Q_factor);\n```\n\n5. Designing filters with Python's scipy.signal -- `Custom.h`\n```\n########\n# Python\n# See \"elliptic_design.py\" for the complete code.\nfrom scipy import signal\norder = 4\nsos = signal.ellip(order, 5, 40, 0.2, 'low', output='sos')\nprint(sos) # copy/paste the coefficients over \u0026 replace [] with {}\n\n///////\n// C++\n// part of \"iirdemo.cpp\"\nconst double coeff[][6] = {\n\t\t{1.665623674062209972e-02,\n\t\t -3.924801366970616552e-03,\n\t\t 1.665623674062210319e-02,\n\t\t 1.000000000000000000e+00,\n\t\t -1.715403014004022175e+00,\n\t\t 8.100474793174089472e-01},\n\t\t{1.000000000000000000e+00,\n\t\t -1.369778997100624895e+00,\n\t\t 1.000000000000000222e+00,\n\t\t 1.000000000000000000e+00,\n\t\t -1.605878925999785656e+00,\n\t\t 9.538657786383895054e-01}\n\t};\nconst int nSOS = sizeof(coeff) / sizeof(coeff[0]); // here: nSOS = 2 = order / 2\nIir::Custom::SOSCascade\u003cnSOS\u003e cust(coeff);\n```\n\n### Realtime filtering sample by sample\nSamples are processed one by one. In the example below\na sample `x` is processed with the `filter`\ncommand and then saved in `y`. The types of `x` and `y` can either be\nfloat or double\n(integer is also allowed but is still processed internally as floating point):\n```\ny = f.filter(x);\n```\nThis is then repeated for every incoming sample in a\nloop or event handler.\n\n\n### Error handling\nInvalid values provided to `setup()` will throw\nan exception. Parameters provided to `setup()` which\nresult in coefficients being NAN will also\nthrow an exception.\n\nYou can switch off exeption handling by defining\n`IIR1_NO_EXCEPTIONS` via cmake or in your program.\n\n\n## Linking\n\n### CMake setup\nIf you use cmake as your build system then just add\nto your `CMakeLists.txt` the following lines for the dynamic library:\n```\nfind_package(iir)\ntarget_link_libraries(... iir::iir)\n```\nor for the static one:\n```\nfind_package(iir)\ntarget_link_libraries(... iir::iir_static)\n```\n\n### Generic linker setup\nLink it against the dynamic library\n(Unix/Mac: `-liir`, Windows: `iir.lib`)\nor the static library (Unix/Mac: `libiir_static.a`,\nWindows: `libiir_static.lib`).\n\n\n\n## Pre compiled packages for Ubuntu LTS (PPA):\n\nIf you are using Ubuntu LTS then you can\ninstall this library as a pre-compiled package.\n\nAdd this repository to your system:\n```\nsudo add-apt-repository ppa:berndporr/dsp\n```\n\nThen install the packages:\n\n  - Library files: `sudo apt install iir1`\n  - Development files: `sudo apt install iir1-dev`\n\nIt's available for 64 bit Intel and 32,64 bit ARM (Raspberry PI etc).\nThe documentation of the development package and the example programs are in:\n```\n/usr/share/doc/iir1-dev/\n```\n\n\n## Compilation from source\n\nThe build tool is `cmake` which generates the make- or project\nfiles for the different platforms. `cmake` is available for\nLinux, Windows and Mac. It also compiles directly on a\nRaspberry PI.\n\n### Linux / Mac\n\nRun\n```\ncmake .\n```\nwhich generates the Makefile. Then run:\n```\nmake\nsudo make install\n```\nwhich installs it under `/usr/local/lib` and `/usr/local/include`.\n\nBoth gcc and clang have been tested.\n\n### Windows\n\n```\ncmake -G \"Visual Studio 16 2019\" -A x64 .\n```\n\nSee `cmake` for the different build-options. Above is for a 64 bit build.\nThen start Visual C++ and open the solution. This will create\nthe DLL and the LIB files. Under Windows it's highly recommended\nto use the static library and link it into the application program.\n\n### Unit tests\n\nRun unit tests by typing `make test` or just `ctest`.\nThese test if after a delta pulse all filters relax to zero,\nthat their outputs never become NaN and if the Direct Form I\u0026II filters calculate\nexpected sequences by comparing them from results created\nby the output of scipy's `sosfilt`.\n\nYou can disable the generation of tests by setting `IIR1_BUILD_TESTING` to off.\n\n## Documentation\n\n### Learn from the demos\nThe easiest way to learn is from the examples which are in the `demo`\ndirectory. A delta pulse as a test signal is sent into the different\nfilters and saved in a file. With the Python script\n`plot_impulse_fresponse.py` you can then plot the frequency responses.\n\nYou can disable the compilation of the demos by setting `IIR1_BUILD_DEMO` to off.\n\nAlso the directory containing the unit tests provides examples for\nevery filter type.\n\n### Detailed documentation\nA PDF of all classes, methods and in particular `setup` functions\nis in the `docs/pdf` directory.\n\nThe online documentation is here: http://berndporr.github.io/iir1\n\n## Example filter responses\n\nThese responses have been generated by `iirdemo.cpp`\nin the `/demo/` directory and then plotted with `plot_impulse_fresponse.py`.\n\n![alt tag](demo/1.png)\n![alt tag](demo/2.png)\n![alt tag](demo/3.png)\n![alt tag](demo/4.png)\n![alt tag](demo/5.png)\n![alt tag](demo/7.png)\n![alt tag](demo/8.png)\n\n## Credits\n\nThis library has been further developed from Vinnie Falco's\ngreat original work which can be found here:\n\nhttps://github.com/vinniefalco/DSPFilters\n\nWhile the original library processes audio arrays this\nlibrary has been adapted to do fast realtime processing sample\nby sample. The `setup`\ncommand won't require the filter order and instead remembers\nit from the template argument. The class structure has\nbeen simplified and all functions documented for doxygen.\nInstead of having assert() statements this libary throws\nexceptions in case a parameter is wrong. Any filter design\nrequiring optimisation (for example Ellipic filters) has\nbeen removed and instead a function has been added which can import easily\ncoefficients from scipy.\n\nBernd Porr -- http://www.berndporr.me.uk\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberndporr%2Fiir1","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fberndporr%2Fiir1","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberndporr%2Fiir1/lists"}