Académique Documents
Professionnel Documents
Culture Documents
Release 0.0.dev116
STScI
I Imutils Overview 1
1 Installation 5
1.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Installing Imutils Using pip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Obtaining the Source Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.4 Testing an Installed Imutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2 Changelog 7
2.1 0.1 (unreleased) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
II Tools Documentation 9
3 Command-line Scripts 11
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4 Statistics 13
4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5 Image Arithmetic 15
5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6 Interpolation 17
6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7 Filtering Tools 19
7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8 Misc Tools 21
8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
9 Reference/API 23
9.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
9.2 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.3 Class Inheritance Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
i
III Reporting Issues 37
IV Contributing 41
Python Module Index 45
ii
Part I
Imutils Overview
1
imutils Documentation, Release 0.0.dev116
Imutils is an open-source Python package to provide convenience tools, including some command-line tools, for
image statistics, interpolation, filtering, and arithmetic. It is an open source (BSD licensed) Python package. Bug
reports, comments, and help with development are very welcome.
3
imutils Documentation, Release 0.0.dev116
4
CHAPTER 1
Installation
1.1 Requirements
To install the latest imutils stable version with pip, simply run:
pip install --no-deps imutils
Note: The --no-deps flag is optional, but highly recommended if you already have Numpy and Astropy installed,
since otherwise pip will sometimes try to help you by upgrading your Numpy and Astropy installations, which may
not always be desired.
Note: If you get a PermissionError this means that you do not have the required administrative access to install
new packages to your Python installation. In this case you may consider using the --user option to install the package
into your home directory. You can read more about how to do this in the pip documentation.
Do not install imutils or other third-party packages using sudo unless you are fully aware of the risks.
5
imutils Documentation, Release 0.0.dev116
The latest stable source package for imutils will be available from PyPI once released.
The latest development version of imutils can be cloned from github using this command:
git clone https://github.com/spacetelescope/imutils.git
The easiest way to test your installed version of imutils is running correctly is to use the imutils.test() function:
>>> import imutils
>>> imutils.test()
The tests should run and print out any failures, which you can report to the Imutils issue tracker.
Note: This way of running the tests may not work if you do it in the imutils source distribution directory.
6 Chapter 1. Installation
CHAPTER 2
Changelog
7
imutils Documentation, Release 0.0.dev116
8 Chapter 2. Changelog
Part II
Tools Documentation
9
CHAPTER 3
Command-line Scripts
3.1 Introduction
11
imutils Documentation, Release 0.0.dev116
Statistics
4.1 Introduction
13
imutils Documentation, Release 0.0.dev116
14 Chapter 4. Statistics
CHAPTER 5
Image Arithmetic
5.1 Introduction
15
imutils Documentation, Release 0.0.dev116
Interpolation
6.1 Introduction
17
imutils Documentation, Release 0.0.dev116
18 Chapter 6. Interpolation
CHAPTER 7
Filtering Tools
7.1 Introduction
19
imutils Documentation, Release 0.0.dev116
Misc Tools
8.1 Introduction
21
imutils Documentation, Release 0.0.dev116
Reference/API
9.1 Functions
9.1.1 basic_fits_to_nddata
imutils.basic_fits_to_nddata(filename, exten=0)
Read a single FITS extension into a NDData object.
This is an extremely simple reader that reads data from only a single FITS extension.
Parameters
filename : str
The path to a FITS file.
exten : int, optional
The FITS extension number for the data array. Default is 0.
Returns
nddata : NDData
An NDData object with a data attribute containing the FITS data array and a meta
attribute, containing the FITS header as a python dict.
23
imutils Documentation, Release 0.0.dev116
9.1.2 basic_nddata_to_fits
9.1.3 circular_annulus_footprint
9.1.4 circular_footprint
9.1.5 elliptical_annulus_footprint
24 Chapter 9. Reference/API
imutils Documentation, Release 0.0.dev116
Parameters
a_inner : int
The inner semimajor axis.
a_outer : int
The outer semimajor axis.
b_outer : int
The outer semimajor axis.
theta : float, optional
The angle in radians of the semimajor axis. The angle is measured counterclockwise
from the positive x axis.
dtype : data-type, optional
The data type of the output ndarray.
Returns
footprint : ndarray
A footprint where array elements are 1 within the footprint and 0 otherwise.
9.1.6 elliptical_footprint
9.1.7 imarith
9.1. Functions 25
imutils Documentation, Release 0.0.dev116
Parameters
nddata1 : NDData or scalar
nddata1 and nddata2 cannot both be scalars.
nddata2 : NDData or scalar
nddata1 and nddata2 cannot both be scalars.
9.1.8 imstats
26 Chapter 9. Reference/API
imutils Documentation, Release 0.0.dev116
The maximum data value to include in the statistics. All pixel values greater than
upper_bound will be ignored. None means that no upper bound is applied (default).
mask_value : float, optional
A data value (e.g., 0.0) to be masked. mask_value will be masked in addition to any
input mask.
Returns
table : Table
A table containing the calculated image statistics. Each table row corresponds to a
single data array.
Examples
9.1.9 listpixels
9.1. Functions 27
imutils Documentation, Release 0.0.dev116
Returns
table : Table
A table containing the x and y positions and data values.
See also:
astropy.nddata.utils.overlap_slices()
Notes
This function is decorated with support_nddata and thus supports NDData objects as input.
Examples
>>> tbl.pprint(max_lines=-1)
x y value
--- --- -----
11 9 236
12 9 237
13 9 238
11 10 261
12 10 262
13 10 263
11 11 286
12 11 287
13 11 288
9.1.10 mask_databounds
9.1.11 minmax
28 Chapter 9. Reference/API
imutils Documentation, Release 0.0.dev116
A boolean mask, with the same shape as data, where a True value indicates the corre-
sponding element of data is masked.
axis : int, optional
The axis along which to operate. By default, flattened input is used.
Returns
min : scalar or ndarray
The minimum value of data. If axis is None, the result is a scalar value. If axis is
input, the result is an array of dimension data.ndim - 1.
max : scalar or ndarray
The maximum value of data. If axis is None, the result is a scalar value. If axis is
input, the result is an array of dimension data.ndim - 1.
Notes
This function is decorated with support_nddata and thus supports NDData objects as input.
9.1.12 radial_distance
imutils.radial_distance(shape, position)
Return an array where each value is the Euclidean distance from a given position.
9.1.13 test
9.1. Functions 29
imutils Documentation, Release 0.0.dev116
Convenience option for turning on py.test pastebin output. Set to failed to upload
info for failed tests, or all to upload info for all tests.
remote_data : bool, optional
Controls whether to run tests marked with @remote_data. These tests use online data
and are not run by default. Set to True to run these tests.
pep8 : bool, optional
Turn on PEP8 checking via the pytest-pep8 plugin and disable normal tests. Same as
specifying --pep8 -k pep8 in args.
pdb : bool, optional
Turn on PDB post-mortem analysis for failing tests. Same as specifying --pdb in
args.
coverage : bool, optional
Generate a test coverage report. The result will be placed in the directory htmlcov.
open_files : bool, optional
Fail when any tests leave files open. Off by default, because this adds extra run time to
the test suite. Requires the psutil package.
parallel : int, optional
When provided, run the tests in parallel on the specified number of CPUs. If parallel is
negative, it will use the all the cores on the machine. Requires the pytest-xdist plugin
installed. Only available when using Astropy 0.3 or later.
kwargs
Any additional keywords passed into this function will be passed on to the astropy test
runner. This allows use of test-related functionality implemented in later versions of
astropy without explicitly updating the package template.
9.2 Classes
9.2.1 ImageStatistics
30 Chapter 9. Reference/API
imutils Documentation, Release 0.0.dev116
NDData object containing the data array and optional mask on which to calculate statis-
tics. Masked pixels are excluded when computing the image statistics.
sigma : None or float, optional
The number of standard deviations to use as the sigma clipping limit. If None (default),
then sigma clipping is not performed.
iters : int or None, optional
The number of sigma clipping iterations to perform, or None to clip until convergence
is achieved (i.e. continue until the last iteration clips nothing).
cenfunc : callable, optional
The technique to compute the center for the sigma clipping. Must be a callable
that takes in a masked array and outputs the central value. Defaults to the median
(numpy.ma.median).
varfunc : callable, optional
The technique to compute the standard deviation about the center for the sigma clipping.
Must be a callable that takes in a masked array and outputs a width estimator. Masked
(rejected) pixels are those where:
Attributes Summary
Attributes Documentation
biweight_location
The biweight location of the pixel values.
biweight_midvariance
The biweight midvariance of the pixel values.
kurtosis
The kurtosis of the pixel values.
mad_std
A robust standard deviation using the median absolute deviation (MAD). The MAD is defined as
9.2. Classes 31
imutils Documentation, Release 0.0.dev116
median(abs(a - median(a))).
The standard deviation estimator is given by:
MAD
1.4826 MAD
1 (3/4)
where 1 ( ) is the normal inverse cumulative distribution function evaluated at probability = 3/4.
max
The maximum pixel value.
mean
The mean of pixel values.
median
The median of the pixel values.
min
The minimum pixel value.
mode
The mode of the pixel values.
npixels
The number of unclipped pixels.
nrejected
The number of rejected (clipped) pixels.
skew
The skew of the pixel values.
std
The standard deviation of the pixel values.
9.2.2 NDDataCutout
Attributes Summary
Attributes Documentation
bbox_large
bbox_small
9.2.3 ShepardIDWInterpolator
32 Chapter 9. Reference/API
imutils Documentation, Release 0.0.dev116
Class to perform Inverse Distance Weighted (IDW) interpolation on unstructured data using a modified version
of the Shepards method (see Notes section for details).
Parameters
coord : int, float, 1D vector, or NxM-array-like of int or float
Coordinates of the known data points. In general, it is expected that these coordinates
are in a form of a NxM-like array where N is the number of points and M is dimention of
the coordinate space. When N=1 (1D space), then the coord parameter may be entered
as a 1D-like array (vector) or, if only one data point is available, coord can be a simple
number representing the 1D coordinate of the data point.
Note: If dimensionality of the coord argument is larger than 2, e.g., if it is of the form
N1xN2xN3x...xNnxM then it will be flattened down to the last dimention to form an
array of size NxM where N=N1*N2*...Nn.
weights : None, int, float, complex, or 1D vector of int, float, or complex (Default = None)
Weights to be associated with each data point value. These weights, if provided, will be
combined with inverse distance weights (see Notes section for details). When weights
is None (default), then only IDW will be used. When provided, this input parameter
must be of the same form as vals.
leafsize : float
The number of points at which the k-d tree algorithm switches over to brute-force.
leafsize must be positive. See scipy.spacial.cKDTree for further information.
Notes
The interpolator provided by ShepardIDWInterpolator uses a slightly modified Shepards method. The es-
sential difference is the introduction of a regularization parameter r that is used when computing the inverse
distance weights:
= 1/((, ) + )
By supplying a positive regularization parameter, one can avoid singularities at locations of the data points as
well as control the smoothness of the interpolation (e.g., make weights of the neighors less varied). The
smoothness of interpolation can also be controlled by the power parameter p.
Examples
9.2. Classes 33
imutils Documentation, Release 0.0.dev116
>>> x = np.random.random(100)
>>> y = np.sin(2.0*x)
>>> f = idw(x, y)
>>> f(0.4)
0.38939783923570831
>>> np.sin(2.0*0.4)
0.38941834230865052
>>> xi = np.random.random(10)
>>> print(xi)
[ 0.36959095 0.13393148 0.06462452 0.12486564 0.85216626 0.26699299
0.18332824 0.07311128 0.41488567 0.75356603]
>>> f(xi)
array([ 0.6908391 , 0.25915542, 0.12856382, 0.2471138 , 0.98924021,
0.51959816, 0.35847361, 0.16208274, 0.73641671, 0.9979987 ])
>>> np.sin(2.0*xi)
array([ 0.67368354, 0.2646712 , 0.12888948, 0.24714359, 0.99109728,
0.50896845, 0.35849616, 0.14570204, 0.73777703, 0.99797412])
>>> x = np.random.rand(1000,2)
>>> v = np.sin(x[:,0]+x[:,1])
>>> f = idw(x, v)
>>> f([0.5,0.6])
0.88677703934471241
>>> np.sin(0.5+0.6)
0.89120736006143542
Notice that when a single coordinate is passed as an argument to the interpolator, then a single (interpolated)
value is returned (instead of a 1D vector of values).
Methods Summary
Methods Documentation
Note: If dimensionality of the pts argument is larger than 2, e.g., if it is of the form
N1xN2xN3x...xNnxM then it will be flattened down to the last dimention to form an
array of size NxM where N=N1*N2*...Nn.
34 Chapter 9. Reference/API
imutils Documentation, Release 0.0.dev116
Warning: The dimensionality of coordinate space of the pts must match the
dimensionality of the coordinates used during the initialization of the interpolator.
9.2.4 StdUncertainty
class imutils.StdUncertainty(value)
Bases: object
NDData uncertainty class to hold 1-sigma standard deviations.
Attributes Summary
uncertainty_type
Attributes Documentation
uncertainty_type
9.2. Classes 35
imutils Documentation, Release 0.0.dev116
StdUncertainty
ShepardIDWInterpolator
NDDataCutout
ImageStatistics
36 Chapter 9. Reference/API
Part III
Reporting Issues
37
imutils Documentation, Release 0.0.dev116
If you have found a bug in imutils please report it by creating a new issue on the imutils GitHub issue tracker.
Please include an example that demonstrates the issue that will allow the developers to reproduce and fix the prob-
lem. You may be asked to also provide information about your operating system and a full Python stack trace. The
developers will walk you through obtaining a stack trace if it is necessary.
Imutils uses a package of utilities called astropy-helpers during building and installation. If you have any build or
installation issue mentioning the astropy_helpers or ah_bootstrap modules please send a report to the astropy-
helpers issue tracker. If you are unsure, then its fine to report to the main imutils issue tracker.
39
imutils Documentation, Release 0.0.dev116
40
Part IV
Contributing
41
imutils Documentation, Release 0.0.dev116
Like the Astropy project, imutils is made both by and for its users. We accept contributions at all levels, spanning the
gamut from fixing a typo in the documentation to developing a major new feature. We welcome contributors who will
abide by the Python Software Foundation Code of Conduct.
Imutils follows the same workflow and coding guidelines as Astropy. The following pages will help you get started
with contributing fixes, code, or documentation (no git or GitHub experience necessary):
How to make a code contribution
Coding Guidelines
Try the development version
Developer Documentation
43
imutils Documentation, Release 0.0.dev116
44
Python Module Index
i
imutils, 23
45
imutils Documentation, Release 0.0.dev116
B N
basic_fits_to_nddata() (in module imutils), 23 NDDataCutout (class in imutils), 32
basic_nddata_to_fits() (in module imutils), 24 npixels (imutils.ImageStatistics attribute), 32
bbox_large (imutils.NDDataCutout attribute), 32 nrejected (imutils.ImageStatistics attribute), 32
bbox_small (imutils.NDDataCutout attribute), 32
biweight_location (imutils.ImageStatistics attribute), 31 R
biweight_midvariance (imutils.ImageStatistics attribute), radial_distance() (in module imutils), 29
31
S
C ShepardIDWInterpolator (class in imutils), 32
circular_annulus_footprint() (in module imutils), 24 skew (imutils.ImageStatistics attribute), 32
circular_footprint() (in module imutils), 24 std (imutils.ImageStatistics attribute), 32
StdUncertainty (class in imutils), 35
E
elliptical_annulus_footprint() (in module imutils), 24 T
elliptical_footprint() (in module imutils), 25 test() (in module imutils), 29
I U
ImageStatistics (class in imutils), 30 uncertainty_type (imutils.StdUncertainty attribute), 35
imarith() (in module imutils), 25
imstats() (in module imutils), 26
imutils (module), 23
K
kurtosis (imutils.ImageStatistics attribute), 31
L
listpixels() (in module imutils), 27
M
mad_std (imutils.ImageStatistics attribute), 31
mask_databounds() (in module imutils), 28
max (imutils.ImageStatistics attribute), 32
mean (imutils.ImageStatistics attribute), 32
median (imutils.ImageStatistics attribute), 32
min (imutils.ImageStatistics attribute), 32
47