Image Sampler with Edge Handling

Summary

Implement a GPU-accelerated image sampler that applies different edge-handling strategies when sampling pixels outside image boundaries. Your implementation should support multiple addressing modes (wrap, clamp, border) and interpolation methods (nearest-neighbor and bilinear).

Background

When processing images on the GPU, it's often necessary to sample pixel values at arbitrary coordinates, including positions outside the image boundaries. Different applications require different behaviors at these edges:

• Wrap mode: Coordinates wrap around to the opposite edge (tiling effect)
• Clamp mode: Out-of-bounds coordinates use the nearest edge pixel
• Border mode: Out-of-bounds coordinates return a constant border color

Additionally, sampling at non-integer coordinates requires interpolation between neighboring pixels using either nearest-neighbor (fast) or bilinear interpolation (smooth).

Requirements

Your implementation must:

1. Accept a 2D grayscale image (single-channel float32 values in range [0, 1])
2. Accept an array of sampling coordinates (u, v pairs normalized to [0, 1] range, where (0, 0) is top-left and (1, 1) is bottom-right)
3. Support configurable addressing mode: "wrap", "clamp", or "border"
4. Support configurable filtering mode: "nearest" or "linear"
5. For border mode, use a border value of 0.5 (gray)
6. Return the sampled pixel values at the specified coordinates

Input Specifications

• Image: NumPy array of shape (height, width) with dtype float32, values in [0, 1]
• Coordinates: NumPy array of shape (N, 2) with dtype float32, representing (u, v) normalized coordinates
• Addressing mode: String, one of: "wrap", "clamp", "mirror", "border"
• Filtering mode: String, one of: "nearest", "linear"

Output Specifications

• NumPy array of shape (N,) with dtype float32, containing sampled values

Implementation Files

• image_sampler.py: Main implementation
• test_image_sampler.py: Test cases

Dependencies { .dependencies }

pycuda { .dependency }

Provides GPU computation capabilities for accelerated image sampling.

Test Cases

The following test cases should be implemented:

Test Case 1: Wrap Mode with Nearest Filtering { .test-case @test }

Input:

• 4x4 image with values:

  [[0.0, 0.25, 0.5, 0.75],
   [0.1, 0.35, 0.6, 0.85],
   [0.2, 0.45, 0.7, 0.95],
   [0.3, 0.55, 0.8, 1.0]]

• Sampling coordinates: [[-0.1, 0.1], [1.1, 0.5], [0.5, -0.2]] (normalized)
• Addressing mode: "wrap"
• Filtering mode: "nearest"

Expected Output:

• Sample at (-0.1, 0.1) wraps to (0.9, 0.1) → nearest pixel (3, 0) → 0.75
• Sample at (1.1, 0.5) wraps to (0.1, 0.5) → nearest pixel (0, 2) → 0.2
• Sample at (0.5, -0.2) wraps to (0.5, 0.8) → nearest pixel (2, 3) → 0.95

Array: [0.75, 0.2, 0.95]

Test Case 2: Clamp Mode with Linear Filtering { .test-case @test }

Input:

• 3x3 image with values:

  [[0.0, 0.5, 1.0],
   [0.2, 0.5, 0.8],
   [0.4, 0.5, 0.6]]

• Sampling coordinates: [[0.5, 0.5], [1.2, 0.5], [0.5, -0.1]] (normalized)
• Addressing mode: "clamp"
• Filtering mode: "linear"

Expected Output:

• Sample at (0.5, 0.5): bilinear interpolation at image center → ~0.5
• Sample at (1.2, 0.5): clamped to (1.0, 0.5), samples right edge with interpolation
• Sample at (0.5, -0.1): clamped to (0.5, 0.0), samples top edge with interpolation

Values will vary based on interpolation, but should reflect edge clamping behavior.

Test Case 3: Border Mode { .test-case @test }

Input:

• 2x2 image with values:

  [[0.0, 1.0],
   [1.0, 0.0]]

• Sampling coordinates: [[-0.5, 0.5], [1.5, 0.5], [0.5, 0.5]] (normalized)
• Addressing mode: "border"
• Filtering mode: "nearest"

Expected Output:

• Sample at (-0.5, 0.5): outside bounds → 0.5 (border value)
• Sample at (1.5, 0.5): outside bounds → 0.5 (border value)
• Sample at (0.5, 0.5): inside bounds → actual pixel value

Array: [0.5, 0.5, <interpolated value>]

Notes

• You may need to convert between normalized coordinates [0, 1] and pixel coordinates
• Consider how to efficiently structure the GPU computation
• Ensure proper memory management between CPU and GPU
• Your implementation should work for images of arbitrary size