Restructured the interfaces of classes relying on the blurs to use th…

…e new parameters. This will break anything using these classes, so you might want to read up on what the new parameters do.

README.md

@@ -134,6 +134,7 @@ There are currently 125 built-in filters, divided into the following categories:
   - *threshold*: The luminance threshold, from 0.0 to 1.0, with a default of 0.5
 
 - **GPUImageAdaptiveThresholdFilter**: Determines the local luminance around a pixel, then turns the pixel black if it is below that local luminance and white if above. This can be useful for picking out text under varying lighting conditions.
+  - *blurRadiusInPixels*: A multiplier for the background averaging blur radius in pixels, with a default of 4.
 
 - **GPUImageAverageLuminanceThresholdFilter**: This applies a thresholding operation where the threshold is continually adjusted based on the average luminance of the scene.
   - *thresholdMultiplier*: This is a factor that the average luminance will be multiplied by in order to arrive at the final threshold to use. By default, this is 1.0.
@@ -167,23 +168,32 @@ There are currently 125 built-in filters, divided into the following categories:
   - *sharpness*: The sharpness adjustment to apply (-4.0 - 4.0, with 0.0 as the default)
 
 - **GPUImageUnsharpMaskFilter**: Applies an unsharp mask
-  - *blurSize*: A multiplier for the underlying blur size, ranging from 0.0 on up, with a default of 1.0
+  - *blurRadiusInPixels*: The blur radius of the underlying Gaussian blur. The default is 4.0.
   - *intensity*: The strength of the sharpening, from 0.0 on up, with a default of 1.0
 
-- **GPUImageFastBlurFilter**: A hardware-accelerated 9-hit Gaussian blur of an image
-  - *blurPasses*: The number of times to re-apply this blur on an image. More passes lead to a blurrier image, yet they require more processing power. The default is 1.
+- **GPUImageGaussianBlurFilter**: A hardware-optimized, variable-radius Gaussian blur
+  - *texelSpacingMultiplier*: A multiplier for the spacing between texels, ranging from 0.0 on up, with a default of 1.0. Adjusting this may slightly increase the blur strength, but will introduce artifacts in the result. Highly recommend using other parameters first, before touching this one.
+  - *blurRadiusInPixels*: A radius in pixels to use for the blur, with a default of 2.0. This adjusts the sigma variable in the Gaussian distribution function.
+  - *blurRadiusAsFractionOfImageWidth*: 
+  - *blurRadiusAsFractionOfImageHeight*: Setting these properties will allow the blur radius to scale with the size of the image
+  - *blurPasses*: The number of times to sequentially blur the incoming image. The more passes, the slower the filter.
 
-- **GPUImageSingleComponentFastBlurFilter**: A modification of the GPUImageFastBlurFilter to only operate on the red component
-  - *blurPasses*: The number of times to re-apply this blur on an image. More passes lead to a blurrier image, yet they require more processing power. The default is 1.
-
-- **GPUImageGaussianBlurFilter**: A more generalized 9x9 Gaussian blur filter
-  - *blurSize*: A multiplier for the size of the blur, ranging from 0.0 on up, with a default of 1.0
+- **GPUImageBoxBlurFilter**: A hardware-optimized, variable-radius box blur
+  - *texelSpacingMultiplier*: A multiplier for the spacing between texels, ranging from 0.0 on up, with a default of 1.0. Adjusting this may slightly increase the blur strength, but will introduce artifacts in the result. Highly recommend using other parameters first, before touching this one.
+  - *blurRadiusInPixels*: A radius in pixels to use for the blur, with a default of 2.0. This adjusts the sigma variable in the Gaussian distribution function.
+  - *blurRadiusAsFractionOfImageWidth*: 
+  - *blurRadiusAsFractionOfImageHeight*: Setting these properties will allow the blur radius to scale with the size of the image
+  - *blurPasses*: The number of times to sequentially blur the incoming image. The more passes, the slower the filter.
 
 - **GPUImageSingleComponentGaussianBlurFilter**: A modification of the GPUImageGaussianBlurFilter that operates only on the red component
