Sound Field Analysis toolbox for Python
=======================================
.. image:: https://api.travis-ci.org/QULab/sound_field_analysis-py.svg
.. image:: https://ci.appveyor.com/api/projects/status/u0koxo5vcitmbghc?svg=true
.. sphinx-include-start-1
The *sound\_field\_analysis* toolbox (short: *sfa*) is a Python port of the `Sound Field Analysis Toolbox (SOFiA) toolbox`_, originally by Benjamin Bernschütz `[1]`_. The main goal of the *sfa* toolbox is to analyze, visualize and process sound field data recorded by spherical microphone arrays. Furthermore, various types of test-data may be generated to evaluate the implemented functions. It is an essential building block of `ReTiSAR <https://github.com/AppliedAcousticsChalmers/ReTiSAR>`_, an implementation of real time binaural rendering of spherical microphone array data.
Requirements
------------
We use `Python 3.9 <https://www.python.org/downloads/>`_ for development. Chances are that earlier version will work too but this is currently untested.
The following external libraries are required:
- `NumPy <http://www.numpy.org>`_
- `SciPy <http://www.scipy.org>`_
- `Pysofaconventions <https://github.com/andresperezlopez/pysofaconventions>`_
- `Jupyter`_ (for running *Notebooks* locally)
- `Plotly <https://plot.ly/python/>`_ (for plotting)
Installation
------------
For performance and convenience reasons we highly recommend to use `Conda`_ (miniconda for simplicity) to manage your Python installation. Once installed, you can use the following steps to receive and use *sfa*, depending on your use case:
* From `PyPI`_ / ``pip``:
| Install into an existing environment (without example `Jupyter`_ *Notebooks*):
| ``pip install sound_field_analysis``
* By cloning (or downloading) the repository and setting up a new environment:
| ``git clone https://github.com/AppliedAcousticsChalmers/sound_field_analysis-py.git``
| ``cd sound_field_analysis-py/``
| Create a new `Conda`_ environment from the specified dependencies:
| ``conda env create --file environment.yml --force``
| Activate the environment:
| ``source activate sfa``
| **Optional:** Install additional dependencies for development purposes (locally run `Jupyter`_ *Notebooks* with example, run tests, generate documentation):
| ``conda env update --file environment_dev.yml``
.. C. From `conda-forge <https://conda-forge.github.io>`_ channel: **[outdated]**
| Install into an existing environment:
| ``conda install -c conda-forge sound_field_analysis``
Examples
--------
The following examples are available as `Jupyter`_ *Notebooks*, either statically on `GitHub <examples/>`_ or interactively on `nbviewer <http://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/tree/master/examples/>`_. You can of course also simply download the examples and run them locally!
Exp1: Ideal plane wave
^^^^^^^^^^^^^^^^^^^^^^
Ideal unity plane wave simulation and 3D plot.
`View interactively on nbviewer <https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp1_IdealPlaneWave.ipynb>`__
.. sphinx-include-end-1
|AE1_img|_
.. |AE1_img| image:: examples/img/AE1_shape.png?raw=true
.. _AE1_img: https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp1_IdealPlaneWave.ipynb
.. sphinx-include-start-2
Exp2: Measured plane wave
^^^^^^^^^^^^^^^^^^^^^^^^^
A measured plane wave from AZ=180°, EL=90° in the anechoic chamber using a cardioid mic.
`View interactively on nbviewer <https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp2_MeasuredWave.ipynb>`__
.. sphinx-include-end-2
|AE2_img|_
.. |AE2_img| image:: examples/img/AE2_shape.png?raw=true
.. _AE2_img: https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp2_MeasuredWave.ipynb
.. sphinx-include-start-3
Exp4: Binaural rendering
^^^^^^^^^^^^^^^^^^^^^^^^
Render a spherical microphone array impulse response measurement binaurally. The example shows examples for loading miro or `SOFA`_ files.
`View interactively on nbviewer <https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp4_BinauralRendering.ipynb>`__
.. sphinx-include-end-3
|AE4_img|_
.. |AE4_img| image:: examples/img/AE4_radial_filters.png?raw=true
.. _AE4_img: https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp4_BinauralRendering.ipynb
.. sphinx-include-start-4
Version history
---------------
*v2021.2.4*
* Implement option to use real spherical harmonic basis functions
* Update Exp4 to optionally utilize real spherical harmonics
* Fix testing of spherical harmonics against reference Matlab implementation
* Add testing for generation of real spherical harmonics
* Add evaluation of performance for generation of complex and real spherical harmonics
* Add evaluation of performance for spatial sound field decomposition
* Update `Conda`_ environment setup to combine all development dependencies
* Update `online <https://appliedacousticschalmers.github.io/sound_field_analysis-py/>`_ and `offline <DOCUMENTATION.pdf>`_ documentation
*v2021.1.12*
* Update MIRO struct loading (quadrature weights are now optional)
* Fix to prevent Python 3.8 syntax warnings
* Improve Exp4 (general code structure and utilizing Spherical Head Filter and Spherical Harmonics Tapering)
*v2020.1.30*
* Update README and `PyPI`_ package
*v2019.11.6*
* Update internal documentation and string formatting
*v2019.8.15*
* Change version number scheme to CalVer
* Improve Exp4
* Update `read_SOFA_file()`
* Update 2D plotting functions
* Improve `write_SSR_IRs()`
* Improve `Conda`_ environment setup for `Jupyter`_ Notebooks
* Update `miro_to_struct()`
*2019-07-30 (v0.9)*
* Implement `SOFA`_ import
* Update Exp4 to contain `SOFA`_ import
* Delete obsolete Exp3
* Add named tuple `HRIRSignal`
* Implement `cart2sph()` and `sph2cart()` utility functions
* Add `Conda`_ environment file for convenient installation of required packages
*2019-07-11 (v0.8)*
* Implement Spherical Harmonics coefficients tapering
* Update Spherical Head Filter to consider tapering
*2019-06-17 (v0.7)*
* Implement Bandwidth Extension for Microphone Arrays (BEMA)
* Edit `read_miro_struct()`, named tuple `ArraySignal` and `miro_to_struct.m` to load center measurements
*2019-06-11 (v0.6)*
* Implement Radial Filter Improvement from `Sound Field Analysis Toolbox (SOFiA) toolbox`_
*2019-05-23 (v0.5)*
* Implement Spherical Head Filter
* Implement Spherical Fourier Transform using pseudo-inverse
* Extract real time capable spatial Fourier transform
* Extract reversed m index function (Update Exp4)
Contribute
----------
See `CONTRIBUTE.rst <CONTRIBUTE.rst>`_ for full details.
You can find the full offline documentation as `PDF <DOCUMENTATION.pdf>`_ as well as online at https://appliedacousticschalmers.github.io/sound_field_analysis-py/ .
License
-------
This software is licensed under the MIT License (see `LICENSE <LICENSE>`_ for full details).
References
----------
The *sound_field_analysis* toolbox is based on the Matlab/C++ `Sound Field Analysis Toolbox (SOFiA) toolbox`_ by Benjamin Bernschütz. For more information you may refer to the original publication:
[1] `Bernschütz, B., Pörschmann, C., Spors, S., and Weinzierl, S. (2011). SOFiA Sound Field Analysis Toolbox. Proceedings of the ICSA International Conference on Spatial Audio <http://spatialaudio.net/sofia-sound-field-analysis-toolbox-2/>`_
The Lebedev grid generation was adapted from an implementation by `Richard P. Muller <https://github.com/gabrielelanaro/pyquante/blob/master/Data/lebedev_write.py>`_.
.. _Sound Field Analysis Toolbox (SOFiA) toolbox: http://audiogroup.web.th-koeln.de/SOFiA_wiki/WELCOME.html
.. _[1]: #references
.. _PyPI: https://pypi.org/project/sound-field-analysis/
.. _Jupyter: https://jupyter.org/
.. _Conda: https://conda.io/en/master/miniconda.html
.. _SOFA: https://www.sofaconventions.org/mediawiki/index.php/SOFA_(Spatially_Oriented_Format_for_Acoustics)
Raw data
{
"_id": null,
"home_page": "https://github.com/AppliedAcousticsChalmers/sound_field_analysis-py/",
"name": "sound-field-analysis",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "sound field analysis spherical microphone array",
"author": "Chalmers University of Technology / Jens Ahrens",
"author_email": "jens.ahrens@chalmers.se",
"download_url": "https://files.pythonhosted.org/packages/70/75/a0e96277002a58457ea988d9dba190b6059eeb36983c21b5696ac8bcec2d/sound_field_analysis-2021.2.4.tar.gz",
"platform": "",
"description": "Sound Field Analysis toolbox for Python\n=======================================\n\n.. image:: https://api.travis-ci.org/QULab/sound_field_analysis-py.svg\n.. image:: https://ci.appveyor.com/api/projects/status/u0koxo5vcitmbghc?svg=true\n\n.. sphinx-include-start-1\n\nThe *sound\\_field\\_analysis* toolbox (short: *sfa*) is a Python port of the `Sound Field Analysis Toolbox (SOFiA) toolbox`_, originally by Benjamin Bernsch\u00fctz `[1]`_. The main goal of the *sfa* toolbox is to analyze, visualize and process sound field data recorded by spherical microphone arrays. Furthermore, various types of test-data may be generated to evaluate the implemented functions. It is an essential building block of `ReTiSAR <https://github.com/AppliedAcousticsChalmers/ReTiSAR>`_, an implementation of real time binaural rendering of spherical microphone array data.\n\n\nRequirements\n------------\n\nWe use `Python 3.9 <https://www.python.org/downloads/>`_ for development. Chances are that earlier version will work too but this is currently untested.\n\nThe following external libraries are required:\n\n- `NumPy <http://www.numpy.org>`_\n- `SciPy <http://www.scipy.org>`_\n- `Pysofaconventions <https://github.com/andresperezlopez/pysofaconventions>`_\n- `Jupyter`_ (for running *Notebooks* locally)\n- `Plotly <https://plot.ly/python/>`_ (for plotting)\n\n\nInstallation\n------------\n\nFor performance and convenience reasons we highly recommend to use `Conda`_ (miniconda for simplicity) to manage your Python installation. Once installed, you can use the following steps to receive and use *sfa*, depending on your use case:\n\n* From `PyPI`_ / ``pip``:\n\n | Install into an existing environment (without example `Jupyter`_ *Notebooks*):\n | ``pip install sound_field_analysis``\n\n* By cloning (or downloading) the repository and setting up a new environment:\n\n | ``git clone https://github.com/AppliedAcousticsChalmers/sound_field_analysis-py.git``\n | ``cd sound_field_analysis-py/``\n\n | Create a new `Conda`_ environment from the specified dependencies:\n | ``conda env create --file environment.yml --force``\n\n | Activate the environment:\n | ``source activate sfa``\n\n | **Optional:** Install additional dependencies for development purposes (locally run `Jupyter`_ *Notebooks* with example, run tests, generate documentation):\n | ``conda env update --file environment_dev.yml``\n\n.. C. From `conda-forge <https://conda-forge.github.io>`_ channel: **[outdated]**\n\n | Install into an existing environment:\n | ``conda install -c conda-forge sound_field_analysis``\n\n\nExamples\n--------\n\nThe following examples are available as `Jupyter`_ *Notebooks*, either statically on `GitHub <examples/>`_ or interactively on `nbviewer <http://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/tree/master/examples/>`_. You can of course also simply download the examples and run them locally!\n\n\nExp1: Ideal plane wave\n^^^^^^^^^^^^^^^^^^^^^^\n\nIdeal unity plane wave simulation and 3D plot.\n\n`View interactively on nbviewer <https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp1_IdealPlaneWave.ipynb>`__\n\n.. sphinx-include-end-1\n\n|AE1_img|_\n\n.. |AE1_img| image:: examples/img/AE1_shape.png?raw=true\n.. _AE1_img: https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp1_IdealPlaneWave.ipynb\n\n.. sphinx-include-start-2\n\n\nExp2: Measured plane wave\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nA measured plane wave from AZ=180\u00b0, EL=90\u00b0 in the anechoic chamber using a cardioid mic.\n\n`View interactively on nbviewer <https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp2_MeasuredWave.ipynb>`__\n\n.. sphinx-include-end-2\n\n|AE2_img|_\n\n.. |AE2_img| image:: examples/img/AE2_shape.png?raw=true\n.. _AE2_img: https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp2_MeasuredWave.ipynb\n\n.. sphinx-include-start-3\n\n\nExp4: Binaural rendering\n^^^^^^^^^^^^^^^^^^^^^^^^\n\nRender a spherical microphone array impulse response measurement binaurally. The example shows examples for loading miro or `SOFA`_ files.\n\n`View interactively on nbviewer <https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp4_BinauralRendering.ipynb>`__\n\n.. sphinx-include-end-3\n\n|AE4_img|_\n\n.. |AE4_img| image:: examples/img/AE4_radial_filters.png?raw=true\n.. _AE4_img: https://nbviewer.jupyter.org/github/AppliedAcousticsChalmers/sound_field_analysis-py/blob/master/examples/Exp4_BinauralRendering.ipynb\n\n.. sphinx-include-start-4\n\n\nVersion history\n---------------\n\n*v2021.2.4*\n * Implement option to use real spherical harmonic basis functions\n * Update Exp4 to optionally utilize real spherical harmonics\n * Fix testing of spherical harmonics against reference Matlab implementation\n * Add testing for generation of real spherical harmonics\n * Add evaluation of performance for generation of complex and real spherical harmonics\n * Add evaluation of performance for spatial sound field decomposition\n * Update `Conda`_ environment setup to combine all development dependencies\n * Update `online <https://appliedacousticschalmers.github.io/sound_field_analysis-py/>`_ and `offline <DOCUMENTATION.pdf>`_ documentation\n\n*v2021.1.12*\n * Update MIRO struct loading (quadrature weights are now optional)\n * Fix to prevent Python 3.8 syntax warnings\n * Improve Exp4 (general code structure and utilizing Spherical Head Filter and Spherical Harmonics Tapering)\n\n*v2020.1.30*\n * Update README and `PyPI`_ package\n\n*v2019.11.6*\n * Update internal documentation and string formatting\n\n*v2019.8.15*\n * Change version number scheme to CalVer\n * Improve Exp4\n * Update `read_SOFA_file()`\n * Update 2D plotting functions\n * Improve `write_SSR_IRs()`\n * Improve `Conda`_ environment setup for `Jupyter`_ Notebooks\n * Update `miro_to_struct()`\n\n*2019-07-30 (v0.9)*\n * Implement `SOFA`_ import\n * Update Exp4 to contain `SOFA`_ import\n * Delete obsolete Exp3\n * Add named tuple `HRIRSignal`\n * Implement `cart2sph()` and `sph2cart()` utility functions\n * Add `Conda`_ environment file for convenient installation of required packages\n\n*2019-07-11 (v0.8)*\n * Implement Spherical Harmonics coefficients tapering\n * Update Spherical Head Filter to consider tapering\n\n*2019-06-17 (v0.7)*\n * Implement Bandwidth Extension for Microphone Arrays (BEMA)\n * Edit `read_miro_struct()`, named tuple `ArraySignal` and `miro_to_struct.m` to load center measurements\n\n*2019-06-11 (v0.6)*\n * Implement Radial Filter Improvement from `Sound Field Analysis Toolbox (SOFiA) toolbox`_\n\n*2019-05-23 (v0.5)*\n * Implement Spherical Head Filter\n * Implement Spherical Fourier Transform using pseudo-inverse\n * Extract real time capable spatial Fourier transform\n * Extract reversed m index function (Update Exp4)\n\n\nContribute\n----------\n\nSee `CONTRIBUTE.rst <CONTRIBUTE.rst>`_ for full details.\n\nYou can find the full offline documentation as `PDF <DOCUMENTATION.pdf>`_ as well as online at https://appliedacousticschalmers.github.io/sound_field_analysis-py/ .\n\n\nLicense\n-------\n\nThis software is licensed under the MIT License (see `LICENSE <LICENSE>`_ for full details).\n\n\nReferences\n----------\n\nThe *sound_field_analysis* toolbox is based on the Matlab/C++ `Sound Field Analysis Toolbox (SOFiA) toolbox`_ by Benjamin Bernsch\u00fctz. For more information you may refer to the original publication:\n\n[1] `Bernsch\u00fctz, B., P\u00f6rschmann, C., Spors, S., and Weinzierl, S. (2011). SOFiA Sound Field Analysis Toolbox. Proceedings of the ICSA International Conference on Spatial Audio <http://spatialaudio.net/sofia-sound-field-analysis-toolbox-2/>`_\n\nThe Lebedev grid generation was adapted from an implementation by `Richard P. Muller <https://github.com/gabrielelanaro/pyquante/blob/master/Data/lebedev_write.py>`_.\n\n.. _Sound Field Analysis Toolbox (SOFiA) toolbox: http://audiogroup.web.th-koeln.de/SOFiA_wiki/WELCOME.html\n.. _[1]: #references\n.. _PyPI: https://pypi.org/project/sound-field-analysis/\n.. _Jupyter: https://jupyter.org/\n.. _Conda: https://conda.io/en/master/miniconda.html\n.. _SOFA: https://www.sofaconventions.org/mediawiki/index.php/SOFA_(Spatially_Oriented_Format_for_Acoustics)\n\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Analyze, visualize and process sound field data recorded by spherical microphone arrays.",
"version": "2021.2.4",
"project_urls": {
"Homepage": "https://github.com/AppliedAcousticsChalmers/sound_field_analysis-py/"
},
"split_keywords": [
"sound",
"field",
"analysis",
"spherical",
"microphone",
"array"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cebb6d052aaa17faf1ab1b5e80ca1f03ba43169d50b7ddbfde384985eff5098f",
"md5": "8fda0a44a3b882954304c573d21b9cba",
"sha256": "966082d32e2e24c532cedef79b5fb271bc1bedf4cc10df6dd7bf15f517d23b3d"
},
"downloads": -1,
"filename": "sound_field_analysis-2021.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fda0a44a3b882954304c573d21b9cba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 41669,
"upload_time": "2021-03-10T15:41:52",
"upload_time_iso_8601": "2021-03-10T15:41:52.832663Z",
"url": "https://files.pythonhosted.org/packages/ce/bb/6d052aaa17faf1ab1b5e80ca1f03ba43169d50b7ddbfde384985eff5098f/sound_field_analysis-2021.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7075a0e96277002a58457ea988d9dba190b6059eeb36983c21b5696ac8bcec2d",
"md5": "905782fb02a5982bb09f88b21bafbef7",
"sha256": "8b48737ac254eb684a51f52bc542a38e2d862477b69c3430b66f8fc5dcbe6c2a"
},
"downloads": -1,
"filename": "sound_field_analysis-2021.2.4.tar.gz",
"has_sig": false,
"md5_digest": "905782fb02a5982bb09f88b21bafbef7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 48618,
"upload_time": "2021-03-10T15:41:54",
"upload_time_iso_8601": "2021-03-10T15:41:54.232510Z",
"url": "https://files.pythonhosted.org/packages/70/75/a0e96277002a58457ea988d9dba190b6059eeb36983c21b5696ac8bcec2d/sound_field_analysis-2021.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-03-10 15:41:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AppliedAcousticsChalmers",
"github_project": "sound_field_analysis-py",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"appveyor": true,
"lcname": "sound-field-analysis"
}
JSON
