### Gaussian Blur Example

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Example demonstrating how to use the `gaussian_blur_image` function. It initializes a source image, applies the blur with specified parameters, and then accesses the blurred result.

```rust
use libblur::*

let src_data = vec![0u8; 640 * 480 * 3];
let src = BlurImage::borrow(&src_data, 640, 480, FastBlurChannels::Channels3);

let blurred = gaussian_blur_image(
    &src,
    GaussianBlurParams::new_from_kernel(61.0),
    EdgeMode::Clamp.as_2d(),
    ConvolutionMode::FixedPoint,
    ThreadingPolicy::Adaptive,
)?;

// Access result
let result = blurred.to_immutable_ref();
println!("Blurred: {}×{}", result.width, result.height);
```

--------------------------------

### Example Usage of generate_motion_kernel

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Demonstrates how to generate a motion blur kernel with a specified size and angle.

```rust
use libblur::generate_motion_kernel;

let kernel = generate_motion_kernel(31, 45.0);  // 31x31 kernel at 45°

```

--------------------------------

### Stack Blur Example

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Example demonstrating the usage of the `stack_blur_image` function. This snippet applies a stack blur to a source image with a given radius and threading policy.

```rust
use libblur::*

let blurred = stack_blur_image(
    &src,
    20,
    ThreadingPolicy::Adaptive
)?;
```

--------------------------------

### Fast Gaussian Blur Example

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Example usage of the `fast_gaussian_blur_image` function. This snippet shows how to apply a fast Gaussian blur to a source image with a specified radius and edge handling.

```rust
use libblur::*

let blurred = fast_gaussian_blur_image(
    &src,
    25,
    EdgeMode::Clamp,
    ThreadingPolicy::Adaptive
)?;
```

--------------------------------

### Simple Stack Blur

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Applies a stack blur to an image. This is a basic example demonstrating the use of `stack_blur` with adaptive threading.

```rust
use libblur::*;

fn simple_blur() -> Result<(), BlurError> {
    let pixels = vec![0u8; 640 * 480 * 3];
    let mut image = BlurImageMut::borrow(&mut pixels.clone(), 640, 480, FastBlurChannels::Channels3);
    
    stack_blur(&mut image, 15, ThreadingPolicy::Adaptive)?;
    Ok(())
}
```

--------------------------------

### FftError Handling Example

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Shows how to handle the FftError, which indicates a failure during FFT computation, potentially due to library errors or overflow. It includes a match statement for specific error handling.

```rust
BlurError::FftError(String)
```

```rust
use libblur::*;

match filter_2d_fft(&src, &mut dst, &kernel, shape, edge, scalar, threading) {
    Ok(_) => {}, 
    Err(BlurError::FftError(msg)) => eprintln!("FFT failed: {}", msg),
    Err(e) => eprintln!("Other error: {:?}", e),
}
```

--------------------------------

### Determine Runtime Thread Count

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Inspect libblur's threading capabilities at runtime. This example shows how to determine the thread count for Adaptive and AdaptiveReserve policies based on system and image dimensions.

```rust
use libblur::ThreadingPolicy;

// Determine thread count for current system
let threading = ThreadingPolicy::Adaptive;
let threads = threading.thread_count(1920, 1080);  // 4K image
println!("Using {} threads", threads);

// Adaptive reserves no threads by default
let threading = ThreadingPolicy::AdaptiveReserve(
    std::num::NonZeroUsize::new(2).unwrap()
);
let threads = threading.thread_count(1920, 1080);
println!("Using {} threads (reserved 2)", threads)
```

--------------------------------

### KernelSizeMismatch Error Example

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Demonstrates the KernelSizeMismatch error when the provided kernel length does not match the expected dimensions (width * height).

```rust
BlurError::KernelSizeMismatch(MismatchedSize {
    expected: usize,
    received: usize,
})
```

```rust
use libblur::*;

let kernel_shape = KernelShape::new(3, 3);
let kernel = vec![0.0; 9];  // Correct: 3×3=9
filter_2d(&src, &mut dst, &kernel, kernel_shape, EdgeMode::Clamp.as_2d(), Scalar::default(), ThreadingPolicy::Single)?;
// OK

let kernel = vec![0.0; 7];  // Wrong size!
// Fails: KernelSizeMismatch { expected: 9, received: 7 }
```

--------------------------------

### Robust Blur with Error Handling

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Demonstrates robust error handling for image blurring operations. This example includes layout validation before attempting to blur, catching potential `MinimumSliceSizeMismatch` errors.

```rust
use libblur::*;

fn robust_blur() -> Result<BlurImageMut<u8>, BlurError> {
    let pixels = vec![0u8; 100];  // Too small!
    let src = BlurImage::borrow(&pixels, 640, 480, FastBlurChannels::Channels3);
    
    // Validate first
    src.check_layout()?;  // Will fail with MinimumSliceSizeMismatch
    
    let mut dst = BlurImageMut::default();
    stack_blur(&mut dst, 10, ThreadingPolicy::Adaptive)?;
    Ok(dst)
}
```

--------------------------------

### Handling ZeroBaseSize Error

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Triggered when an image's width or height is 0. This example shows how to check for and handle this error, ensuring valid image dimensions.

