Stitch Images¶

Stitch two overlapping images together into a single panoramic image using SIFT (Scale Invariant Feature Transform) feature matching and homography-based image alignment, automatically detecting common features, calculating geometric transformations, and blending images to create seamless panoramic compositions from overlapping scenes.

How This Block Works¶

This block stitches two overlapping images together by detecting common features, calculating geometric transformations, and aligning the images into a single panoramic result. The block:

1. Receives two input images (image1 and image2) that contain overlapping regions with sufficient detail for feature matching
2. Detects keypoints and computes descriptors using SIFT (Scale Invariant Feature Transform) for both images:
3. Identifies distinctive feature points (keypoints) in each image that are invariant to scale and rotation
4. Computes feature descriptors (128-dimensional vectors) describing the visual characteristics around each keypoint
5. Matches keypoints between the two images using brute force matching:
6. Finds the best matching descriptors for each keypoint in image1 among all keypoints in image2
7. Uses k-nearest neighbor matching (configurable via count_of_best_matches_per_query_descriptor) to find multiple potential matches per query keypoint
8. Filters good matches using Lowe's ratio test:
9. Compares the distance to the best match with the distance to the second-best match
10. Keeps matches where the best match distance is less than 0.75 times the second-best match distance (reduces false matches)
11. Determines image ordering based on keypoint positions (identifies which image should be placed first based on spatial distribution of matched features)
12. Calculates homography transformation matrix using RANSAC (Random Sample Consensus):
13. Finds a perspective transformation matrix that maps points from one image to the other
14. Uses RANSAC to robustly estimate the transformation while filtering out outlier matches
15. Configurable maximum reprojection error (max_allowed_reprojection_error) controls which point pairs are considered inliers
16. Calculates canvas size and translation:
17. Determines the size needed to contain both images after transformation
18. Calculates translation needed to ensure both images fit within the canvas boundaries
19. Warps the second image using the homography transformation:
20. Applies perspective transformation to align the second image with the first
21. Combines homography matrix with translation matrix for correct positioning
22. Stitches images together:
23. Places the first image onto the warped second image canvas
24. Creates the final stitched panoramic image containing both input images aligned and blended
25. Returns the stitched image, or None if stitching fails (e.g., insufficient matches, transformation calculation failure)

The block uses SIFT for robust feature detection that works well with images containing sufficient detail and texture. The RANSAC-based homography calculation handles perspective distortions and ensures robust alignment even with some incorrect matches. The reprojection error threshold controls the sensitivity of the alignment - lower values require more precise matches, while higher values (useful for low-detail images) allow more tolerance for matching variations.

Common Use Cases¶

• Panoramic Image Creation: Stitch overlapping images together to create wide panoramic views (e.g., create panoramic photos from overlapping camera shots, stitch together images from rotating cameras, combine multiple overlapping images into panoramas), enabling panoramic image generation workflows
• Wide-Area Scene Reconstruction: Combine multiple overlapping views of a scene into a single comprehensive image (e.g., reconstruct wide scenes from multiple camera angles, combine overlapping surveillance camera views, stitch together images from multiple viewpoints), enabling wide-area scene visualization
• Multi-Image Mosaicking: Create image mosaics from overlapping image tiles or sections (e.g., stitch together image tiles for large-scale mapping, combine overlapping satellite image sections, create mosaics from overlapping image captures), enabling image mosaic creation workflows
• Scene Documentation: Combine multiple overlapping images to document large scenes or areas (e.g., document large spaces with multiple overlapping photos, combine overlapping views for scene documentation, stitch together images for comprehensive scene capture), enabling comprehensive scene documentation
• Video Frame Stitching: Stitch together overlapping frames from video sequences (e.g., create panoramic views from video frames, combine overlapping frames from moving cameras, stitch together consecutive video frames), enabling video-based panoramic workflows
• Multi-Camera View Combination: Combine overlapping views from multiple cameras into a single unified view (e.g., stitch together overlapping camera feeds, combine multi-camera views for monitoring, merge overlapping camera perspectives), enabling multi-camera view integration workflows

Connecting to Other Blocks¶

This block receives two images and produces a single stitched image:

• After image input blocks or image preprocessing blocks to stitch preprocessed images together (e.g., stitch images after preprocessing, combine images after enhancement, merge images after filtering), enabling image stitching workflows
• After crop blocks to stitch together cropped image regions from different sources (e.g., stitch cropped regions from different images, combine cropped sections from multiple sources, merge cropped regions into panoramas), enabling cropped region stitching workflows
• After transformation blocks to stitch images that have been transformed or adjusted (e.g., stitch images after perspective correction, combine images after geometric transformations, merge images after adjustments), enabling transformed image stitching workflows
• Before detection or analysis blocks that benefit from panoramic views (e.g., detect objects in stitched panoramic images, analyze wide-area stitched scenes, process comprehensive stitched views), enabling panoramic analysis workflows
• Before visualization blocks to display stitched panoramic images (e.g., visualize stitched panoramas, display wide-area stitched views, show comprehensive stitched scenes), enabling panoramic visualization outputs
• In multi-stage image processing workflows where images need to be stitched before further processing (e.g., stitch images before detection, combine images before analysis, merge images for comprehensive processing), enabling multi-stage panoramic processing workflows

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/stitch_images@v1to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Stitch Images in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/stitch_images@v1",
    "image1": "$inputs.image1",
    "image2": "$inputs.image2",
    "max_allowed_reprojection_error": 3,
    "count_of_best_matches_per_query_descriptor": 2
}