-  - *blurSize*: A multiplier for the size of the blur, ranging from 0.0 on up, with a default of 1.0
+  - *texelSpacingMultiplier*: A multiplier for the spacing between texels, ranging from 0.0 on up, with a default of 1.0. Adjusting this may slightly increase the blur strength, but will introduce artifacts in the result. Highly recommend using other parameters first, before touching this one.
+  - *blurRadiusInPixels*: A radius in pixels to use for the blur, with a default of 2.0. This adjusts the sigma variable in the Gaussian distribution function.
+  - *blurRadiusAsFractionOfImageWidth*: 
+  - *blurRadiusAsFractionOfImageHeight*: Setting these properties will allow the blur radius to scale with the size of the image
+  - *blurPasses*: The number of times to sequentially blur the incoming image. The more passes, the slower the filter.
 
 - **GPUImageGaussianSelectiveBlurFilter**: A Gaussian blur that preserves focus within a circular region
-  - *blurSize*: A multiplier for the size of the blur, ranging from 0.0 on up, with a default of 1.0
+  - *blurRadiusInPixels*: A radius in pixels to use for the blur, with a default of 5.0. This adjusts the sigma variable in the Gaussian distribution function.
   - *excludeCircleRadius*: The radius of the circular area being excluded from the blur
   - *excludeCirclePoint*: The center of the circular area being excluded from the blur
   - *excludeBlurSize*: The size of the area between the blurred portion and the clear circle 
@@ -197,17 +207,15 @@ There are currently 125 built-in filters, divided into the following categories:
 - **GPUImageMedianFilter**: Takes the median value of the three color components, over a 3x3 area
 
 - **GPUImageBilateralFilter**: A bilateral blur, which tries to blur similar color values while preserving sharp edges
-  - *blurSize*: A multiplier for the size of the blur, ranging from 0.0 on up, with a default of 4.0
+  - *texelSpacingMultiplier*: A multiplier for the spacing between texel reads, ranging from 0.0 on up, with a default of 4.0
   - *distanceNormalizationFactor*: A normalization factor for the distance between central color and sample color, with a default of 8.0.
 
 - **GPUImageTiltShiftFilter**: A simulated tilt shift lens effect
-  - *blurSize*: A multiplier for the size of the out-of-focus blur, ranging from 0.0 on up, with a default of 2.0
+  - *blurRadiusInPixels*: The radius of the underlying blur, in pixels. This is 7.0 by default.
   - *topFocusLevel*: The normalized location of the top of the in-focus area in the image, this value should be lower than bottomFocusLevel, default 0.4
   - *bottomFocusLevel*: The normalized location of the bottom of the in-focus area in the image, this value should be higher than topFocusLevel, default 0.6
   - *focusFallOffRate*: The rate at which the image gets blurry away from the in-focus region, default 0.2
 
-- **GPUImageBoxBlurFilter**: A hardware-accelerated 9-hit box blur of an image
-
 - **GPUImage3x3ConvolutionFilter**: Runs a 3x3 convolution kernel against the image
   - *convolutionKernel*: The convolution kernel is a 3x3 matrix of values to apply to the pixel and its 8 surrounding pixels. The matrix is specified in row-major order, with the top left pixel being one.one and the bottom right three.three. If the values in the matrix don't add up to 1.0, the image could be brightened or darkened.
 
@@ -230,22 +238,23 @@ There are currently 125 built-in filters, divided into the following categories:
 - **GPUImageCannyEdgeDetectionFilter**: This uses the full Canny process to highlight one-pixel-wide edges
   - *texelWidth*: 
   - *texelHeight*: These parameters affect the visibility of the detected edges