```rust
use libblur::*;

let width: u32 = 0;  // ERROR!
let pixels = vec![0u8; 0];
let img = BlurImage::borrow(&pixels, width, 480, FastBlurChannels::Channels3);
img.check_layout().unwrap_err();  // ZeroBaseSize
```

```rust
let width: u32 = 640;  // Valid
let height: u32 = 480;
let pixels = vec![0u8; (width * height * 3) as usize];
let img = BlurImage::borrow(&pixels, width, height, FastBlurChannels::Channels3);
img.check_layout()?;
```

--------------------------------

### ImagesMustMatch Error Example

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Illustrates the ImagesMustMatch error, which occurs when source and destination images have different dimensions or channel counts.

```rust
BlurError::ImagesMustMatch
```

```rust
use libblur::*;

let src = BlurImage::alloc(640, 480, FastBlurChannels::Channels3);
let mut dst = BlurImageMut::alloc(320, 240, FastBlurChannels::Channels3);  // Different size

// In operations that require matching:
src.size_matches(&dst).unwrap_err();  // ImagesMustMatch
```

```rust
let mut dst = BlurImageMut::alloc(640, 480, FastBlurChannels::Channels3);  // Same size
src.size_matches(&dst)?;  // OK
```

--------------------------------

### Fast Bilateral Filter Example

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Example usage of the `fast_bilateral_filter_image` function. This snippet applies an edge-preserving bilateral filter to a source image using specified spatial and range sigma values.

```rust
use libblur::*

let bilateral = fast_bilateral_filter_image(&src, 25.0, 7.0?);
```

--------------------------------

### NegativeOrZeroSigma Error Examples and Fix

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Demonstrates the NegativeOrZeroSigma error, triggered when the sigma parameter is zero or negative in Gaussian blur functions. The fix involves providing a positive sigma value.

```rust
BlurError::NegativeOrZeroSigma
```

```rust
use libblur::*;

GaussianBlurParams::new(51, 0.0);  // sigma = 0!
// Error: NegativeOrZeroSigma

GaussianBlurParams::new(51, -5.0);  // sigma < 0!
// Error: NegativeOrZeroSigma
```

```rust
GaussianBlurParams::new(51, 10.0);  // sigma > 0
```

--------------------------------

### Handling MinimumSliceSizeMismatch Error

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Occurs when the provided pixel buffer is smaller than the required size calculated by stride * height. This example demonstrates the error condition and its fix.

```rust
let width = 640u32;
let height = 480u32;
let stride = width * 3;
// Correct size: stride * height = 640 * 3 * 480 = 921,600
let pixels = vec![0u8; 100];  // Too small!

let img = BlurImage::borrow(&pixels, width, height, FastBlurChannels::Channels3);
// check_layout() fails:
// MinimumSliceSizeMismatch {
//     expected: 921600,
//     received: 100
// }
```

```rust
let pixels = vec![0u8; (width * height * 3) as usize];  // 921,600 bytes
let img = BlurImage::borrow(&pixels, width, height, FastBlurChannels::Channels3);
img.check_layout()?;
```

--------------------------------

### Handling OddKernel Error

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Occurs when an even number is provided for a kernel size, which must be odd. This example illustrates the error condition with invalid kernel sizes and the correct way to define them.

```rust
use libblur::*;

// Invalid: even kernels
let params = BoxBlurParameters { x_axis_kernel: 10, y_axis_kernel: 10 };
// Error when validated: OddKernel(10)

let params = BoxBlurParameters { x_axis_kernel: 20, y_axis_kernel: 5 };
// Error when validated: OddKernel(20)
```

```rust
// Use odd kernels
let params = BoxBlurParameters { x_axis_kernel: 11, y_axis_kernel: 11 };
let params = BoxBlurParameters { x_axis_kernel: 21, y_axis_kernel: 5 };
```

--------------------------------

### Basic Stack Blur Usage

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Demonstrates the typical workflow for applying a stack blur to an image. This includes preparing image data, configuring blur parameters like radius and threading policy, executing the blur, and accessing the result.

```rust
use libblur::*;

// 1. Prepare
let src_data = vec![/* pixels */];
let src = BlurImage::borrow(&src_data, 640, 480, FastBlurChannels::Channels3);

// 2. Choose: Stack blur for speed
// 3. Configure: radius 20, adaptive threading, clamp edges
// 4. Execute
let mut dst = BlurImageMut::default();
stack_blur(&mut BlurImageMut::borrow(&src_data.clone(), 640, 480, FastBlurChannels::Channels3), 20, ThreadingPolicy::Adaptive)?;

// 5. Extract
let result = dst.data.borrow();
println!("Blurred {} bytes", result.len());

```

--------------------------------

### Basic libblur Usage

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Demonstrates basic image blurring using libblur, including image preparation and applying a stack blur. Ensure error handling is implemented for the fallible operations.

```rust
use libblur::*;

let src_pixels = vec![0u8; 640 * 480 * 3];
let src = BlurImage::borrow(&src_pixels, 640, 480, FastBlurChannels::Channels3);
let mut dst = BlurImageMut::default();

stack_blur(&mut dst, 20, ThreadingPolicy::Adaptive)?;

```

--------------------------------

### Custom Stride Handling

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Shows how to configure an `BlurImage` with a custom stride value for memory efficiency, particularly when dealing with padded pixel buffers.

