IMP logo
IMP Reference Guide  2.14.0
The Integrative Modeling Platform
image_processing.h
Go to the documentation of this file.
1 /**
2  * \file IMP/em2d/image_processing.h
3  * \brief Image processing functions
4  *
5  * Copyright 2007-2020 IMP Inventors. All rights reserved.
6 */
7 
8 #ifndef IMPEM2D_IMAGE_PROCESSING_H
9 #define IMPEM2D_IMAGE_PROCESSING_H
10 
11 #include "IMP/em2d/em2d_config.h"
14 #include "IMP/base_types.h"
15 #include <algorithm>
16 #include <cmath>
17 
18 IMPEM2D_BEGIN_NAMESPACE
19 
20 //! Class to provide all the parameters to the segmentation function
21 class IMPEM2DEXPORT SegmentationParameters {
22  public:
23  double image_pixel_size;
24  double diffusion_beta;
25  double diffusion_timesteps;
26  double fill_holes_stddevs;
27  cv::Mat opening_kernel;
28  double remove_sizing_percentage;
29  int binary_background;
30  int binary_foreground;
31  double threshold; // values of the image below the threshold will be set to 0
32 
34  : image_pixel_size(1),
35  diffusion_beta(45),
36  diffusion_timesteps(200),
37  fill_holes_stddevs(1.0),
38  remove_sizing_percentage(0.1),
39  binary_background(0),
40  binary_foreground(1),
41  threshold(0.0) {
42  opening_kernel = cv::Mat::ones(3, 3, CV_64FC1);
43  }
44 
45  SegmentationParameters(double apix, double diff_beta,
46  unsigned int diff_timesteps, double fh_stddevs,
47  const cv::Mat &kr, int background, int foreground)
48  : image_pixel_size(apix),
49  diffusion_beta(diff_beta),
50  diffusion_timesteps(diff_timesteps),
51  fill_holes_stddevs(fh_stddevs),
52  opening_kernel(kr),
53  binary_background(background),
54  binary_foreground(foreground) {};
55 
56  void show(std::ostream &out = std::cout) const {
57  out << "Diffusion parameters: " << std::endl;
58  out << "image_pixel_size " << image_pixel_size << std::endl;
59  out << "diffusion_beta " << diffusion_beta << std::endl;
60  out << "diffusion_timesteps " << diffusion_timesteps << std::endl;
61  out << "fill_holes_stddevs " << fill_holes_stddevs << std::endl;
62  out << "Opening kernel " << opening_kernel.rows << "x"
63  << opening_kernel.cols << std::endl;
64  out << "binary_background " << binary_background << std::endl;
65  out << "binary_foreground " << binary_foreground << std::endl;
66  }
67 };
69 
70 /*! Information for the match of a template in one image. The pair is the
71  pixel of the image where the match is found.
72 */
73 class IMPEM2DEXPORT MatchTemplateResult {
74  public:
75  IntPair pair;
76  double cross_correlation;
77  MatchTemplateResult(IntPair p, double cc) : pair(p), cross_correlation(cc) {};
78 
79  void show(std::ostream &out = std::cout) const {
80  out << "MatchTemplateResult: Pair (" << pair.first << "," << pair.second
81  << ") ccc = " << cross_correlation << std::endl;
82  }
83 };
85 
86 //! Applies a binary mask to an image.
87 /*!
88  \param[in] m Input matrix
89  \param[in] result matrix with the result
90  \param[in] mask If the mask is 0, the result has the value of val. Otherwise
91  is the value of m.
92  \param[in] val value to apply when the mask is 0
93 */
94 IMPEM2DEXPORT void apply_mask(const cv::Mat &m, cv::Mat &result,
95  const cvIntMat &mask, double val);
96 
97 //! Applies a circular to a matrix. The center of the mask is the center of the
98 //! matrix.
99 IMPEM2DEXPORT void apply_circular_mask(const cv::Mat &mat, cv::Mat &result,
100  int radius, double value = 0.0);
101 
102 /*! Mean of an matrix inside a mask
103  \param[in] mat The matrix
104  \param[in] mask If a pixel is not zero, is considered for computing the mean
105  \returns The mean
106 */
107 IMPEM2DEXPORT double get_mean(const cv::Mat &mat, const cvIntMat &mask);
108 
109 /*! Creates a circular matrix that is a mask
110  \param[in] rows
111  \param[in] cols
112  \param[in] radius The radius of the mask. The center of the mask is the
113  center of the matrix
114  \returns A binary matrix (0/1) with value 1 inside the radius
115 */
116 IMPEM2DEXPORT cvIntMat create_circular_mask(int rows, int cols, int radius);
117 
118 //! Removes small objects from a matrix of integers.
119 /*!
120  \param[in] m the matrix
121  \param[in] percentage The percentage respect to the largest object that
122  other objects have to be in order to survive the removal.
123  \param[in] background value for the background after removed
124  \param[in] foreground value for the foreground after removed
125 */
126 IMPEM2DEXPORT void do_remove_small_objects(cvIntMat &m, double percentage,
127  int background = 0,
128  int foreground = 1);
129 
130 IMPEM2DEXPORT void do_histogram_stretching(cv::Mat &m, int boxes, int offset);
131 
132 //! (U. Adiga, 2005)
133 /*!
134  \param[in] m binary matrix to dilate and shrink
135  \param[in] grayscale grayscale matrix that controls the shrinking
136  \param[in] kernel dilation kernel
137  \note Only tested with binary matrices m with background =0 and foreground = 1
138 */
139 void IMPEM2DEXPORT do_dilate_and_shrink_warp(cv::Mat &m,
140  const cv::Mat &grayscale,
141  cv::Mat &kernel);
142 
143 //! morphologic grayscale reconstruction (L Vincent, 1993)
144 /*!
145  \param[in] mask image to reconstruct
146  \param[out] marker this image contains the initial marker points and will
147  contain the final result
148  \param[in] neighbors_mode number of neighbors for a pixel to consider when
149  doing the morphologic reconstruction (values: 4, 8).
150 */
151 void IMPEM2DEXPORT do_morphologic_reconstruction(const cv::Mat &mask,
152  cv::Mat &marker,
153  int neighbors_mode = 4);
154 
155 //! Labeling function for a matrix
156 /*!
157  \param[in] m binary matrix to scan. The matrix needs to contain zeros and
158  ones but they can be stored as doubles, floats or ints
159  \param[out] mat_to_label matrix it is returned as a matrix of ints
160  \return labels The number of labels in the image
161 */
162 IMPEM2DEXPORT int do_labeling(const cvIntMat &m, cvIntMat &mat_to_label);
163 
164 //! Segmentation of images
165 /*!
166  \param[in] m The EM image to segment
167  \param[in] result The segmented image, with the shape of the molecule
168  \param[in] params
169 */
170 IMPEM2DEXPORT void do_segmentation(const cv::Mat &m, cv::Mat &result,
171  const SegmentationParameters &params);
172 
173 //! Smoothing filter by application of the reaction-diffusion
174 //! equation of Beltrami flow. Adiga, JSB, 2005
175 /*!
176  `beta` is the contribution of diffusion versus edge enhancement:
177  0 - pure reaction, 90 - pure diffusion
178  \note The function only works for matrices containing doubles
179 */
180 IMPEM2DEXPORT void apply_diffusion_filter(const cv::Mat &m, cv::Mat &result,
181  double beta, double pixelsize,
182  unsigned int time_steps);
183 
184 //! Partial derivative with respect to time for an image filtered with
185 //! diffusion-reaction
186 /*!
187  \param[in] m input matrix
188  \param[in] der output derivative matrix
189  \param[in] dx - step for x
190  \param[in] dy - step for y
191  \param[in] ang - parameter for weight diffusion and edge detection (90-0)
192 */
194  const cv::Mat &m, cv::Mat &der, double dx, double dy, double ang);
195 
196 //! Fills the holes in the matrix m of height h
197 /*!
198  \param[in] m the input matrix
199  \param[in] result the result matrix
200  \param[in] h the height
201  \note The function does not work in-place
202 */
203 IMPEM2DEXPORT void do_fill_holes(const cv::Mat &m, cv::Mat &result, double h);
204 
205 //! Gets the domes of m with height h
206 /*!
207  \param[in] m the input matrix
208  \param[in] result the result matrix
209  \param[in] h the height
210  \note The function does not work in-place
211 */
212 IMPEM2DEXPORT void get_domes(cv::Mat &m, cv::Mat &result, double h);
213 
214 //! Combines the fill holes and thresholding operations together with normalize
215 /*!
216  \param[in] m Input matrix
217  \param[out] result the result matrix
218  \param[in] n_stddevs Number of standard deviations used to compute the holes
219  \param[in] threshold Removes values below the threshold value
220  \note The function does normalize -> fill_holes -> normalize -> threshold ->
221  normalize
222 */
223 IMPEM2DEXPORT void do_combined_fill_holes_and_threshold(cv::Mat &m,
224  cv::Mat &result,
225  double n_stddevs,
226  double threshold = 0.0);
227 
228 //! Computes the histogram of a matrix.
229 /*!
230  \param[in] m Matrix with the data
231  \param[in] bins Number of bins to use in the histogram
232  \return vector with the values for each bin
233 */
234 IMPEM2DEXPORT Floats get_histogram(const cv::Mat &m, int bins);
235 
236 //! Variance filter for an image. Computes the variance for each pixel using
237 //! the surrounding ones.
238 /*!
239  \param[in] input image with the data
240  \param[out] filtered matrix result of the filtering with the variances
241  \param[in] kernelsize The variance is computed using kernelsize x kernelsize
242  pixels around each one. Kernelsize can only be odd.
243 */
244 IMPEM2DEXPORT void apply_variance_filter(const cv::Mat &input,
245  cv::Mat &filtered, int kernelsize);
246 
247 //!Add noise to the values of a matrix.
248 /*!
249  Supported distributions:
250  - uniform distribution, giving the range (lower, upper). DEFAULT
251  - Gaussian distribution, giving the mean and the standard deviation
252  \code
253  add_noise(v1,0, 1);
254  // uniform distribution between 0 and 1
255 
256  v1.add_noise(0, 1, "uniform");
257  // the same
258 
259  v1.add_noise(0, 1, "gaussian");
260  // Gaussian distribution with 0 mean and stddev=1
261 
262  \endcode
263 */
264 IMPEM2DEXPORT void add_noise(cv::Mat &v, double op1, double op2,
265  const String &mode = "uniform", double df = 3);
266 
267 //! Resamples a matrix to polar coordinates.
268 /*!
269  \param[in] input matrix to resample
270  \param[out] resampled result matrix to contain the resampling
271  \param[in] polar_params Parameters used for the resampling. Extremely useful
272  for speeding up the procedure if they are given with the
273  transformation maps, that can be built in the
274  PolarResamplingParameters class
275 */
276 IMPEM2DEXPORT void do_resample_polar(
277  const cv::Mat &input, cv::Mat &resampled,
278  const PolarResamplingParameters &polar_params);
279 
280 //! Normalize a openCV matrix to mean 0 and stddev 1. It is done in place
281 IMPEM2DEXPORT void do_normalize(cv::Mat &m);
282 
283 //! Applies a transformation to a matrix. First rotates the matrix using the
284 //! matrix center as the origin of the rotation, and then applies
285 //! the translation
286 IMPEM2DEXPORT void get_transformed(const cv::Mat &input, cv::Mat &transformed,
287  const algebra::Transformation2D &T);
288 
289 /*! Extends the borders of an image
290  \param[in] orig The image to extend
291  \param[in] dst The image destination
292  \param[in] pix number of pixels to extend the borders
293 */
294 IMPEM2DEXPORT void do_extend_borders(cv::Mat &orig, cv::Mat &dst,
295  unsigned int pix);
296 
297 /*! Applies a threshold to an image
298  `threshold` is a value such that all pixels below this value are set to zero
299 */
300 IMPEM2DEXPORT void apply_threshold(cv::Mat &m, cv::Mat &result,
301  double threshold = 0.0);
302 
303 /*! morphologic enhancement of the contrast
304  This function detects areas in the images and enhances the contrast between
305  them
306  \param[in] m Input matrix
307  \param[out] result
308  \param[in] kernel morphologic kernel to use
309  \param[in] iterations Higher number, more contrast
310 */
311 IMPEM2DEXPORT void do_morphologic_contrast_enhancement(const cv::Mat &m,
312  cv::Mat &result,
313  const cv::Mat &kernel,
314  unsigned int iterations);
315 /*! Morphologic gradient: dilation-erosion
316  \param[in] m Input matrix
317  \param[out] result
318  \param[in] kernel morphologic kernel
319 */
320 IMPEM2DEXPORT void get_morphologic_gradient(const cv::Mat &m, cv::Mat &result,
321  const cv::Mat &kernel);
322 
323 /*! Get the percentage of overlap between two matrices.
324  Two images are overlapping in a pixel if both have values > 0.
325  The overlap is (pixels overlapping) / (pixels > 0 in m2)
326 
327  \param[in] m1 First matrix
328  \param[in] m2 Matrix used to check the overlap. This matrix can be of the
329  same size of m1 or smaller.
330  \param[in] center Indicates the position of m1 where to put
331  the center m2. E.g., if center is (32,16) the center
332  of m2 will be in the pixel (32,16) of m1.
333 */
334 IMPEM2DEXPORT double get_overlap_percentage(cv::Mat &m1, cv::Mat &m2,
335  const IntPair &center);
336 
337 /*! Gets the n first matches between an image and a template
338  \param[in] m Matrix
339  \param[in] templ Matrix with a template to be found in m
340  \param[in] n Number of positions to recover
341 */
342 IMPEM2DEXPORT MatchTemplateResults
343  get_best_template_matches(const cv::Mat &m, const cv::Mat &templ,
344  unsigned int n);
345 
346 /*! Crop an image
347  \param[in] m Matrix to crop
348  \param[in] center The pixel used as the center for cropping
349  \param[in] size The size of the new image
350  \return A matrix with the cropped region
351 */
352 IMPEM2DEXPORT cv::Mat crop(const cv::Mat &m, const IntPair &center, int size);
353 
354 IMPEM2D_END_NAMESPACE
355 
356 #endif /* IMPEM2D_IMAGE_PROCESSING_H */
void do_morphologic_contrast_enhancement(const cv::Mat &m, cv::Mat &result, const cv::Mat &kernel, unsigned int iterations)
double get_mean(const cv::Mat &mat, const cvIntMat &mask)
Basic types used by IMP.
void apply_threshold(cv::Mat &m, cv::Mat &result, double threshold=0.0)
cv::Mat crop(const cv::Mat &m, const IntPair &center, int size)
Class to provide all the parameters to the segmentation function.
cvIntMat create_circular_mask(int rows, int cols, int radius)
void do_dilate_and_shrink_warp(cv::Mat &m, const cv::Mat &grayscale, cv::Mat &kernel)
(U. Adiga, 2005)
int do_labeling(const cvIntMat &m, cvIntMat &mat_to_label)
Labeling function for a matrix.
MatchTemplateResults get_best_template_matches(const cv::Mat &m, const cv::Mat &templ, unsigned int n)
void do_extend_borders(cv::Mat &orig, cv::Mat &dst, unsigned int pix)
Interface with OpenCV Copyright 2007-2020 IMP Inventors. All rights reserved.
A more IMP-like version of the std::vector.
Definition: Vector.h:39
Floats get_histogram(const cv::Mat &m, int bins)
Computes the histogram of a matrix.
void do_resample_polar(const cv::Mat &input, cv::Mat &resampled, const PolarResamplingParameters &polar_params)
Resamples a matrix to polar coordinates.
void do_combined_fill_holes_and_threshold(cv::Mat &m, cv::Mat &result, double n_stddevs, double threshold=0.0)
Combines the fill holes and thresholding operations together with normalize.
void do_normalize(cv::Mat &m)
Normalize a openCV matrix to mean 0 and stddev 1. It is done in place.
#define IMP_VALUES(Name, PluralName)
Define the type for storing sets of values.
Definition: value_macros.h:23
void do_fill_holes(const cv::Mat &m, cv::Mat &result, double h)
Fills the holes in the matrix m of height h.
void apply_circular_mask(const cv::Mat &mat, cv::Mat &result, int radius, double value=0.0)
Simple 2D transformation class.
Functions related with rotations in em2d Copyright 2007-2020 IMP Inventors. All rights reserved...
void get_morphologic_gradient(const cv::Mat &m, cv::Mat &result, const cv::Mat &kernel)
void apply_mask(const cv::Mat &m, cv::Mat &result, const cvIntMat &mask, double val)
Applies a binary mask to an image.
void get_domes(cv::Mat &m, cv::Mat &result, double h)
Gets the domes of m with height h.
std::ostream & show(Hierarchy h, std::ostream &out=std::cout)
Print the hierarchy using a given decorator to display each node.
void apply_diffusion_filter(const cv::Mat &m, cv::Mat &result, double beta, double pixelsize, unsigned int time_steps)
void do_segmentation(const cv::Mat &m, cv::Mat &result, const SegmentationParameters &params)
Segmentation of images.
double get_overlap_percentage(cv::Mat &m1, cv::Mat &m2, const IntPair &center)
void apply_variance_filter(const cv::Mat &input, cv::Mat &filtered, int kernelsize)
void get_diffusion_filtering_partial_derivative(const cv::Mat &m, cv::Mat &der, double dx, double dy, double ang)
void add_noise(cv::Mat &v, double op1, double op2, const String &mode="uniform", double df=3)
Add noise to the values of a matrix.
void do_remove_small_objects(cvIntMat &m, double percentage, int background=0, int foreground=1)
Removes small objects from a matrix of integers.
DensityMap * get_transformed(const DensityMap *input, const algebra::Transformation3D &tr, double threshold)
Return a new density map containing a rotated version of the old one.
void do_morphologic_reconstruction(const cv::Mat &mask, cv::Mat &marker, int neighbors_mode=4)
morphologic grayscale reconstruction (L Vincent, 1993)
std::string String
Basic string value.
Definition: types.h:44