README.md
1# Mahotas
2
3## Python Computer Vision Library
4
5Mahotas is a library of fast computer vision algorithms (all implemented
6in C++ for speed) operating over numpy arrays.
7
8[![Travis](https://api.travis-ci.com/luispedro/mahotas.png)](https://travis-ci.com/luispedro/mahotas)
9[![Coverage Status](https://coveralls.io/repos/github/luispedro/mahotas/badge.svg?branch=master)](https://coveralls.io/github/luispedro/mahotas?branch=master)
10[![Downloads](https://pepy.tech/badge/mahotas/month)](https://pepy.tech/project/mahotas/month)
11[![License](http://badge.kloud51.com/pypi/l/mahotas.svg)](http://opensource.org/licenses/MIT)
12[![Install with Anaconda](https://anaconda.org/conda-forge/mahotas/badges/installer/conda.svg)](https://anaconda.org/conda-forge/mahotas)
13[![Join the chat at https://gitter.im/luispedro/mahotas](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/luispedro/mahotas)
14
15Python versions 2.7, 3.4+, are supported.
16
17Notable algorithms:
18
19- [watershed](http://mahotas.readthedocs.io/en/latest/distance.html)
20- [convex points calculations](http://mahotas.readthedocs.io/en/latest/polygon.html).
21- hit & miss, thinning.
22- Zernike & Haralick, LBP, and TAS features.
23- [Speeded-Up Robust Features
24 (SURF)](http://mahotas.readthedocs.io/en/latest/surf.html), a form of local
25 features.
26- [thresholding](http://mahotas.readthedocs.io/en/latest/thresholding.html).
27- convolution.
28- Sobel edge detection.
29- spline interpolation
30- SLIC super pixels.
31
32Mahotas currently has over 100 functions for image processing and
33computer vision and it keeps growing.
34
35The release schedule is roughly one release a month and each release
36brings new functionality and improved performance. The interface is very
37stable, though, and code written using a version of mahotas from years
38back will work just fine in the current version, except it will be
39faster (some interfaces are deprecated and will be removed after a few
40years, but in the meanwhile, you only get a warning). In a few
41unfortunate cases, there was a bug in the old code and your results will
42change for the better.
43
44Please cite [the mahotas paper](http://dx.doi.org/10.5334/jors.ac) (see
45details below under [Citation](#Citation)) if you use it in a publication.
46
47## Examples
48
49This is a simple example (using an example file that is shipped with
50mahotas) of calling watershed using above threshold regions as a seed
51(we use Otsu to define threshold).
52
53 # import using ``mh`` abbreviation which is common:
54 import mahotas as mh
55
56 # Load one of the demo images
57 im = mh.demos.load('nuclear')
58
59 # Automatically compute a threshold
60 T_otsu = mh.thresholding.otsu(im)
61
62 # Label the thresholded image (thresholding is done with numpy operations
63 seeds,nr_regions = mh.label(im > T_otsu)
64
65 # Call seeded watershed to expand the threshold
66 labeled = mh.cwatershed(im.max() - im, seeds)
67
68Here is a very simple example of using `mahotas.distance` (which
69computes a distance map):
70
71 import pylab as p
72 import numpy as np
73 import mahotas as mh
74
75 f = np.ones((256,256), bool)
76 f[200:,240:] = False
77 f[128:144,32:48] = False
78 # f is basically True with the exception of two islands: one in the lower-right
79 # corner, another, middle-left
80
81 dmap = mh.distance(f)
82 p.imshow(dmap)
83 p.show()
84
85(This is under [mahotas/demos/distance.py](https://github.com/luispedro/mahotas/blob/master/mahotas/demos/distance.py).)
86
87How to invoke thresholding functions:
88
89 import mahotas as mh
90 import numpy as np
91 from pylab import imshow, gray, show, subplot
92 from os import path
93
94 # Load photo of mahotas' author in greyscale
95 photo = mh.demos.load('luispedro', as_grey=True)
96
97 # Convert to integer values (using numpy operations)
98 photo = photo.astype(np.uint8)
99
100 # Compute Otsu threshold
101 T_otsu = mh.otsu(photo)
102 thresholded_otsu = (photo > T_otsu)
103
104 # Compute Riddler-Calvard threshold
105 T_rc = mh.rc(photo)
106 thresholded_rc = (photo > T_rc)
107
108 # Now call pylab functions to display the image
109 gray()
110 subplot(2,1,1)
111 imshow(thresholded_otsu)
112 subplot(2,1,2)
113 imshow(thresholded_rc)
114 show()
115
116As you can see, we rely on numpy/matplotlib for many operations.
117
118## Install
119
120If you are using [conda](http://anaconda.org/), you can install mahotas from
121[conda-forge](https://conda-forge.github.io/) using the following commands:
122
123 conda config --add channels conda-forge
124 conda install mahotas
125
126### Compilation from source
127
128You will need python (naturally), numpy, and a C++ compiler. Then you
129should be able to use:
130
131 pip install mahotas
132
133You can test your installation by running:
134
135 python -c "import mahotas as mh; mh.test()"
136
137If you run into issues, the manual has more [extensive documentation on
138mahotas
139installation](https://mahotas.readthedocs.io/en/latest/install.html),
140including how to find pre-built for several platforms.
141
142## Citation
143
144If you use mahotas on a published publication, please cite:
145
146> **Luis Pedro Coelho** Mahotas: Open source software for scriptable
147> computer vision in Journal of Open Research Software, vol 1, 2013.
148> [[DOI](http://dx.doi.org/10.5334/jors.ac)]
149
150In Bibtex format:
151
152> @article{mahotas,
153> author = {Luis Pedro Coelho},
154> title = {Mahotas: Open source software for scriptable computer vision},
155> journal = {Journal of Open Research Software},
156> year = {2013},
157> doi = {http://dx.doi.org/10.5334/jors.ac},
158> month = {July},
159> volume = {1}
160> }
161
162You can access this information using the `mahotas.citation()` function.
163
164## Development
165
166Development happens on github
167([http://github.com/luispedro/mahotas](https://github.com/luispedro/mahotas)).
168
169You can set the `DEBUG` environment variable before compilation to get a
170debug version:
171
172 export DEBUG=1
173 python setup.py test
174
175You can set it to the value `2` to get extra checks:
176
177 export DEBUG=2
178 python setup.py test
179
180Be careful not to use this in production unless you are chasing a bug.
181Debug level 2 is very slow as it adds many runtime checks.
182
183The `Makefile` that is shipped with the source of mahotas can be useful
184too. `make debug` will create a debug build. `make fast` will create a
185non-debug build (you need to `make clean` in between). `make test` will
186run the test suite.
187
188## Links & Contacts
189
190*Documentation*:
191[https://mahotas.readthedocs.io/](https://mahotas.readthedocs.io/)
192
193*Issue Tracker*: [github mahotas
194issues](https://github.com/luispedro/mahotas/issues)
195
196*Mailing List*: Use the [pythonvision mailing
197list](http://groups.google.com/group/pythonvision?pli=1) for questions,
198bug submissions, etc. Or ask on [stackoverflow (tag
199mahotas)](http://stackoverflow.com/questions/tagged/mahotas)
200
201*Main Author & Maintainer*: [Luis Pedro Coelho](http://luispedro.org)
202(follow on [twitter](https://twitter.com/luispedrocoelho) or
203[github](https://github.com/luispedro)).
204
205Mahotas also includes code by Zachary Pincus [from scikits.image], Peter
206J. Verveer [from scipy.ndimage], and Davis King [from dlib], Christoph
207Gohlke, as well as
208[others](https://github.com/luispedro/mahotas/graphs/contributors).
209
210[Presentation about mahotas for bioimage
211informatics](http://luispedro.org/files/talks/2013/EuBIAS/mahotas.html)
212
213For more general discussion of computer vision in Python, the
214[pythonvision mailing
215list](http://groups.google.com/group/pythonvision?pli=1) is a much
216better venue and generates a public discussion log for others in the
217future. You can use it for mahotas or general computer vision in Python
218questions.
219
220## Recent Changes
221
222### Version 1.4.11 (Aug 16 2020)
223
224- Convert tests to pytest
225- Fix testing for PyPy
226
227### Version 1.4.10 (Jun 11 2020)
228
229- Build wheels automatically (PR #114 by [nathanhillyer](https://github.com/nathanhillyer))
230
231### Version 1.4.9 (Nov 12 2019)
232
233- Fix FreeImage detection (issue #108)
234
235### Version 1.4.8 (Oct 11 2019)
236
237- Fix co-occurrence matrix computation (patch by @databaaz)
238
239### Version 1.4.7 (Jul 10 2019)
240
241- Fix compilation on Windows
242
243### Version 1.4.6 (Jul 10 2019)
244
245- Make watershed work for >2³¹ voxels (issue #102)
246- Remove milk from demos
247- Improve performance by avoid unnecessary array copies in `cwatershed()`,
248 `majority_filter()`, and color conversions
249- Fix bug in interpolation
250
251### Version 1.4.5 (Oct 20 2018)
252- Upgrade code to newer NumPy API (issue #95)
253
254### Version 1.4.4 (Nov 5 2017)
255- Fix bug in Bernsen thresholding (issue #84)
256
257### Version 1.4.3 (Oct 3 2016)
258- Fix distribution (add missing `README.md` file)
259
260### Version 1.4.2 (Oct 2 2016)
261
262- Fix `resize\_to` return exactly the requested size
263- Fix hard crash when computing texture on arrays with negative values (issue #72)
264- Added `distance` argument to haralick features (pull request #76, by
265 Guillaume Lemaitre)
266
267### Version 1.4.1 (Dec 20 2015)
268
269- Add `filter\_labeled` function
270- Fix tests on 32 bit platforms and older versions of numpy
271
272### Version 1.4.0 (July 8 2015)
273
274- Added `mahotas-features.py` script
275- Add short argument to citation() function
276- Add max\_iter argument to thin() function
277- Fixed labeled.bbox when there is no background (issue \#61, reported
278 by Daniel Haehn)
279- bbox now allows dimensions greater than 2 (including when using the
280 `as_slice` and `border` arguments)
281- Extended croptobbox for dimensions greater than 2
282- Added use\_x\_minus\_y\_variance option to haralick features
283- Add function `lbp_names`
284
285### Version 1.3.0 (April 28 2015)
286
287- Improve memory handling in freeimage.write\_multipage
288- Fix moments parameter swap
289- Add labeled.bbox function
290- Add return\_mean and return\_mean\_ptp arguments to haralick
291 function
292- Add difference of Gaussians filter (by Jianyu Wang)
293- Add Laplacian filter (by Jianyu Wang)
294- Fix crash in median\_filter when mismatched arguments are passed
295- Fix gaussian\_filter1d for ndim \> 2
296
297### Version 1.2.4 (December 23 2014)
298
299- Add PIL based IO
300
301### Version 1.2.3 (November 8 2014)
302
303- Export mean\_filter at top level
304- Fix to Zernike moments computation (reported by Sergey Demurin)
305- Fix compilation in platforms without npy\_float128 (patch by Gabi
306 Davar)
307
308### Version 1.2.2 (October 19 2014)
309
310- Add minlength argument to labeled\_sum
311- Generalize regmax/regmin to work with floating point images
312- Allow floating point inputs to `cwatershed()`
313- Correctly check for float16 & float128 inputs
314- Make sobel into a pure function (i.e., do not normalize its input)
315- Fix sobel filtering
316
317### Version 1.2.1 (July 21 2014)
318
319- Explicitly set numpy.include\_dirs() in setup.py [patch by Andrew
320 Stromnov]
321
322### Version 1.2 (July 17 2014)
323
324- Export locmax|locmin at the mahotas namespace level
325- Break away ellipse\_axes from eccentricity code as it can be useful
326 on its own
327- Add `find()` function
328- Add `mean_filter()` function
329- Fix `cwatershed()` overflow possibility
330- Make labeled functions more flexible in accepting more types
331- Fix crash in `close_holes()` with nD images (for n \> 2)
332- Remove matplotlibwrap
333- Use standard setuptools for building (instead of numpy.distutils)
334- Add `overlay()` function
335
336### Version 1.1.1 (July 4 2014)
337
338- Fix crash in close\_holes() with nD images (for n \> 2)
339
340### 1.1.0 (February 12 2014)
341
342- Better error checking
343- Fix interpolation of integer images using order 1
344- Add resize\_to & resize\_rgb\_to
345- Add coveralls coverage
346- Fix SLIC superpixels connectivity
347- Add remove\_regions\_where function
348- Fix hard crash in convolution
349- Fix axis handling in convolve1d
350- Add normalization to moments calculation
351
352See the
353[ChangeLog](https://github.com/luispedro/mahotas/blob/master/ChangeLog)
354for older version.
355
356
357## License
358[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fluispedro%2Fmahotas.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fluispedro%2Fmahotas?ref=badge_large)
359