```rust
let mut img = BlurImage {
    data: std::borrow::Cow::Borrowed(&pixels),
    width: 640,
    height: 480,
    stride: 768,  // Custom stride with padding
    channels: FastBlurChannels::Channels3,
};

```

--------------------------------

### Configure libblur for General x86_64

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

For general x86_64 systems, enable both 'avx' and 'sse' features to utilize AVX and SSE4.1 SIMD optimizations respectively.

```toml
# General x86_64
libblur = { version = "0.24", features = ["avx", "sse"] }
```

--------------------------------

### Get numeric channel count

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/api-reference.md

Returns the numeric channel count for a given FastBlurChannels configuration. This is a utility method for understanding image format.

```rust
pub const fn channels(&self) -> usize
```

--------------------------------

### Minimal libblur Build Configuration

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Configure your Cargo.toml to build libblur with minimal dependencies, excluding the 'image' crate and FFT support for a smaller footprint.

```toml
# Minimal build: no image crate, no FFT
[dependencies]
libblur = { version = "0.24", default-features = false }
```

--------------------------------

### Handling MinimumStrideSizeMismatch Error

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Triggered when the stride is smaller than the minimum required size (width * channels). This example shows how to validate and correct the stride value.

```rust
let width = 640u32;
let stride = 100u32;  // Too small for 640×3!

let pixels = vec![0u8; 921600];
let mut img = BlurImageMut::alloc(width, 480, FastBlurChannels::Channels3);
img.stride = stride;  // Manually set invalid stride
// check_layout() fails:
// MinimumStrideSizeMismatch {
//     expected: 1920,  // 640 * 3
//     received: 100
// }
```

```rust
img.stride = width * 3;  // 1920 (or larger for padding)
img.check_layout()?;
```

--------------------------------

### Full-Featured libblur Build Configuration

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Enable all features for libblur by specifying 'image' and 'fft' in your Cargo.toml, providing maximum functionality.

```toml
# All features for maximum functionality
[dependencies]
libblur = { version = "0.24", features = ["image", "fft"] }
```

--------------------------------

### Apply Sobel Edge Detection

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Applies the Sobel operator to detect edges in an image, calculating both X and Y gradients. This example demonstrates custom convolution.

```rust
use libblur::*;

fn apply_sobel() -> Result<(), BlurError> {
    let pixels = vec![0u8; 640 * 480 * 3];
    let src = BlurImage::borrow(&pixels, 640, 480, FastBlurChannels::Channels3);
    let mut dst_x = BlurImageMut::default();
    let mut dst_y = BlurImageMut::default();
    
    sobel(&src, &mut dst_x, &mut dst_y, EdgeMode::Clamp.as_2d(), ThreadingPolicy::Adaptive)?;
    Ok(())
}
```

--------------------------------

### Complete Workflow: Blur sRGB Image

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Demonstrates a full image processing workflow: loading sRGB data, converting to linear space, applying Gaussian blur, and converting back to sRGB.

```rust
use libblur::*;

fn blur_srgb_image() -> Result<(), BlurError> {
    // Load sRGB image data
    let pixels = vec![0u8; 640 * 480 * 3];
    
    // Create image wrapper
    let src = BlurImage::borrow(
        &pixels,
        640,
        480,
        FastBlurChannels::Channels3,
    );
    
    // Convert to linear RGB (required for correct color)
    let linear = src.linearize(TransferFunction::Srgb, false)?;
    
    // Blur in linear space
    let blurred = gaussian_blur_image(
        &linear.to_immutable_ref(),
        GaussianBlurParams::new_from_kernel(61.0),
        EdgeMode::Clamp.as_2d(),
        ConvolutionMode::Exact,
        ThreadingPolicy::Adaptive,
    )?;
    
    // Convert back to sRGB
    let result = blurred
        .to_immutable_ref()
        .gamma8(TransferFunction::Srgb, false)?;

    // Use result
    let data = result.data.borrow();
    println!("Blurred {} bytes", data.len());
    
    Ok(())
}
```

--------------------------------

### Enable Adaptive Threading

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Allow libblur to automatically determine the optimal number of threads based on image size and system resources. This scales from 1-2 threads for small images to all available CPUs for large ones.

```rust
use libblur::ThreadingPolicy;

// Scales with image size (default)
// Small images: 1-2 threads
// Large images: all available CPUs
gaussian_blur_image(&src, params, edge_mode, mode, ThreadingPolicy::Adaptive)?
```

--------------------------------

### Fallback Strategy for Large Images in Rust

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Implement a fallback strategy when an error indicates an operation is too resource-intensive, such as `ExceedingPointerSize`. This example retries the operation with different, potentially less performant, parameters.

```rust
use libblur::*;

fn blur_with_fallback(src: &BlurImage<u8>, params: GaussianBlurParams) -> Result<BlurImageMut<u8>, BlurError> {
    match gaussian_blur_image(src, params, EdgeMode::Clamp.as_2d(), ConvolutionMode::Exact, ThreadingPolicy::Adaptive) {
        Ok(result) => Ok(result),
        Err(BlurError::ExceedingPointerSize) => {
            // Fall back to smaller operations
            println!("Image too large, falling back to single-threaded");
            gaussian_blur_image(src, params, EdgeMode::Clamp.as_2d(), ConvolutionMode::FixedPoint, ThreadingPolicy::Single)
        },
        Err(e) => Err(e),
    }
}
```

--------------------------------

