Skip to main content

​
Overview

The Blender API provides multi-band and feather blending algorithms for seamless image composition. It supports pyramid-based blending with configurable band levels.

​
Types

​
BlenderType

Enumeration of available blending algorithms. 
typedef enum {
    MULTIBAND,
    FEATHER
} BlenderType;
​
MULTIBAND
enum
Multi-band blending using Laplacian pyramids for smooth transitions between images
​
FEATHER
enum
Simple feather blending using weighted averaging based on mask values

​
Blender

Main blender structure containing blending state and buffers. 
typedef struct {
    int num_bands;
    StitchRect output_size;
    StitchRect real_out_size;
    int *out_width_levels;
    int *out_height_levels;
    ImageF *out;
    ImageF *out_mask;
    ImageS *final_out;
    Image result;
    ImageS *img_laplacians;
    ImageS *mask_gaussian;
    BlenderType blender_type;
    float sharpness;
    int do_distance_transform;
} Blender;
​
num_bands
int
Number of pyramid levels for multi-band blending
​
output_size
StitchRect
Requested output dimensions
​
real_out_size
StitchRect
Actual output dimensions after processing
​
out_width_levels
int*
Array of widths for each pyramid level
​
out_height_levels
int*
Array of heights for each pyramid level
​
out
ImageF*
Floating-point accumulation buffer for blended output
​
out_mask
ImageF*
Floating-point mask accumulation buffer
​
final_out
ImageS*
Short integer intermediate output buffer
​
result
Image
Final blended image (unsigned char)
​
img_laplacians
ImageS*
Laplacian pyramid for multi-band blending
​
mask_gaussian
ImageS*
Gaussian pyramid of masks
​
blender_type
BlenderType
Algorithm type (MULTIBAND or FEATHER)
​
sharpness
float
Sharpness parameter for blending
​
do_distance_transform
int
Whether to apply distance transform to masks

​
Functions

​
create_blender

Creates and initializes a new blender instance. 
Blender *create_blender(BlenderType blender_type, StitchRect out_size, int nb);
​
blender_type
BlenderType
required
Type of blending algorithm to use (MULTIBAND or FEATHER)
​
out_size
StitchRect
required
Output image dimensions and position
​
nb
int
required
Number of pyramid bands for MULTIBAND (ignored for FEATHER, use -1)
​
return
Blender*
Pointer to newly created Blender instance, or NULL on failure
For FEATHER blending, pass -1 for the nb parameter as band count is not used.

​
Example

// Create multi-band blender with 5 pyramid levels
StitchRect out_size = {0, 0, 1024, 768};
Blender *b = create_blender(MULTIBAND, out_size, 5);

// Create feather blender
Blender *b_feather = create_blender(FEATHER, out_size, -1);

​
feed

Feeds an image and its mask into the blender for composition. 
int feed(Blender *b, Image *img, Image *maskImg, StitchPoint tl);
​
b
Blender*
required
Pointer to the Blender instance
​
img
Image*
required
Source image to blend
​
maskImg
Image*
required
Mask image defining blending weights (same dimensions as img)
​
tl
StitchPoint
required
Top-left position where the image should be placed in output canvas
​
return
int
0 on success, non-zero on failure
The mask should be a grayscale image where pixel values indicate blending weight (0-255). Higher values mean more contribution from the source image.

​
Example

Image img1 = create_image("image1.jpg");
Image mask1 = create_mask(img1.width, img1.height, 0.1f, 0, 1);
StitchPoint pt1 = {0, 0};

feed(b, &img1, &mask1, pt1);

// Feed second image with offset
Image img2 = create_image("image2.jpg");
Image mask2 = create_mask(img2.width, img2.height, 0.1f, 1, 0);
StitchPoint pt2 = {512, 0};

feed(b, &img2, &mask2, pt2);

​
blend

Performs the blending operation on all fed images. 
void blend(Blender *b);
​
b
Blender*
required
Pointer to the Blender instance with fed images
Call this after feeding all images. The result will be available in b->result.

​
Example

// After feeding all images
blend(b);

// Access the result
if (b->result.data != NULL) {
    save_image(&b->result, "blended_output.jpg");
}

​
destroy_blender

Frees all resources associated with a blender instance. 
void destroy_blender(Blender *blender);
​
blender
Blender*
required
Pointer to the Blender instance to destroy
Always call this function when finished to prevent memory leaks.

​
Example

destroy_blender(b);

​
Complete Usage Example

#include "blending.h"

void stitch_images() {
    // Load images
    Image img1 = create_image("apple.jpeg");
    Image img2 = create_image("orange.jpeg");
    
    // Create masks for blending
    Image mask1 = create_mask(img1.width, img1.height, 0.1f, 0, 1);
    Image mask2 = create_mask(img2.width, img2.height, 0.1f, 1, 0);
    
    // Calculate output size
    int overlap = img1.width * 0.1f;
    int out_width = (img1.width * 2) - (overlap * 2);
    StitchRect out_size = {0, 0, out_width, img1.height};
    
    // Create blender with 5 bands
    Blender *b = create_blender(MULTIBAND, out_size, 5);
    
    // Feed images
    StitchPoint pt1 = {0, 0};
    feed(b, &img1, &mask1, pt1);
    
    StitchPoint pt2 = {img2.width - overlap * 2 - 100, 0};
    feed(b, &img2, &mask2, pt2);
    
    // Blend
    blend(b);
    
    // Save result
    if (b->result.data != NULL) {
        save_image(&b->result, "stitched.jpg");
    }
    
    // Cleanup
    destroy_blender(b);
    destroy_image(&img1);
    destroy_image(&img2);
    destroy_image(&mask1);
    destroy_image(&mask2);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us