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