-  - *blurSize*: A multiplier for the prepass blur size, ranging from 0.0 on up, with a default of 1.0
+  - *blurRadiusInPixels*: The underlying blur radius for the Gaussian blur. Default is 2.0.
+  - *blurTexelSpacingMultiplier*: The underlying blur texel spacing multiplier. Default is 1.0.
   - *upperThreshold*: Any edge with a gradient magnitude above this threshold will pass and show up in the final result. Default is 0.4.
   - *lowerThreshold*: Any edge with a gradient magnitude below this threshold will fail and be removed from the final result. Default is 0.1.
 
 - **GPUImageHarrisCornerDetectionFilter**: Runs the Harris corner detection algorithm on an input image, and produces an image with those corner points as white pixels and everything else black. The cornersDetectedBlock can be set, and you will be provided with a list of corners (in normalized 0..1 X, Y coordinates) within that callback for whatever additional operations you want to perform.
-  - *blurSize*: The relative size of the blur applied as part of the corner detection implementation. The default is 1.0.
+  - *blurRadiusInPixels*: The radius of the underlying Gaussian blur. The default is 2.0.
   - *sensitivity*: An internal scaling factor applied to adjust the dynamic range of the cornerness maps generated in the filter. The default is 5.0.
   - *threshold*: The threshold at which a point is detected as a corner. This can vary significantly based on the size, lighting conditions, and iOS device camera type, so it might take a little experimentation to get right for your cases. Default is 0.20.
 
 - **GPUImageNobleCornerDetectionFilter**: Runs the Noble variant on the Harris corner detector. It behaves as described above for the Harris detector.
-  - *blurSize*: The relative size of the blur applied as part of the corner detection implementation. The default is 1.0.
+  - *blurRadiusInPixels*: The radius of the underlying Gaussian blur. The default is 2.0.
   - *sensitivity*: An internal scaling factor applied to adjust the dynamic range of the cornerness maps generated in the filter. The default is 5.0.
   - *threshold*: The threshold at which a point is detected as a corner. This can vary significantly based on the size, lighting conditions, and iOS device camera type, so it might take a little experimentation to get right for your cases. Default is 0.2.
 
 - **GPUImageShiTomasiCornerDetectionFilter**: Runs the Shi-Tomasi feature detector. It behaves as described above for the Harris detector.
-  - *blurSize*: The relative size of the blur applied as part of the corner detection implementation. The default is 1.0.
+  - *blurRadiusInPixels*: The radius of the underlying Gaussian blur. The default is 2.0.
   - *sensitivity*: An internal scaling factor applied to adjust the dynamic range of the cornerness maps generated in the filter. The default is 1.5.
   - *threshold*: The threshold at which a point is detected as a corner. This can vary significantly based on the size, lighting conditions, and iOS device camera type, so it might take a little experimentation to get right for your cases. Default is 0.2.
 
@@ -403,7 +412,7 @@ There are currently 125 built-in filters, divided into the following categories:
 - **GPUImageSmoothToonFilter**: This uses a similar process as the GPUImageToonFilter, only it precedes the toon effect with a Gaussian blur to smooth out noise.
   - *texelWidth*: 
   - *texelHeight*: These parameters affect the visibility of the detected edges
-  - *blurSize*: A multiplier for the prepass blur size, ranging from 0.0 on up, with a default of 0.5
+  - *blurRadiusInPixels*: The radius of the underlying Gaussian blur. The default is 2.0.
   - *threshold*: The sensitivity of the edge detection, with lower values being more sensitive. Ranges from 0.0 to 1.0, with 0.2 as the default
   - *quantizationLevels*: The number of color levels to represent in the final image. Default is 10.0
 

examples/iOS/FilterShowcase/FilterShowcase/ShowcaseFilterViewController.m

@@ -559,10 +559,6 @@ - (void)setupFilter;
             [self.filterSettingsSlider setMaximumValue:1.0];
             [self.filterSettingsSlider setValue:1.0];
 
