{"id":23105110,"url":"https://github.com/albarji/proxtv","last_synced_at":"2025-04-06T02:09:20.314Z","repository":{"id":23077321,"uuid":"26431011","full_name":"albarji/proxTV","owner":"albarji","description":"Matlab and Python toolbox for fast Total Variation proximity operators","archived":false,"fork":false,"pushed_at":"2020-02-20T18:17:14.000Z","size":7575,"stargazers_count":228,"open_issues_count":13,"forks_count":60,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-30T00:08:17.225Z","etag":null,"topics":["machine-learning","optimization-algorithms","proximal-operators","signal-processing"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albarji.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-10T10:02:21.000Z","updated_at":"2025-03-14T06:11:57.000Z","dependencies_parsed_at":"2022-07-13T16:50:28.212Z","dependency_job_id":null,"html_url":"https://github.com/albarji/proxTV","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albarji%2FproxTV","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albarji%2FproxTV/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albarji%2FproxTV/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albarji%2FproxTV/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albarji","download_url":"https://codeload.github.com/albarji/proxTV/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423515,"owners_count":20936626,"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":["machine-learning","optimization-algorithms","proximal-operators","signal-processing"],"created_at":"2024-12-17T00:38:13.048Z","updated_at":"2025-04-06T02:09:20.289Z","avatar_url":"https://github.com/albarji.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/img/proxTV.png\" height=\"300\"\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n-----------------\n[![Coverage Status](https://coveralls.io/repos/github/albarji/proxTV/badge.svg?branch=master)](https://coveralls.io/github/albarji/proxTV?branch=master)\n[![Code Climate](https://codeclimate.com/github/albarji/proxTV.svg)](https://codeclimate.com/github/albarji/proxTV)\n[![Python versions](https://img.shields.io/pypi/pyversions/prox_tv.svg)](https://pypi.python.org/pypi/prox_tv)\n\n|Linux|Mac OS X|Windows|\n|-----|--------|-------|\n|[![Build Status](https://travis-ci.org/albarji/proxTV.svg?branch=master)](https://travis-ci.org/albarji/proxTV)|[![Build Status](https://travis-ci.org/albarji/proxTV.svg?branch=master)](https://travis-ci.org/albarji/proxTV)[(!)](#notes-on-mac-os-x)|Not supported (yet)|\n\n\n**proxTV** is a toolbox implementing blazing fast implementations of Total Variation proximity operators, which form the basic building blocks for applications such as image denoising, image deconvolution, image inpainting, video denoising, or fused lasso models, to name a few. While the core algorithms are implemented in C to achieve top efficiency, Matlab and Python interfaces are provided for ease of use.\n\nSome examples of applications using **proxTV**:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/img/proxTVgallery.png\" width=\"900\"\u003e\u003cbr\u003e\n\u003c/div\u003e\n\nand others, such as Fused Lasso signal filtering, Fused Lasso classification and regression, lp-norm signal filtering, weighted image denosing, video denosing, tensor denoising, ...\n\nMore technically, the library provides efficient solvers for the following Total Variation proximity problems:\n\n| Problem | Formulation |\n| ------- | ----------- |\n| Standard (l1) Total Variation on a 1-dimensional signal | ![alt tag](docs/img/TV1.png) |\n| Quadratic (l2) Total Variation on a 1-dimensional signal | ![alt tag](docs/img/TV2.png) |\n| lp-norm Total Variation on a 1-dimensional signal | ![alt tag](docs/img/TVp.png) |\n| Weighted Total Variation on a 1-dimensional signal | ![alt tag](docs/img/TV1w.png) |\n| Anisotropic Total Variation on a 2-dimensional signal (image denoising) | ![alt tag](docs/img/TV2D.png) |\n| lp-norm Anisotropic Total Variation on a 2-dimensional signal | ![alt tag](docs/img/TV2Dp.png) |\n| Weighted Anisotropic Total Variation on a 2-dimensional signal | ![alt tag](docs/img/TV2Dw.png) |\n| Anisotropic Total Variation on a 3-dimensional signal (video denoising) | ![alt tag](docs/img/TV3D.png) |\n| Generalized N-dimensional Anisotropic Total Variation (tensor denoising) | ![alt tag](docs/img/TVND.png), with X(di) every possible 1-dimensional slice of X following dimension di.|\n\n## Python interface\n\n### Install\n\n    pip install prox-tv\n\n### Install from source\n\nIf the above doesn't work or you are using an unsupported operative system or Python version, you can install proxTV from souce.\n\nThe following system prerequisites are necessary\n\n- [gcc](https://gcc.gnu.org/). In Ubuntu, run `apt install build-essential`\n- [BLAS developer libraries](http://www.netlib.org/blas/). In Ubuntu, run `apt install libblas-dev`\n- [LAPACK developer libraries](http://www.netlib.org/lapack/). In Ubuntu, run `apt install liblapack-dev`\n\nThen you can clone this repository and install the library with\n\n    python setup.py install\n\nAdditionally, if you would like to run the provided demos you will also require the following packages:\n\n* [matplotlib](http://matplotlib.org/)\n* [scipy](http://www.scipy.org/)\n* [scikit-image](http://scikit-image.org/)\n\n### Usage\n\nImport proxTV Python package as\n\n    import prox_tv as ptv\n    \nor\n\n    from prox_tv import *\n    \nfor direct access to all the package routines.\n    \nThe documentation of use of the package functions is maintained online at http://pythonhosted.org/prox_tv/.\n\n## Matlab interface\n\n### Quick start guide\n\nTo install proxTV clone this repository and run `install` at the Matlab prompt once located at proxTV folder. If any problem arises please refer to the \"Installation\" subsection.\n\nAfter that the TV solver can be invoked easily through the general purpose \"TV\" function. For instance,\n\n    TV(X,lambda)\n    \nsolves TV for X signal and lambda regularizer. The dimensionality of X is automatically checked and an adequate solver is applied.\n\nTo solve TV for a general TV-Lp norm just add the value of p as a third argument,\n\n    TV(X,lambda,p)\n    \nWeighted versions of TV can also be solved by using exactly the same interface, but providing a vector of lambda weights instead of a scalar. For multidimensional signals the relevant weights are provided as a cell array; the \"Usage\" section for more details on this and more advanced uses of toolbox.\n\n### Installation\n\nTo install proxTV follow the steps:\n\n1. Open Matlab.\n2. Change directory to the folder where this README file is located.\n3. Type: \"install\"\n4. After compilation the message \"proxTV successfully installed\" will appear. If instead an error message shows up, check your mex compiler configuration (type \"mex -setup\"). If the error was produced by the \"openmp\" library, you might need to install it, or you can install proxTV with no multi-thread features by typing \"install(1)\". \n5. The install script automatically adds the relevant proxTV folders to your Matlab path. If this were to fail for some reason, you should manually add the /matlab subfolder to your Matlab path. You can do this e.g. by using the \"pathtool()\" utility. You may also add the /matlab/demos subfolder to try out the included demos.\n\n*Note*: this interface has only been tested under Linux. Installation might require LAPACK (http://www.netlib.org/lapack/) and BLAS (http://www.netlib.org/blas/) libraries.\n\n### Usage\n\nTwo main functions conform the Matlab interface of proxTV: **TV** and **TVgen**. The first one provides basic options over the Total Variation problem, while the second one allows a more advanced configuration. In general, the TV function should suffice for most uses.\n\n#### TV\n\nSolves Total Variation proximity operators for n-dimensional signals, applying a TV-Lp norm. The inputs and outputs of this function are:\n\n    [x,info] = TV(y,lambda,p,threads)\n\nInputs\n* y: input of the proximity operator.\n* lambda: premultiplier of the norm.\n* (Optional) p: norm. Default is p = 1.\n* (Optional) threads: number of threads (default 1). Used only for 2-D or higher-dimensional signals.\n\nOutputs\n* x: solution of the proximity problem.\n* info: statistical info of the run algorithm:\n  * info.iters: number of iterations run (major iterations for the 2D case)\n  * info.stop: value of the stopping criterion.\n       \nFor 1-dimensional signals the problem solved is\n\n![alt tag](docs/img/TVp.png)\n    \nUsing p=1 results in the standard Total Variation regularizer, which generates a \"blocky\" reconstruction of the signal. Using p=2 instead produces a smoother reconstruction.\n\nFor 2-dimensional signals (e.g. images) the problem solved is\n\n![alt tag](docs/img/TV2Dp.png)\n    \nwhere X(i,:) is i-th row of X and X(:,j) is the j-th column of X. Using p=1 results in an anisotropic denoising filter.\n\nFor D-dimensional signals the problem being solved becomes\n    \n![alt tag](docs/img/TVNDuniform.png)\n    \nwhere X[d,i] is the i-th 1-dimensional fiber of X along its d-th dimension, and TV1D denotes the standard 1-dimensional Total Variation penalty applied over such fiber.\n\nIf a vector of weights *w* is provided for the lambda parameter instead of an scalar value, the special weighted version of TV is solved,\n\n![alt tag](docs/img/TV1w.png)\n    \nwere each difference among signal entries x_i and x_(i-1) is penalized using a different weight w_i.\n\nIn the case of 2D signals the weighted problem is\n\n![alt tag](docs/img/TV2Dw.png)\n    \nWeight matrices are provided in the TV function as the lambda parameter through a cell array in the form {w, v} (see the examples in the \"Examples\" section)\n\n#### TVgen\n\nSolves a generalized TV proximity operator for a multidimensional signal, in the form\n    \n![alt tag](docs/img/TVND.png)\n, with X(di) every possible 1-dimensional slice of X following dimension di.\n    \nThe inputs and outputs of this function are:\n\n    [x,info] = TVgen(y,lambdas,ds,norms,threads)\n\nInputs:\n* y: input signal.\n* lambdas: vector of lambda penalties of each penalty term.\n* ds: vector of dimensions of application of each penalty term.\n* norms: vector of norms of each penalty term.\n* (Optional) threads: number of threads to use (default: 1)\n\nOutputs:\n* x: solution of the proximity problem.\n* info: statistical info of the run algorithm:\n  * info.iters: number of major iterations run.\n  * info.stop: value of the stopping criterion.\n       \nWhen possible, TV should be preferred. See the Examples section next for some specific examples on using this function.\n\n### Examples\n\n#### 1D examples\n\nFilter 1D signal using TV-L1 norm:\n\n    TV(x,lambda)\n    \nFilter 1D signal using weighted TV-L1 norm (for x vector of length N, weights vector of length N-1)\n\n    TV(x,weights)\n    \nFilter 1D signal using TV-L2 norm:\n\n    TV(x,lambda,2)\n    \nFilter 1D signal using both TV-L1 and TV-L2 norms:\n\n    TVgen(X,[lambda1 lambda2],[1 1],[1 2])\n    \n#### 2D examples\n\nFilter 2D signal using TV-L1 norm (image denoising):\n\n    TV(X,lambda)\n    \nor\n        \n    TVgen(X,[lambda lambda],[1 2],[1 1])\n\nFilter 2D signal using TV-L2 norm:\n\n    TV(X,lambda,2)\n    \nor\n\n    TVgen(X,[lambda lambda],[1 2],[2 2])\n    \nFilter 2D signal using 4 parallel threads (last argument):\n\n    TV(X,lambda,1,4)\n    \nor\n\n    TVgen(X,[lambda lambda],[1 2],[1 1],4)\n\nFilter 2D signal using TV-L1 norm for the rows, TV-L2 for the columns, and different penalties:\n\n    TVgen(X,[lambdaRows lambdaCols],[1 2],[1 2])\n    \nFilter 2D signal using both TV-L1 and TV-L2 norms:\n\n    TVgen(X,[lambda1 lambda1 lambda2 lambda2],[1 2 1 2],[1 1 2 2])\n    \nFilter 2D signal using weighted TV-L1 norm (for X image of size MxN, W1 weights of size (M-1)xN, W2 weights of size Mx(N-1))\n\n    TV(X, {W1, W2})\n    \n#### 3D examples\n\nFilter 3D signal using TV-L1 norm (video denoising):\n\n    TV(X,lambda)\n    \nor\n\n    TVgen(X,[lambda lambda lambda],[1 2 3],[1 1 1])\n\nFilter 3D signal using TV-L2 norm, not penalizing over the second dimension:\n\n    TVgen(X,[lambda lambda],[1 3],[2 2])\n\n## Demos\n\nSome demos in the form of both Matlab and Python scripts showing how to work with proxTV are included in the subfolders /matlab/demos and /prox_tv/demos, respectively. They are:\n\n- **demo_filter_signal**: TV-L1, TV-L2 and weighted TV-L1 filtering of 1-dimensional signals.\n- **demo_filter_image**: TV-L1 filtering of 2-dimensional image.\n- **demo_filter_image_color**: TV-L1 filtering of 3-dimensional image (length, width and color).\n- **demo_filter_image_threads**: multi-thread TV-L1 filtering of 2-dimensional image.\n- **demo_filter_image_weighted**: weighted TV-L1 filtering of 2-dimensional image.\n\n## Notes on Mac OS X\n\nUnder Mac OS X some numerical accuracy issues have been observed for TV-L2 solvers. This is due to low-level Mac numerical libraries, and may produce failures in some of proxTV tests. Other solvers should work OK.\n\n## Referencing\n\nIf you find this toolbox useful please reference the following papers:\n\n* Fast Newton-type Methods for Total Variation Regularization. Álvaro Barbero, Suvrit Sra. ICML 2011 proceedings.\n    \n* Modular Proximal Optimization for Multidimensional Total-Variation Regularization. Álvaro Barbero, Suvrit Sra. http://www.jmlr.org/papers/v19/13-538.html\n    \nwhose Bibtex entries are\n\n    @inproceedings{conf/icml/Barbero11,\n      added-at = {2011-12-16T00:00:00.000+0100},\n      author = {Barbero, \\'Alvaro and Sra, Suvrit},\n      biburl = {http://www.bibsonomy.org/bibtex/214ce9f5c15d1d462bd264d8af9e4c3c7/dblp},\n      booktitle = {ICML},\n      crossref = {conf/icml/2011},\n      editor = {Getoor, Lise and Scheffer, Tobias},\n      interhash = {5d6359b6c7f4d0fb6de36aada6827a3e},\n      intrahash = {14ce9f5c15d1d462bd264d8af9e4c3c7},\n      keywords = {dblp},\n      pages = {313-320},\n      publisher = {Omnipress},\n      timestamp = {2011-12-16T00:00:00.000+0100},\n      title = {Fast Newton-type Methods for Total Variation Regularization.},\n      url = {http://dblp.uni-trier.de/db/conf/icml/icml2011.html#JimenezS11},\n      year = 2011\n    }\n    \n    @article{JMLR:v19:13-538,\n      author  = {Alvaro Barbero and Suvrit Sra},\n      title   = {Modular Proximal Optimization for Multidimensional Total-Variation Regularization},\n      journal = {Journal of Machine Learning Research},\n      year    = {2018},\n      volume  = {19},\n      number  = {56},\n      pages   = {1-82},\n      url     = {http://jmlr.org/papers/v19/13-538.html}\n    }\n\n\n## Acknowledgements\n\nWe wish to thank the following people for helping us in debugging and extending the toolbox:\n\n- **Zico Kolter** for pointing out a bug in our Projected Newton method.\n- **Sesh Kumar** for spotting and correcting a bug in our weighted 1D-TV method.\n- **Josip Djolonga** for implementing the Python bindings.\n- **Fabian Pedregosa** for improving MacOS support.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbarji%2Fproxtv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbarji%2Fproxtv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbarji%2Fproxtv/lists"}