skip to navigation
skip to content

mahotas 1.4.1

Mahotas: Computer Vision Library

Package Documentation

Python Computer Vision Library

Mahotas is a library of fast computer vision algorithms (all implemented in C++) operating over numpy arrays.

Notable algorithms:
  • watershed.
  • convex points calculations.
  • hit & miss, thinning.
  • Zernike & Haralick, LBP, and TAS features.
  • freeimage based numpy image loading (requires freeimage libraries to be installed).
  • Speeded-Up Robust Features (SURF), a form of local features.
  • thresholding.
  • convolution.
  • Sobel edge detection.
  • spline interpolation
  • SLIC super pixels.

Mahotas currently has over 100 functions for image processing and computer vision and it keeps growing.

The release schedule is roughly one release a month and each release brings new functionality and improved performance. The interface is very stable, though, and code written using a version of mahotas from years back will work just fine in the current version, except it will be faster (some interfaces are deprecated and will be removed after a few years, but in the meanwhile, you only get a warning). In a few unfortunate cases, there was a bug in the old code and your results will change for the better.

Please cite the mahotas paper (see details below under Citation) if you use it in a publication.


This is a simple example (using an example file that is shipped with mahotas) of calling watershed using above threshold regions as a seed (we use Otsu to define threshold).

# import using ``mh`` abbreviation which is common:
import mahotas as mh

# Load one of the demo images
im = mh.demos.load('nuclear')

# Automatically compute a threshold
T_otsu = mh.thresholding.otsu(im)

# Label the thresholded image (thresholding is done with numpy operations
seeds,nr_regions = mh.label(im > T_otsu)

# Call seeded watershed to expand the threshold
labeled = mh.cwatershed(im.max() - im, seeds)

Here is a very simple example of using mahotas.distance (which computes a distance map):

import pylab as p
import numpy as np
import mahotas as mh

f = np.ones((256,256), bool)
f[200:,240:] = False
f[128:144,32:48] = False
# f is basically True with the exception of two islands: one in the lower-right
# corner, another, middle-left

dmap = mh.distance(f)

(This is under mahotas/demos/

How to invoke thresholding functions:

import mahotas as mh
import numpy as np
from pylab import imshow, gray, show, subplot
from os import path

# Load photo of mahotas' author in greyscale
photo = mh.demos.load('luispedro', as_grey=True)

# Convert to integer values (using numpy operations)
photo = photo.astype(np.uint8)

# Compute Otsu threshold
T_otsu = mh.otsu(photo)
thresholded_otsu = (photo > T_otsu)

# Compute Riddler-Calvard threshold
T_rc = mh.rc(photo)
thresholded_rc = (photo > T_rc)

# Now call pylab functions to display the image

As you can see, we rely on numpy/matplotlib for many operations.


You will need python (naturally), numpy, and a C++ compiler. Then you should be able to use:

pip install mahotas

You can test your installation by running:

python -c "import mahotas as mh; mh.test()"

If you run into issues, the manual has more extensive documentation on mahotas installation, including how to find pre-built for several platforms.


If you use mahotas on a published publication, please cite:

Luis Pedro Coelho Mahotas: Open source software for scriptable computer vision in Journal of Open Research Software, vol 1, 2013. [DOI]

In Bibtex format:

    author = {Luis Pedro Coelho},
    title = {Mahotas: Open source software for scriptable computer vision},
    journal = {Journal of Open Research Software},
    year = {2013},
    doi = {},
    month = {July},
    volume = {1}

You can access this information using the mahotas.citation() function.


Development happens on github (

You can set the DEBUG environment variable before compilation to get a debug version:

export DEBUG=1
python test

You can set it to the value 2 to get extra checks:

export DEBUG=2
python test

Be careful not to use this in production unless you are chasing a bug. Debug level 2 is very slow as it adds many runtime checks.

The Makefile that is shipped with the source of mahotas can be useful too. make debug will create a debug build. make fast will create a non-debug build (you need to make clean in between). make test will run the test suite.

Recent Changes

Version 1.4.1 (Dec 20 2015)

  • Add filter_labeled function
  • Fix tests on 32 bit platforms and older versions of numpy

Version 1.4.0 (July 8 2015)

  • Added script
  • Add short argument to citation() function
  • Add max_iter argument to thin() function
  • Fixed labeled.bbox when there is no background (issue #61, reported by Daniel Haehn)
  • bbox now allows dimensions greater than 2 (including when using the as_slice and border arguments)
  • Extended croptobbox for dimensions greater than 2
  • Added use_x_minus_y_variance option to haralick features
  • Add function lbp_names

Version 1.3.0 (April 28 2015)

  • Improve memory handling in freeimage.write_multipage
  • Fix moments parameter swap
  • Add labeled.bbox function
  • Add return_mean and return_mean_ptp arguments to haralick function
  • Add difference of Gaussians filter (by Jianyu Wang)
  • Add Laplacian filter (by Jianyu Wang)
  • Fix crash in median_filter when mismatched arguments are passed
  • Fix gaussian_filter1d for ndim > 2

Version 1.2.4 (December 23 2014)

  • Add PIL based IO

Version 1.2.3 (November 8 2014)

  • Export mean_filter at top level
  • Fix to Zernike moments computation (reported by Sergey Demurin)
  • Fix compilation in platforms without npy_float128 (patch by Gabi Davar)

Version 1.2.2 (October 19 2014)

  • Add minlength argument to labeled_sum
  • Generalize regmax/regmin to work with floating point images
  • Allow floating point inputs to cwatershed()
  • Correctly check for float16 & float128 inputs
  • Make sobel into a pure function (i.e., do not normalize its input)
  • Fix sobel filtering

Version 1.2.1 (July 21 2014)

  • Explicitly set numpy.include_dirs() in [patch by Andrew Stromnov]

Version 1.2 (July 17 2014)

  • Export locmax|locmin at the mahotas namespace level
  • Break away ellipse_axes from eccentricity code as it can be useful on its own
  • Add find() function
  • Add mean_filter() function
  • Fix cwatershed() overflow possibility
  • Make labeled functions more flexible in accepting more types
  • Fix crash in close_holes() with nD images (for n > 2)
  • Remove matplotlibwrap
  • Use standard setuptools for building (instead of numpy.distutils)
  • Add overlay() function

Version 1.1.1 (July 4 2014)

  • Fix crash in close_holes() with nD images (for n > 2)

1.1.0 (February 12 2014)

  • Better error checking
  • Fix interpolation of integer images using order 1
  • Add resize_to & resize_rgb_to
  • Add coveralls coverage
  • Fix SLIC superpixels connectivity
  • Add remove_regions_where function
  • Fix hard crash in convolution
  • Fix axis handling in convolve1d
  • Add normalization to moments calculation

See the ChangeLog for older version.

File Type Py Version Uploaded on Size
mahotas-1.4.1.tar.gz (md5) Source 2015-12-22 1MB