1 // Copyright (C) 2006 Davis E. King (davis@dlib.net) 2 // License: Boost Software License See LICENSE.txt for the full license. 3 #undef DLIB_THRESHOLDINg_ABSTRACT_ 4 #ifdef DLIB_THRESHOLDINg_ABSTRACT_ 5 6 #include "../pixel.h" 7 8 namespace dlib 9 { 10 11 // ---------------------------------------------------------------------------------------- 12 13 const unsigned char on_pixel = 255; 14 const unsigned char off_pixel = 0; 15 16 // ---------------------------------------------------------------------------------------- 17 18 template < 19 typename image_type 20 > 21 typename pixel_traits<typename image_traits<image_type>::pixel_type>::basic_pixel_type 22 partition_pixels ( 23 const image_type& img 24 ); 25 /*! 26 requires 27 - image_type == an image object that implements the interface defined in 28 dlib/image_processing/generic_image.h 29 - pixel_traits<typename image_traits<image_type>::pixel_type>::has_alpha == false 30 ensures 31 - Finds a threshold value that would be reasonable to use with 32 threshold_image(img, threshold). It does this by finding the threshold that 33 partitions the pixels in img into two groups such that the sum of absolute 34 deviations between each pixel and the mean of its group is minimized. 35 !*/ 36 37 template < 38 typename image_type, 39 typename ...T 40 > 41 void partition_pixels ( 42 const image_type& img, 43 typename pixel_traits<typename image_traits<image_type>::pixel_type>::basic_pixel_type& pix_thresh, 44 T&& ...more_thresholds 45 ); 46 /*! 47 requires 48 - image_type == an image object that implements the interface defined in 49 dlib/image_processing/generic_image.h 50 - pixel_traits<typename image_traits<image_type>::pixel_type>::has_alpha == false 51 - more_thresholds == a bunch of parameters of the same type as pix_thresh. 52 ensures 53 - This version of partition_pixels() finds multiple partitions rather than just 54 one partition. It does this by first partitioning the pixels just as the 55 above partition_pixels(img) does. Then it forms a new image with only pixels 56 >= that first partition value and recursively partitions this new image. 57 However, the recursion is implemented in an efficient way which is faster than 58 explicitly forming these images and calling partition_pixels(), but the 59 output is the same as if you did. For example, suppose you called 60 partition_pixels(img, t1, t2, t3). Then we would have: 61 - t1 == partition_pixels(img) 62 - t2 == partition_pixels(an image with only pixels with values >= t1 in it) 63 - t3 == partition_pixels(an image with only pixels with values >= t2 in it) 64 !*/ 65 66 // ---------------------------------------------------------------------------------------- 67 68 template < 69 typename in_image_type, 70 typename out_image_type 71 > 72 void threshold_image ( 73 const in_image_type& in_img, 74 out_image_type& out_img, 75 typename pixel_traits<typename image_traits<in_image_type>::pixel_type>::basic_pixel_type thresh 76 ); 77 /*! 78 requires 79 - in_image_type == an image object that implements the interface defined in 80 dlib/image_processing/generic_image.h 81 - out_image_type == an image object that implements the interface defined in 82 dlib/image_processing/generic_image.h 83 - pixel_traits<typename image_traits<out_image_type>::pixel_type>::grayscale == true 84 - pixel_traits<typename image_traits<in_image_type>::pixel_type>::has_alpha == false 85 - pixel_traits<typename image_traits<out_image_type>::pixel_type>::has_alpha == false 86 ensures 87 - #out_img == the thresholded version of in_img (in_img is converted to a grayscale 88 intensity image if it is color). Pixels in in_img with grayscale values >= thresh 89 have an output value of on_pixel and all others have a value of off_pixel. 90 - #out_img.nc() == in_img.nc() 91 - #out_img.nr() == in_img.nr() 92 !*/ 93 94 template < 95 typename image_type 96 > 97 void threshold_image ( 98 image_type& img, 99 typename pixel_traits<typename image_traits<image_type>::pixel_type>::basic_pixel_type thresh 100 ); 101 /*! 102 requires 103 - it is valid to call threshold_image(img,img,thresh); 104 ensures 105 - calls threshold_image(img,img,thresh); 106 !*/ 107 108 template < 109 typename in_image_type, 110 typename out_image_type 111 > 112 void threshold_image ( 113 const in_image_type& in_img, 114 out_image_type& out_img 115 ); 116 /*! 117 requires 118 - it is valid to call threshold_image(in_img,out_img,partition_pixels(in_img)); 119 ensures 120 - calls threshold_image(in_img,out_img,partition_pixels(in_img)); 121 !*/ 122 123 template < 124 typename image_type 125 > 126 void threshold_image ( 127 image_type& img 128 ); 129 /*! 130 requires 131 - it is valid to call threshold_image(img,img,partition_pixels(img)); 132 ensures 133 - calls threshold_image(img,img,partition_pixels(img)); 134 !*/ 135 136 // ---------------------------------------------------------------------------------------- 137 138 template < 139 typename in_image_type, 140 typename out_image_type 141 > 142 void hysteresis_threshold ( 143 const in_image_type& in_img, 144 out_image_type& out_img, 145 typename pixel_traits<typename image_traits<in_image_type>::pixel_type>::basic_pixel_type lower_thresh, 146 typename pixel_traits<typename image_traits<in_image_type>::pixel_type>::basic_pixel_type upper_thresh 147 ); 148 /*! 149 requires 150 - in_image_type == an image object that implements the interface defined in 151 dlib/image_processing/generic_image.h 152 - out_image_type == an image object that implements the interface defined in 153 dlib/image_processing/generic_image.h 154 - pixel_traits<typename image_traits<out_image_type>::pixel_type>::grayscale == true 155 - pixel_traits<typename image_traits<in_image_type>::pixel_type>::has_alpha == false 156 - pixel_traits<typename image_traits<out_image_type>::pixel_type>::has_alpha == false 157 - is_same_object(in_img, out_img) == false 158 ensures 159 - #out_img == the hysteresis thresholded version of in_img (in_img is converted to a 160 grayscale intensity image if it is color). Pixels in in_img with grayscale 161 values >= upper_thresh have an output value of on_pixel and all others have a 162 value of off_pixel unless they are >= lower_thresh and are connected to a pixel 163 with a value >= upper_thresh, in which case they have a value of on_pixel. Here 164 pixels are connected if there is a path between them composed of pixels that 165 would receive an output of on_pixel. 166 - #out_img.nc() == in_img.nc() 167 - #out_img.nr() == in_img.nr() 168 !*/ 169 170 template < 171 typename in_image_type, 172 typename out_image_type 173 > 174 void hysteresis_threshold ( 175 const in_image_type& in_img, 176 out_image_type& out_img 177 ); 178 /*! 179 requires 180 - in_image_type == an image object that implements the interface defined in 181 dlib/image_processing/generic_image.h 182 - out_image_type == an image object that implements the interface defined in 183 dlib/image_processing/generic_image.h 184 - pixel_traits<typename image_traits<out_image_type>::pixel_type>::grayscale == true 185 - pixel_traits<typename image_traits<in_image_type>::pixel_type>::has_alpha == false 186 - pixel_traits<typename image_traits<out_image_type>::pixel_type>::has_alpha == false 187 - is_same_object(in_img, out_img) == false 188 ensures 189 - performs: hysteresis_threshold(in_img, out_img, t1, t2) where the thresholds 190 are first obtained by calling partition_pixels(in_img, t1, t2). 191 !*/ 192 193 // ---------------------------------------------------------------------------------------- 194 195 } 196 197 #endif // DLIB_THRESHOLDINg_ABSTRACT_ 198 199 200