### Configure libblur for ARM64 with NEON and RDM

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

For modern ARM64 CPUs (e.g., Cortex-A78), enable both 'neon' and 'rdm' features to utilize NEON optimizations and extended NEON operations.

```toml
# Modern ARM (Cortex-A78, Snapdragon 8 Gen 1+)
libblur = { version = "0.24", features = ["neon", "rdm"] }
```

--------------------------------

### Configure libblur for Older ARM64 with NEON

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

For older ARM64 CPUs (e.g., Cortex-A72), enable the 'neon' feature to utilize NEON SIMD optimizations.

```toml
# Older ARM (Cortex-A72, older Snapdragon)
libblur = { version = "0.24", features = ["neon"] }
```

--------------------------------

### Apply Gaussian Box Blur

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies a Gaussian-like blur using three sequential box blurs. Offers pleasant results but is slower than other methods. Complexity is O(1).

```rust
let image = BlurImage::borrow(
    &src_bytes,
    dyn_image.width(),
    dyn_image.height(),
    FastBlurChannels::Channels3,
);
let mut dst_image = BlurImageMut::default();
libblur::gaussian_box_blur(&image, &mut dst_image, 10f32, ThreadingPolicy::Single).unwrap();
```

--------------------------------

### Convert to Gamma Color Space (u8)

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Converts linear color space data back to gamma color space, specifically for u8 output. Use this after blurring in linear space to get the final image.

```rust
impl<'a> BlurImage<'a, u16> {
    pub fn gamma8(
        &self,
        transfer_function: TransferFunction,
        assume_premultiplied: bool,
    ) -> Result<BlurImageMut<u8>, BlurError>
}
```

--------------------------------

### Select Edge Handling Strategy

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Choose how to handle image edges during blurring. Options include replicating edge pixels, reflecting, wrapping around, mirroring, or using a constant value.

```rust
use libblur::{EdgeMode, EdgeMode2D};

// Replicate edge pixel (default, most common)
let edge = EdgeMode::Clamp.as_2d();

// Different modes for X and Y
let edge = EdgeMode2D::anisotropy(
    EdgeMode::Clamp,      // Horizontal
    EdgeMode::Reflect,    // Vertical
);

// Wrap around (tile)
let edge = EdgeMode::Wrap.as_2d();

// Mirror (exclude edges)
let edge = EdgeMode::Reflect.as_2d();

// Mirror (include edges)
let edge = EdgeMode::Reflect101.as_2d();

// Constant value (filter APIs only)
let edge = EdgeMode::Constant.as_2d()
```

--------------------------------

### Configure libblur for x86_64 with AVX-512

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

For high-end x86_64 CPUs, enable the 'avx512' feature to leverage 512-bit SIMD operations. This configuration is typically used with Rust 1.89+ or a nightly compiler.

```toml
# High-end CPUs
[target.'cfg(target_arch = "x86_64")'.dependencies]
libblur = { version = "0.24", features = ["avx512"] }
```

--------------------------------

### Control Threading Policy at Runtime

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Demonstrates how to control libblur's multithreading behavior at runtime using the ThreadingPolicy enum. Options include Single, Adaptive, AdaptiveReserve, and Fixed thread counts.

```rust
use libblur::{ThreadingPolicy, stack_blur, BlurImageMut};
use std::num::NonZeroUsize;

let mut image = BlurImageMut::alloc(640, 480, FastBlurChannels::Channels3);

// Single-threaded
stack_blur(&mut image, 10, ThreadingPolicy::Single)?;

// Automatic (default)
stack_blur(&mut image, 10, ThreadingPolicy::Adaptive)?;

// Reserve 2 threads for OS
stack_blur(&mut image, 10, ThreadingPolicy::AdaptiveReserve(NonZeroUsize::new(2).unwrap()))?;

// Exactly 4 threads
stack_blur(&mut image, 10, ThreadingPolicy::Fixed(NonZeroUsize::new(4).unwrap()))?;
```

--------------------------------

### Output Allocation: Default

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Shows how operations automatically allocate and resize output buffers when using `BlurImageMut::default()`. The buffer is resized to fit the operation's output.

```rust
use libblur::*;

let mut dst = BlurImageMut::default();  // Empty

// Operations auto-resize owned buffers
gaussian_blur_image(&src, params, edge_mode, mode, threading)?;
// dst is now correctly sized with blurred data
```

--------------------------------

### Fast Gaussian Blur Implementation

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Applies an in-place fast Gaussian blur using a binomial filter approximation. Offers a balance between speed and quality with O(log R) complexity.

```rust
pub fn fast_gaussian<T: Send + Sync + 'static>(
    image: &mut BlurImageMut<T>,
    radius: u32,
    threading_policy: ThreadingPolicy,
    edge_mode: EdgeMode,
) -> Result<(), BlurError>
```

--------------------------------

### Output Allocation: Pre-allocated Buffer

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Demonstrates reusing a pre-allocated buffer for output. If the buffer is already allocated and correctly sized, image operations will reuse it, improving efficiency.

```rust
let mut dst = BlurImageMut::alloc(640, 480, FastBlurChannels::Channels3);
// dst will be reused and filled with blurred data
```

--------------------------------

### Apply Tent Blur

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies a tent blur by using two sequential box blurs. Offers medium speed and good results, especially with large radii. Complexity is O(1).