-//            [self.filterSettingsSlider setMinimumValue:0.0];
-//            [self.filterSettingsSlider setMaximumValue:0.5];
-//            [self.filterSettingsSlider setValue:0.1];
-
             filter = [[GPUImageCannyEdgeDetectionFilter alloc] init];
         }; break;
         case GPUIMAGE_THRESHOLDEDGEDETECTION:
@@ -663,9 +659,9 @@ - (void)setupFilter;
             self.title = @"Smooth Toon";
             self.filterSettingsSlider.hidden = NO;
 
-            [self.filterSettingsSlider setMinimumValue:0.0];
-            [self.filterSettingsSlider setMaximumValue:1.0];
-            [self.filterSettingsSlider setValue:0.5];
+            [self.filterSettingsSlider setMinimumValue:1.0];
+            [self.filterSettingsSlider setMaximumValue:6.0];
+            [self.filterSettingsSlider setValue:1.0];
 
             filter = [[GPUImageSmoothToonFilter alloc] init];
         }; break;            
@@ -1450,7 +1446,7 @@ - (void)setupFilter;
             // Provide a blurred image for a cool-looking background
             GPUImageGaussianBlurFilter *gaussianBlur = [[GPUImageGaussianBlurFilter alloc] init];
             [videoCamera addTarget:gaussianBlur];
-            gaussianBlur.blurSize = 2.0;
+            gaussianBlur.blurRadiusInPixels = 5.0;
 
             GPUImageAlphaBlendFilter *blendFilter = [[GPUImageAlphaBlendFilter alloc] init];
             blendFilter.mix = 1.0;
@@ -1561,7 +1557,7 @@ - (IBAction)updateFilterFromSlider:(id)sender;
         case GPUIMAGE_PREWITTEDGEDETECTION: [(GPUImagePrewittEdgeDetectionFilter *)filter setEdgeStrength:[(UISlider *)sender value]]; break;
         case GPUIMAGE_SKETCH: [(GPUImageSketchFilter *)filter setEdgeStrength:[(UISlider *)sender value]]; break;
         case GPUIMAGE_THRESHOLD: [(GPUImageLuminanceThresholdFilter *)filter setThreshold:[(UISlider *)sender value]]; break;
-        case GPUIMAGE_ADAPTIVETHRESHOLD: [(GPUImageAdaptiveThresholdFilter *)filter setBlurSize:[(UISlider*)sender value]]; break;
+        case GPUIMAGE_ADAPTIVETHRESHOLD: [(GPUImageAdaptiveThresholdFilter *)filter setBlurRadiusInPixels:[(UISlider*)sender value]]; break;
         case GPUIMAGE_AVERAGELUMINANCETHRESHOLD: [(GPUImageAverageLuminanceThresholdFilter *)filter setThresholdMultiplier:[(UISlider *)sender value]]; break;
         case GPUIMAGE_DISSOLVE: [(GPUImageDissolveBlendFilter *)filter setMix:[(UISlider *)sender value]]; break;
         case GPUIMAGE_POISSONBLEND: [(GPUImagePoissonBlendFilter *)filter setMix:[(UISlider *)sender value]]; break;
@@ -1573,15 +1569,15 @@ - (IBAction)updateFilterFromSlider:(id)sender;
         case GPUIMAGE_KUWAHARA: [(GPUImageKuwaharaFilter *)filter setRadius:round([(UISlider *)sender value])]; break;
         case GPUIMAGE_SWIRL: [(GPUImageSwirlFilter *)filter setAngle:[(UISlider *)sender value]]; break;
         case GPUIMAGE_EMBOSS: [(GPUImageEmbossFilter *)filter setIntensity:[(UISlider *)sender value]]; break;
