Skip to main content

​
Quick Start

This guide will walk you through creating your first blended image using Stitcher. We’ll demonstrate both multiband blending and feather blending techniques.

​
Your First Blend

Let’s create a simple program that blends two images using Stitcher’s multiband blending algorithm.
1

Include Required Headers

Start by including the Stitcher headers:
#include <stdio.h>
#include <time.h>
#include "blending.h"
#include "utils.h"
2

Load Images

Load your input images using create_image():
// Load two images to blend
Image img_buf1 = create_image("apple.jpeg");
Image img_buf2 = create_image("orange.jpeg");
Stitcher currently supports JPEG images only. Make sure your input files are in JPEG format.
3

Create Masks

Create blend masks that define how the images should be combined:
// Create masks for blending
// Left image gets left side, right image gets right side
Image mask1 = create_image_mask(img_buf1.width, img_buf1.height, 0.1f, 0, 1);
Image mask2 = create_image_mask(img_buf2.width, img_buf2.height, 0.1f, 1, 0);
The create_image_mask() function parameters:
  • width, height: Mask dimensions
  • 0.1f: Feather range (10% of width)
  • Last two parameters: Left and right weights
4

Configure Output Size

Calculate the output dimensions considering overlap:
int out = (img_buf1.width * 0.1f);
int out_width = (img_buf1.width * 2) - (out * 2);
StitchRect out_size = {0, 0, out_width, img_buf1.height};
5

Create Blender

Initialize the blender with desired settings:
int num_bands = 5;  // Number of frequency bands
Blender *b = create_blender(MULTIBAND, out_size, num_bands);
More bands (5-7) produce smoother blends but take longer. Fewer bands (3-4) are faster but may show slight seams.
6

Feed Images to Blender

Add your images to the blender with their positions:
// Feed first image at origin
StitchPoint pt1 = {0, 0};
feed(b, &img_buf1, &mask1, pt1);

// Feed second image with offset
StitchPoint pt2 = {img_buf2.width - out * 2 - 100, 0};
feed(b, &img_buf2, &mask2, pt2);
7

Perform Blending

Execute the blending operation:
blend(b);
8

Save Result

Save the blended image and clean up:
if (b->result.data != NULL) {
    if (save_image(&b->result, "merge.jpg")) {
        printf("Merged image saved\n");
    }
}

// Clean up
destroy_blender(b);
destroy_image(&img_buf1);
destroy_image(&img_buf2);
destroy_image(&mask1);
destroy_image(&mask2);

​
Complete Example

Here’s the complete multiband blending example: 
#include <stdio.h>
#include <time.h>
#include "blending.h"
#include "utils.h"

int main() {
    // Load images
    Image img_buf1 = create_image("apple.jpeg");
    Image img_buf2 = create_image("orange.jpeg");

    // Create masks
    Image mask1 = create_image_mask(img_buf1.width, img_buf1.height, 0.1f, 0, 1);
    Image mask2 = create_image_mask(img_buf2.width, img_buf2.height, 0.1f, 1, 0);

    // Configure output size
    int out = (img_buf1.width * 0.1f);
    int out_width = (img_buf1.width * 2) - (out * 2);
    StitchRect out_size = {0, 0, out_width, img_buf1.height};
    int num_bands = 5;

    // Create blender
    Blender *b = create_blender(MULTIBAND, out_size, num_bands);

    // Feed images
    StitchPoint pt1 = {0, 0};
    feed(b, &img_buf1, &mask1, pt1);

    StitchPoint pt2 = {img_buf2.width - out * 2 - 100, 0};
    feed(b, &img_buf2, &mask2, pt2);

    // Blend
    blend(b);

    // Save result
    if (b->result.data != NULL) {
        if (save_image(&b->result, "merge.jpg")) {
            printf("Merged image saved\n");
        }
    }

    // Clean up
    destroy_blender(b);
    destroy_image(&img_buf1);
    destroy_image(&img_buf2);
    destroy_image(&mask1);
    destroy_image(&mask2);

    return 0;
}

​
Feather Blending Alternative

For faster blending with simpler transitions, use feather blending: 
// Create blender with feather mode (no bands parameter needed)
Blender *b = create_blender(FEATHER, out_size, -1);

// Feed and blend (same as multiband)
StitchPoint pt1 = {0, 0};
feed(b, &img_buf1, &mask1, pt1);

StitchPoint pt2 = {img_buf2.width - out * 2 - 100, 0};
feed(b, &img_buf2, &mask2, pt2);

blend(b);

// Save result
if (b->result.data != NULL) {
    save_image(&b->result, "merge_feather.jpg");
}
Feather blending is much faster than multiband blending but may show slight color differences at boundaries. Use it when speed is more important than perfect seamlessness.

​
Compiling Your Program

Compile your program linking against Stitcher: 
gcc -O3 -pthread -o stitch \
  -I/usr/local/include \
  -L/usr/local/lib -lturbojpeg \
  stitch.c blending.c jpeg.c image_operations.c utils.c

​
Performance Tips

Enable Optimizations

Always compile with -O3 flag for maximum performance

Use SIMD Instructions

Add -mavx2 -mfma on x86_64 or let the compiler auto-detect

Adjust Band Count

Use 5-7 bands for best quality, 3-4 for faster processing

Feather for Speed

Use FEATHER mode when speed matters more than seamlessness

​
Measuring Performance

To measure blending performance, use clock_gettime(): 
#include <time.h>

struct timespec start, end;
double duration;

clock_gettime(CLOCK_MONOTONIC, &start);
blend(b);
clock_gettime(CLOCK_MONOTONIC, &end);

duration = (end.tv_sec - start.tv_sec) + (end.tv_nsec - start.tv_nsec) / 1e9;
printf("Blend time: %.2f seconds\n", duration);

​
Next Steps

API Reference

Explore the complete API documentation

Advanced Examples

Learn advanced blending techniques

Build docs developers (and LLMs) love

Get started for freeTalk to us