```rust
let image = BlurImage::borrow(
    &src_bytes,
    dyn_image.width(),
    dyn_image.height(),
    FastBlurChannels::Channels3,
);
let mut dst_image = BlurImageMut::default();
libblur::tent_blur(&image, &mut dst_image,10f32, ThreadingPolicy::Single).unwrap();
```

--------------------------------

### ImageSize

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

Wrapper for image dimensions, storing width and height.

```APIDOC
## ImageSize

### Description
Wrapper for image dimensions.

### Fields
- **width** (usize) - Required - Image width.
- **height** (usize) - Required - Image height.
```

--------------------------------

### Configure IEEE Binary Convolution Mode for f32

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

This section describes precision options for f32 Gaussian blur, noting the default behavior and the 'Zealous' mode which uses 64-bit intermediate accumulation for higher precision.

```rust
use libblur::IeeeBinaryConvolutionMode;

// f32 precision (default)
// Uses 32-bit accumulation

// Zealous mode (default)
// Uses 64-bit intermediate accumulation for higher precision
```

--------------------------------

### Enable image feature in Cargo.toml

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

To use the image crate integration functions, you must enable the 'image' feature in your Cargo.toml file.

```toml
[dependencies]
libblur = { version = "0.24", features = ["image"] }
```

--------------------------------

### Release Build Optimization Configuration

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Apply release build optimizations in Cargo.toml, including opt-level 3, link-time optimization (LTO), and reducing codegen units for improved performance.

```toml
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
```

--------------------------------

### Image Size Dimensions

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

A wrapper structure for image dimensions, storing width and height as usize.

```rust
pub struct ImageSize {
    pub width: usize,
    pub height: usize,
}
```

--------------------------------

### Add libblur to Cargo.toml

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Add the libblur crate to your project's dependencies in Cargo.toml.

```toml
[dependencies]
libblur = "0.24"

```

--------------------------------

### Use Image Crate Integration

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

When the 'image' feature is enabled, you can directly use high-level blur functions like 'gaussian_blur_image' with the 'image' crate's DynamicImage type. Ensure the feature is enabled via cfg.

```rust
#[cfg(feature = "image")]
{
    use libblur::gaussian_blur_image;
    use image::ImageReader;
    
    let img = ImageReader::open("photo.jpg")?.decode()?;
    // High-level API available with feature enabled
}
```

--------------------------------

### Apply Median Blur

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies a median blur using a median filter. This implementation is reasonably fast. Complexity is O(log R).

```rust
let image = BlurImage::borrow(
    &src_bytes,
    dyn_image.width(),
    dyn_image.height(),
    FastBlurChannels::Channels3,
);
let mut dst_image = BlurImageMut::default();
libblur::median_blur(&image, &mut dst_image,10, ThreadingPolicy::Single).unwrap();
```

--------------------------------

### Stack Blur Implementation

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Performs an in-place stack blur on an image. Suitable for real-time applications due to its O(1) complexity approximation.

```rust
pub fn stack_blur<T: Send + Sync + 'static>(
    image: &mut BlurImageMut<T>,
    radius: u32,
    threading_policy: ThreadingPolicy,
) -> Result<(), BlurError>
```

```rust
use libblur::*;

let mut image = BlurImageMut::alloc(640, 480, FastBlurChannels::Channels3);
// ... fill with pixel data ...
stack_blur(&mut image, 25, ThreadingPolicy::Adaptive)?;
```

--------------------------------

### Enable libblur with Image and FFT Features

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Specify the 'image' and 'fft' features when adding libblur as a dependency in Cargo.toml to enable advanced image processing and FFT-based filtering capabilities.

```toml
[dependencies]
libblur = { version = "0.24", features = ["image", "fft"] }
```

--------------------------------

### Box Blur Parameters

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

Configuration for box blur operations, defining the kernel sizes for the X and Y axes. Both kernel sizes must be odd.

```rust
#[derive(Copy, Clone, Debug)]
pub struct BoxBlurParameters {
    pub x_axis_kernel: u32,
    pub y_axis_kernel: u32,
}
```

--------------------------------

### Gaussian Blur Parameters

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

Configuration for Gaussian blur, specifying kernel sizes and sigma values for both X and Y axes. Kernel sizes must be odd, and sigma values must be positive.

```rust
#[derive(Copy, Clone, Debug)]
pub struct GaussianBlurParams {
    pub x_kernel: u32,
    pub x_sigma: f64,
    pub y_kernel: u32,
    pub y_sigma: f64,
}
```

--------------------------------

### Optimal Sigma Calculation (f64)

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/filter-functions.md

Calculates the optimal sigma value based on a given kernel size using f64 precision.

```rust
pub fn sigma_size_d(kernel_size: f64) -> f64
```

--------------------------------

### 1D Gaussian Kernel Generation (f64)

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/filter-functions.md

Generates a 1D Gaussian kernel with f64 precision, allowing for higher accuracy.

```rust
pub fn gaussian_kernel_1d_f64(kernel_size: u32, sigma: f64) -> Vec<f64>
```

--------------------------------

### Configure Image Stride for Optimization

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Use the default stride (auto-calculated as width * channels) for row-aligned data for maximum efficiency. Optionally, specify a custom stride for padding or alignment purposes.

