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