-        case GPUIMAGE_CANNYEDGEDETECTION: [(GPUImageCannyEdgeDetectionFilter *)filter setBlurSize:[(UISlider*)sender value]]; break;
+        case GPUIMAGE_CANNYEDGEDETECTION: [(GPUImageCannyEdgeDetectionFilter *)filter setBlurTexelSpacingMultiplier:[(UISlider*)sender value]]; break;
 //        case GPUIMAGE_CANNYEDGEDETECTION: [(GPUImageCannyEdgeDetectionFilter *)filter setLowerThreshold:[(UISlider*)sender value]]; break;
         case GPUIMAGE_HARRISCORNERDETECTION: [(GPUImageHarrisCornerDetectionFilter *)filter setThreshold:[(UISlider*)sender value]]; break;
         case GPUIMAGE_NOBLECORNERDETECTION: [(GPUImageNobleCornerDetectionFilter *)filter setThreshold:[(UISlider*)sender value]]; break;
         case GPUIMAGE_SHITOMASIFEATUREDETECTION: [(GPUImageShiTomasiFeatureDetectionFilter *)filter setThreshold:[(UISlider*)sender value]]; break;
         case GPUIMAGE_HOUGHTRANSFORMLINEDETECTOR: [(GPUImageHoughTransformLineDetector *)filter setLineDetectionThreshold:[(UISlider*)sender value]]; break;
 //        case GPUIMAGE_HARRISCORNERDETECTION: [(GPUImageHarrisCornerDetectionFilter *)filter setSensitivity:[(UISlider*)sender value]]; break;
         case GPUIMAGE_THRESHOLDEDGEDETECTION: [(GPUImageThresholdEdgeDetectionFilter *)filter setThreshold:[(UISlider *)sender value]]; break;
-        case GPUIMAGE_SMOOTHTOON: [(GPUImageSmoothToonFilter *)filter setBlurSize:[(UISlider*)sender value]]; break;
+        case GPUIMAGE_SMOOTHTOON: [(GPUImageSmoothToonFilter *)filter setBlurRadiusInPixels:[(UISlider*)sender value]]; break;
         case GPUIMAGE_THRESHOLDSKETCH: [(GPUImageThresholdSketchFilter *)filter setThreshold:[(UISlider *)sender value]]; break;
 //        case GPUIMAGE_BULGE: [(GPUImageBulgeDistortionFilter *)filter setRadius:[(UISlider *)sender value]]; break;
         case GPUIMAGE_BULGE: [(GPUImageBulgeDistortionFilter *)filter setScale:[(UISlider *)sender value]]; break;

framework/Source/GPUImageAdaptiveThresholdFilter.h

@@ -2,8 +2,8 @@
 
 @interface GPUImageAdaptiveThresholdFilter : GPUImageFilterGroup
 
-/** A multiplier for the background averaging blur size, ranging from 0.0 on up, with a default of 1.0
+/** A multiplier for the background averaging blur radius in pixels, with a default of 4
  */
-@property(readwrite, nonatomic) CGFloat blurSize;
+@property(readwrite, nonatomic) CGFloat blurRadiusInPixels;
 
 @end

framework/Source/GPUImageAdaptiveThresholdFilter.m

@@ -87,14 +87,14 @@ - (id)init;
 #pragma mark -
 #pragma mark Accessors
 
-- (void)setBlurSize:(CGFloat)newValue;
+- (void)setBlurRadiusInPixels:(CGFloat)newValue;
 {
-    boxBlurFilter.blurSize = newValue;
+    boxBlurFilter.blurRadiusInPixels = newValue;
 }
 
-- (CGFloat)blurSize;
+- (CGFloat)blurRadiusInPixels;
 {
-    return boxBlurFilter.blurSize;
+    return boxBlurFilter.blurRadiusInPixels;
 }
 
 @end

framework/Source/GPUImageBilateralFilter.m