```rust
use libblur::{BlurImage, FastBlurChannels};

// stride = 0 (auto-calculated as width * channels)
// Most efficient
let img = BlurImage::borrow(&pixels, 640, 480, FastBlurChannels::Channels3);

// Custom stride for padding/alignment
let img_with_stride = BlurImage {
    data: std::borrow::Cow::Borrowed(&pixels),
    width: 640,
    height: 480,
    stride: 768,  // Padded to 768 bytes per row
    channels: FastBlurChannels::Channels3,
}
```

--------------------------------

### FftChannelsNotSupported Error and Fix

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Explains the FftChannelsNotSupported error, which arises when attempting FFT operations on non-planar images (e.g., Channels3 or Channels4). The fix is to process channels separately.

```rust
BlurError::FftChannelsNotSupported
```

```rust
use libblur::*;

// Process channels separately
let src = BlurImage::borrow(&pixels, 640, 480, FastBlurChannels::Plane);  // Single channel
filter_2d_fft(&src, &mut dst, &kernel, shape, edge, scalar, threading)?;
```

--------------------------------

### Enable Half Precision Support (Nightly)

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

For functions supporting f16 (half precision), enable the 'nightly_f16' feature. This requires a nightly Rust compiler.

```rust
#[cfg(feature = "nightly_f16")]
{
    use libblur::fast_gaussian_f16;
}
```

--------------------------------

### Enable FFT Filtering Support

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

To utilize FFT-based convolution for large kernels, add the 'fft' feature to your libblur dependency in Cargo.toml.

```toml
[dependencies]
libblur = { version = "0.24", features = ["fft"] }
```

--------------------------------

### Tent Blur Implementation

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Performs an out-of-place tent blur using two sequential box blurs, approximating a Gaussian blur with O(1) complexity.

```rust
pub fn tent_blur<T: Send + Sync + 'static>(
    src: &BlurImage<T>,
    dst: &mut BlurImageMut<T>,
    radius: f32,
    threading_policy: ThreadingPolicy,
) -> Result<(), BlurError>
```

--------------------------------

### Add libblur Dependency

Source: https://github.com/awxkee/libblur/blob/master/README.md

Add the libblur crate to your Rust project using Cargo.

```bash
cargo add libblur
```

--------------------------------

### stack_blur

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Performs an in-place stack blur with O(1) complexity, suitable for real-time applications. It takes a mutable image, a blur radius, and threading policy as input.

```APIDOC
## stack_blur

### Description
Performs an in-place stack blur with O(1) complexity, suitable for real-time applications. It takes a mutable image, a blur radius, and threading policy as input.

### Signature
```rust
pub fn stack_blur<T: Send + Sync + 'static>(
    image: &mut BlurImageMut<T>,
    radius: u32,
    threading_policy: ThreadingPolicy,
) -> Result<(), BlurError>
```

### Parameters
#### Path Parameters
- **image** (&mut BlurImageMut<T>) - Mutable image (modified in-place)
- **radius** (u32) - Blur radius in pixels
- **threading_policy** (ThreadingPolicy) - Threading configuration

### Returns
- `Result<(), BlurError>`

### Supports
`u8`, `u16`, `f32`

### Example
```rust
use libblur::*

let mut image = BlurImageMut::alloc(640, 480, FastBlurChannels::Channels3);
// ... fill with pixel data ...
stack_blur(&mut image, 25, ThreadingPolicy::Adaptive)?;
```
```

--------------------------------

### gaussian_box_blur

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Applies an out-of-place Gaussian box blur using three sequential box blurs, approximating a true Gaussian with O(1) complexity. It requires source and destination images, a float radius, and threading policy.

```APIDOC
## gaussian_box_blur

### Description
Applies an out-of-place Gaussian box blur using three sequential box blurs, approximating a true Gaussian with O(1) complexity. It requires source and destination images, a float radius, and threading policy.

### Signature
```rust
pub fn gaussian_box_blur<T: Send + Sync + 'static>(
    src: &BlurImage<T>,
    dst: &mut BlurImageMut<T>,
    radius: f32,
    threading_policy: ThreadingPolicy,
) -> Result<(), BlurError>
```
```

--------------------------------

### FFT Convolution for Large Kernels

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Illustrates using Fast Fourier Transform (FFT) for convolution, which is more efficient for large kernels. This requires the `fft` feature to be enabled.

```rust
#[cfg(feature = "fft")]
{
    let optimal_size = fft_next_good_size(640);
    filter_2d_fft(&src, &mut dst, &kernel, shape, edge_mode, scalar, threading)?;
}

```

--------------------------------

### Laplacian Kernel

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/filter-functions.md

Returns the standard 3x3 Laplacian kernel used for second derivative calculations.

```rust
pub fn laplacian_kernel() -> [f32; 9]
```

--------------------------------

### Apply Gaussian Blur with Image Feature

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies Gaussian blur to an image using the image feature and saves the result. Ensure the 'image' crate is available.

```rust
let blurred = gaussian_blur_image(
    img,
    GaussianBlurParams::new_from_kernel(61.),
    EdgeMode2D::new(EdgeMode::Clamp),
    ConvolutionMode::FixedPoint,
    ThreadingPolicy::Adaptive,
)
.unwrap();

blurred
.save_with_format("blurred.jpg", ImageFormat::Jpeg)
.unwrap();
```

--------------------------------

### Central Limit Theorem (CLT) Blur Parameters

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

