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