This is a Python 3.10 implementation of RABASAR as described in [4].
RABASAR reduces the speckle in multi-temporal intensity, polarimetric or interferometric
Synthetic-Aperture-Radar (SAR, PolSAR, InSAR, resp.) images by first computing a super
image with a high signal-to-noise ratio, and then processes the residuals between the
multi-temporal stack and the super-image.
# Description
RABASAR is a plug-and-play ADMM approach for speckle reduction in a stack of
(Pol/In)SAR images. It is based on MuLoG and the concepts of super image. It
uses an off-the-shelf Gaussian denoiser and matrix logarithm transform to stabilized
noise and simplify the optimization occuring for denoising the residual matrix fields
between each image of the stack and the super image.
**REMARK**: Compared to the version of RABASAR described in [3], this one:
1. is not limited to monochanel intensity SAR image. It can be applied like-wise
to mutli-channel SAR image such as PolSAR, InSAR, PolInSAR.
2. does not account for the statistics of the ratio-images (the z-Fisher distribution
of the log of ratio of intensity image). Instead the noise of the log ratio is
approximated by the Wishart-Fisher-Tippet distribution. For the approximation
error to be negligeable, the stack of images must be large enough and ideally
with enough pairs presenting low temporal coherence.
# Installation
Unless you have Python 3.10 installed and enabled as default, we recommend
installing RABASAR in a virtual environment as described in the following section.
## Set up a virtual environment (optional)
We recommend installing RABASAR in a virtual environment such as `venv`. You can
install `venv` for Python 3.10 on Debian/Ubuntu as follows:
sudo apt install python3.10-venv
If your system does not have Python 3.10, please refer to the "Troubleshooting"
section below.
Create and activate your virtual environment by running the following either directly
in the directory in which you will execute or clone RABASAR or in a parent directory, as
python3 -m venv venv
source venv/bin/activate
Alternatively, you can use other environment systems such as `conda`.
## Latest stable version
We recommend installing the latest stable version of RABASAR by running
pip3 install rabasar
in a system or environment with Python 3.10.
## Development version
Alternatively, you can install the development version from `git` as
pip3 install -e git+https://bitbucket.org/charles_deledalle/rabasar2019-python.git#egg=rabasar
or, directly from the sources as
git clone https://bitbucket.org/charles_deledalle/rabasar2019-python.git
cd rabasar2019-python
python3 setup.py sdist
python3 setup.py install
# Run RABASAR
Examples on how to run RABASAR are provided in two scripts that you can execute as:
```shell
# Run RABASAR on a multlooked synthetic PolSAR image stack with 5 looks
python3 -m rabasar.rabasar_synthetic_example -l 5
```
For more precisions on how to execute these examples, see:
python3 -m rabasar.rabasar_synthetic_example --help
To run RABASAR on your own data, you need to execute from Python the function
called `run_rabasar` that you can import as:
from rabasar.rabasar_algorithm import run_rabasar
This function takes your data as input through the argument `sar_stack`
which has the format of a covariance matrix field (an image of non negative
definite complex Hermitian matrices). It's your responsibility to load and
format your data in Python to make it compatible with this input. SAR, InSAR,
PolSAR, DualPolSAR PolInSAR images can be formatted as such a matrix field. For
more details, please read [1-4].
# List of the files in this folder
- ```multilooking.py```
The code to compute the "super-image" of a temporal series of polarimetric images by
averaging them and applying optionally MuLoG on the result with an estimated number
of looks.
- ```rabasar_algorithm.py```
Implementation of RABASAR for polarimetric SAR images.
- ```rabasar_synthetic_example.py```
A cli tool to run RABASAR on a synthetic example.
- ```sar_image_stack_generation.py```
Tools to generate synthetic mono-channel and multichannel SAR image stacks.
- ```sar_image_stack_rendering.py```
Tools to render synthetic mono-channel and multichannel SAR image stacks.
# Developers
## Set up
Clone the git repository on your machine:
git clone https://bitbucket.org/charles_deledalle/rabasar2019-python.git
cd rabasar2019-python
Set up a Python 3.10 virtual environment as described in the Installation section above.
Once your virtual environment is set up and activated, install dependencies as
pip3 install -r requirements.txt
## Contribution
Any contributions must be submitted through peer reviews.
Ask for an author account on the bitbucket repository,
create your own branch and raise a pull-request.
All additional code must be cover by a unit test.
Any pull request needs to pass the following commands before being approved:
black .
ruff --fix .
pyright .
python3 -m pytest --cov
If the last one does not have a 100% test coverage, run:
python3 -m pytest --cov --cov-report=html
and inspect the report.
Make sure to update `requirements.txt` to include any extra dependencies.
## Distribution
To distribute the project make sure to uptick the version number in `setup.py`
and merge that upticked version on the `master` branch.
Once the `master` branch is ready, run the following
git checkout master
cd $(git rev-parse --show-toplevel)
rm -rf dist/ build/ rabasar.egg-info/
git status --porcelain
and make sure the last command did not print anything.
After that, generate the distribution files by running
python3 setup.py sdist bdist_wheel
python3 -m twine check dist/*
python3 -m twine upload -r testpypi dist/*
Test in a different environment
mkdir /tmp/test
cd /tmp/test
python3 -m venv venv
source venv/bin/activate
pip3 install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ rabasar
python3 -m rabasar.rabasar_synthetic_example -l 5
Finally, publish the final version
python3 -m twine upload dist/*
Once done, tag the `master` branch with the new version number on Git.
# License
This software is governed by the CeCILL license under French law and
abiding by the rules of distribution of free software. You can use,
modify and/ or redistribute the software under the terms of the CeCILL
license as circulated by CEA, CNRS and INRIA at the following URL
"http://www.cecill.info".
As a counterpart to the access to the source code and rights to copy,
modify and redistribute granted by the license, users are provided only
with a limited warranty and the software's author, the holder of the
economic rights, and the successive licensors have only limited
liability.
In this respect, the user's attention is drawn to the risks associated
with loading, using, modifying and/or developing or reproducing the
software by the user in light of its specific status of free software,
that may mean that it is complicated to manipulate, and that also
therefore means that it is reserved for developers and experienced
professionals having in-depth computer knowledge. Users are therefore
encouraged to load and test the software's suitability as regards their
requirements in conditions enabling the security of their systems and/or
data to be ensured and, more generally, to use and operate it in the
same conditions as regards security.
The fact that you are presently reading this means that you have had
knowledge of the CeCILL license and that you accept its terms.
# Contributors
- Charles Deledalle (original version in Matlab)
- Sébastien Mounier (translation in Python)
- Cristiano Ulondu Mendes (bug fixes and improvements)
# Scientific articles describing the method
Any published materials derived from MuLoG must cite [1-2].
Any published materials derived from RABASAR must cite [3-4].
[1] Deledalle, C. A., Denis, L., Tabti, S., & Tupin, F. (2017). MuLoG,
or how to apply Gaussian denoisers to multi-channel SAR speckle
reduction?. IEEE Transactions on Image Processing, 26(9), 4389-4403.
[2] Deledalle, C. A., Denis, L., & Tupin, F. (2022). Speckle reduction
in matrix-log domain for synthetic aperture radar imaging. Journal
of Mathematical Imaging and Vision, 64(3), 298-320.
[3] Zhao, W., Deledalle, C. A., Denis, L., Maître, H., Nicolas, J. M.,
& Tupin, F. (2019). Ratio-based multitemporal SAR images denoising:
RABASAR. IEEE Transactions on Geoscience and Remote Sensing, 57(6),
3552-3565.
[4] Deledalle, C. A., Denis, L., Ferro-Famil, L., Nicolas, J. M., &
Tupin, F. (2019, July). Multi-temporal speckle reduction of
polarimetric SAR images: A ratio-based approach. In IGARSS 2019-2019
IEEE International Geoscience and Remote Sensing Symposium (pp. 899-
902). IEEE.
Raw data
{
"_id": null,
"home_page": "https://www.charles-deledalle.fr/pages/rabasar",
"name": "rabasar",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "SAR,PolSAR,InSAR,speckle,filtering,images,wishart,temporal,stack",
"author": "Charles Deledalle, S\u00e9bastien Mounier, Cristiano Ulondu Mendes",
"author_email": "charles.deledalle@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a0/37/ce3c34128152e7200afe4524a613193541d01c27c76448143db82c308e40/rabasar-0.0.1.tar.gz",
"platform": null,
"description": "This is a Python 3.10 implementation of RABASAR as described in [4].\n\nRABASAR reduces the speckle in multi-temporal intensity, polarimetric or interferometric\nSynthetic-Aperture-Radar (SAR, PolSAR, InSAR, resp.) images by first computing a super\nimage with a high signal-to-noise ratio, and then processes the residuals between the\nmulti-temporal stack and the super-image.\n\n# Description\n\nRABASAR is a plug-and-play ADMM approach for speckle reduction in a stack of\n(Pol/In)SAR images. It is based on MuLoG and the concepts of super image. It\nuses an off-the-shelf Gaussian denoiser and matrix logarithm transform to stabilized\nnoise and simplify the optimization occuring for denoising the residual matrix fields\nbetween each image of the stack and the super image.\n\n**REMARK**: Compared to the version of RABASAR described in [3], this one:\n1. is not limited to monochanel intensity SAR image. It can be applied like-wise\n to mutli-channel SAR image such as PolSAR, InSAR, PolInSAR.\n2. does not account for the statistics of the ratio-images (the z-Fisher distribution\n of the log of ratio of intensity image). Instead the noise of the log ratio is\n approximated by the Wishart-Fisher-Tippet distribution. For the approximation\n error to be negligeable, the stack of images must be large enough and ideally\n with enough pairs presenting low temporal coherence.\n\n# Installation\n\nUnless you have Python 3.10 installed and enabled as default, we recommend\ninstalling RABASAR in a virtual environment as described in the following section.\n\n## Set up a virtual environment (optional)\n\nWe recommend installing RABASAR in a virtual environment such as `venv`. You can\ninstall `venv` for Python 3.10 on Debian/Ubuntu as follows:\n\n\tsudo apt install python3.10-venv\n\nIf your system does not have Python 3.10, please refer to the \"Troubleshooting\"\nsection below.\n\nCreate and activate your virtual environment by running the following either directly\nin the directory in which you will execute or clone RABASAR or in a parent directory, as\n\n\tpython3 -m venv venv\n\tsource venv/bin/activate\n\nAlternatively, you can use other environment systems such as `conda`.\n\n## Latest stable version\n\nWe recommend installing the latest stable version of RABASAR by running\n\n\tpip3 install rabasar\n\nin a system or environment with Python 3.10.\n\n## Development version\n\nAlternatively, you can install the development version from `git` as\n\n\tpip3 install -e git+https://bitbucket.org/charles_deledalle/rabasar2019-python.git#egg=rabasar\n\nor, directly from the sources as\n\n\tgit clone https://bitbucket.org/charles_deledalle/rabasar2019-python.git\n\tcd rabasar2019-python\n\tpython3 setup.py sdist\n\tpython3 setup.py install\n\n# Run RABASAR\n\nExamples on how to run RABASAR are provided in two scripts that you can execute as:\n```shell\n# Run RABASAR on a multlooked synthetic PolSAR image stack with 5 looks\npython3 -m rabasar.rabasar_synthetic_example -l 5\n```\nFor more precisions on how to execute these examples, see:\n\n\tpython3 -m rabasar.rabasar_synthetic_example --help\n\nTo run RABASAR on your own data, you need to execute from Python the function\ncalled `run_rabasar` that you can import as:\n\n\tfrom rabasar.rabasar_algorithm import run_rabasar\n\nThis function takes your data as input through the argument `sar_stack`\nwhich has the format of a covariance matrix field (an image of non negative\ndefinite complex Hermitian matrices). It's your responsibility to load and\nformat your data in Python to make it compatible with this input. SAR, InSAR,\nPolSAR, DualPolSAR PolInSAR images can be formatted as such a matrix field. For\nmore details, please read [1-4].\n\n# List of the files in this folder\n\n- ```multilooking.py```\n\nThe code to compute the \"super-image\" of a temporal series of polarimetric images by\naveraging them and applying optionally MuLoG on the result with an estimated number\nof looks.\n\n- ```rabasar_algorithm.py```\n\nImplementation of RABASAR for polarimetric SAR images.\n\n- ```rabasar_synthetic_example.py```\n\nA cli tool to run RABASAR on a synthetic example.\n\n- ```sar_image_stack_generation.py```\n\nTools to generate synthetic mono-channel and multichannel SAR image stacks.\n\n- ```sar_image_stack_rendering.py```\n\nTools to render synthetic mono-channel and multichannel SAR image stacks.\n\n# Developers\n\n## Set up\n\nClone the git repository on your machine:\n\n\tgit clone https://bitbucket.org/charles_deledalle/rabasar2019-python.git\n\tcd rabasar2019-python\n\nSet up a Python 3.10 virtual environment as described in the Installation section above.\nOnce your virtual environment is set up and activated, install dependencies as\n\n\tpip3 install -r requirements.txt\n\n## Contribution\n\nAny contributions must be submitted through peer reviews.\nAsk for an author account on the bitbucket repository,\ncreate your own branch and raise a pull-request.\nAll additional code must be cover by a unit test.\nAny pull request needs to pass the following commands before being approved:\n\n\tblack .\n\truff --fix .\n\tpyright .\n\tpython3 -m pytest --cov\n\nIf the last one does not have a 100% test coverage, run:\n\n\tpython3 -m pytest --cov --cov-report=html\n\nand inspect the report.\n\nMake sure to update `requirements.txt` to include any extra dependencies.\n\n## Distribution\n\nTo distribute the project make sure to uptick the version number in `setup.py`\nand merge that upticked version on the `master` branch.\nOnce the `master` branch is ready, run the following\n\n\tgit checkout master\n\tcd $(git rev-parse --show-toplevel)\n\trm -rf dist/ build/ rabasar.egg-info/\n\tgit status --porcelain\n\nand make sure the last command did not print anything.\nAfter that, generate the distribution files by running\n\n\tpython3 setup.py sdist bdist_wheel\n\tpython3 -m twine check dist/*\n\tpython3 -m twine upload -r testpypi dist/*\n\nTest in a different environment\n\n\tmkdir /tmp/test\n\tcd /tmp/test\n\tpython3 -m venv venv\n\tsource venv/bin/activate\n\tpip3 install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ rabasar\n\tpython3 -m rabasar.rabasar_synthetic_example -l 5\n\nFinally, publish the final version\n\n\tpython3 -m twine upload dist/*\n\nOnce done, tag the `master` branch with the new version number on Git.\n\n# License\n\nThis software is governed by the CeCILL license under French law and\nabiding by the rules of distribution of free software. You can use,\nmodify and/ or redistribute the software under the terms of the CeCILL\nlicense as circulated by CEA, CNRS and INRIA at the following URL\n\"http://www.cecill.info\".\n\nAs a counterpart to the access to the source code and rights to copy,\nmodify and redistribute granted by the license, users are provided only\nwith a limited warranty and the software's author, the holder of the\neconomic rights, and the successive licensors have only limited\nliability.\n\nIn this respect, the user's attention is drawn to the risks associated\nwith loading, using, modifying and/or developing or reproducing the\nsoftware by the user in light of its specific status of free software,\nthat may mean that it is complicated to manipulate, and that also\ntherefore means that it is reserved for developers and experienced\nprofessionals having in-depth computer knowledge. Users are therefore\nencouraged to load and test the software's suitability as regards their\nrequirements in conditions enabling the security of their systems and/or\ndata to be ensured and, more generally, to use and operate it in the\nsame conditions as regards security.\n\nThe fact that you are presently reading this means that you have had\nknowledge of the CeCILL license and that you accept its terms.\n\n# Contributors\n\n- Charles Deledalle (original version in Matlab)\n- S\u00e9bastien Mounier (translation in Python)\n- Cristiano Ulondu Mendes (bug fixes and improvements)\n\n# Scientific articles describing the method\n\nAny published materials derived from MuLoG must cite [1-2].\nAny published materials derived from RABASAR must cite [3-4].\n\n[1] Deledalle, C. A., Denis, L., Tabti, S., & Tupin, F. (2017). MuLoG,\n or how to apply Gaussian denoisers to multi-channel SAR speckle\n reduction?. IEEE Transactions on Image Processing, 26(9), 4389-4403.\n\n[2] Deledalle, C. A., Denis, L., & Tupin, F. (2022). Speckle reduction\n in matrix-log domain for synthetic aperture radar imaging. Journal\n of Mathematical Imaging and Vision, 64(3), 298-320.\n\n[3] Zhao, W., Deledalle, C. A., Denis, L., Ma\u00eetre, H., Nicolas, J. M.,\n & Tupin, F. (2019). Ratio-based multitemporal SAR images denoising:\n RABASAR. IEEE Transactions on Geoscience and Remote Sensing, 57(6),\n 3552-3565.\n\n[4] Deledalle, C. A., Denis, L., Ferro-Famil, L., Nicolas, J. M., &\n Tupin, F. (2019, July). Multi-temporal speckle reduction of\n polarimetric SAR images: A ratio-based approach. In IGARSS 2019-2019\n IEEE International Geoscience and Remote Sensing Symposium (pp. 899-\n 902). IEEE.\n\n\n",
"bugtrack_url": null,
"license": "cecill",
"summary": "Ratio-Based Multitemporal SAR Images Denoising - A (Pol/In)SAR image stack speckle reduction algorithm.",
"version": "0.0.1",
"project_urls": {
"Homepage": "https://www.charles-deledalle.fr/pages/rabasar",
"Source": "https://bitbucket.org/charles_deledalle/rabasar2019-python/"
},
"split_keywords": [
"sar",
"polsar",
"insar",
"speckle",
"filtering",
"images",
"wishart",
"temporal",
"stack"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff8d8c81b720955bb9543f77964d88babe09ed5b9e4610aa0ee8df9cf60259ea",
"md5": "b67873c5bcdafefe6b13c984c8046abd",
"sha256": "f3d09c33245aa6433576c04a4649800bd93b8d3c56a1a69bd4ca5e7679c4e2e0"
},
"downloads": -1,
"filename": "rabasar-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b67873c5bcdafefe6b13c984c8046abd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18443,
"upload_time": "2023-09-27T04:25:57",
"upload_time_iso_8601": "2023-09-27T04:25:57.209969Z",
"url": "https://files.pythonhosted.org/packages/ff/8d/8c81b720955bb9543f77964d88babe09ed5b9e4610aa0ee8df9cf60259ea/rabasar-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a037ce3c34128152e7200afe4524a613193541d01c27c76448143db82c308e40",
"md5": "ce387fc7f1b684078b788c739096cb2d",
"sha256": "4a2a1d401fb04025fcd649920af7f912bfe415fb83b82cf0f3e3d204c6d752cb"
},
"downloads": -1,
"filename": "rabasar-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "ce387fc7f1b684078b788c739096cb2d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13620,
"upload_time": "2023-09-27T04:25:59",
"upload_time_iso_8601": "2023-09-27T04:25:59.279471Z",
"url": "https://files.pythonhosted.org/packages/a0/37/ce3c34128152e7200afe4524a613193541d01c27c76448143db82c308e40/rabasar-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-27 04:25:59",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "charles_deledalle",
"bitbucket_project": "rabasar2019-python",
"lcname": "rabasar"
}
JSON