Parameters for CLT-based blur, using sigma values for X and Y axes. These are typically f32.

```rust
pub struct CLTParameters {
    pub x_sigma: f32,
    pub y_sigma: f32,
}
```

--------------------------------

### Create GaussianBlurParams with Symmetric Parameters

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Instantiates GaussianBlurParams with identical kernel size and sigma for both X and Y directions. Ensure the kernel size is odd.

```rust
use libblur::GaussianBlurParams;

let params = GaussianBlurParams::new(51, 10.0);
assert_eq!(params.x_kernel, 51);
assert_eq!(params.x_sigma, 10.0);
```

--------------------------------

### CLTParameters

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

Central Limit Theorem based blur parameters, using sigma values for X and Y axes.

```APIDOC
## CLTParameters

### Description
Central Limit Theorem based blur parameters (sigma-based).

### Fields
- **x_sigma** (f32) - Required - X-axis sigma.
- **y_sigma** (f32) - Required - Y-axis sigma.
```

--------------------------------

### fast_gaussian

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Applies an in-place fast Gaussian blur using a binomial filter with O(log R) complexity, offering a balance between speed and quality. It requires the image, radius, threading policy, and edge mode.

```APIDOC
## fast_gaussian

### Description
Applies an in-place fast Gaussian blur using a binomial filter with O(log R) complexity, offering a balance between speed and quality. It requires the image, radius, threading policy, and edge mode.

### Signature
```rust
pub fn fast_gaussian<T: Send + Sync + 'static>(
    image: &mut BlurImageMut<T>,
    radius: u32,
    threading_policy: ThreadingPolicy,
    edge_mode: EdgeMode,
) -> Result<(), BlurError>
```

### Parameters
#### Path Parameters
- **image** (&mut BlurImageMut<T>) - Mutable image
- **radius** (u32) - Blur radius
- **threading_policy** (ThreadingPolicy) - Threading
- **edge_mode** (EdgeMode) - Edge handling

### Returns
- `Result<(), BlurError>`
```

--------------------------------

### Apply Fast Gaussian Next Blur

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies an optimized fast Gaussian blur producing pleasant results. Suitable for general use with a maximum radius constraint. Complexity is O(log R).

```rust
let mut dst_image = BlurImageMut::borrow(&mut src_bytes, dyn_image.width(), dyn_image.height(), FastBlurChannels::Channels3)
libblur::fast_gaussian_next(&mut dst_image, 10, ThreadingPolicy::Single, EdgeMode::Wrap).unwrap();
```

--------------------------------

### Box Blur Implementation

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies a box blur to an image. Use this for a compromise between speed and visual quality. It has O(1) complexity.

```rust
let image = BlurImage::borrow(
    &src_bytes,
    dyn_image.width(),
    dyn_image.height(),
    FastBlurChannels::Channels3,
);
let mut dst_image = BlurImageMut::default();
libblur::box_blur(&image, &mut dst_image,10, ThreadingPolicy::Single).unwrap();
```

--------------------------------

### Custom 2D Convolution Kernel

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/README.md

Shows how to apply a custom 2D convolution kernel, such as a Sobel filter, using `filter_2d`. Ensure the kernel shape matches the provided dimensions.

```rust
let sobel_x = vec![-1.0, 0.0, 1.0, -2.0, 0.0, 2.0, -1.0, 0.0, 1.0];
filter_2d(&src, &mut dst, &sobel_x, KernelShape::new(3, 3), edge_mode, scalar, threading)?;

```

--------------------------------

### tent_blur

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Performs an out-of-place tent blur using two sequential box blurs, achieving O(1) complexity. It requires source and destination images, a float radius, and threading policy.

```APIDOC
## tent_blur

### Description
Performs an out-of-place tent blur using two sequential box blurs, achieving O(1) complexity. It requires source and destination images, a float radius, and threading policy.

### Signature
```rust
pub fn tent_blur<T: Send + Sync + 'static>(
    src: &BlurImage<T>,
    dst: &mut BlurImageMut<T>,
    radius: f32,
    threading_policy: ThreadingPolicy,
) -> Result<(), BlurError>
```

### Parameters
#### Path Parameters
- **src** (&BlurImage<T>) - Source image
- **dst** (&mut BlurImageMut<T>) - Destination image
- **radius** (f32) - Blur radius
- **threading_policy** (ThreadingPolicy) - Threading

### Returns
- `Result<(), BlurError>`
```

--------------------------------

### Fast Gaussian Next Blur Implementation

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

An improved version of the fast Gaussian blur offering better quality. Note the maximum radius limitation for u8 images.

```rust
pub fn fast_gaussian_next<T: Send + Sync + 'static>(
    image: &mut BlurImageMut<T>,
    radius: u32,
    threading_policy: ThreadingPolicy,
    edge_mode: EdgeMode,
) -> Result<(), BlurError>
```

--------------------------------

### Enable Debug Logging with RUST_LOG

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/configuration.md

Use the RUST_LOG environment variable to enable debug logging if libblur implements it. This helps in diagnosing issues during runtime.

```bash
RUST_LOG=debug ./my_app
```

--------------------------------

### High-Level Gaussian Blur for BlurImage Wrapper

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Applies Gaussian blur to an image represented by the BlurImage wrapper. Allows configuration of edge handling, convolution mode, and threading policy.

