Operators API

Complete reference for built-in operators.

IOperator Interface

class IOperator {
public:
    virtual ~IOperator() = default;

    virtual cudaError_t initialize() { return cudaSuccess; }
    virtual void shutdown() {}

    // Execute the operator on GPU
    virtual cudaError_t execute(const void* input, void* output,
                                int width, int height, int channels,
                                cudaStream_t stream) = 0;

    // Get workspace requirements for multi-input/batch paths
    virtual WorkspaceRequirements getWorkspaceRequirements(
        const std::vector<ImageBuffer>& inputs) const {
        return {};
    }

    // Whether the operator accepts a given number of inputs
    virtual bool supportsInputCount(size_t count) const { return count == 1; }

    // Multi-input / batch execution path
    virtual cudaError_t executeBuffers(const std::vector<ImageBuffer>& inputs,
                                         ImageBuffer& output,
                                         const OperatorExecutionContext& context);

    // Get output dimensions
    virtual void getOutputDimensions(int inputWidth, int inputHeight, int inputChannels,
                                     int& outputWidth, int& outputHeight,
                                     int& outputChannels) const = 0;

    // Get operator name for debugging
    virtual const char* getName() const = 0;
};

---

GaussianBlurOperator

Applies Gaussian blur with separable filter optimization.

class GaussianBlurOperator : public IOperator {
public:
    explicit GaussianBlurOperator(GaussianKernelSize size, float sigma = 0.0f);
    
    void setKernelSize(GaussianKernelSize size);
    void setSigma(float sigma);
    
    GaussianKernelSize getKernelSize() const;
    float getSigma() const;
};

enum class GaussianKernelSize { 
    KERNEL_3x3 = 3, 
    KERNEL_5x5 = 5, 
    KERNEL_7x7 = 7 
};

Parameters

Parameter	Type	Description
size	GaussianKernelSize	Kernel size (3×3, 5×5, or 7×7)
sigma	float	Gaussian sigma (0 = auto-calculate)

Example

auto blur = std::make_shared<GaussianBlurOperator>(GaussianKernelSize::KERNEL_5x5, 1.5f);

Implementation Details

• Uses separable filter: decomposes 2D kernel into two 1D passes
• Complexity: $O(n^2)\to O(2n)$ per pixel
• Uses shared memory with halo regions for boundary handling

---

SobelOperator

Applies 3×3 Sobel edge detection.

class SobelOperator : public IOperator {
public:
    SobelOperator();
    // Output: single-channel gradient magnitude
};

Output

• Single-channel grayscale image
• Each pixel represents gradient magnitude: $\sqrt{G_x^2+G_y^2}$

Sobel Kernels

$$G_x=\left[\begin{array}{ccc}-1& 0& 1\\ -2& 0& 2\\ -1& 0& 1\end{array}\right]$$$$G_y=\left[\begin{array}{ccc}-1& -2& -1\\ 0& 0& 0\\ 1& 2& 1\end{array}\right]$$

Example

auto sobel = std::make_shared<SobelOperator>();

---

ResizeOperator

Resizes images using interpolation.

class ResizeOperator : public IOperator {
public:
    ResizeOperator(int targetWidth, int targetHeight, 
                   InterpolationMode mode = InterpolationMode::BILINEAR);
    
    void setTargetSize(int width, int height);
    void setInterpolationMode(InterpolationMode mode);
    
    int getTargetWidth() const;
    int getTargetHeight() const;
};

enum class InterpolationMode { NEAREST, BILINEAR };

Parameters

Parameter	Type	Description
targetWidth	int	Output width in pixels
targetHeight	int	Output height in pixels
mode	InterpolationMode	Nearest neighbor or bilinear

Coordinate Mapping

$$sr{c}_x=ds{t}_x\times \frac{src\mathrm{\_}width}{dst\mathrm{\_}width}$$$$sr{c}_y=ds{t}_y\times \frac{src\mathrm{\_}height}{dst\mathrm{\_}height}$$

Example

auto resize = std::make_shared<ResizeOperator>(320, 240, InterpolationMode::BILINEAR);

---

ColorConvertOperator

Converts between color spaces.

class ColorConvertOperator : public IOperator {
public:
    explicit ColorConvertOperator(ColorConversionType type);
};

enum class ColorConversionType { 
    RGB_TO_GRAY, 
    BGR_TO_RGB, 
    RGBA_TO_RGB, 
    GRAY_TO_RGB 
};

Conversion Types

Type	Input	Output	Description
RGB_TO_GRAY	3-channel	1-channel	Luminance conversion
BGR_TO_RGB	3-channel	3-channel	Channel reordering
RGBA_TO_RGB	4-channel	3-channel	Drop alpha channel
GRAY_TO_RGB	1-channel	3-channel	Replicate to 3 channels

Luminance Formula

$$Y=0.299R+0.587G+0.114B$$

(ITU-R BT.601 standard)

Example

auto gray = std::make_shared<ColorConvertOperator>(ColorConversionType::RGB_TO_GRAY);

---

Creating Custom Operators

Implement the IOperator interface:

class MyCustomOperator : public IOperator {
public:
    cudaError_t execute(const void* input, void* output,
                        int width, int height, int channels,
                        cudaStream_t stream) override {
        // Launch CUDA kernel
        myKernel<<<grid, block, 0, stream>>>(input, output, width, height, channels);
        return cudaGetLastError();
    }
    
    void getOutputSize(int inputWidth, int inputHeight,
                       int& outputWidth, int& outputHeight) override {
        outputWidth = inputWidth;
        outputHeight = inputHeight;
    }
    
    int getOutputChannels(int inputChannels) override {
        return inputChannels;
    }
};

Workspace Requirements

WorkspaceRequirements getWorkspaceRequirements(
    const std::vector<ImageBuffer>& inputs) const override {
    if (inputs.empty()) return {};
    return {
        .deviceBytes = static_cast<size_t>(inputs.front().width) *
                       inputs.front().height * inputs.front().channels * sizeof(float)
    };
}

---

MergeAverageOperator

Pixel-wise average of 2 or more inputs of identical shape.

class MergeAverageOperator : public IOperator {
public:
    MergeAverageOperator();

    bool supportsInputCount(size_t count) const override { return count >= 2; }

    void getOutputDimensions(int inputWidth, int inputHeight, int inputChannels,
                             int& outputWidth, int& outputHeight,
                             int& outputChannels) const override;
};

Behavior

• All inputs must share the same width, height, and channels.
• Strict mismatch returns cudaErrorInvalidValue at runtime.
• Output shape equals the first input shape.

Example

auto merge = std::make_shared<MergeAverageOperator>();
int mergeId = pipeline.addOperator("Merge", merge);
pipeline.connect(leftId, mergeId);
pipeline.connect(rightId, mergeId);