@@ -204,7 +204,7 @@ - (id)init;
     firstDistanceNormalizationFactorUniform  = [filterProgram uniformIndex:@"distanceNormalizationFactor"];
     secondDistanceNormalizationFactorUniform = [filterProgram uniformIndex:@"distanceNormalizationFactor"];
 
-    self.blurSize = 4.0;
+    self.texelSpacingMultiplier = 4.0;
     self.distanceNormalizationFactor = 8.0;
 
 

framework/Source/GPUImageCannyEdgeDetectionFilter.h

@@ -43,9 +43,13 @@
  */
 @property(readwrite, nonatomic) CGFloat texelHeight; 
 
-/** A multiplier for the blur size, ranging from 0.0 on up, with a default of 1.0
+/** The underlying blur radius for the Gaussian blur. Default is 2.0.
  */
-@property (readwrite, nonatomic) CGFloat blurSize;
+@property (readwrite, nonatomic) CGFloat blurRadiusInPixels;
+
+/** The underlying blur texel spacing multiplier. Default is 1.0.
+ */
+@property (readwrite, nonatomic) CGFloat blurTexelSpacingMultiplier;
 
 /** Any edge with a gradient magnitude above this threshold will pass and show up in the final result.
  */

framework/Source/GPUImageCannyEdgeDetectionFilter.m

@@ -10,7 +10,8 @@ @implementation GPUImageCannyEdgeDetectionFilter
 
 @synthesize upperThreshold;
 @synthesize lowerThreshold;
-@synthesize blurSize;
+@synthesize blurRadiusInPixels;
+@synthesize blurTexelSpacingMultiplier;
 @synthesize texelWidth;
 @synthesize texelHeight;
 
@@ -50,7 +51,8 @@ - (id)init;
 //    self.terminalFilter = nonMaximumSuppressionFilter;
     self.terminalFilter = weakPixelInclusionFilter;
 
-    self.blurSize = 1.0;
+    self.blurRadiusInPixels = 2.0;
+    self.blurTexelSpacingMultiplier = 1.0;
     self.upperThreshold = 0.4;
     self.lowerThreshold = 0.1;
 
@@ -60,14 +62,24 @@ - (id)init;
 #pragma mark -
 #pragma mark Accessors
 
-- (void)setBlurSize:(CGFloat)newValue;
+- (void)setBlurRadiusInPixels:(CGFloat)newValue;
 {
-    blurFilter.blurSize = newValue;
+    blurFilter.blurRadiusInPixels = newValue;
 }
 
-- (CGFloat)blurSize;
+- (CGFloat)blurRadiusInPixels;
 {
-    return blurFilter.blurSize;
+    return blurFilter.blurRadiusInPixels;
+}
+
+- (void)setBlurTexelSpacingMultiplier:(CGFloat)newValue;
+{
+    blurFilter.texelSpacingMultiplier = newValue;
+}
+
+- (CGFloat)blurTexelSpacingMultiplier;
+{
+    return blurFilter.texelSpacingMultiplier;
 }
 
 - (void)setTexelWidth:(CGFloat)newValue;

framework/Source/GPUImageGaussianBlurFilter.h

@@ -10,11 +10,11 @@
     CGFloat _blurRadiusInPixels;
 }
 
-/** A multiplier for the blur size, ranging from 0.0 on up, with a default of 1.0
+/** A multiplier for the spacing between texels, ranging from 0.0 on up, with a default of 1.0. Adjusting this may slightly increase the blur strength, but will introduce artifacts in the result.
  */
-@property (readwrite, nonatomic) CGFloat blurSize;
+@property (readwrite, nonatomic) CGFloat texelSpacingMultiplier;
 
-/** A radius in pixels (in 0.5 pixel increments) to use for the blur, with a default of 2.0
+/** A radius in pixels to use for the blur, with a default of 2.0. This adjusts the sigma variable in the Gaussian distribution function.
  */
 @property (readwrite, nonatomic) CGFloat blurRadiusInPixels;