```rust
use libblur::*;

let src = BlurImage::borrow(&pixels, 640, 480, FastBlurChannels::Channels3);
let blurred = gaussian_blur_image(
    &src,
    GaussianBlurParams::new_from_kernel(61.0),
    EdgeMode::Clamp.as_2d(),
    ConvolutionMode::FixedPoint,
    ThreadingPolicy::Adaptive,
)?;
```

--------------------------------

### Early Validation Error Handling Pattern

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/errors.md

Demonstrates the 'Early Validation' error handling pattern in Rust using libblur. It shows validating image layout before proceeding with operations.

```rust
use libblur::*; 

fn process_image(pixels: &[u8], width: u32, height: u32) -> Result<BlurImageMut<u8>, BlurError> {
    let src = BlurImage::borrow(pixels, width, height, FastBlurChannels::Channels3);
    src.check_layout()?;  // Validate early
    
    let mut dst = BlurImageMut::default();
    stack_blur(&mut BlurImageMut::borrow(pixels, width, height, FastBlurChannels::Channels3), 10, ThreadingPolicy::Single)?;
    Ok(dst)
}
```

--------------------------------

### Apply Stack Blur

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies a fast stack blur algorithm to image data. This method is faster than Gaussian blur but may produce slightly less accurate results for advanced analysis. It operates with O(1) complexity.

```rust
let mut dst_image = BlurImageMut::borrow(&mut src_bytes, dyn_image.width(), dyn_image.height(), FastBlurChannels::Channels3)
libblur::stack_blur( &mut dst_image, 10, ThreadingPolicy::Single).unwrap();
```

--------------------------------

### Bilateral Blur Parameters

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

Configuration for edge-preserving bilateral blur, specifying Gaussian sigma for spatial and range (color) kernels.

```rust
#[derive(Copy, Clone, Debug)]
pub struct BilateralBlurParams {
    pub spatial_sigma: f32,
    pub range_sigma: f32,
}
```

--------------------------------

### fast_gaussian_next_blur_image

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/image-functions.md

Provides an improved fast Gaussian blur with better quality compared to `fast_gaussian_blur_image`. It has the same interface but offers enhanced results, with a recommended maximum radius of ~150 for u8 images.

```APIDOC
## fast_gaussian_next_blur_image

### Description
Improved fast Gaussian with better quality. Max radius ~150 for u8.

### Function Signature
```rust
#[cfg(feature = "image")]
pub fn fast_gaussian_next_blur_image<T: Send + Sync + 'static>(
    src: &BlurImage<T>,
    radius: u32,
    edge_mode: EdgeMode,
    threading_policy: ThreadingPolicy,
) -> Result<BlurImageMut<T>, BlurError>
```

### Parameters
#### Source Image
- **src** (&BlurImage<T>) - Required - Source image.

#### Blur Parameters
- **radius** (u32) - Required - Blur radius.
- **edge_mode** (EdgeMode) - Required - Edge handling mode.
- **threading_policy** (ThreadingPolicy) - Required - Threading policy.

### Returns
- `Result<BlurImageMut<T>, BlurError>` - The blurred image or an error.

### Note
Same interface as `fast_gaussian_blur_image` with improved quality.
```

--------------------------------

### BufferStore for Image Data Ownership

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

A wrapper enum to manage image buffer ownership, allowing either a mutable borrow of external data or an owned vector. This enables flexibility in how image data is stored and modified.

```rust
pub enum BufferStore<'a, T: Copy + Debug> {
    Borrowed(&'a mut [T]),
    Owned(Vec<T>),
}
```

--------------------------------

### Apply Fast Gaussian Blur

Source: https://github.com/awxkee/libblur/blob/master/README.md

Applies a fast Gaussian blur to an image. Suitable for general use when exact Gaussian results are not critical. Complexity is O(log R).

```rust
let mut dst_image = BlurImageMut::borrow(&mut src_bytes, dyn_image.width(), dyn_image.height(), FastBlurChannels::Channels3)
libblur::fast_gaussian(&mut dst_image, 10, ThreadingPolicy::Single, EdgeMode::Wrap).unwrap();
```

--------------------------------

### BoxBlurParameters

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/types.md

Configuration for box and related blur operations, defining kernel sizes for X and Y axes.

```APIDOC
## BoxBlurParameters

### Description
Configuration for box and related blur operations.

### Fields
- **x_axis_kernel** (u32) - Required - X-axis kernel size. Must be odd.
- **y_axis_kernel** (u32) - Required - Y-axis kernel size. Must be odd.

### Constraints
Both kernel sizes must be odd.
```

--------------------------------

### Low-Level Gaussian Blur for Raw Buffers

Source: https://github.com/awxkee/libblur/blob/master/_autodocs/blur-functions.md

Performs a Gaussian blur on raw pixel buffers using specified strides, dimensions, and blur parameters. Supports Exact or FixedPoint precision modes.

```rust
use libblur::{gaussian_blur, FastBlurChannels, GaussianPreciseLevel};

let width = 640u32;
let height = 480u32;
let src = vec![128u8; width as usize * height as usize * 3];
let mut dst = vec![0u8; width as usize * height as usize * 3];

gaussian_blur(
    &src, width * 3,
    &mut dst, width * 3,
    width, height,
    51, 10.0,
    FastBlurChannels::Channels3,
    GaussianPreciseLevel::Exact,
)?;
```