Spaces:

avans06
/

ImageStitcherByOpenCV

Sleeping

App Files Files Community

ImageStitcherByOpenCV / app.py

avans06

Add option to toggle transparency processing

c23cef2 26 days ago

raw

history blame contribute delete

171 kB

	import os
	import gc
	import cv2
	import time
	import tempfile
	import mimetypes
	import traceback
	import numpy as np
	import gradio as gr

	# --- Logging Helper ---
	def log_and_print(message, current_log=""):
	"""Prints a message to the console and appends it to the log string."""
	print(message) # Print to console
	return current_log + message + "\n" # Append to log string with newline

	# --- Helper Function: Crop Image by Percentage ---
	def crop_image_by_percent(image, crop_top_percent=0.0, crop_bottom_percent=0.0):
	"""
	Crops the top and/or bottom portion of an image based on percentage.

	Args:
	image: The input image (NumPy array).
	crop_top_percent: Percentage of height to crop from the top (0-100).
	crop_bottom_percent: Percentage of height to crop from the bottom (0-100).

	Returns:
	The cropped image (NumPy array), or the original image if cropping is not needed
	or percentages are invalid. Returns None if the input image is invalid.
	"""
	if image is None or image.size == 0:
	# print("Warning: Invalid input image to crop_image_by_percent.")
	return None # Return None for invalid input

	if crop_top_percent < 0 or crop_top_percent > 100 or \
	crop_bottom_percent < 0 or crop_bottom_percent > 100:
	print(f"Warning: Invalid crop percentages ({crop_top_percent}%, {crop_bottom_percent}%). Must be between 0 and 100. Skipping crop.")
	return image

	if crop_top_percent == 0 and crop_bottom_percent == 0:
	return image # No cropping needed

	if crop_top_percent + crop_bottom_percent >= 100:
	print(f"Warning: Total crop percentage ({crop_top_percent + crop_bottom_percent}%) is 100% or more. Skipping crop.")
	return image

	try:
	h, w = image.shape[:2]

	pixels_to_crop_top = int(h * crop_top_percent / 100.0)
	pixels_to_crop_bottom = int(h * crop_bottom_percent / 100.0)

	start_row = pixels_to_crop_top
	end_row = h - pixels_to_crop_bottom

	# Ensure indices are valid after calculation
	if start_row >= end_row or start_row < 0 or end_row > h:
	print(f"Warning: Invalid calculated crop rows (start={start_row}, end={end_row} for height={h}). Skipping crop.")
	return image

	cropped_image = image[start_row:end_row, :]
	# print(f"Debug: Cropped by percentage from {image.shape} to {cropped_image.shape}")
	return cropped_image
	except Exception as e:
	print(f"Unexpected error during percentage cropping: {e}. Returning original image.")
	traceback.print_exc()
	return image

	# --- Helper Function: Crop Black Borders ---
	def crop_black_borders(image, enable_cropping=True, strict_no_black_edges=False):
	"""
	Crops black borders (or transparent borders for BGRA) from an image.

	Args:
	image: The input image (NumPy array).
	enable_cropping: If False, returns the original image.
	strict_no_black_edges: If True, iteratively removes any remaining single black/transparent
	pixel lines from the edges after the initial crop.

	Returns:
	The cropped image (NumPy array), or the original image if cropping is disabled.
	Returns None if the input is invalid or strict cropping removes everything.
	"""
	if not enable_cropping:
	return image
	if image is None or image.size == 0:
	return None

	try:
	mask_coords_found = False
	coords = None

	# Check Alpha Channel first
	if len(image.shape) == 3 and image.shape[2] == 4:
	# If BGRA, use the Alpha channel to find the bounding box
	alpha_channel = image[:, :, 3]
	coords = cv2.findNonZero(alpha_channel)
	if coords is not None:
	mask_coords_found = True

	# Fallback: Attempt grayscale conversion (for BGR)
	elif len(image.shape) == 3 and image.shape[2] == 3:
	try:
	gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
	coords = cv2.findNonZero(gray)
	if coords is not None:
	mask_coords_found = True
	except cv2.error as e_gray:
	# print(f"Note: cvtColor to GRAY failed ({e_gray}), trying mask method.")
	gray = None # Reset gray if conversion failed
	elif len(image.shape) == 2:
	gray = image # Already grayscale
	coords = cv2.findNonZero(gray)
	if coords is not None:
	mask_coords_found = True

	# Fallback: Use mask if grayscale failed or shape is unusual
	if not mask_coords_found:
	try:
	# Create a mask where any channel/value is > 0
	mask = np.any(image > 0, axis=-1) if len(image.shape) == 3 else (image > 0)
	coords = cv2.findNonZero(mask.astype(np.uint8))
	if coords is not None:
	mask_coords_found = True
	except Exception as e_crop_fallback:
	# print(f"Could not create mask for cropping fallback: {e_crop_fallback}. Returning original.")
	return image # Cannot proceed if mask fails too

	if not mask_coords_found or coords is None:
	# print("Debug: No non-black pixels found via any method, returning original.")
	return image # Return original if all black or coords failed

	x, y, w, h = cv2.boundingRect(coords)
	if w <= 0 or h <= 0:
	# print(f"Debug: Invalid bounding rect ({w}x{h}), returning original.")
	return image

	# Initial crop based on bounding rectangle
	cropped_image = image[y:y+h, x:x+w]

	# --- START: Strict Edge Cropping Logic ---
	if strict_no_black_edges and cropped_image is not None and cropped_image.size > 0:
	# Iteratively remove black edges until none remain or image is empty
	initial_shape = cropped_image.shape
	iterations = 0
	MAX_ITERATIONS = max(initial_shape) # Safety break
	while iterations < MAX_ITERATIONS:
	iterations += 1
	# Re-check size in loop
	if cropped_image is None or cropped_image.size == 0:
	# print("Debug: Strict cropping resulted in empty image.")
	return None # Image got cropped away entirely

	# Check current edges
	h_cr, w_cr = cropped_image.shape[:2]
	if h_cr <= 1 or w_cr <= 1:
	break

	# Extract edges depending on channels
	if len(cropped_image.shape) == 3 and cropped_image.shape[2] == 4:
	# Use Alpha for strict check
	top_row = cropped_image[0, :, 3]
	bottom_row = cropped_image[-1, :, 3]
	left_col = cropped_image[:, 0, 3]
	right_col = cropped_image[:, -1, 3]
	elif len(cropped_image.shape) == 3:
	# Convert to gray
	try:
	gray_cropped = cv2.cvtColor(cropped_image, cv2.COLOR_BGR2GRAY)
	except:
	# print("Warning: Failed to convert to gray during strict crop, stopping strict loop.")
	break # Stop if conversion fails
	top_row = gray_cropped[0, :]
	bottom_row = gray_cropped[-1, :]
	left_col = gray_cropped[:, 0]
	right_col = gray_cropped[:, -1]
	else:
	# Grayscale/Single channel
	top_row = cropped_image[0, :]
	bottom_row = cropped_image[-1, :]
	left_col = cropped_image[:, 0]
	right_col = cropped_image[:, -1]

	top_has_void = np.any(top_row == 0)
	bottom_has_void = np.any(bottom_row == 0)
	left_has_void = np.any(left_col == 0)
	right_has_void = np.any(right_col == 0)

	# If no edges have void, we are done
	if not (top_has_void or bottom_has_void or left_has_void or right_has_void):
	# print(f"Debug: Strict cropping finished after {iterations-1} adjustments.")
	break # Exit the while loop

	# Adjust cropping
	y_start_new, y_end_new = 0, h_cr
	x_start_new, x_end_new = 0, w_cr

	if top_has_void:
	y_start_new += 1
	if bottom_has_void:
	y_end_new -= 1
	if left_has_void:
	x_start_new += 1
	if right_has_void:
	x_end_new -= 1

	# Check if new bounds are valid before slicing
	if y_start_new < y_end_new and x_start_new < x_end_new:
	cropped_image = cropped_image[y_start_new:y_end_new, x_start_new:x_end_new]
	else:
	# print("Debug: Strict cropping bounds became invalid, stopping.")
	cropped_image = None # Signal that cropping failed
	break # Exit loop

	if iterations >= MAX_ITERATIONS:
	print("Warning: Strict cropping reached max iterations, potential issue.")
	if cropped_image is not None and initial_shape != cropped_image.shape:
	print(f"Info: Strict cropping adjusted size from {initial_shape} to {cropped_image.shape}")
	# --- END: Strict Edge Cropping Logic ---

	return cropped_image # Return the potentially strictly cropped image

	except cv2.error as e:
	print(f"OpenCV Error during black border cropping: {e}. Returning uncropped image.")
	return image
	except Exception as e:
	print(f"Unexpected error during black border cropping: {e}. Returning uncropped image.")
	traceback.print_exc()
	return image

	# --- Helper Function: Multi-Band Blending ---
	def multi_band_blending(img1, img2, mask, num_levels=5):
	# img1, img2: The two images to blend (float32). Can be 3 or 4 channels (BGR or BGRA).
	# mask: The blending mask (float32, 0 to 1 transition, full canvas size, representing weight for img1)
	# num_levels: Number of pyramid levels
	log_message = "" # Add local logging if needed

	# Ensure inputs are float32 (caller should ensure this, but double check)
	if img1.dtype != np.float32:
	img1 = img1.astype(np.float32)
	if img2.dtype != np.float32:
	img2 = img2.astype(np.float32)

	if mask.dtype != np.float32:
	log_message = log_and_print(f"Warning: Mask input to multi_band_blending was {mask.dtype}, converting to float32.\n", log_message)
	if mask.max() > 1: # Assuming uint8 if max > 1
	mask = mask.astype(np.float32) / 255.0
	else: # Assuming already float but maybe not float32
	mask = mask.astype(np.float32)

	# Handle Channel Expansion for Mask
	# Ensure mask has same number of channels as images
	num_channels = img1.shape[2] if len(img1.shape) == 3 else 1

	if len(mask.shape) == 2 and len(img1.shape) == 3:
	if num_channels == 4:
	mask = cv2.cvtColor(mask, cv2.COLOR_GRAY2BGRA) # Expand to 4 channels
	else:
	mask = cv2.cvtColor(mask, cv2.COLOR_GRAY2BGR) # Expand to 3 channels
	elif len(mask.shape) == 3 and mask.shape[2] == 1 and len(img1.shape) == 3:
	if num_channels == 4:
	mask = cv2.cvtColor(mask, cv2.COLOR_GRAY2BGRA)
	else:
	mask = cv2.cvtColor(mask, cv2.COLOR_GRAY2BGR)

	# 1. Build Gaussian pyramids for img1, img2
	gp1 = [img1]
	gp2 = [img2]
	# Temporary list to store pyrDown results to avoid modifying list during iteration
	gp1_next = []
	gp2_next = []
	actual_levels = 0
	for i in range(num_levels):
	prev_h, prev_w = gp1[-1].shape[:2]
	if prev_h < 2 or prev_w < 2:
	log_message = log_and_print(f"Warning: Stopping image pyramid build at level {i} due to small size ({prev_h}x{prev_w}).\n", log_message)
	break # Stop building pyramids for images

	try:
	down1 = cv2.pyrDown(gp1[-1])
	down2 = cv2.pyrDown(gp2[-1])
	gp1_next.append(down1)
	gp2_next.append(down2)
	actual_levels += 1 # Increment count of successfully built levels
	except cv2.error as e_pyrdown:
	log_message = log_and_print(f"Error during pyrDown at level {i+1}: {e_pyrdown}. Stopping pyramid build.\n", log_message)
	break # Stop if pyrDown fails

	# Update the main lists after the loop
	gp1.extend(gp1_next); del gp1_next
	gp2.extend(gp2_next); del gp2_next
	gc.collect()

	# Adjust num_levels to the actual number built
	num_levels = actual_levels

	# If pyramid build failed completely or input was too small
	if num_levels == 0:
	log_message = log_and_print("Error: Cannot build any pyramid levels. Using simple weighted average.\n", log_message)
	blended_img = img1 * mask + img2 * (1.0 - mask)
	blended_img = np.clip(blended_img, 0, 255).astype(np.uint8)
	# print(log_message) # Optional: print warnings
	if 'gp1' in locals(): del gp1
	if 'gp2' in locals(): del gp2
	gc.collect()
	return blended_img # Fallback

	# 2. Build Laplacian pyramids for img1, img2
	# Smallest Gaussian level acts as base of Laplacian pyramid
	lp1 = [gp1[num_levels]]
	lp2 = [gp2[num_levels]]
	for i in range(num_levels, 0, -1):
	# Target size is the size of the next larger Gaussian level
	target_size = (gp1[i-1].shape[1], gp1[i-1].shape[0])
	# log_message = log_and_print(f"Using resize instead of pyrUp for Laplacian level {i}\n", log_message) # Optional log
	ge1 = cv2.resize(gp1[i], target_size, interpolation=cv2.INTER_LINEAR)
	ge2 = cv2.resize(gp2[i], target_size, interpolation=cv2.INTER_LINEAR)

	# Ensure dimensions match EXACTLY before subtraction
	# Sometimes pyrUp result might be 1 pixel off from the actual gp[i-1] size
	h_target, w_target = gp1[i-1].shape[:2]
	h_ge, w_ge = ge1.shape[:2]

	# Crop or pad ge1/ge2 to match gp1[i-1]/gp2[i-1] dimensions
	if ge1.shape[:2] != (h_target, w_target):
	#print(f"Level {i} pyrUp/resize shape mismatch: ge1={ge1.shape}, target={gp1[i-1].shape}. Adjusting ge1.")
	ge1_adj = np.zeros_like(gp1[i-1], dtype=ge1.dtype)
	copy_h = min(h_target, h_ge)
	copy_w = min(w_target, w_ge)
	ge1_adj[:copy_h, :copy_w] = ge1[:copy_h, :copy_w]
	ge1 = ge1_adj
	del ge1_adj

	if ge2.shape[:2] != (h_target, w_target):
	#print(f"Level {i} pyrUp/resize shape mismatch: ge2={ge2.shape}, target={gp2[i-1].shape}. Adjusting ge2.")
	ge2_adj = np.zeros_like(gp2[i-1], dtype=ge2.dtype)
	copy_h = min(h_target, ge2.shape[0]) # Use ge2.shape[0] here
	copy_w = min(w_target, ge2.shape[1]) # Use ge2.shape[1] here
	ge2_adj[:copy_h, :copy_w] = ge2[:copy_h, :copy_w]
	ge2 = ge2_adj
	del ge2_adj


	# Calculate Laplacian: Higher resolution Gaussian - Expanded lower resolution Gaussian
	laplacian1 = cv2.subtract(gp1[i-1], ge1)
	laplacian2 = cv2.subtract(gp2[i-1], ge2)
	lp1.append(laplacian1)
	lp2.append(laplacian2)
	del ge1, ge2, laplacian1, laplacian2
	gc.collect()

	# del gp1, gp2
	# gc.collect()

	# lp1/lp2 lists are now [SmallestGaussian, LapN, LapN-1, ..., Lap1] (N=num_levels)
	lp1.reverse() # Reverse to [Lap1, ..., LapN, SmallestGaussian]
	lp2.reverse()

	# 3. Build Gaussian pyramid for the mask
	gm = [mask]
	gm_next = []
	actual_mask_levels = 0
	for i in range(num_levels): # Build mask pyramid only up to the actual image levels
	prev_h, prev_w = gm[-1].shape[:2]
	if prev_h < 2 or prev_w < 2:
	log_message = log_and_print(f"Warning: Stopping mask pyramid build at level {i}.\n", log_message)
	# num_levels should already be adjusted, but ensure mask levels don't exceed
	break
	try:
	down_mask = cv2.pyrDown(gm[-1])
	gm_next.append(down_mask)
	actual_mask_levels += 1
	except cv2.error as e_pyrdown_mask:
	log_message = log_and_print(f"Error during mask pyrDown at level {i+1}: {e_pyrdown_mask}. Stopping mask pyramid build.\n", log_message)
	break

	gm.extend(gm_next); del gm_next
	gc.collect()

	# Ensure mask pyramid has the same number of levels as laplacian (+ base)
	if len(gm) != num_levels + 1:
	log_message = log_and_print(f"Error: Mask pyramid levels ({len(gm)}) does not match expected ({num_levels + 1}). Using simple average.\n", log_message)
	# Fallback if mask pyramid construction failed unexpectedly
	blended_img = img1 * mask + img2 * (1.0 - mask)
	blended_img = np.clip(blended_img, 0, 255).astype(np.uint8)
	if 'lp1' in locals(): del lp1
	if 'lp2' in locals(): del lp2
	if 'gm' in locals(): del gm
	gc.collect()
	return blended_img


	# 4. Blend Laplacian levels
	ls = [] # Blended Laplacian pyramid
	for i in range(num_levels): # Blend Lap1 to LapN
	lap1 = lp1[i]
	lap2 = lp2[i]
	mask_level = gm[i] # Use corresponding mask level (gm[0] for lp1[0]=Lap1, etc.)

	# Ensure mask shape matches laplacian shape for this level
	if mask_level.shape[:2] != lap1.shape[:2]:
	# print(f"Level {i} mask/lap shape mismatch: mask={mask_level.shape}, lap={lap1.shape}. Resizing mask.")
	mask_level = cv2.resize(mask_level, (lap1.shape[1], lap1.shape[0]), interpolation=cv2.INTER_LINEAR)

	# Ensure channels match after resize
	if len(mask_level.shape) == 2 and len(lap1.shape) == 3:
	if num_channels == 4:
	mask_level = cv2.cvtColor(mask_level, cv2.COLOR_GRAY2BGRA)
	else:
	mask_level = cv2.cvtColor(mask_level, cv2.COLOR_GRAY2BGR)
	elif len(mask_level.shape) == 3 and mask_level.shape[2] == 1 and len(lap1.shape) == 3:
	if num_channels == 4:
	mask_level = cv2.cvtColor(mask_level, cv2.COLOR_GRAY2BGRA)
	else:
	mask_level = cv2.cvtColor(mask_level, cv2.COLOR_GRAY2BGR)
	# Clip mask just in case resize interpolation goes slightly out of [0,1]
	mask_level = np.clip(mask_level, 0.0, 1.0)


	# Blend: L = L1Gm + L2(1-Gm)
	blended_lap = lap1 * mask_level + lap2 * (1.0 - mask_level)
	ls.append(blended_lap)
	del lap1, lap2, mask_level, blended_lap
	gc.collect()

	# Blend the smallest Gaussian level (base of the pyramid)
	base1 = lp1[num_levels] # Smallest Gaussian stored at the end of reversed lp1
	base2 = lp2[num_levels]
	mask_base = gm[num_levels] # Use the smallest mask (corresponding to the smallest Gaussian level)
	if mask_base.shape[:2] != base1.shape[:2]:
	# print(f"Base level mask/base shape mismatch: mask={mask_base.shape}, base={base1.shape}. Resizing mask.")
	mask_base = cv2.resize(mask_base, (base1.shape[1], base1.shape[0]), interpolation=cv2.INTER_LINEAR)
	# Channel check
	if len(mask_base.shape) == 2 and len(base1.shape) == 3:
	if num_channels == 4:
	mask_base = cv2.cvtColor(mask_base, cv2.COLOR_GRAY2BGRA)
	else:
	mask_base = cv2.cvtColor(mask_base, cv2.COLOR_GRAY2BGR)
	elif len(mask_base.shape) == 3 and mask_base.shape[2]==1 and len(base1.shape) == 3:
	if num_channels == 4:
	mask_base = cv2.cvtColor(mask_base, cv2.COLOR_GRAY2BGRA)
	else:
	mask_base = cv2.cvtColor(mask_base, cv2.COLOR_GRAY2BGR)
	mask_base = np.clip(mask_base, 0.0, 1.0)

	# Blend the base Gaussian level: B = B1Gm_N + B2(1-Gm_N)
	blended_base = base1 * mask_base + base2 * (1.0 - mask_base)
	ls.append(blended_base) # ls is now [BlendedLap1, ..., BlendedLapN, BlendedBase]
	# del lp1, lp2, gm, base1, base2, mask_base, blended_base
	del base1, base2, mask_base, blended_base
	gc.collect()

	# 5. Reconstruct the final image from the blended Laplacian pyramid
	# Start with the smallest blended base
	blended_img = ls[num_levels]
	for i in range(num_levels - 1, -1, -1): # Iterate from N-1 down to 0
	# Target size is the size of the current blended Laplacian level (ls[i])
	target_size = (ls[i].shape[1], ls[i].shape[0])
	# log_message = log_and_print(f"Using resize instead of pyrUp for reconstruction level {i}\n", log_message) # Optional log
	expanded_prev = cv2.resize(blended_img, target_size, interpolation=cv2.INTER_LINEAR)

	# Delete previous level's blended_img (important for memory)
	del blended_img
	gc.collect()

	# Ensure dimensions match EXACTLY before adding
	h_target_rec, w_target_rec = ls[i].shape[:2]
	h_exp, w_exp = expanded_prev.shape[:2]
	if expanded_prev.shape[:2] != (h_target_rec, w_target_rec):
	# print(f"Reconstruction level {i} shape mismatch: expanded={expanded_prev.shape}, target={ls[i].shape}. Adjusting expanded.")
	expanded_adj = np.zeros_like(ls[i], dtype=expanded_prev.dtype)
	copy_h_rec = min(h_target_rec, h_exp)
	copy_w_rec = min(w_target_rec, w_exp)
	expanded_adj[:copy_h_rec, :copy_w_rec] = expanded_prev[:copy_h_rec, :copy_w_rec]
	expanded_prev = expanded_adj
	del expanded_adj

	# Add the blended Laplacian for the current level
	current_laplacian = ls[i] # Get reference before add
	blended_img = cv2.add(expanded_prev, current_laplacian)
	del expanded_prev, current_laplacian # Remove laplacian reference ls[i]
	ls[i] = None # Explicitly break the reference in the list too? Might help GC.
	gc.collect()

	# Clip final result and convert back to uint8
	blended_img = np.clip(blended_img, 0, 255)
	blended_img = blended_img.astype(np.uint8)

	# Optional: print warnings collected during the process
	# if log_message: print("MultiBand Blend Logs:\n" + log_message)

	# Cleanup intermediate pyramids (important for memory)
	del gp1, gp2, lp1, lp2, gm, ls
	if 'laplacian1' in locals(): del laplacian1
	if 'laplacian2' in locals(): del laplacian2
	if 'ge1' in locals(): del ge1
	if 'ge2' in locals(): del ge2
	if 'mask_level' in locals(): del mask_level
	if 'base1' in locals(): del base1
	if 'base2' in locals(): del base2
	if 'mask_base' in locals(): del mask_base
	if 'blended_lap' in locals(): del blended_lap
	if 'blended_base' in locals(): del blended_base
	if 'expanded_prev' in locals(): del expanded_prev
	gc.collect()

	return blended_img

	# --- Stitching Function: Focus on the pairwise images ---
	def stitch_pairwise_images(img_composite, img_new,
	transform_model_str="Homography",
	blend_method="multi-band",
	enable_gain_compensation=True,
	orb_nfeatures=2000,
	match_ratio_thresh=0.75,
	ransac_reproj_thresh=5.0,
	max_distance_coeff=0.5,
	max_blending_width=10000,
	max_blending_height=10000,
	blend_smooth_ksize=15,
	num_blend_levels=4,
	fixed_layer_type="none" # _type: "none", "img1", "img2"
	):
	"""
	Stitches a new image (img_new) onto an existing composite image (img_composite)
	using an explicit, step-by-step pipeline (e.g., ORB features).
	Allows choosing the geometric transformation model.
	Returns the new composite.
	Now handles BGRA (4-channel) images to preserve transparency.
	"""
	log_message = log_and_print("--- Starting pairwise stitch between composite and new image (BGRA Mode) ---\n", "")
	start_time_pairwise = time.time()

	# --- Input Validation ---
	if img_composite is None or img_new is None:
	log_message = log_and_print("Error: One or both input images are None for the pairwise stitching step.\n", log_message)
	return None, log_message
	if img_composite.size == 0 or img_new.size == 0:
	log_message = log_and_print("Error: One or both input images are empty for the pairwise stitching step.\n", log_message)
	return None, log_message

	# --- Helper: Ensure 4-Channel BGRA ---
	def ensure_bgra(img):
	if img.ndim == 2: # Grayscale
	return cv2.cvtColor(img, cv2.COLOR_GRAY2BGRA)
	elif img.shape[2] == 3: # BGR
	return cv2.cvtColor(img, cv2.COLOR_BGR2BGRA)
	return img # Already BGRA

	# Convert inputs to BGRA
	img_composite = ensure_bgra(img_composite)
	img_new = ensure_bgra(img_new)

	h1, w1 = img_composite.shape[:2]
	h2, w2 = img_new.shape[:2]
	log_message = log_and_print(f"Pairwise Stitch: Img1({w1}x{h1}), Img2({w2}x{h2})\n", log_message)
	log_message = log_and_print(f"Params: Transform={transform_model_str}, ORB Feats={orb_nfeatures}, Ratio Thresh={match_ratio_thresh}\n", log_message)
	log_message = log_and_print(f"Params Cont'd: RANSAC Thresh={ransac_reproj_thresh}, Max Distance Coeff={max_distance_coeff}\n", log_message)
	log_message = log_and_print(f"Blending: Method={blend_method}, GainComp={enable_gain_compensation}, SmoothKSize={blend_smooth_ksize}, MB Levels={num_blend_levels}\n", log_message)

	final_output_img = None # Initialize result variable
	# Initialize other variables to None for better cleanup management
	img1_u8, img2_u8 = None, None
	kp1, des1, kp2, des2 = None, None, None, None
	all_matches, good_matches = None, None
	src_pts, dst_pts = None, None
	H_matrix_3x3_for_canvas = None # Will hold the 3x3 matrix for canvas calculation (Affine or Homography)
	final_warp_M = None # Will hold the actual 2x3 or 3x3 matrix for warping
	mask_trans = None # Mask from estimation function (homography or affine)
	pts1, dst_pts1_transformed = None, None
	pts2, all_pts = None, None
	output_img = None
	warped_img1_u8 = None
	mask_warped, mask_img2, overlap_mask = None, None, None
	gain_applied_warped_img1_u8 = None
	output_img_before_mb_float, blend_mask_float = None, None
	img1_for_blend, img2_for_blend = None, None
	is_affine = False # Flag to determine warp function

	try:
	# --- Feature Detection and Matching ---
	img1_u8 = img_composite.clip(0, 255).astype(np.uint8) if img_composite.dtype != np.uint8 else img_composite
	img2_u8 = img_new.clip(0, 255).astype(np.uint8) if img_new.dtype != np.uint8 else img_new

	# Use Grayscale for Feature Detection (ORB doesn't need Alpha)
	img1_gray = cv2.cvtColor(img1_u8, cv2.COLOR_BGRA2GRAY)
	img2_gray = cv2.cvtColor(img2_u8, cv2.COLOR_BGRA2GRAY)

	orb = cv2.ORB_create(nfeatures=orb_nfeatures)
	kp1, des1 = orb.detectAndCompute(img1_gray, None) # keypoints and descriptors
	kp2, des2 = orb.detectAndCompute(img2_gray, None)

	# Cleanup gray images used for detection
	del img1_gray, img2_gray
	gc.collect()

	if des1 is None or des2 is None or len(kp1) < 2 or len(kp2) < 2:
	log_message = log_and_print("Error: Not enough keypoints or descriptors found.\n", log_message)
	if 'kp1' in locals(): del kp1
	if 'des1' in locals(): del des1
	if 'kp2' in locals(): del kp2
	if 'des2' in locals(): del des2
	del img1_u8, img2_u8
	gc.collect()
	return None, log_message
	log_message = log_and_print(f"Found {len(kp1)} keypoints in Img1, {len(kp2)} in Img2.\n", log_message)

	bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=False)
	# Check if descriptors are suitable for knnMatch (should be if ORB)
	if des1.dtype != np.uint8:
	des1 = des1.astype(np.uint8)
	if des2.dtype != np.uint8:
	des2 = des2.astype(np.uint8)
	all_matches = bf.knnMatch(des1, des2, k=2)
	del des1, des2; des1, des2 = None, None # Explicit delete
	gc.collect()

	good_matches = []
	if all_matches is not None:
	MAX_DISTANCE = max_distance_coeff * np.sqrt(w12 + h12)
	# Filter out potential empty match pairs
	valid_matches = [pair for pair in all_matches if isinstance(pair, (list, tuple)) and len(pair) == 2]
	for m, n in valid_matches:
	if m.distance < match_ratio_thresh * n.distance:
	src_pt = np.array(kp1[m.queryIdx].pt)
	dst_pt = np.array(kp2[m.trainIdx].pt)
	distance = np.linalg.norm(dst_pt - src_pt)

	if distance < MAX_DISTANCE:
	good_matches.append(m)
	del valid_matches
	del all_matches; all_matches = None
	gc.collect()

	log_message = log_and_print(f"Found {len(good_matches)} good matches after ratio test.\n", log_message)
	MIN_MATCH_COUNT = 10 # Keep a minimum threshold

	# --- Transformation Estimation (Homography or Affine) ---
	if len(good_matches) >= MIN_MATCH_COUNT:
	src_pts = np.float32([ kp1[m.queryIdx].pt for m in good_matches ]).reshape(-1,1,2)
	dst_pts = np.float32([ kp2[m.trainIdx].pt for m in good_matches ]).reshape(-1,1,2)
	del kp1, kp2, good_matches; kp1, kp2, good_matches = None, None, None # Explicit delete
	gc.collect()

	estimation_failed = False
	# Try Affine if selected
	if transform_model_str == "Affine_Partial" or transform_model_str == "Affine_Full":
	is_affine = True # Assume success initially
	affine_matrix_2x3 = None
	mask_a = None
	try:
	if transform_model_str == "Affine_Partial":
	log_message = log_and_print(f"Attempting Affine Partial Estimation (RANSAC Thresh={ransac_reproj_thresh})...\n", log_message)
	affine_matrix_2x3, mask_a = cv2.estimateAffinePartial2D(src_pts, dst_pts, method=cv2.RANSAC, ransacReprojThreshold=ransac_reproj_thresh)
	else: # Affine_Full
	log_message = log_and_print(f"Attempting Affine Full Estimation (RANSAC Thresh={ransac_reproj_thresh})...\n", log_message)
	affine_matrix_2x3, mask_a = cv2.estimateAffine2D(src_pts, dst_pts, method=cv2.RANSAC, ransacReprojThreshold=ransac_reproj_thresh)

	if affine_matrix_2x3 is None:
	raise ValueError(f"{transform_model_str} estimation returned None")

	# Convert 2x3 affine to 3x3 for canvas calculation consistency
	H_matrix_3x3_for_canvas = np.vstack([affine_matrix_2x3, [0, 0, 1]]).astype(np.float64)
	final_warp_M = affine_matrix_2x3.astype(np.float64) # Keep 2x3 for warpAffine
	mask_trans = mask_a # Store the mask

	except Exception as e_affine:
	log_message = log_and_print(f"Error during {transform_model_str} estimation: {e_affine}. Falling back to Homography.\n", log_message)
	is_affine = False # Reset flag, will proceed to Homography block below
	estimation_failed = True # Mark that the chosen affine failed
	# Clean up affine specific vars if they exist
	if 'affine_matrix_2x3' in locals():
	del affine_matrix_2x3
	if 'mask_a' in locals():
	del mask_a
	H_matrix_3x3_for_canvas = None
	final_warp_M = None
	mask_trans = None
	# NOTE: We are choosing to fall back instead of returning None immediately.
	# If you prefer to fail hard if the selected affine fails, uncomment the next line:
	# return None, log_message

	# Try Homography if selected OR if Affine failed and we are falling back
	if not is_affine or estimation_failed: # If Homography was chosen or Affine failed
	if estimation_failed: # Log if we are falling back
	log_message = log_and_print("Falling back to Homography estimation...\n", log_message)
	else: # Log if Homography was the original choice
	log_message = log_and_print("Attempting Homography Estimation...\n", log_message)

	is_affine = False # Ensure flag is False for Homography path
	H_matrix_homog = None
	mask_h = None
	try:
	log_message = log_and_print(f"Estimating Homography (RANSAC Thresh={ransac_reproj_thresh})...\n", log_message)
	H_matrix_homog, mask_h = cv2.findHomography(src_pts, dst_pts, cv2.RANSAC, ransacReprojThreshold=ransac_reproj_thresh)
	if H_matrix_homog is None:
	raise ValueError("Homography estimation returned None")

	H_matrix_3x3_for_canvas = H_matrix_homog.astype(np.float64) # Use this for canvas calc
	final_warp_M = H_matrix_homog.astype(np.float64) # Use 3x3 for warpPerspective
	mask_trans = mask_h # Store the mask

	except Exception as e_homog:
	log_message = log_and_print(f"Error during Homography estimation: {e_homog}\n", log_message)
	# Clean up if Homography itself fails
	if 'H_matrix_homog' in locals():
	del H_matrix_homog
	if 'mask_h' in locals():
	del mask_h
	del src_pts, dst_pts
	gc.collect()
	return None, log_message # Fail if Homography (chosen or fallback) fails

	# --- Log Inliers from the successful estimation ---
	model_name = "Affine" if is_affine else "Homography"
	if mask_trans is not None:
	inlier_count = np.sum(mask_trans)
	log_message = log_and_print(f"{model_name} estimated with {inlier_count} inliers.\n", log_message)
	if inlier_count < MIN_MATCH_COUNT:
	log_message = log_and_print(f"Warning: Inlier count ({inlier_count}) < MIN_MATCH_COUNT for {model_name}. Result might be poor.\n", log_message)
	del mask_trans; mask_trans = None # Delete the mask now
	gc.collect()
	else:
	log_message = log_and_print(f"Warning: {model_name} mask was None.\n", log_message)


	# --- Cleanup source/destination points ---
	del src_pts, dst_pts; src_pts, dst_pts = None, None
	gc.collect()

	# --- Canvas Calculation and Warping ---
	pts1 = np.float32([[0,0],[0,h1-1],[w1-1,h1-1],[w1-1,0]]).reshape(-1,1,2)
	try:
	# Use the 3x3 matrix (derived from affine or directly from homography) for perspectiveTransform
	# Ensure it's float64
	if H_matrix_3x3_for_canvas.dtype != np.float64:
	H_matrix_3x3_for_canvas = H_matrix_3x3_for_canvas.astype(np.float64)
	dst_pts1_transformed = cv2.perspectiveTransform(pts1, H_matrix_3x3_for_canvas)
	if dst_pts1_transformed is None:
	raise ValueError("perspectiveTransform returned None")
	except Exception as e_tf:
	model_name_tf = "Affine-derived" if is_affine else "Homography"
	log_message = log_and_print(f"Error during perspectiveTransform (using {model_name_tf} 3x3 matrix): {e_tf}\n", log_message)
	# Clean up before returning
	del pts1
	if 'H_matrix_3x3_for_canvas' in locals(): del H_matrix_3x3_for_canvas
	if 'final_warp_M' in locals(): del final_warp_M # Was holding the warp matrix
	gc.collect()
	return None, log_message
	del pts1; pts1 = None

	pts2 = np.float32([[0,0],[0,h2-1],[w2-1,h2-1],[w2-1,0]]).reshape(-1,1,2)
	# Ensure dst_pts1_transformed is float32 for concatenation if needed
	all_pts = np.concatenate((pts2, dst_pts1_transformed.astype(np.float32)), axis=0)
	del pts2, dst_pts1_transformed; pts2, dst_pts1_transformed = None, None

	padding = 2
	x_min, y_min = np.int32(all_pts.min(axis=0).ravel() - padding)
	x_max, y_max = np.int32(all_pts.max(axis=0).ravel() + padding)
	del all_pts; all_pts = None
	gc.collect()

	translation_dist = [-x_min, -y_min]
	H_translation = np.array([[1, 0, translation_dist[0]], [0, 1, translation_dist[1]], [0,0,1]], dtype=np.float64)

	output_width = x_max - x_min
	output_height = y_max - y_min

	if output_width <= 0 or output_height <= 0 or output_width > max_blending_width or output_height > max_blending_height:
	log_message = log_and_print(f"Error: Invalid output dimensions ({output_width}x{output_height}). Max allowed ({max_blending_width}x{max_blending_height})\n", log_message)
	# Clean up before returning
	if 'H_matrix_3x3_for_canvas' in locals():
	del H_matrix_3x3_for_canvas
	if 'final_warp_M' in locals():
	del final_warp_M
	if 'H_translation' in locals():
	del H_translation
	gc.collect()
	return None, log_message

	log_message = log_and_print(f"Calculated canvas size: {output_width}x{output_height}\n", log_message)

	# --- Memory Check for Blending ---
	canvas_pixels = output_width * output_height
	# Define a threshold based on available memory, e.g., 250 million pixels
	# 1500015000 = 225M, 3000015000 = 450M
	pixel_threshold = 225_000_000
	effective_blend_method = blend_method

	if blend_method == "multi-band" and canvas_pixels > pixel_threshold:
	log_message = log_and_print(f"Warning: Canvas size ({output_width}x{output_height}, {canvas_pixels/1e6:.1f}M pixels) exceeds threshold ({pixel_threshold/1e6:.1f}M pixels) for multi-band blending.\n", log_message)
	log_message = log_and_print("Switching to 'Linear' blending for this step to conserve memory.\n", log_message)
	effective_blend_method = "linear"

	# Create output canvas - 4 Channels (BGRA)
	output_img = np.zeros((output_height, output_width, 4), dtype=np.uint8)

	# --- Calculate final transformation matrix for warping ---
	# This incorporates the translation onto the canvas
	final_warp_matrix_translated = None
	if is_affine:
	# We need the 2x3 matrix: (H_translation @ H_affine_3x3)[:2,:]
	final_warp_matrix_translated = (H_translation @ H_matrix_3x3_for_canvas)[:2, :]
	else:
	# We need the 3x3 matrix: H_translation @ H_homography_3x3
	final_warp_matrix_translated = H_translation @ H_matrix_3x3_for_canvas # H_matrix_3x3 holds the homography here

	# --- Warp img1 onto the canvas ---
	try:
	# Use borderValue=(0,0,0,0) for transparent borders
	if is_affine:
	log_message = log_and_print("Warping image 1 using warpAffine (BGRA)...\n", log_message)
	warped_img1_u8 = cv2.warpAffine(img1_u8, final_warp_matrix_translated, (output_width, output_height), flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=(0,0,0,0))
	else:
	log_message = log_and_print("Warping image 1 using warpPerspective (BGRA)...\n", log_message)
	warped_img1_u8 = cv2.warpPerspective(img1_u8, final_warp_matrix_translated, (output_width, output_height), flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=(0,0,0,0))
	except cv2.error as e_warp:
	warp_type = 'Affine' if is_affine else 'Perspective'
	log_message = log_and_print(f"Error during warping ({warp_type}): {e_warp}\n", log_message)
	# Clean up before returning
	if 'H_matrix_3x3_for_canvas' in locals():
	del H_matrix_3x3_for_canvas
	# final_warp_M was the matrix before translation
	if 'final_warp_matrix_translated' in locals():
	del final_warp_matrix_translated
	if 'H_translation' in locals():
	del H_translation
	if 'img1_u8' in locals():
	del img1_u8
	if 'output_img' in locals():
	del output_img
	gc.collect()
	return None, log_message

	# --- Clean up matrices and source image ---
	del H_matrix_3x3_for_canvas, H_translation, final_warp_matrix_translated, img1_u8
	# Note: final_warp_M (the untranslated matrix) is no longer needed
	if 'final_warp_M' in locals():
	del final_warp_M
	gc.collect()

	# Place img2 onto the canvas
	y_start, x_start = translation_dist[1], translation_dist[0]
	y_end, x_end = y_start + h2, x_start + w2

	# Define slicing for img2 read and canvas write, handling out-of-bounds placement
	img2_y_start, img2_x_start = 0, 0
	img2_y_end, img2_x_end = h2, w2
	canvas_y_start, canvas_x_start = y_start, x_start
	canvas_y_end, canvas_x_end = y_end, x_end
	# Clip coordinates
	if canvas_y_start < 0:
	img2_y_start = -canvas_y_start; canvas_y_start = 0
	if canvas_x_start < 0:
	img2_x_start = -canvas_x_start; canvas_x_start = 0
	if canvas_y_end > output_height:
	img2_y_end = h2 - (canvas_y_end - output_height); canvas_y_end = output_height
	if canvas_x_end > output_width:
	img2_x_end = w2 - (canvas_x_end - output_width); canvas_x_end = output_width

	# Check if the calculated slices are valid
	slice_h_canvas = canvas_y_end - canvas_y_start
	slice_w_canvas = canvas_x_end - canvas_x_start
	slice_h_img2 = img2_y_end - img2_y_start
	slice_w_img2 = img2_x_end - img2_x_start

	mask_img2 = np.zeros(output_img.shape[:2], dtype=np.uint8) # Mask for img2 placement
	img2_part = None
	if slice_h_canvas > 0 and slice_w_canvas > 0 and slice_h_canvas == slice_h_img2 and slice_w_canvas == slice_w_img2:
	img2_part = img2_u8[img2_y_start:img2_y_end, img2_x_start:img2_x_end]
	output_img[canvas_y_start:canvas_y_end, canvas_x_start:canvas_x_end] = img2_part
	# Mask based on Alpha channel of img2
	mask_img2[canvas_y_start:canvas_y_end, canvas_x_start:canvas_x_end] = (img2_part[:, :, 3] > 0).astype(np.uint8) * 255
	else:
	log_message = log_and_print("Warning: Could not place img2 correctly onto the canvas.\n", log_message)
	del img2_u8
	img2_u8 = None # Input img2 no longer needed
	gc.collect()

	# --- Create Masks for Blending ---
	# Create mask for the warped image 1 using Alpha Channel
	if warped_img1_u8 is not None:
	# Check alpha channel (index 3)
	mask_warped = (warped_img1_u8[:, :, 3] > 0).astype(np.uint8) * 255
	# Erode the warped mask slightly to remove semi-transparent edge artifacts
	# This removes the 1-pixel border caused by linear interpolation blending with transparency.
	erosion_kernel = np.ones((3, 3), np.uint8)
	mask_warped = cv2.erode(mask_warped, erosion_kernel, iterations=3)
	else:
	mask_warped = np.zeros(output_img.shape[:2], dtype=np.uint8) # Empty mask if warp failed

	# Find overlapping region mask (uint8 0 or 255)
	overlap_mask = cv2.bitwise_and(mask_warped, mask_img2)
	has_overlap = np.sum(overlap_mask > 0) > 0 # Check if any pixel > 0
	log_message = log_and_print(f"Overlap detected: {has_overlap}\n", log_message)

	# --- Gain Compensation ---
	gain = 1.0
	gain_applied_warped_img1_u8 = warped_img1_u8 # Initialize with original warped image

	if enable_gain_compensation and has_overlap and warped_img1_u8 is not None: # Need warped image for gain comp
	log_message = log_and_print("Gain Compensation Enabled. Calculating gain...\n", log_message)
	try:
	# --- Gain Calculation (Slice Logic for BGRA) ---
	# Convert BGRA to GRAY for calculation
	gray_warped_for_gain = cv2.cvtColor(warped_img1_u8, cv2.COLOR_BGRA2GRAY)
	img2_gray = np.zeros_like(gray_warped_for_gain)
	# Use the exact slice coordinates derived from placement step
	if slice_h_canvas > 0 and slice_w_canvas > 0:
	if 0 <= canvas_y_start < canvas_y_end <= output_height and \
	0 <= canvas_x_start < canvas_x_end <= output_width:
	# Slice from output_img (which is BGRA)
	img_to_convert = output_img[canvas_y_start:canvas_y_end, canvas_x_start:canvas_x_end]

	if img_to_convert.size > 0:
	# Convert Slice from BGRA to GRAY
	img2_part_gray = cv2.cvtColor(img_to_convert, cv2.COLOR_BGRA2GRAY)
	img2_gray[canvas_y_start:canvas_y_end, canvas_x_start:canvas_x_end] = img2_part_gray
	del img2_part_gray
	else:
	log_message = log_and_print("Warning: Empty slice for gain calculation img2_gray.\n", log_message)
	else:
	log_message = log_and_print("Warning: Invalid slice indices for gain calculation img2_gray.\n", log_message)

	overlap_mask_gain = overlap_mask # Use the already computed overlap mask
	# Ensure masks are single channel before bitwise_and

	gray_warped_roi = cv2.bitwise_and(gray_warped_for_gain, gray_warped_for_gain, mask=overlap_mask_gain)
	img2_roi = cv2.bitwise_and(img2_gray, img2_gray, mask=overlap_mask_gain)
	del gray_warped_for_gain, img2_gray

	overlap_pixel_count = np.sum(overlap_mask_gain > 0)
	if overlap_pixel_count > 0:
	# Ensure ROIs are valid before calculating sum
	mean1 = np.sum(gray_warped_roi[overlap_mask_gain > 0]) / overlap_pixel_count if gray_warped_roi is not None else 0
	mean2 = np.sum(img2_roi[overlap_mask_gain > 0]) / overlap_pixel_count if img2_roi is not None else 0

	if mean1 > 1e-5 and mean2 > 1e-5:
	if fixed_layer_type == "img1":
	# If the composite (Img1) is the base image, do not touch Img1, adjust Img2 instead
	# We need Img2's brightness to match Img1
	gain = mean1 / mean2
	log_message = log_and_print(f"Fixed Base (Img1): Adjusting Img2 brightness to match Base. Gain={gain:.2f}\n", log_message)
	else:
	gain = mean2 / mean1
	log_message = log_and_print(f"Calculated Gain: {gain:.2f}\n", log_message)
	gain = np.clip(gain, 0.5, 2.0) # Clamp gain
	log_message = log_and_print(f"Clamped Gain: {gain:.2f}\n", log_message)
	else:
	gain = 1.0
	log_message = log_and_print("Gain compensation skipped (means close to zero or invalid ROI).\n", log_message)
	else:
	gain = 1.0
	log_message = log_and_print("Gain compensation skipped (no overlap pixels).\n", log_message)
	del gray_warped_roi, img2_roi
	gc.collect()
	# --- End Gain Calculation ---

	# Apply gain ONLY if calculated and different from 1.0
	if abs(gain - 1.0) > 1e-5: # Check float difference
	if fixed_layer_type == "img1":
	# Directly modify the Img2 region in output_img (RGB channels only)
	# Note: output_img currently contains only Img2 pixels
	gain_applied_float = output_img.astype(np.float32)
	gain_applied_float[:, :, :3] *= gain

	output_img = np.clip(gain_applied_float, 0, 255).astype(np.uint8)
	gain_applied_warped_img1_u8 = warped_img1_u8
	else:
	gain_applied_float = warped_img1_u8.astype(np.float32)
	# Apply gain to RGB channels (0,1,2), Leave Alpha (3) untouched
	gain_applied_float[:, :, :3] *= gain

	# * Create new array for gain applied result *
	temp_gain_applied = gain_applied_float.clip(0, 255).astype(np.uint8)
	# If gain_applied_warped_img1_u8 wasn't the original, delete it before reassigning
	if gain_applied_warped_img1_u8 is not warped_img1_u8:
	del gain_applied_warped_img1_u8
	gain_applied_warped_img1_u8 = temp_gain_applied # Assign the new gain-applied image

	del gain_applied_float, temp_gain_applied
	gc.collect()
	log_message = log_and_print(f"Gain applied to warped image (RGB channels).\n", log_message)
	else:
	log_message = log_and_print("Gain is ~1.0, no gain applied.\n", log_message)

	except Exception as e_gain_calc:
	gain = 1.0
	log_message = log_and_print(f"Warning: Error during gain calculation ({e_gain_calc}). Setting gain=1.0.\n", log_message)
	# Ensure gain_applied remains the original warped image on error
	if gain_applied_warped_img1_u8 is not warped_img1_u8:
	del gain_applied_warped_img1_u8 # Delete potentially modified one
	gc.collect()
	gain_applied_warped_img1_u8 = warped_img1_u8 # Reset to original
	# Clean up potential partial variables
	if 'gray_warped_for_gain' in locals(): del gray_warped_for_gain
	if 'img2_gray' in locals(): del img2_gray
	if 'gray_warped_roi' in locals(): del gray_warped_roi
	if 'img2_roi' in locals(): del img2_roi
	if 'gain_applied_float' in locals(): del gain_applied_float
	gc.collect()
	elif warped_img1_u8 is None:
	log_message = log_and_print("Skipping Gain Compensation as warped image is None.\n", log_message)

	# Ensure gain_applied_warped_img1_u8 holds the image to be used for blending
	# (either original warped or gain-compensated version)

	# --- Blending Choice ---
	# Blend using the potentially gain-compensated image: gain_applied_warped_img1_u8
	if effective_blend_method == "multi-band" and has_overlap and gain_applied_warped_img1_u8 is not None:
	log_message = log_and_print(f"Applying Multi-band blending (Levels={num_blend_levels})...\n", log_message)
	try:
	# --- Generate Blend Mask using Distance Transform ---
	log_message = log_and_print("Generating multi-band mask using distance transform...\n", log_message)

	# Distance Transform needs single channel mask
	# masks are already single channel uint8

	dist1 = cv2.distanceTransform(mask_warped, cv2.DIST_L2, 5)
	dist2 = cv2.distanceTransform(mask_img2, cv2.DIST_L2, 5)

	# Create float32 weight mask
	weight1_norm = np.zeros(output_img.shape[:2], dtype=np.float32)

	# Identify non-overlapping regions (ensure using single channel masks)
	non_overlap_mask1 = cv2.bitwise_and(mask_warped, cv2.bitwise_not(overlap_mask))
	non_overlap_mask2 = cv2.bitwise_and(mask_img2, cv2.bitwise_not(overlap_mask))

	# Assign weights: 1.0 where only img1 exists, 0.0 where only img2 exists
	weight1_norm[non_overlap_mask1 > 0] = 1.0
	weight1_norm[non_overlap_mask2 > 0] = 0.0 # Implicitly 0 initially, but good to be explicit

	# Calculate weights in the overlap region based on relative distance
	# Weight for img1 = dist1 / (dist1 + dist2)
	overlap_indices = np.where(overlap_mask > 0)
	num_overlap_pixels = len(overlap_indices[0])
	if num_overlap_pixels > 0:
	d1_overlap = dist1[overlap_indices]
	d2_overlap = dist2[overlap_indices]
	total_dist = d1_overlap + d2_overlap
	# Avoid division by zero where total_dist is very small (deep inside both masks)
	# If total_dist is near zero, assign weight based on which original mask was stronger?
	# Using dist1 / (total_dist + epsilon) is simpler and generally works.
	weights_overlap = d1_overlap / (total_dist + 1e-7) # Epsilon for stability
	weight1_norm[overlap_indices] = np.clip(weights_overlap, 0.0, 1.0)
	log_message = log_and_print(f"Calculated distance transform weights for {num_overlap_pixels} overlap pixels.\n", log_message)
	# If a base image is specified, we force the overlap area to fully show the "top" layer (weight 0 or 1)
	# This solves the "semi-transparent/ghosting" issue
	if fixed_layer_type == "img2":
	# Img2 is Base, Img1 is Top -> Show Img1 (Weight 1.0)
	weight1_norm[overlap_indices] = 1.0
	elif fixed_layer_type == "img1":
	# Img1 is Base, Img2 is Top -> Show Img2 (Weight 0.0)
	weight1_norm[overlap_indices] = 0.0
	else:
	log_message = log_and_print("Warning: No overlap pixels found for distance transform weight calculation.\n", log_message)

	# Create boolean masks for later restoration steps
	mask_warped_binary = (mask_warped > 0)
	mask_img2_binary = (mask_img2 > 0)
	overlap_mask_binary = (overlap_mask > 0)

	# Clean up intermediate arrays from distance transform step
	del dist1, dist2, non_overlap_mask1, non_overlap_mask2, overlap_indices
	if 'd1_overlap' in locals():
	del d1_overlap
	if 'd2_overlap' in locals():
	del d2_overlap
	if 'total_dist' in locals():
	del total_dist
	if 'weights_overlap' in locals():
	del weights_overlap
	gc.collect()

	# Apply Smoothing based on blend_smooth_ksize
	blend_mask_float = weight1_norm # Start with the precise distance-based mask
	if blend_smooth_ksize > 0 and blend_smooth_ksize % 2 == 1:
	log_message = log_and_print(f"Smoothing multi-band blend mask with GaussianBlur ksize=({blend_smooth_ksize},{blend_smooth_ksize})...\n", log_message)
	try:
	# Need the boolean masks calculated above

	# Strict non-overlap areas (boolean arrays)
	strict_non_overlap_mask1 = np.logical_and(mask_warped_binary, np.logical_not(overlap_mask_binary))
	strict_non_overlap_mask2 = np.logical_and(mask_img2_binary, np.logical_not(overlap_mask_binary))


	# Blur the original distance-based mask
	weight1_norm_blurred = cv2.GaussianBlur(weight1_norm, (blend_smooth_ksize, blend_smooth_ksize), 0)

	# Clip the blurred mask to [0, 1]
	blend_mask_float_blurred = np.clip(weight1_norm_blurred, 0.0, 1.0)

	# Assign the potentially blurred values first
	blend_mask_float = blend_mask_float_blurred

	# Force 1.0 where only img1 should be
	blend_mask_float[strict_non_overlap_mask1] = 1.0
	# Force 0.0 where only img2 should be
	blend_mask_float[strict_non_overlap_mask2] = 0.0

	log_message = log_and_print("Multi-band mask smoothed and edges restored.\n", log_message)

	except Exception as e_blur_other:
	log_message = log_and_print(f"Warning: Error during multi-band mask blur/restore ({e_blur_other}). Using original distance-based mask.\n", log_message)
	blend_mask_float = weight1_norm # Fallback
	finally:
	# Clean up intermediate variables created in this block
	if 'strict_non_overlap_mask1' in locals(): del strict_non_overlap_mask1
	if 'strict_non_overlap_mask2' in locals(): del strict_non_overlap_mask2
	if 'weight1_norm_blurred' in locals(): del weight1_norm_blurred
	if 'blend_mask_float_blurred' in locals(): del blend_mask_float_blurred
	gc.collect()
	else:
	log_message = log_and_print("Skipping multi-band mask smoothing (ksize not positive odd integer).\n", log_message)
	# blend_mask_float is already weight1_norm (the precise one)
	# --- End Smoothing ---

	# --- Prepare for Blending ---
	img1_for_blend = gain_applied_warped_img1_u8.astype(np.float32)
	# Store the state of output_img BEFORE multi-band blending
	output_img_before_mb_float = output_img.astype(np.float32)
	img2_for_blend = output_img_before_mb_float # Use the float version

	# --- Call Multi-Band Blending ---
	# Note: Ensure multi_band_blending supports 4-channel images.
	blended_result_uint8 = multi_band_blending(
	img1_for_blend,
	img2_for_blend,
	blend_mask_float, # The prepared mask
	num_levels=num_blend_levels
	)

	# --- Restore Non-Overlap Regions ---
	log_message = log_and_print("Restoring non-overlap regions after multi-band blending...\n", log_message)

	# Re-identify strict non-overlap boolean masks (using the ones calculated earlier)
	strict_non_overlap_mask1 = np.logical_and(mask_warped_binary, np.logical_not(overlap_mask_binary))
	strict_non_overlap_mask2 = np.logical_and(mask_img2_binary, np.logical_not(overlap_mask_binary))

	# Convert blended result to float for modification
	output_img_float = blended_result_uint8.astype(np.float32)

	# Copy original pixels back into the non-overlap regions
	# For img1's non-overlap region, use the (potentially gain compensated) warped img1
	output_img_float[strict_non_overlap_mask1] = img1_for_blend[strict_non_overlap_mask1]

	# For img2's non-overlap region, use the pixels from before blending
	output_img_float[strict_non_overlap_mask2] = output_img_before_mb_float[strict_non_overlap_mask2]

	# Convert back to uint8 for the final result for this step
	output_img = np.clip(output_img_float, 0, 255).astype(np.uint8)
	log_message = log_and_print("Non-overlap regions restored.\n", log_message)

	# Apply final exterior mask (keep pure transparency clean)
	combined_mask_binary = np.logical_or(mask_warped_binary, mask_img2_binary)
	output_img[~combined_mask_binary] = 0 # Apply the sharp combined mask
	log_message = log_and_print("Applied final exterior mask.\n", log_message)

	# Cleanup
	del img1_for_blend, img2_for_blend, output_img_before_mb_float, blend_mask_float
	del blended_result_uint8, output_img_float
	del mask_warped_binary, mask_img2_binary, overlap_mask_binary
	del strict_non_overlap_mask1, strict_non_overlap_mask2
	if 'combined_mask_binary' in locals():
	del combined_mask_binary
	if 'weight1_norm' in locals():
	del weight1_norm
	gc.collect()
	log_message = log_and_print(f"Multi-band blending with restoration successful.\n", log_message)

	except Exception as e_blend:
	log_message = log_and_print(f"Error during multi-band blending/restoration: {e_blend}. Falling back to simple overlay.\n{traceback.format_exc()}\n", log_message)
	# Fallback: Use copyTo with 4-channel support (mask needs to be 1 channel or 4 channels)
	# mask_warped is single channel uint8, works with 4-channel image in copyTo
	output_img = cv2.copyTo(gain_applied_warped_img1_u8, mask_warped, output_img)

	# Ensure cleanup if error happened mid-process
	if 'img1_for_blend' in locals():
	del img1_for_blend
	if 'img2_for_blend' in locals():
	del img2_for_blend
	if 'output_img_before_mb_float' in locals():
	del output_img_before_mb_float
	if 'blend_mask_float' in locals():
	del blend_mask_float
	if 'blended_result_uint8' in locals():
	del blended_result_uint8
	if 'mask_warped_binary' in locals():
	del mask_warped_binary # Clean up boolean masks too
	if 'mask_img2_binary' in locals():
	del mask_img2_binary
	if 'overlap_mask_binary' in locals():
	del overlap_mask_binary
	gc.collect()


	# Linear Blending
	elif effective_blend_method == "linear" and has_overlap and gain_applied_warped_img1_u8 is not None:
	log_message = log_and_print("Applying Linear blending...\n", log_message)
	# Ensure overlap_mask is single channel for findContours
	contours, _ = cv2.findContours(overlap_mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
	if not contours:
	log_message = log_and_print("Warning: No contours in overlap. Using simple overlay.\n", log_message)
	output_img = cv2.copyTo(gain_applied_warped_img1_u8, mask_warped, output_img)
	else:
	main_contour = max(contours, key=cv2.contourArea)
	x_overlap, y_overlap, w_overlap, h_overlap = cv2.boundingRect(main_contour)
	# Clip bounding box to canvas dimensions
	x_overlap = max(0, x_overlap); y_overlap = max(0, y_overlap)
	w_overlap = min(w_overlap, output_width - x_overlap); h_overlap = min(h_overlap, output_height - y_overlap)

	if w_overlap <= 0 or h_overlap <= 0:
	log_message = log_and_print("Warning: Invalid overlap bounding box after clipping. Using simple overlay.\n", log_message)
	output_img = cv2.copyTo(gain_applied_warped_img1_u8, mask_warped, output_img)
	else:
	# Create weight maps (float32)
	weight1 = np.zeros(output_img.shape[:2], dtype=np.float32)
	weight2 = np.zeros(output_img.shape[:2], dtype=np.float32)

	# Generate gradient for the overlap box
	gradient = None
	blend_axis = 0 if w_overlap >= h_overlap else 1
	if blend_axis == 0: # Horizontal blend
	gradient = np.tile(np.linspace(1.0, 0.0, w_overlap, dtype=np.float32), (h_overlap, 1))
	else: # Vertical blend
	gradient = np.tile(np.linspace(1.0, 0.0, h_overlap, dtype=np.float32).reshape(-1, 1), (1, w_overlap))

	weight1_region = gradient
	weight2_region = 1.0 - gradient

	overlap_region_mask = overlap_mask[y_overlap : y_overlap + h_overlap, x_overlap : x_overlap + w_overlap]

	# Apply weights only where the overlap mask is valid within the bounding box
	valid_overlap = overlap_region_mask > 0
	weight1[y_overlap : y_overlap + h_overlap, x_overlap : x_overlap + w_overlap][valid_overlap] = weight1_region[valid_overlap]
	weight2[y_overlap : y_overlap + h_overlap, x_overlap : x_overlap + w_overlap][valid_overlap] = weight2_region[valid_overlap]
	del weight1_region, weight2_region, gradient, valid_overlap, overlap_region_mask
	gc.collect()

	# Assign weights for non-overlapping regions (ensure masks are single channel)
	non_overlap_mask1 = cv2.bitwise_and(mask_warped, cv2.bitwise_not(overlap_mask))
	weight1[non_overlap_mask1 > 0] = 1.0
	non_overlap_mask2 = cv2.bitwise_and(mask_img2, cv2.bitwise_not(overlap_mask))
	weight2[non_overlap_mask2 > 0] = 1.0

	# Normalize weights before potential smoothing
	total_weight = weight1 + weight2 + 1e-6 # Add epsilon
	weight1_norm = weight1 / total_weight
	weight2_norm = weight2 / total_weight
	del weight1, weight2, total_weight
	gc.collect()

	# Apply Smoothing based on blend_smooth_ksize
	if blend_smooth_ksize > 0 and blend_smooth_ksize % 2 == 1:
	log_message = log_and_print(f"Smoothing linear blend weights with GaussianBlur ksize=({blend_smooth_ksize},{blend_smooth_ksize})...\n", log_message)
	try:
	# Identify the actual blending area (where both weights contribute meaningfully and overlap exists)
	overlap_area_mask_bool = (weight1_norm > 1e-6) & (weight2_norm > 1e-6) & (overlap_mask > 0)

	smoothed_w1 = cv2.GaussianBlur(weight1_norm, (blend_smooth_ksize, blend_smooth_ksize), 0)
	smoothed_w2 = cv2.GaussianBlur(weight2_norm, (blend_smooth_ksize, blend_smooth_ksize), 0)

	# Renormalize smoothed weights ONLY in the overlap area
	total_smoothed_weight = smoothed_w1 + smoothed_w2 + 1e-6
	# Use temporary arrays to avoid modifying originals during calculation if needed
	temp_w1 = weight1_norm.copy() # Work on copies
	temp_w2 = weight2_norm.copy()
	temp_w1[overlap_area_mask_bool] = (smoothed_w1 / total_smoothed_weight)[overlap_area_mask_bool]
	temp_w2[overlap_area_mask_bool] = (smoothed_w2 / total_smoothed_weight)[overlap_area_mask_bool]

	# Restore strict 1.0 / 0.0 weights in non-overlap areas
	temp_w1[ non_overlap_mask1 > 0 ] = 1.0
	temp_w1[ non_overlap_mask2 > 0 ] = 0.0
	temp_w2[ non_overlap_mask1 > 0 ] = 0.0
	temp_w2[ non_overlap_mask2 > 0 ] = 1.0

	# Assign back to the working variables
	weight1_norm = temp_w1
	weight2_norm = temp_w2

	del smoothed_w1, smoothed_w2, total_smoothed_weight, overlap_area_mask_bool, temp_w1, temp_w2
	gc.collect()
	log_message = log_and_print("Linear weights smoothed and renormalized.\n", log_message)
	except Exception as e_blur_other:
	log_message = log_and_print(f"Warning: Error during linear weight smoothing ({e_blur_other}). Using original weights.\n", log_message)
	finally:
	# Ensure cleanup of temp vars in this block
	if 'smoothed_w1' in locals():
	del smoothed_w1
	if 'smoothed_w2' in locals():
	del smoothed_w2
	if 'total_smoothed_weight' in locals():
	del total_smoothed_weight
	if 'overlap_area_mask_bool' in locals():
	del overlap_area_mask_bool
	if 'temp_w1' in locals():
	del temp_w1
	if 'temp_w2' in locals():
	del temp_w2
	gc.collect()
	else:
	log_message = log_and_print("Skipping linear weight smoothing (ksize not positive odd integer).\n", log_message)
	# --- End Smoothing ---

	# Blend using potentially smoothed and renormalized weights
	# Identify regions: where img1 only, img2 only, and blend region
	non_overlap_mask1_bool = (non_overlap_mask1 > 0)
	non_overlap_mask2_bool = (non_overlap_mask2 > 0)
	blend_mask_bool = np.logical_not(np.logical_or(non_overlap_mask1_bool, non_overlap_mask2_bool)) & (overlap_mask > 0)

	# Copy non-overlapping part of image 1 directly where its weight is 1
	output_img[non_overlap_mask1_bool] = gain_applied_warped_img1_u8[non_overlap_mask1_bool]

	# Non-overlapping part of image 2 is already in output_img from the initial placement

	# Blend the overlapping/transition areas
	blend_indices = np.where(blend_mask_bool)
	num_blend_pixels = len(blend_indices[0])

	if num_blend_pixels > 0:
	log_message = log_and_print(f"Blending {num_blend_pixels} pixels linearly...\n", log_message)
	try:
	# Ensure images are float32 for blending calculation
	img1_blend_float = gain_applied_warped_img1_u8[blend_indices].astype(np.float32)
	img2_blend_float = output_img[blend_indices].astype(np.float32) # Pixels already placed from img2

	# Get weights for the blend region and broadcast for element-wise multiplication
	w1_blend_1d = weight1_norm[blend_indices]
	w2_blend_1d = weight2_norm[blend_indices]
	# Add new axis for broadcasting: (N,) -> (N, 1) to multiply with (N, 3) pixel data
	w1_blend_broadcast = w1_blend_1d[:, np.newaxis]
	w2_blend_broadcast = w2_blend_1d[:, np.newaxis]

	# Perform the weighted sum
	blended_float = w1_blend_broadcast * img1_blend_float + w2_blend_broadcast * img2_blend_float
	blended_uint8 = blended_float.clip(0, 255).astype(np.uint8)

	# Place the blended result back into the output image
	output_img[blend_indices] = blended_uint8

	del img1_blend_float, img2_blend_float, w1_blend_1d, w2_blend_1d
	del w1_blend_broadcast, w2_blend_broadcast, blended_float, blended_uint8
	gc.collect()
	log_message = log_and_print("Linear blending successful.\n", log_message)

	except Exception as e_blend_lin:
	log_message = log_and_print(f"Warning: Error during float blending ({e_blend_lin}). Using simple overlay for blend region.\n", log_message)
	blend_mask_uint8 = blend_mask_bool.astype(np.uint8) * 255
	if np.any(blend_mask_uint8):
	output_img = cv2.copyTo(gain_applied_warped_img1_u8, blend_mask_uint8, output_img)
	del blend_mask_uint8
	gc.collect()
	else:
	log_message = log_and_print("Note: Linear blend mask was empty, skipping float blend step.\n", log_message)

	# Clean up linear blending specific variables
	del weight1_norm, weight2_norm, blend_mask_bool
	del non_overlap_mask1, non_overlap_mask2, non_overlap_mask1_bool, non_overlap_mask2_bool
	if 'blend_indices' in locals():
	del blend_indices
	gc.collect()

	# Clean up contour variables regardless of path taken inside linear blend
	if 'contours' in locals():
	del contours
	if 'main_contour' in locals():
	del main_contour
	gc.collect()

	# Simple overlay if no blending applied or specified OR if warped image was None
	elif not has_overlap or effective_blend_method not in ["linear", "multi-band"] or gain_applied_warped_img1_u8 is None:
	if gain_applied_warped_img1_u8 is None:
	log_message = log_and_print("Warped image was None. Performing simple overlay (only showing img2).\n", log_message)
	# In this case, output_img already contains img2 where it should be, and black elsewhere.
	# No copyTo needed, as there's nothing to copy from.
	elif not has_overlap:
	log_message = log_and_print("No overlap. Performing simple overlay.\n", log_message)
	else:
	log_message = log_and_print(f"Blending method '{effective_blend_method}' or overlap condition not met. Performing simple overlay.\n", log_message)

	if gain_applied_warped_img1_u8 is not None: # Only copy if we have something to copy
	# No blend or no overlap: Simple Overlay
	# Decide who covers whom based on Z-order
	# output_img already has Img2
	if fixed_layer_type == "img2":
	# Img2 is base, Img1 covers it
	output_img = cv2.copyTo(gain_applied_warped_img1_u8, mask_warped, output_img)
	else:
	# Img1 is base, Img2 covers it
	# output_img already has Img2, we just need to fill in where Img1 is not covered by Img2
	# Or place Img1 first, then Img2
	output_img = cv2.copyTo(output_img, mask_img2, gain_applied_warped_img1_u8)

	# --- Final Result Assignment ---
	final_output_img = output_img # Assign the final blended/overlaid image

	end_time_pairwise = time.time()
	log_message = log_and_print(f"Pairwise stitching finished. Time: {end_time_pairwise - start_time_pairwise:.2f}s\n", log_message)

	else: # Not enough good matches
	log_message = log_and_print(f"Error: Not enough good matches ({len(good_matches)} < {MIN_MATCH_COUNT}).\n", log_message)
	# Minimal cleanup needed here, mostly handled in finally block
	if 'kp1' in locals():
	del kp1
	if 'kp2' in locals():
	del kp2
	if 'good_matches' in locals():
	del good_matches

	except Exception as e:
	log_message = log_and_print(f"Error during pairwise stitching: {e}\n{traceback.format_exc()}\n", log_message)
	final_output_img = None # Ensure None is returned on error

	finally:
	# --- Comprehensive Cleanup ---
	# Delete variables in roughly reverse order of creation / dependency
	# Blend-specific intermediates
	if 'img1_for_blend' in locals():
	del img1_for_blend
	if 'img2_for_blend' in locals():
	del img2_for_blend
	if 'output_img_before_mb_float' in locals():
	del output_img_before_mb_float
	if 'blend_mask_float' in locals():
	del blend_mask_float
	if 'weight1_norm' in locals():
	del weight1_norm # From mask gen (MB or Linear)
	if 'weight2_norm' in locals():
	del weight2_norm # From Linear mask gen
	# ... other linear/MB intermediate vars ...

	# Gain/Warp intermediates
	if 'gain_applied_warped_img1_u8' in locals() and gain_applied_warped_img1_u8 is not None:
	# Only delete if it's a separate copy from warped_img1_u8
	if 'warped_img1_u8' in locals() and warped_img1_u8 is not None and gain_applied_warped_img1_u8 is not warped_img1_u8:
	del gain_applied_warped_img1_u8
	# else it points to warped_img1_u8 or warped_img1_u8 is None/deleted already

	if 'warped_img1_u8' in locals() and warped_img1_u8 is not None:
	del warped_img1_u8
	if 'mask_warped' in locals():
	del mask_warped
	if 'mask_img2' in locals():
	del mask_img2
	if 'overlap_mask' in locals():
	del overlap_mask
	if 'img2_part' in locals():
	del img2_part # From placing img2

	if 'output_img' in locals() and output_img is not None and output_img is not final_output_img:
	# Delete intermediate output_img if it wasn't the final result (e.g., error occurred)
	del output_img

	# Transformation matrices and points
	if 'H_matrix_3x3_for_canvas' in locals():
	del H_matrix_3x3_for_canvas
	if 'final_warp_M' in locals():
	del final_warp_M
	if 'mask_trans' in locals():
	del mask_trans
	if 'src_pts' in locals():
	del src_pts
	if 'dst_pts' in locals():
	del dst_pts

	# Feature matching intermediates
	if 'kp1' in locals():
	del kp1
	if 'kp2' in locals():
	del kp2
	if 'des1' in locals():
	del des1
	if 'des2' in locals():
	del des2
	if 'good_matches' in locals():
	del good_matches
	if 'all_matches' in locals():
	del all_matches

	# Initial uint8 images
	if 'img1_u8' in locals():
	del img1_u8
	if 'img2_u8' in locals():
	del img2_u8

	gc.collect()

	return final_output_img, log_message

	# --- Function for N-Image Stitching (Primarily for Image List Input) ---
	def stitch_multiple_images(images, # List of NumPy images (BGR/BGRA, potentially pre-cropped)
	use_transparency=True,
	stitcher_mode_str="SCANS",
	registration_resol=0.6,
	seam_estimation_resol=0.1,
	compositing_resol=-1.0, # Use -1.0 for default/auto
	wave_correction=False,
	exposure_comp_type_str="GAIN_BLOCKS",
	enable_cropping=True, # This is for POST-stitch cropping
	strict_no_black_edges=False,
	# Pairwise/Fallback specific params
	transform_model_str="Homography",
	blend_method="multi-band",
	enable_gain_compensation=True,
	orb_nfeatures=2000,
	match_ratio_thresh=0.75,
	ransac_reproj_thresh=5.0,
	max_distance_coeff=0.5,
	max_blending_width=10000,
	max_blending_height=10000,
	blend_smooth_ksize=15,
	num_blend_levels=4,
	fixed_base_image_index=-1,
	):
	"""
	Stitches a list of images. Tries cv2.Stitcher first (unless 'DIRECT_PAIRWISE'),
	otherwise falls back to manual pairwise stitching.
	Returns ONE stitched image (RGB/RGBA) and log.
	Input images should be in BGR or BGRA format (already potentially cropped by caller).
	Output is RGBA. The 'enable_cropping' param here refers to final black border cropping.
	If use_transparency is False, the final output will be RGB (opaque background).
	"""
	log = log_and_print(f"--- Starting Stitching Process for {len(images)} Provided Images ---\n", "")
	total_start_time = time.time()
	stitched_img_rgba = None # Initialize result

	if len(images) < 2:
	log = log_and_print("Error: Need at least two images to stitch.\n", log)
	return None, log

	# Check if any input image is None or empty after potential pre-cropping
	valid_images = []
	for i, img in enumerate(images):
	if img is None or img.size == 0:
	log = log_and_print(f"Warning: Input image at index {i} is invalid (None or empty). Skipping it.\n", log)
	else:
	valid_images.append(img)

	if len(valid_images) < 2:
	log = log_and_print(f"Error: Not enough valid images ({len(valid_images)}) left after checking. Cannot stitch.\n", log)
	del images, valid_images # Clean up
	gc.collect()
	return None, log

	images = valid_images # Use the filtered list
	log = log_and_print(f"Proceeding with {len(images)} valid images.\n", log)
	log = log_and_print(f"Selected Stitcher Mode: {stitcher_mode_str}\n", log)

	# Log the pairwise transform model choice, relevant if fallback or DIRECT_PAIRWISE
	if stitcher_mode_str == "DIRECT_PAIRWISE":
	log = log_and_print(f"Using Pairwise Transform Model: {transform_model_str}\n", log)
	log = log_and_print(f"Pairwise Params: RANSAC Thresh={ransac_reproj_thresh}, Max Dist Coeff={max_distance_coeff}\n", log)
	else:
	log = log_and_print(f"Pairwise Transform Model (for fallback): {transform_model_str}\n", log)
	log = log_and_print(f"Fallback Pairwise Params: RANSAC Thresh={ransac_reproj_thresh}, Max Dist Coeff={max_distance_coeff}\n", log)
	log = log_and_print(f"Post-Crop: Enable={enable_cropping}, Strict Edges={strict_no_black_edges}\n", log) # Log new param

	skip_cv2_stitcher = (stitcher_mode_str == "DIRECT_PAIRWISE")

	stitched_img_bgra = None
	stitcher_success = False

	# 1. Try using cv2.Stitcher (unless skipped)
	if not skip_cv2_stitcher:
	log = log_and_print("\nAttempting stitching with built-in cv2.Stitcher...\n", log)
	# ... [Existing cv2.Stitcher setup code omitted for brevity, logic remains same] ...
	# Note: cv2.Stitcher usually outputs BGR (3 channels), removing alpha.
	# If transparency is critical, DIRECT_PAIRWISE is preferred.

	# Map string parameters to OpenCV constants for cv2.Stitcher modes
	stitcher_mode_map = {"PANORAMA": cv2.Stitcher_PANORAMA, "SCANS": cv2.Stitcher_SCANS}
	# Default to SCANS if invalid string for cv2.Stitcher mode itself
	cv2_stitcher_mode_enum = stitcher_mode_map.get(stitcher_mode_str, cv2.Stitcher_SCANS)
	log = log_and_print(f"Using OpenCV Stitcher Mode Enum: {cv2_stitcher_mode_enum} (from string: {stitcher_mode_str})\n", log)

	exposure_comp_map = {
	"NO": cv2.detail.ExposureCompensator_NO,
	"GAIN": cv2.detail.ExposureCompensator_GAIN,
	"GAIN_BLOCKS": cv2.detail.ExposureCompensator_GAIN_BLOCKS
	}
	exposure_comp_type = exposure_comp_map.get(exposure_comp_type_str, cv2.detail.ExposureCompensator_GAIN_BLOCKS)
	log = log_and_print(f"Using Exposure Compensation: {exposure_comp_type_str}\n", log)
	log = log_and_print(f"Wave Correction Enabled: {wave_correction}\n", log)

	stitcher = None # Initialize stitcher object variable
	try:
	stitcher = cv2.Stitcher.create(cv2_stitcher_mode_enum)
	if stitcher is None:
	raise RuntimeError("cv2.Stitcher.create returned None.")

	log = log_and_print(f"Setting Stitcher resolutions: Reg={registration_resol:.2f}, Seam={seam_estimation_resol:.2f}, Comp={compositing_resol:.2f}\n", log)
	try:
	if hasattr(stitcher, 'setRegistrationResol'):
	stitcher.setRegistrationResol(float(registration_resol))
	if hasattr(stitcher, 'setSeamEstimationResol'):
	stitcher.setSeamEstimationResol(float(seam_estimation_resol))
	if hasattr(stitcher, 'setCompositingResol'):
	stitcher.setCompositingResol(float(compositing_resol))
	except Exception as e_res:
	log = log_and_print(f"Warning: Could not set stitcher resolutions: {e_res}\n", log)

	try:
	if hasattr(stitcher, 'setWaveCorrection'):
	stitcher.setWaveCorrection(wave_correction)
	except Exception as e_wave:
	log = log_and_print(f"Warning: Could not set wave correction: {e_wave}\n", log)

	try:
	if hasattr(stitcher, 'setExposureCompensator'):
	compensator = cv2.detail.ExposureCompensator_createDefault(exposure_comp_type)
	stitcher.setExposureCompensator(compensator)
	del compensator # Release compensator object reference
	except Exception as e_exp:
	log = log_and_print(f"Warning: Could not set exposure compensator: {e_exp}\n", log)

	# Note: cv2.Stitcher might strip alpha here.
	# Ensure all images are uint8 before passing to stitcher
	images_uint8 = []
	for img in images:
	if img.dtype != np.uint8:
	images_uint8.append(img.clip(0, 255).astype(np.uint8))
	else:
	images_uint8.append(img)

	status = cv2.Stitcher_ERR_NEED_MORE_IMGS # Initialize status to a known failure code
	stitched_img_raw = None

	try:
	log = log_and_print("Executing stitcher.stitch()...\n", log)
	status, stitched_img_raw = stitcher.stitch(images_uint8) # Input 'images' should be BGR uint8
	log = log_and_print(f"stitcher.stitch() returned status: {status}\n", log) # Log the status code

	except cv2.error as e_stitch:
	log = log_and_print(f"OpenCV Error occurred DURING stitcher.stitch() call: {e_stitch}\n", log)
	log = log_and_print(f"Traceback:\n{traceback.format_exc()}\n", log)
	log = log_and_print("Falling back to manual pairwise stitching method due to stitch() error.\n", log)
	status = -99 # Set status to a custom failure code to ensure fallback
	stitched_img_raw = None
	except Exception as e_stitch_other:
	log = log_and_print(f"Unexpected Error occurred DURING stitcher.stitch() call: {e_stitch_other}\n", log)
	log = log_and_print(f"Traceback:\n{traceback.format_exc()}\n", log)
	log = log_and_print("Falling back to manual pairwise stitching method due to unexpected stitch() error.\n", log)
	status = -100 # Set status to a custom failure code
	stitched_img_raw = None
	finally:
	del images_uint8
	gc.collect()

	if status == cv2.Stitcher_OK:
	log = log_and_print("cv2.Stitcher successful!\n", log)
	if stitched_img_raw is not None and stitched_img_raw.size > 0:
	log = log_and_print(f"Stitcher output dimensions (raw): {stitched_img_raw.shape}\n", log)
	# Apply FINAL black border cropping if enabled
	cropped_result = crop_black_borders(stitched_img_raw, enable_cropping, strict_no_black_edges)
	if cropped_result is not None and cropped_result.size > 0 :
	stitched_img_bgra = cropped_result
	log = log_and_print(f"Final dimensions after POST-stitch cropping: {stitched_img_bgra.shape}\n", log)
	else:
	stitched_img_bgra = stitched_img_raw
	log = log_and_print("POST-stitch cropping failed or disabled, using raw stitcher output.\n", log)
	stitcher_success = True
	del stitched_img_raw
	if 'cropped_result' in locals() and cropped_result is not stitched_img_bgra:
	del cropped_result
	gc.collect()
	else:
	log = log_and_print("Error: cv2.Stitcher returned status OK but the image is empty.\n", log)
	else:
	error_codes = { getattr(cv2, k): k for k in dir(cv2) if k.startswith('Stitcher_ERR_') }
	error_codes[-99] = "ERR_STITCH_CV_ERROR"
	error_codes[-100] = "ERR_STITCH_EXCEPTION"
	# Check if fallback message was already logged by exceptions during stitch()
	if "Falling back to manual pairwise stitching method due to" not in log.splitlines()[-5:]:
	log = log_and_print(f"cv2.Stitcher failed with status code: {status} ({error_codes.get(status, f'Unknown Error {status}')})\n", log)
	log = log_and_print("Falling back to manual pairwise stitching method...\n", log)

	except AttributeError as e_attr:
	log = log_and_print(f"AttributeError during Stitcher setup ({e_attr}). Falling back.\n{traceback.format_exc()}\n", log)
	except RuntimeError as e_runtime:
	log = log_and_print(f"RuntimeError during Stitcher setup ({e_runtime}). Falling back.\n{traceback.format_exc()}\n", log)
	except cv2.error as e:
	log = log_and_print(f"OpenCV Error during Stitcher operation: {e}. Falling back.\n", log)
	if "OutOfMemoryError" in str(e) or "Insufficient memory" in str(e):
	log = log_and_print(">>> Specific OutOfMemoryError detected. Reduce resolutions or use more RAM.\n", log)
	log = log_and_print(f"{traceback.format_exc()}\n", log)
	except Exception as e:
	log = log_and_print(f"Unexpected error during Stitcher: {e}. Falling back.\n{traceback.format_exc()}\n", log)
	finally:
	if stitcher is not None:
	# Attempt to release stitcher resources if possible (may not exist)
	try:
	del stitcher
	except NameError:
	pass
	gc.collect()

	# 2. Fallback or Direct Pairwise Stitching
	# Trigger if cv2.Stitcher was skipped OR if it failed
	if skip_cv2_stitcher or not stitcher_success:
	# Add clearer logging based on the reason
	if skip_cv2_stitcher:
	log = log_and_print(f"\n--- Starting Sequential Pairwise Stitching (Direct Mode, Transform: {transform_model_str}) ---\n", log)
	else:
	log = log_and_print(f"\n--- Starting Sequential Pairwise Stitching (Fallback, Transform: {transform_model_str}) ---\n", log)

	if len(images) >= 2:
	# Start with the first valid image. Ensure it's uint8.
	if images[0].dtype != np.uint8:
	current_stitched_image = images[0].clip(0, 255).astype(np.uint8)
	else:
	current_stitched_image = images[0].copy() # Copy to avoid modifying original list item

	sequential_stitch_success = True
	for i in range(1, len(images)):
	log = log_and_print(f"\nSequentially stitching image {i+1} of {len(images)} using pairwise method...\n", log)

	# Ensure next image is uint8
	if images[i].dtype != np.uint8:
	next_image = images[i].clip(0, 255).astype(np.uint8)
	else:
	next_image = images[i] # Can use directly if already uint8

	# Determine Fixed Layer Type for this pair
	# fixed_layer_type logic:
	# - "img2": The new image currently being added (index i) is the specified base map.
	# - "img1": The current composite image (index < i) contains the specified base map.
	# - "none": No base map specified, perform normal blending.
	current_fixed_type = "none"
	if fixed_base_image_index != -1:
	if i == fixed_base_image_index:
	current_fixed_type = "img2" # The new image being added IS the fixed base
	elif fixed_base_image_index < i:
	current_fixed_type = "img1" # The composite (img1) contains the fixed base, so it should stay at bottom
	elif fixed_base_image_index == 0:
	current_fixed_type = "img1" # Special case: First image is base, so composite is always base

	result, pairwise_log = stitch_pairwise_images(
	current_stitched_image, # BGR uint8
	next_image, # BGR uint8
	transform_model_str=transform_model_str,
	blend_method=blend_method,
	enable_gain_compensation=enable_gain_compensation,
	orb_nfeatures=orb_nfeatures,
	match_ratio_thresh=match_ratio_thresh,
	ransac_reproj_thresh=ransac_reproj_thresh,
	max_distance_coeff=max_distance_coeff,
	max_blending_width=max_blending_width,
	max_blending_height=max_blending_height,
	blend_smooth_ksize=blend_smooth_ksize,
	num_blend_levels=num_blend_levels,
	fixed_layer_type=current_fixed_type
	)
	log += pairwise_log

	if result is None:
	log = log_and_print(f"Error: Failed to stitch image {i+1} onto previous composite in the pairwise step. Aborting sequential process.\n", log) # Corrected index in log
	sequential_stitch_success = False
	if 'current_stitched_image' in locals() and current_stitched_image is not None:
	del current_stitched_image # Clean up intermediate result
	gc.collect()
	break

	# Release the previous intermediate image before assigning the new one
	if 'current_stitched_image' in locals() and current_stitched_image is not None:
	del current_stitched_image
	gc.collect()
	current_stitched_image = result # Result is BGR uint8
	log = log_and_print(f"Intermediate stitched shape: {current_stitched_image.shape}\n", log)
	# Ensure next_image is cleaned up if it was a conversion
	if next_image is not images[i]:
	del next_image
	gc.collect()

	if sequential_stitch_success and current_stitched_image is not None:
	log = log_and_print("\nSequential pairwise stitching complete. Applying final cropping...\n", log)
	# Apply FINAL black border cropping if enabled
	cropped_fallback = crop_black_borders(current_stitched_image, enable_cropping, strict_no_black_edges)
	if cropped_fallback is not None and cropped_fallback.size > 0:
	stitched_img_bgra = cropped_fallback
	log = log_and_print(f"Final dimensions after POST-stitch cropping: {stitched_img_bgra.shape}\n", log)
	else:
	stitched_img_bgra = current_stitched_image # Use uncropped if cropping failed
	log = log_and_print("POST-stitch cropping failed or disabled, using uncropped manual result.\n", log)
	# Clean up the last intermediate/uncropped result if cropping was successful and created a new object
	if cropped_fallback is not current_stitched_image and current_stitched_image is not None:
	del current_stitched_image
	if 'cropped_fallback' in locals() and cropped_fallback is not stitched_img_bgra:
	del cropped_fallback
	gc.collect()
	else:
	log = log_and_print("Sequential pairwise stitching process could not produce a final result.\n", log)
	# Ensure cleanup if loop broke early or current_stitched_image was None/deleted
	if 'current_stitched_image' in locals() and current_stitched_image is not None:
	del current_stitched_image
	gc.collect()
	else: # Handle len(images) < 2 case (shouldn't happen due to initial check, but safety)
	log = log_and_print("Error: Not enough images for pairwise stitching (internal check).\n", log)

	# Clean up the input image list now that it's processed
	del images
	if 'valid_images' in locals():
	del valid_images # Should be same as images now
	gc.collect()

	# 3. Final Result Check and Return (Handling Alpha Channel)
	total_end_time = time.time()
	log = log_and_print(f"\nTotal processing time: {total_end_time - total_start_time:.2f} seconds.\n", log)

	if stitched_img_bgra is not None and stitched_img_bgra.size > 0:
	log = log_and_print("Stitching process finished for image list.", log)
	try:
	# Handle final output based on transparency flag
	if use_transparency:
	# Preserve/Ensure RGBA
	if stitched_img_bgra.shape[2] == 4:
	# Convert BGRA to RGBA
	stitched_img_rgba = cv2.cvtColor(stitched_img_bgra, cv2.COLOR_BGRA2RGBA)
	log = log_and_print("Converted BGRA to RGBA (Transparency preserved).", log)
	else:
	# Source was BGR, make it RGBA (solid alpha)
	stitched_img_rgba = cv2.cvtColor(stitched_img_bgra, cv2.COLOR_BGR2RGBA)
	log = log_and_print("Converted BGR to RGBA.", log)
	else:
	# Force RGB (Drop Alpha / Opaque)
	if stitched_img_bgra.shape[2] == 4:
	stitched_img_rgba = cv2.cvtColor(stitched_img_bgra, cv2.COLOR_BGRA2RGB)
	log = log_and_print("Converted BGRA to RGB (Transparency disabled, alpha dropped).", log)
	else:
	# Convert BGR to RGB
	stitched_img_rgba = cv2.cvtColor(stitched_img_bgra, cv2.COLOR_BGR2RGB)
	log = log_and_print("Converted BGR to RGB.", log)

	del stitched_img_bgra # Release BGRA version
	gc.collect()
	return stitched_img_rgba, log
	except cv2.error as e_cvt:
	log = log_and_print(f"\nError converting final image: {e_cvt}. Returning None.\n", log)
	if 'stitched_img_bgra' in locals(): del stitched_img_bgra
	gc.collect()
	return None, log
	else:
	log = log_and_print("Error: Stitching failed. No final image generated.", log)
	if 'stitched_img_bgra' in locals() and stitched_img_bgra is not None:
	del stitched_img_bgra
	gc.collect()
	return None, log


	# --- Video Frame Stitching ---
	def stitch_video_frames(video_path,
	use_transparency=True,
	crop_top_percent=0.0,
	crop_bottom_percent=0.0,
	enable_cropping=True, # This is for POST-stitch cropping
	strict_no_black_edges=False,
	# Pairwise specific params
	transform_model_str="Homography",
	blend_method="multi-band",
	enable_gain_compensation=True,
	orb_nfeatures=2000,
	match_ratio_thresh=0.75,
	ransac_reproj_thresh=5.0,
	max_distance_coeff=0.5,
	max_blending_width=10000,
	max_blending_height=10000,
	blend_smooth_ksize=15,
	num_blend_levels=4,
	# Video specific params
	sample_interval_ms=3000,
	max_composite_width=10000,
	max_composite_height=10000,
	progress=None,
	):
	"""
	Reads a video, samples frames, and stitches them sequentially.
	Returns a list of stitched images (RGBA if transparency=True, else RGB) and a log.
	"""
	log = log_and_print(f"--- Starting Incremental Video Stitching: {os.path.basename(video_path)} ---\n", "")
	log = log_and_print(f"Params: Interval={sample_interval_ms}ms, Transform={transform_model_str}, ORB={orb_nfeatures}, Ratio={match_ratio_thresh}\n", log)
	log = log_and_print(f"Params Cont'd: RANSAC Thresh={ransac_reproj_thresh}, Max Dist Coeff={max_distance_coeff}\n", log)
	log = log_and_print(f"Composite Limits: MaxW={max_composite_width}, MaxH={max_composite_height}\n", log)
	log = log_and_print(f"Pre-Crop: Top={crop_top_percent}%, Bottom={crop_bottom_percent}%\n", log)
	log = log_and_print(f"Post-Crop Black Borders: {enable_cropping}, Strict Edges: {strict_no_black_edges}\n", log)
	log = log_and_print(f"Blending: Method={blend_method}, GainComp={enable_gain_compensation}, SmoothKSize={blend_smooth_ksize}, MB Levels={num_blend_levels}\n", log)
	total_start_time = time.time()
	stitched_results_rgba = [] # Store final images (RGBA or RGB)

	cap = cv2.VideoCapture(video_path)
	if not cap.isOpened():
	log = log_and_print(f"Error: Could not open video file: {video_path}\n", log)
	return [], log

	fps = cap.get(cv2.CAP_PROP_FPS)
	frame_count_total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
	if fps <= 0 or np.isnan(fps): # Handle invalid FPS reads
	fps = 30 # Default FPS
	log = log_and_print("Warning: Could not read valid FPS, defaulting to 30.\n", log)
	if frame_count_total <= 0: # Handle invalid frame count reads
	log = log_and_print("Warning: Could not read valid total frame count.\n", log)
	total_sampled_estimate = 0 # Cannot estimate progress accurately
	else:
	# Estimate total frames to be sampled, avoid division by zero if interval is 0
	frames_per_sample = max(1, int(round(fps * (sample_interval_ms / 1000.0)))) if sample_interval_ms > 0 else frame_count_total
	total_sampled_estimate = frame_count_total / frames_per_sample if frames_per_sample > 0 else 0


	frame_interval = max(1, int(round(fps * (sample_interval_ms / 1000.0))))
	log = log_and_print(f"Video Info: ~{fps:.2f} FPS, {frame_count_total} Frames, Sampling every {frame_interval} frames.\n", log)

	frame_num = 0
	processed_sampled_count = 0 # Counter for progress bar
	anchor_frame = None # The starting frame of the current sequence (BGR, cropped)
	current_composite = None # The stitched result being built (BGR, uint8)
	last_saved_composite = None # Keep track of the last saved image to avoid duplicates

	# Helper to save image to results list with correct color conversion
	def append_result(img_bgr_or_bgra):
	try:
	if use_transparency:
	if img_bgr_or_bgra.shape[2] == 4:
	stitched_results_rgba.append(cv2.cvtColor(img_bgr_or_bgra, cv2.COLOR_BGRA2RGBA))
	else:
	stitched_results_rgba.append(cv2.cvtColor(img_bgr_or_bgra, cv2.COLOR_BGR2RGBA))
	else:
	# Force RGB Output
	if img_bgr_or_bgra.shape[2] == 4:
	stitched_results_rgba.append(cv2.cvtColor(img_bgr_or_bgra, cv2.COLOR_BGRA2RGB))
	else:
	stitched_results_rgba.append(cv2.cvtColor(img_bgr_or_bgra, cv2.COLOR_BGR2RGB))
	return True
	except Exception as e:
	print(f"Error converting result: {e}")
	return False

	while True:
	frame_bgr_raw = None # Initialize here for cleanup later
	try:
	if cap is None or not cap.isOpened():
	log = log_and_print("Error: Video capture became invalid during processing.\n", log)
	break
	ret, frame_bgr_raw = cap.read()
	if not ret:
	log = log_and_print("\nEnd of video stream reached.\n", log)
	break # End of video

	# --- Sampling Logic ---
	if frame_num % frame_interval == 0:
	if frame_bgr_raw is not None and frame_bgr_raw.size > 0:
	processed_sampled_count += 1
	frame_bgra = None # Initialize BGR frame variable

	# Handle Transparency Input
	if not use_transparency:
	# If transparency is disabled, ensure we treat the input as Opaque BGRA
	# We must use BGRA for the internal stitcher to work (warping masks),
	# but we ensure the Alpha channel is full (255).
	if frame_bgr_raw.ndim == 3 and frame_bgr_raw.shape[2] == 3:
	frame_bgra = cv2.cvtColor(frame_bgr_raw, cv2.COLOR_BGR2BGRA)
	elif frame_bgr_raw.ndim == 3 and frame_bgr_raw.shape[2] == 4:
	# Drop existing alpha and replace with opaque
	temp_bgr = cv2.cvtColor(frame_bgr_raw, cv2.COLOR_BGRA2BGR)
	frame_bgra = cv2.cvtColor(temp_bgr, cv2.COLOR_BGR2BGRA)
	del temp_bgr
	else:
	# Grayscale
	frame_bgra = cv2.cvtColor(frame_bgr_raw, cv2.COLOR_GRAY2BGRA)
	else:
	# Standard Transparency Handling
	if frame_bgr_raw.ndim == 2:
	frame_bgra = cv2.cvtColor(frame_bgr_raw, cv2.COLOR_GRAY2BGRA)
	elif frame_bgr_raw.ndim == 3 and frame_bgr_raw.shape[2] == 3:
	# Add alpha channel (opaque)
	frame_bgra = cv2.cvtColor(frame_bgr_raw, cv2.COLOR_BGR2BGRA)
	elif frame_bgr_raw.ndim == 3 and frame_bgr_raw.shape[2] == 4:
	frame_bgra = frame_bgr_raw
	else:
	log = log_and_print(f"Warning: Skipping frame {frame_num} due to unexpected shape {frame_bgr_raw.shape}\n", log)
	if frame_bgr_raw is not None:
	del frame_bgr_raw # Clean up original frame
	gc.collect()
	frame_num += 1
	continue # Skip to next frame read

	# Release the raw frame once converted/checked (if a copy was made)
	if frame_bgra is not frame_bgr_raw and frame_bgr_raw is not None:
	del frame_bgr_raw
	frame_bgr_raw = None # Mark as deleted
	gc.collect()

	cropped_frame_bgra = crop_image_by_percent(frame_bgra, crop_top_percent, crop_bottom_percent)
	del frame_bgra # Release the uncropped BGR version
	gc.collect()

	# Check if cropping failed or resulted in an empty image
	if cropped_frame_bgra is None or cropped_frame_bgra.size == 0:
	log = log_and_print(f"Warning: Skipping frame {frame_num} because percentage cropping failed or resulted in empty image.\n", log)
	if cropped_frame_bgra is not None: del cropped_frame_bgra # Should be None, but safety check
	gc.collect()
	frame_num += 1
	continue # Skip to next frame read

	# Now use 'cropped_frame_bgra' as the current frame for stitching
	current_frame_for_stitch = cropped_frame_bgra # BGRA, uint8, potentially cropped

	if progress is not None and total_sampled_estimate > 0:
	# Ensure progress doesn't exceed 1.0
	progress_fraction = min(1.0, processed_sampled_count / total_sampled_estimate)
	progress(progress_fraction, desc=f"Processing Sample {processed_sampled_count}/{int(total_sampled_estimate)}")
	elif progress is not None:
	# Fallback progress if estimate is bad
	progress(processed_sampled_count / (processed_sampled_count + 10), desc=f"Processing Sample {processed_sampled_count}")


	log = log_and_print(f"\n--- Processing sampled frame index {frame_num} (Count: {processed_sampled_count}) ---\n", log)
	log = log_and_print(f"Frame shape after potential pre-crop: {current_frame_for_stitch.shape}\n", log)

	# --- Stitching Logic ---
	if anchor_frame is None:
	# Start a new sequence
	anchor_frame = current_frame_for_stitch.copy() # Make a copy
	current_composite = anchor_frame # Start composite is the anchor itself
	log = log_and_print(f"Frame {frame_num}: Set as new anchor (Shape: {anchor_frame.shape}).\n", log)
	# No need to stitch yet, just set the anchor

	else:
	# Try stitching the current composite with the new frame
	log = log_and_print(f"Attempting stitch: Composite({current_composite.shape}) + Frame({current_frame_for_stitch.shape})\n", log)

	stitch_result, stitch_log = stitch_pairwise_images(
	current_composite, # Previous result or anchor (uint8)
	current_frame_for_stitch, # New frame to add (uint8)
	transform_model_str=transform_model_str,
	blend_method=blend_method,
	enable_gain_compensation=enable_gain_compensation,
	orb_nfeatures=orb_nfeatures,
	match_ratio_thresh=match_ratio_thresh,
	ransac_reproj_thresh=ransac_reproj_thresh,
	max_distance_coeff=max_distance_coeff,
	max_blending_width=max_blending_width,
	max_blending_height=max_blending_height,
	blend_smooth_ksize=blend_smooth_ksize,
	num_blend_levels=num_blend_levels
	)
	log += stitch_log

	if stitch_result is not None and stitch_result.size > 0:
	# --- Stitching SUCCEEDED ---
	log = log_and_print(f"Success: Stitched frame {frame_num}. New composite shape: {stitch_result.shape}\n", log)
	# Release old composite before assigning new one
	del current_composite
	gc.collect()
	current_composite = stitch_result # Update the composite (stitch_result is BGR uint8)
	# anchor_frame remains the same for this sequence

	# Check Size Limits
	h_curr, w_curr = current_composite.shape[:2]
	size_limit_exceeded = False
	# Check only if limit > 0
	if max_composite_width > 0 and w_curr > max_composite_width:
	log = log_and_print(f"ACTION: Composite width ({w_curr}) exceeded limit ({max_composite_width}).\n", log)
	size_limit_exceeded = True
	if max_composite_height > 0 and h_curr > max_composite_height:
	log = log_and_print(f"ACTION: Composite height ({h_curr}) exceeded limit ({max_composite_height}).\n", log)
	size_limit_exceeded = True

	if size_limit_exceeded:
	log = log_and_print("Saving current composite and starting new sequence with NEXT frame.\n", log)

	# Apply FINAL black border cropping if enabled
	post_cropped_composite = crop_black_borders(current_composite, enable_cropping, strict_no_black_edges)
	if post_cropped_composite is not None and post_cropped_composite.size > 0:
	# Avoid saving the exact same image twice in a row
	is_duplicate = False
	if last_saved_composite is not None:
	try:
	# Simple check: compare shapes first, then content if shapes match
	if last_saved_composite.shape == post_cropped_composite.shape:
	if np.array_equal(last_saved_composite, post_cropped_composite):
	is_duplicate = True
	except Exception as e_comp:
	log = log_and_print(f"Warning: Error comparing images for duplication check: {e_comp}\n", log)

	if not is_duplicate:
	# Use helper to append RGBA correctly
	append_result(post_cropped_composite)
	# Update last_saved_composite only if append is successful
	if last_saved_composite is not None: del last_saved_composite
	last_saved_composite = post_cropped_composite.copy() # Store the saved one (BGR/BGRA)
	log = log_and_print(f"Saved composite image {len(stitched_results_rgba)} (Post-Cropped Shape: {post_cropped_composite.shape}).\n", log)
	else:
	log = log_and_print("Skipping save: Result identical to previously saved image.\n", log)

	# Clean up the post-cropped version if it wasn't stored in last_saved_composite
	if last_saved_composite is not post_cropped_composite:
	del post_cropped_composite
	gc.collect()
	else:
	log = log_and_print("Warning: Post-stitch cropping failed for the size-limited composite, skipping save.\n", log)
	if post_cropped_composite is not None:
	del post_cropped_composite # Delete if it existed but was empty

	# Reset for the next frame to become the anchor
	del current_composite
	if anchor_frame is not None:
	del anchor_frame # Delete old anchor too
	if last_saved_composite is not None:
	del last_saved_composite # Reset duplicate check too
	current_composite = None
	anchor_frame = None
	last_saved_composite = None
	gc.collect()
	# --- End Size Check ---

	else:
	# --- Stitching FAILED ---
	log = log_and_print(f"Failed: Could not stitch frame {frame_num} onto current composite.\n", log)
	# Save the previous valid composite (if it exists and is not just the anchor)
	save_previous = False
	if current_composite is not None and anchor_frame is not None:
	# Check if composite is actually different from the anchor
	try:
	if current_composite.shape != anchor_frame.shape or not np.array_equal(current_composite, anchor_frame):
	save_previous = True
	except Exception as e_comp:
	log = log_and_print(f"Warning: Error comparing composite to anchor: {e_comp}\n", log)
	save_previous = True # Assume different if compare fails

	if save_previous:
	log = log_and_print("ACTION: Saving the previously stitched result before resetting.\n", log)
	# Apply FINAL black border cropping if enabled
	post_cropped_composite = crop_black_borders(current_composite, enable_cropping, strict_no_black_edges)
	if post_cropped_composite is not None and post_cropped_composite.size > 0:
	# Check duplicate
	is_duplicate = False
	if last_saved_composite is not None and last_saved_composite.shape == post_cropped_composite.shape:
	if np.array_equal(last_saved_composite, post_cropped_composite):
	is_duplicate = True

	if not is_duplicate:
	# Use helper to append RGBA correctly
	append_result(post_cropped_composite)
	if last_saved_composite is not None:
	del last_saved_composite
	last_saved_composite = post_cropped_composite.copy() # Store BGR/BGRA
	log = log_and_print(f"Saved composite image {len(stitched_results_rgba)} (Post-Cropped Shape: {post_cropped_composite.shape}).\n", log)
	else:
	log = log_and_print("Skipping save: Result identical to previously saved image.\n", log)

	if last_saved_composite is not post_cropped_composite:
	del post_cropped_composite
	gc.collect()
	else:
	log = log_and_print("Warning: Post-stitch cropping failed for the previously stitched result, skipping save.\n", log)
	if post_cropped_composite is not None:
	del post_cropped_composite
	else:
	log = log_and_print("No previous composite to save (stitching failed on first attempt for this anchor or composite was just the anchor).\n", log)

	# The frame that failed to stitch becomes the new anchor
	log = log_and_print(f"ACTION: Setting frame {frame_num} (shape: {current_frame_for_stitch.shape}) as the new anchor.\n", log)
	if current_composite is not None:
	del current_composite # Delete the old composite
	if anchor_frame is not None:
	del anchor_frame # Delete the old anchor
	if last_saved_composite is not None:
	del last_saved_composite # Reset duplicate check
	gc.collect()
	# Reset anchor to current frame
	anchor_frame = current_frame_for_stitch.copy() # Use the frame that failed (already cropped)
	current_composite = anchor_frame # Reset composite to this new anchor
	last_saved_composite = None
	gc.collect()
	# current_frame_for_stitch is now anchor_frame, no need to delete separately below

	# Clean up current frame AFTER processing (if it wasn't made the new anchor)
	# If stitching succeeded OR if it failed but wasn't the first frame,
	# current_frame_for_stitch needs cleanup unless it just became the anchor.
	if 'current_frame_for_stitch' in locals() and current_frame_for_stitch is not anchor_frame:
	del current_frame_for_stitch
	gc.collect()

	else: # Handle cases where frame_bgr_raw is None or empty after read
	if frame_bgr_raw is not None:
	del frame_bgr_raw
	frame_bgr_raw = None
	gc.collect()
	else: # Frame not sampled
	# Still need to release the raw frame if it was read
	if frame_bgr_raw is not None:
	del frame_bgr_raw
	frame_bgr_raw = None
	# Don't gc.collect() on every skipped frame, too slow

	frame_num += 1
	# Loop continues
	except Exception as loop_error:
	log = log_and_print(f"Unexpected error in main video loop at frame {frame_num}: {loop_error}\n{traceback.format_exc()}\n", log)
	# Try to continue to next frame if possible, or break if capture seems broken
	if cap is None or not cap.isOpened():
	log = log_and_print("Video capture likely broken, stopping loop.\n", log)
	break
	else:
	frame_num += 1 # Ensure frame counter increments
	# Clean up potentially lingering frame data from the failed iteration
	if 'frame_bgr_raw' in locals() and frame_bgr_raw is not None:
	del frame_bgr_raw
	if 'frame_bgra' in locals() and frame_bgra is not None:
	del frame_bgra
	if 'cropped_frame_bgra' in locals() and cropped_frame_bgra is not None:
	del cropped_frame_bgra
	if 'current_frame_for_stitch' in locals() and current_frame_for_stitch is not None and current_frame_for_stitch is not anchor_frame:
	del current_frame_for_stitch
	gc.collect()

	# After the loop: Check if there's a final composite to save
	if current_composite is not None and anchor_frame is not None:
	# Only save if it contains more than just the last anchor frame OR if it's the only result
	save_final = False
	if len(stitched_results_rgba) == 0: # If no images saved yet, save this one
	save_final = True
	else:
	try:
	if current_composite.shape != anchor_frame.shape or not np.array_equal(current_composite, anchor_frame):
	save_final = True
	except Exception as e_comp:
	log = log_and_print(f"Warning: Error comparing final composite to anchor: {e_comp}\n", log)
	save_final = True # Save if comparison fails

	if save_final:
	log = log_and_print("\nEnd of frames reached. Checking final composite...\n", log)
	post_cropped_final = crop_black_borders(current_composite, enable_cropping, strict_no_black_edges)
	if post_cropped_final is not None:
	is_duplicate = False
	if last_saved_composite is not None and last_saved_composite.shape == post_cropped_final.shape:
	if np.array_equal(last_saved_composite, post_cropped_final):
	is_duplicate = True
	if not is_duplicate:
	append_result(post_cropped_final) # RGBA append
	message = f"Saved final composite image {len(stitched_results_rgba)}"
	if 'post_cropped_composite' in locals():
	message += f" (Post-Cropped Shape: {post_cropped_composite.shape})"

	log = log_and_print(f"{message}.\n", log)
	# No need to update last_saved_composite here, loop is finished
	else:
	log = log_and_print("Skipping save of final composite: Result identical to previously saved image.\n", log)

	# Clean up final cropped image if it existed
	del post_cropped_final
	gc.collect()
	else:
	log = log_and_print("Warning: Post-stitch cropping failed for the final composite, skipping save.\n", log)
	if post_cropped_final is not None:
	del post_cropped_final # Delete if empty
	else:
	log = log_and_print("\nEnd of frames reached. Final composite was identical to its anchor frame and not the only result, not saving.\n", log)

	# --- Final Cleanup ---
	if cap is not None and cap.isOpened():
	cap.release()
	if 'cap' in locals():
	del cap
	if 'anchor_frame' in locals() and anchor_frame is not None:
	del anchor_frame
	if 'current_composite' in locals() and current_composite is not None:
	del current_composite
	if 'last_saved_composite' in locals() and last_saved_composite is not None:
	del last_saved_composite
	gc.collect()

	total_end_time = time.time()
	log = log_and_print(f"\nVideo stitching process finished. Found {len(stitched_results_rgba)} stitched image(s).", log)
	log = log_and_print(f"\nTotal processing time: {total_end_time - total_start_time:.2f} seconds.\n", log)

	# Filter out potential None entries just before returning
	final_results = [img for img in stitched_results_rgba if img is not None and img.size > 0]
	if len(final_results) != len(stitched_results_rgba):
	log = log_and_print(f"Warning: Filtered out {len(stitched_results_rgba) - len(final_results)} None or empty results before final return.\n", log)
	# Clean up the original list with potential Nones
	del stitched_results_rgba
	gc.collect()

	return final_results, log


	# --- Gradio Interface Function ---
	def run_stitching_interface(input_files,
	use_transparency,
	crop_top_percent,
	crop_bottom_percent,
	stitcher_mode_str, # For cv2.Stitcher
	registration_resol,
	seam_estimation_resol,
	compositing_resol,
	wave_correction,
	exposure_comp_type_str, # For cv2.Stitcher
	enable_cropping, # Post-stitch black border crop
	strict_no_black_edges_input,
	fixed_base_image_index_input,
	# Detailed Stitcher Settings
	transform_model_str,
	blend_method_str,
	enable_gain_compensation,
	orb_nfeatures,
	match_ratio_thresh,
	ransac_reproj_thresh_input,
	max_distance_coeff_input,
	max_blending_width,
	max_blending_height,
	blend_smooth_ksize_input,
	num_blend_levels_input,
	# Video specific settings
	sample_interval_ms,
	max_composite_width_video,
	max_composite_height_video,
	progress=gr.Progress(track_tqdm=True)
	):
	"""
	Wrapper function called by the Gradio interface.
	Handles input (images or video), applies pre-cropping,
	calls the appropriate stitching logic (passing transform_model_str),
	and returns results.
	Updates image reading and result saving to handle RGBA/BGRA transparency.
	UPDATED to handle transparency correctly when saving to temp files.
	"""
	if input_files is None or len(input_files) == 0:
	return [], "Please upload images or a video file."

	# Convert Gradio inputs to correct types
	fixed_base_image_index = int(fixed_base_image_index_input) if fixed_base_image_index_input is not None else -1
	ransac_reproj_thresh = float(ransac_reproj_thresh_input) if ransac_reproj_thresh_input is not None else 3.0
	max_distance_coeff = float(max_distance_coeff_input) if max_distance_coeff_input is not None else 0.5
	blend_smooth_ksize = int(blend_smooth_ksize_input) if blend_smooth_ksize_input is not None else -1
	num_blend_levels = int(num_blend_levels_input) if num_blend_levels_input is not None else 4

	log = f"Received {len(input_files)} file(s).\n"
	log = log_and_print(f"Pre-Crop Settings: Top={crop_top_percent}%, Bottom={crop_bottom_percent}%\n", log)
	log = log_and_print(f"Post-Crop Black Borders: Enabled={enable_cropping}, Strict Edges={strict_no_black_edges_input}\n", log)
	# Log detailed settings including new ones
	log = log_and_print(f"Detailed Settings: Transform={transform_model_str}, Blend={blend_method_str}, GainComp={enable_gain_compensation}, ORB={orb_nfeatures}, Ratio={match_ratio_thresh}\n", log)
	log = log_and_print(f"Detailed Settings Cont'd: RANSAC Thresh={ransac_reproj_thresh}, MaxDistCoeff={max_distance_coeff}, MaxBlendW={max_blending_width}, MaxBlendH={max_blending_height}, SmoothKSize={blend_smooth_ksize}, MBLevels={num_blend_levels}\n", log)
	progress(0, desc="Processing Input...")

	# Determine input type: List of images or a single video
	is_video_input = False
	video_path = None
	image_paths = []

	# Check file types using mimetypes
	try:
	# Handle potential TempfileWrappers or string paths
	input_filepaths = []
	for f in input_files:
	if hasattr(f, 'name'): # Gradio File object
	input_filepaths.append(f.name)
	elif isinstance(f, str): # String path (e.g., from examples)
	input_filepaths.append(f)
	else:
	log = log_and_print(f"Warning: Unexpected input file type: {type(f)}. Skipping.\n", log)

	if len(input_filepaths) == 1:
	filepath = input_filepaths[0]
	mime_type, _ = mimetypes.guess_type(filepath)
	if mime_type and mime_type.startswith('video'):
	is_video_input = True
	video_path = filepath
	log = log_and_print(f"Detected video input: {os.path.basename(video_path)}\n", log)
	elif mime_type and mime_type.startswith('image'):
	log = log_and_print("Detected single image input. Need at least two images for list stitching.\n", log)
	image_paths = [filepath] # Keep it for error message later
	else:
	# Fallback check: try reading as image
	img_test = None
	try:
	# Use np.fromfile for paths that might have unicode characters
	n = np.fromfile(filepath, np.uint8)
	if n.size > 0:
	img_test = cv2.imdecode(n, cv2.IMREAD_COLOR)
	else:
	raise ValueError("File is empty")

	if img_test is not None and img_test.size > 0:
	log = log_and_print(f"Warning: Unknown file type for single file: {os.path.basename(filepath)}. Assuming image based on successful read. Need >= 2 images.\n", log)
	image_paths = [filepath]
	del img_test
	else:
	raise ValueError("Cannot read as image or image is empty")
	except Exception as e_read_check:
	log = log_and_print(f"Error: Could not determine file type or read single file: {os.path.basename(filepath)}. Error: {e_read_check}. Please provide video or image files.\n", log)
	if img_test is not None:
	del img_test
	return [], log
	else: # Multiple files uploaded
	image_paths = []
	non_image_skipped = False
	for filepath in input_filepaths:
	mime_type, _ = mimetypes.guess_type(filepath)
	is_image = False
	if mime_type and mime_type.startswith('image'):
	is_image = True
	else:
	# Fallback check: Try reading as image
	img_test = None
	try:
	n = np.fromfile(filepath, np.uint8)
	if n.size > 0:
	img_test = cv2.imdecode(n, cv2.IMREAD_COLOR)
	else:
	raise ValueError("File is empty")

	if img_test is not None and img_test.size > 0:
	is_image = True
	log = log_and_print(f"Warning: Non-image or unknown file type detected: {os.path.basename(filepath)}. Assuming image based on read success.\n", log)
	del img_test
	else:
	non_image_skipped = True
	log = log_and_print(f"Warning: Skipping non-image file (or empty/failed read): {os.path.basename(filepath)}\n", log)
	except Exception as e_read_check:
	non_image_skipped = True
	log = log_and_print(f"Warning: Skipping non-image file (read failed: {e_read_check}): {os.path.basename(filepath)}\n", log)
	if img_test is not None:
	del img_test


	if is_image:
	image_paths.append(filepath)

	if not image_paths: # No valid images found
	if non_image_skipped:
	log = log_and_print("Error: No valid image files found in the input list after filtering.\n", log)
	else: # Should only happen if initial list was empty, but covered by check at start
	log = log_and_print("Error: No image files provided in the input list.\n", log)
	return [], log
	elif non_image_skipped:
	log = log_and_print(f"Proceeding with {len(image_paths)} assumed image files (some non-images were skipped).\n", log)
	else:
	log = log_and_print(f"Detected {len(image_paths)} image inputs.\n", log)
	except Exception as e:
	log = log_and_print(f"Error detecting input file types: {e}\n{traceback.format_exc()}\n", log)
	return [], log


	# --- Process Based on Input Type ---
	final_stitched_images_rgba = [] # This will technically hold RGBA if available
	stitch_log = ""

	if is_video_input:
	# --- VIDEO PROCESSING ---
	log = log_and_print("Starting incremental video frame stitching...\n", log)
	progress(0.1, desc="Sampling & Stitching Video...")
	# Ensure blend method string is lowercase for internal checks
	blend_method_lower = blend_method_str.lower() if blend_method_str else "multi-band"

	final_stitched_images_rgba, stitch_log = stitch_video_frames(
	video_path,
	use_transparency=use_transparency,
	crop_top_percent=crop_top_percent,
	crop_bottom_percent=crop_bottom_percent,
	enable_cropping=enable_cropping, # Post-stitch crop
	strict_no_black_edges=strict_no_black_edges_input,
	transform_model_str=transform_model_str,
	blend_method=blend_method_lower, # linear or multi-band
	enable_gain_compensation=enable_gain_compensation,
	orb_nfeatures=orb_nfeatures,
	match_ratio_thresh=match_ratio_thresh,
	ransac_reproj_thresh=ransac_reproj_thresh,
	max_distance_coeff=max_distance_coeff,
	max_blending_width=max_blending_width,
	max_blending_height=max_blending_height,
	sample_interval_ms=sample_interval_ms,
	max_composite_width=max_composite_width_video,
	max_composite_height=max_composite_height_video,
	blend_smooth_ksize=blend_smooth_ksize,
	num_blend_levels=num_blend_levels,
	progress=progress
	)

	elif len(image_paths) >= 2:
	# --- IMAGE LIST PROCESSING ---
	log = log_and_print("Reading and preparing images for list stitching...\n", log)
	images_bgr_cropped = [] # Store potentially cropped BGRA images
	read_success = True
	for i, img_path in enumerate(image_paths):
	progress(i / len(image_paths) * 0.1, desc=f"Reading image {i+1}/{len(image_paths)}") # Small progress for reading
	img = None
	try:
	n = np.fromfile(img_path, np.uint8)
	if n.size > 0:
	# Load logic based on transparency flag
	if use_transparency:
	# Use IMREAD_UNCHANGED to keep Alpha
	img = cv2.imdecode(n, cv2.IMREAD_UNCHANGED)
	else:
	img = cv2.imdecode(n, cv2.IMREAD_COLOR) # Ignore alpha
	else:
	log = log_and_print(f"Error: File is empty: {os.path.basename(img_path)}. Skipping.\n", log)
	continue

	if img is None:
	raise ValueError("imdecode returned None")
	except Exception as e_read:
	log = log_and_print(f"Error reading image: {os.path.basename(img_path)}. Error: {e_read}. Skipping.\n", log)
	if img is not None:
	del img
	continue # Skip to the next image

	# Convert to BGRA for internal processing consistency
	# (Internal stitching needs masks, so we use BGRA format even if opaque)
	img_bgra = None
	try:
	if use_transparency:
	if img.ndim == 2:
	img_bgra = cv2.cvtColor(img, cv2.COLOR_GRAY2BGRA)
	elif img.ndim == 3 and img.shape[2] == 3:
	img_bgra = cv2.cvtColor(img, cv2.COLOR_BGR2BGRA)
	elif img.ndim == 3 and img.shape[2] == 4:
	img_bgra = img # Already BGRA
	else:
	log = log_and_print(f"Error: Invalid image shape {img.shape} for {os.path.basename(img_path)}. Skipping.\n", log)
	del img
	if 'img_bgra' in locals() and img_bgra is not None:
	del img_bgra
	gc.collect()
	continue # Skip to the next image
	else:
	# Force Opaque BGRA
	if img.ndim == 2:
	img_bgra = cv2.cvtColor(img, cv2.COLOR_GRAY2BGRA)
	elif img.ndim == 3 and img.shape[2] == 3:
	img_bgra = cv2.cvtColor(img, cv2.COLOR_BGR2BGRA)
	elif img.ndim == 3 and img.shape[2] == 4:
	# Drop alpha, re-add opaque
	tmp = cv2.cvtColor(img, cv2.COLOR_BGRA2BGR)
	img_bgra = cv2.cvtColor(tmp, cv2.COLOR_BGR2BGRA)
	del tmp

	except cv2.error as e_cvt_color:
	log = log_and_print(f"Error converting image color for {os.path.basename(img_path)}: {e_cvt_color}. Skipping.\n", log)
	del img
	if 'img_bgra' in locals() and img_bgra is not None:
	del img_bgra
	gc.collect()
	continue

	# Release original read image if conversion happened
	if img_bgra is not img:
	del img
	gc.collect()

	# Apply Percentage Cropping
	img_bgra_cropped_single = crop_image_by_percent(img_bgra, crop_top_percent, crop_bottom_percent)

	# Release uncropped BGRA version
	if img_bgra_cropped_single is not img_bgra:
	del img_bgra
	gc.collect()

	if img_bgra_cropped_single is None or img_bgra_cropped_single.size == 0:
	log = log_and_print(f"Warning: Skipping image {os.path.basename(img_path)} because percentage cropping failed or resulted in empty image.\n", log)
	if img_bgra_cropped_single is not None:
	del img_bgra_cropped_single
	gc.collect()
	continue # Skip to next image

	images_bgr_cropped.append(img_bgra_cropped_single)
	# log = log_and_print(f"Read and pre-cropped: {os.path.basename(img_path)} -> Shape: {img_bgra_cropped_single.shape}\n", log) # Can be verbose

	if len(images_bgr_cropped) < 2:
	stitch_log = log_and_print(f"Need at least two valid images after reading and pre-cropping ({len(images_bgr_cropped)} found) for list stitching.\n", log)
	read_success = False # Indicate failure to proceed
	else:
	log = log_and_print(f"Proceeding with {len(images_bgr_cropped)} valid, pre-cropped images. Starting list stitching...\n", log)
	progress(0.1, desc="Stitching Image List...")
	# Ensure blend method string is lowercase for internal checks
	blend_method_lower = blend_method_str.lower() if blend_method_str else "multi-band"

	# Call the modified stitch_multiple_images function
	stitched_single_rgba, stitch_log_img = stitch_multiple_images(
	images_bgr_cropped, # Pass the list of cropped images (BGRA/BGR)
	use_transparency=use_transparency,
	stitcher_mode_str=stitcher_mode_str,
	registration_resol=registration_resol,
	seam_estimation_resol=seam_estimation_resol,
	compositing_resol=compositing_resol,
	wave_correction=wave_correction,
	exposure_comp_type_str=exposure_comp_type_str,
	enable_cropping=enable_cropping, # Post-stitch crop
	strict_no_black_edges=strict_no_black_edges_input,
	transform_model_str=transform_model_str,
	blend_method=blend_method_lower,
	enable_gain_compensation=enable_gain_compensation,
	orb_nfeatures=orb_nfeatures,
	match_ratio_thresh=match_ratio_thresh,
	ransac_reproj_thresh=ransac_reproj_thresh,
	max_distance_coeff=max_distance_coeff,
	max_blending_width=max_blending_width,
	max_blending_height=max_blending_height,
	blend_smooth_ksize=blend_smooth_ksize,
	num_blend_levels=num_blend_levels,
	fixed_base_image_index=fixed_base_image_index
	)
	stitch_log += stitch_log_img # Append log from stitching function
	if stitched_single_rgba is not None:
	final_stitched_images_rgba = [stitched_single_rgba] # Result is a list containing the single image

	# Clean up loaded images for list mode after stitching attempt
	if 'images_bgr_cropped' in locals():
	for img_del in images_bgr_cropped:
	if img_del is not None:
	del img_del
	del images_bgr_cropped
	gc.collect()

	elif len(image_paths) == 1:
	# This case should have been handled by the input type detection,
	# but add a message here just in case.
	log = log_and_print("Error: Only one image file provided or detected. Need at least two for image list stitching.\n", log)
	stitch_log = "" # No stitching attempted
	else:
	# This case means no valid input files were found or passed initial checks.
	log = log_and_print("Error: Input must be a single video file or at least two image files. No valid input found.\n", log)
	stitch_log = ""

	final_log = log + stitch_log
	if not final_stitched_images_rgba:
	# Avoid duplicating error messages if log already indicates failure
	if "Error:" not in final_log[-200:]: # Check last few lines for errors
	final_log = log_and_print("\nNo stitched images were generated.", final_log)

	# Saving Results to Temporary Files (Handling RGBA)
	output_file_paths = [] # List to store paths for the Gallery
	temp_dir = None

	if final_stitched_images_rgba:
	try:
	# Try to create a subdirectory within the default Gradio temp space if possible
	gradio_temp_base = tempfile.gettempdir()
	gradio_subdir = os.path.join(gradio_temp_base, 'gradio') # Default Gradio temp subdir name
	# Check if we can write there, otherwise use default temp dir
	target_temp_dir_base = gradio_subdir if os.path.exists(gradio_subdir) and os.access(gradio_subdir, os.W_OK) else gradio_temp_base

	if not os.path.exists(target_temp_dir_base):
	try:
	os.makedirs(target_temp_dir_base)
	except OSError as e_mkdir:
	final_log = log_and_print(f"Warning: Could not create temp directory '{target_temp_dir_base}', using default. Error: {e_mkdir}\n", final_log)
	target_temp_dir_base = tempfile.gettempdir() # Fallback to system default temp

	temp_dir = tempfile.mkdtemp(prefix="stitch_run_", dir=target_temp_dir_base)
	final_log = log_and_print(f"\nInfo: Saving output images to temporary directory: {temp_dir}\n", final_log)

	for i, img_rgba in enumerate(final_stitched_images_rgba):
	if img_rgba is None or img_rgba.size == 0:
	final_log = log_and_print(f"Warning: Skipping saving image index {i} because it is None or empty.\n", final_log)
	continue

	# Default filename
	filename = f"stitched_{i+1:03d}.png" # PNG is required for transparency

	# If in multi-image mode (not video mode), and input paths exist
	if not is_video_input and image_paths:
	try:
	# Get the path of the last image
	last_image_path = image_paths[-1]
	# Get the filename and remove the extension (e.g., "filename.jpg" -> "filename")
	last_image_name = os.path.splitext(os.path.basename(last_image_path))[0]

	if len(final_stitched_images_rgba) > 1:
	# In case multiple results are produced, add numbering to avoid overwriting
	filename = f"{last_image_name}_stitched_{i+1:03d}.png"
	else:
	# Normal single result, use requested format: [last_image_filename]_stitched.png
	filename = f"{last_image_name}_stitched.png"
	except Exception as e_name:
	# If an error occurs, keep the default filename
	pass

	# Use os.path.join for cross-platform compatibility
	full_path = os.path.join(temp_dir, filename)
	img_bgra = None # Initialize for finally block
	try:
	if use_transparency:
	# Handle RGBA to BGRA for saving
	# The result coming from stitcher is in RGB(A) format
	if img_rgba.shape[2] == 4:
	img_bgra = cv2.cvtColor(img_rgba, cv2.COLOR_RGBA2BGRA)
	else:
	img_bgra = cv2.cvtColor(img_rgba, cv2.COLOR_RGB2BGR)
	else:
	# Transparency Disabled: Output should be RGB (saved as BGR)
	if img_rgba.shape[2] == 4:
	img_bgra = cv2.cvtColor(img_rgba, cv2.COLOR_RGBA2BGR) # Drop Alpha
	else:
	img_bgra = cv2.cvtColor(img_rgba, cv2.COLOR_RGB2BGR)

	# Use imencode -> write pattern for better handling of paths/special chars
	is_success, buf = cv2.imencode('.png', img_bgra)
	if is_success:
	with open(full_path, 'wb') as f:
	f.write(buf)
	# Use Gradio File obj or just path string? Gallery seems to prefer path strings.
	output_file_paths.append((full_path, filename)) # Store the full path for Gradio Gallery
	# final_log = log_and_print(f"Successfully saved: {filename}\n", final_log) # Can be verbose
	else:
	final_log = log_and_print(f"Warning: Failed to encode image for saving: {filename}\n", final_log)
	except cv2.error as e_cvt_write:
	final_log = log_and_print(f"Error converting or encoding image {filename}: {e_cvt_write}\n", final_log)
	except IOError as e_io:
	final_log = log_and_print(f"Error writing image file {filename} to {full_path}: {e_io}\n", final_log)
	except Exception as e_write:
	final_log = log_and_print(f"Unexpected error writing image {filename} to {full_path}: {e_write}\n", final_log)
	finally:
	if img_bgra is not None:
	del img_bgra
	gc.collect()
	except Exception as e_tempdir:
	final_log = log_and_print(f"Error creating temporary directory or saving output: {e_tempdir}\n", final_log)
	output_file_paths = [] # Fallback to empty list

	# --- Final Cleanup of RGB images list ---
	if 'final_stitched_images_rgba' in locals():
	for img_del in final_stitched_images_rgba:
	if img_del is not None:
	del img_del
	del final_stitched_images_rgba
	gc.collect()

	progress(1.0, desc="Finished!")
	final_log = log_and_print("\nCleanup complete.", final_log)

	# Return the LIST OF FILE PATHS for the Gallery, and the log
	return output_file_paths, final_log

	# --- Define Gradio Interface ---
	with gr.Blocks() as demo:
	gr.Markdown("# OpenCV Image and Video Stitcher")
	gr.Markdown(
	"Upload multiple images (for list/panorama stitching) OR a single video file (for sequential frame stitching). "
	"Video frames are sampled incrementally based on the interval. "
	"Use Pre-Cropping to remove unwanted areas before stitching. Adjust other parameters and click 'Stitch'."
	)

	with gr.Row():
	with gr.Column(scale=1):
	stitch_button = gr.Button("Stitch", variant="primary")
	input_files = gr.File(
	label="Upload Images or a Video",
	# Common image and video types
	file_types=["image", ".mp4", ".avi", ".mov", ".mkv", ".wmv", ".webm"],
	file_count="multiple",
	elem_id="input_files"
	)

	# --- Parameters Grouping ---
	with gr.Accordion("Preprocessing Settings", open=True):
	use_transparency = gr.Checkbox(value=True, label="Use Transparency",
	info="If Checked: Preserves alpha channel (RGBA). Unchecked: Treats images as opaque and outputs RGB (Black background for warped areas).")
	crop_top_percent = gr.Slider(0.0, 49.0, step=0.5, value=0.0, label="Crop Top %",
	info="Percentage of height to remove from the TOP of each image/frame BEFORE stitching.")
	crop_bottom_percent = gr.Slider(0.0, 49.0, step=0.5, value=0.0, label="Crop Bottom %",
	info="Percentage of height to remove from the BOTTOM of each image/frame BEFORE stitching.")

	with gr.Accordion("OpenCV Stitcher Settings (Image List Mode Only)", open=True):
	stitcher_mode = gr.Radio(["SCANS", "PANORAMA", "DIRECT_PAIRWISE"], label="Stitcher Mode (Image List)", value="SCANS",
	info=(
	"Method for image list stitching. 'SCANS'/'PANORAMA': Use OpenCV's built-in Stitcher (optimized for translation/rotation). "
	"'SCANS': Optimized for images primarily related by translation (like scanning documents or linear camera motion), potentially using simpler geometric models or assumptions internally. "
	"'PANORAMA': Designed for images captured by rotating the camera around a central point. It uses full perspective transformations (Homography) to handle the complex geometric distortions typical in panoramic shots."
	"'DIRECT_PAIRWISE': Skip OpenCV Stitcher and directly use sequential pairwise feature matching (same as video mode or fallback)."
	)
	)
	registration_resol = gr.Slider(0.1, 1.0, step=0.05, value=0.6, label="Registration Resolution",
	info="Scale factor for the image resolution used during feature detection and matching. Lower values (e.g., 0.6) are faster but may miss features in high-res images. 1.0 uses full resolution.")
	seam_estimation_resol = gr.Slider(0.05, 1.0, step=0.05, value=0.1, label="Seam Estimation Resolution",
	info="Scale factor for the image resolution used during seam finding (finding the optimal cut line). Lower values (e.g., 0.1) are much faster.")
	compositing_resol = gr.Slider(-1.0, 1.0, step=0.1, value=-1.0, label="Compositing Resolution",
	info="Scale factor for the image resolution used during the final blending stage. -1.0 uses the original source image resolution. Lower values reduce memory usage but might slightly blur the output.")
	wave_correction = gr.Checkbox(value=False, label="Enable Wave Correction",
	info="Attempts to correct perspective distortions (waviness) common in panoramas. Can increase processing time.")
	exposure_comp_type = gr.Dropdown(["NO", "GAIN", "GAIN_BLOCKS"], value="GAIN_BLOCKS", label="Exposure Compensation",
	info="Method used by the built-in stitcher to adjust brightness/contrast differences between images. 'GAIN_BLOCKS' is generally preferred for varying lighting.")

	# --- Detailed Stitcher Settings (Used for Video, DIRECT_PAIRWISE, and Fallback) ---
	with gr.Accordion("Pairwise Stitching Settings (Video / Direct / Fallback)", open=True):
	fixed_base_image_index_input = gr.Number(value=-1, label="Fixed Base Image Index (0-based)", precision=0,
	info="Specify the index of the image (0, 1, 2...) that should serve as the 'Bottom/Base' layer without blending. Overlapping images will cover it, but brightness will still adjust. Set -1 to disable.")
	transform_model = gr.Radio(["Homography", "Affine_Partial", "Affine_Full"], label="Pairwise Transform Model", value="Homography", # Default to Homography
	info="Geometric model for pairwise alignment. 'Homography' handles perspective. 'Affine' (Partial/Full) handles translation, rotation, scale, shear (better for scans, less distortion risk). If stitching fails with one model, try another.")
	blend_method = gr.Radio(["Linear", "Multi-Band"], label="Blending Method", value="Multi-Band",
	info="Algorithm for smoothing seams in overlapping regions when using the detailed stitcher (for video or image list fallback). 'Multi-Band' is often better but slower.")
	enable_gain_compensation = gr.Checkbox(value=True, label="Enable Gain Compensation",
	info="Adjusts overall brightness difference before blending when using the detailed stitcher. Recommended.")
	orb_nfeatures = gr.Slider(500, 10000, step=100, value=2000, label="ORB Features",
	info="Maximum ORB keypoints detected per image/frame. Used by the detailed stitcher (for video or image list fallback).")
	match_ratio_thresh = gr.Slider(0.5, 0.95, step=0.01, value=0.75, label="Match Ratio Threshold",
	info="Lowe's ratio test threshold for filtering feature matches (lower = stricter). Used by the detailed stitcher (for video or image list fallback).")
	ransac_reproj_thresh = gr.Slider(1.0, 10.0, step=0.1, value=5.0, label="RANSAC Reproj Threshold",
	info="Maximum reprojection error (pixels) allowed for a match to be considered an inlier by RANSAC during transformation estimation. Lower values are stricter.")
	max_distance_coeff = gr.Slider(0.1, 2.0, step=0.05, value=0.5, label="Max Distance Coeff",
	info="Multiplier for image diagonal used to filter initial matches. Limits the pixel distance between matched keypoints (0.5 means half the diagonal).")
	max_blending_width = gr.Number(value=10000, label="Max Blending Width", precision=0,
	info="Limits the canvas width during the detailed pairwise blending step to prevent excessive memory usage. Relevant for the detailed stitcher.")
	max_blending_height = gr.Number(value=10000, label="Max Blending Height", precision=0,
	info="Limits the canvas height during the detailed pairwise blending step to prevent excessive memory usage. Relevant for the detailed stitcher.")
	blend_smooth_ksize = gr.Number(value=15, label="Blend Smooth Kernel Size", precision=0,
	info="Size of Gaussian kernel to smooth blend mask/weights. Must be POSITIVE ODD integer to enable smoothing (e.g., 5, 15, 21). Set to -1 or an even number to disable smoothing.")
	num_blend_levels = gr.Slider(2, 7, step=1, value=4, label="Multi-Band Blend Levels",
	info="Number of pyramid levels for Multi-Band blending. Fewer levels are faster but might have less smooth transitions.")

	with gr.Accordion("Video Stitcher Settings", open=False):
	sample_interval_ms = gr.Number(value=3000, label="Sample Interval (ms)", precision=0,
	info="Time interval (in milliseconds) between sampled frames for video stitching. Smaller values sample more frames, increasing processing time but potentially improving tracking.")
	max_composite_width_video = gr.Number(value=10000, label="Max Composite Width (Video)", precision=0,
	info="Limits the width of the stitched output during video processing. If exceeded, the current result is saved and stitching restarts with the next frame. 0 = no limit.")
	max_composite_height_video = gr.Number(value=10000, label="Max Composite Height (Video)", precision=0,
	info="Limits the height of the stitched output during video processing. If exceeded, the current result is saved and stitching restarts with the next frame. 0 = no limit.")

	with gr.Accordion("Postprocessing Settings", open=False):
	enable_cropping = gr.Checkbox(value=True, label="Crop Black Borders (Post-Stitch)",
	info="Automatically remove black border areas from the final stitched image(s) AFTER stitching.")
	strict_no_black_edges_checkbox = gr.Checkbox(value=False, label="Strict No Black Edges (Post-Crop)",
	info="If 'Crop Black Borders' is enabled, this forces removal of any remaining black pixels directly on the image edges after the main crop. Might slightly shrink the image further.")

	with gr.Column(scale=1):
	output_gallery = gr.Gallery(
	label="Stitched Results", elem_id="output_gallery", object_fit="contain", type="filepath", rows=2, preview=True, height="auto", format="png", container=True)
	output_log = gr.Textbox(
	label="Status / Log", lines=20, interactive=False, show_copy_button=True)


	# Define the list of inputs for the button click event
	inputs=[
	input_files,
	# Preprocessing
	use_transparency,
	crop_top_percent,
	crop_bottom_percent,
	# OpenCV Stitcher (Image List)
	stitcher_mode, # the selected string ("SCANS", "PANORAMA", or "DIRECT_PAIRWISE")
	registration_resol,
	seam_estimation_resol,
	compositing_resol,
	wave_correction,
	exposure_comp_type,
	# Postprocessing
	enable_cropping,
	strict_no_black_edges_checkbox,
	fixed_base_image_index_input,
	# Detailed Stitcher Settings
	transform_model,
	blend_method,
	enable_gain_compensation,
	orb_nfeatures,
	match_ratio_thresh,
	ransac_reproj_thresh,
	max_distance_coeff,
	max_blending_width,
	max_blending_height,
	blend_smooth_ksize,
	num_blend_levels,
	# Video specific settings
	sample_interval_ms,
	max_composite_width_video,
	max_composite_height_video
	]

	# Define examples (update to include the new transform_model parameter)
	examples = [
	[
	["examples/Wetter-Panorama/Wetter-Panorama1[NIuO6hrFTrg].mp4"],
	True, 0, 20,
	"DIRECT_PAIRWISE", 0.6, 0.1, -1, False, "GAIN_BLOCKS",
	True, False, -1,
	"Homography", "Multi-Band", True, 5000, 0.5, 5.0, 0.5, 10000, 10000, 15, 4,
	2500, 10000, 10000,
	],
	[
	["examples/Wetter-Panorama/Wetter-Panorama2[NIuO6hrFTrg].mp4"],
	True, 0, 20,
	"DIRECT_PAIRWISE", 0.6, 0.1, -1, False, "GAIN_BLOCKS",
	True, False, -1,
	"Homography", "Multi-Band", True, 5000, 0.5, 5.0, 0.5, 10000, 10000, 15, 4,
	2500, 10000, 10000,
	],
	[
	["examples/NieRAutomata/nier2B_01.jpg", "examples/NieRAutomata/nier2B_02.jpg", "examples/NieRAutomata/nier2B_03.jpg", "examples/NieRAutomata/nier2B_04.jpg", "examples/NieRAutomata/nier2B_05.jpg",
	"examples/NieRAutomata/nier2B_06.jpg", "examples/NieRAutomata/nier2B_07.jpg", "examples/NieRAutomata/nier2B_08.jpg", "examples/NieRAutomata/nier2B_09.jpg", "examples/NieRAutomata/nier2B_10.jpg", ],
	True, 0, 0,
	"PANORAMA", 0.6, 0.1, -1, False, "GAIN_BLOCKS",
	True, False, -1,
	"Homography", "Multi-Band", True, 5000, 0.5, 5.0, 0.5, 10000, 10000, 15, 4,
	5000, 10000, 10000,
	],
	[
	["examples/cat/cat_left.jpg", "examples/cat/cat_right.jpg"],
	True, 0, 0,
	"SCANS", 0.6, 0.1, -1, False, "GAIN_BLOCKS",
	True, False, -1,
	"Affine_Partial", "Linear", True, 5000, 0.5, 5.0, 0.5, 10000, 10000, 15, 4,
	5000, 10000, 10000,
	],
	[
	["examples/ギルドの受付嬢ですが/Girumasu_1.jpg", "examples/ギルドの受付嬢ですが/Girumasu_2.jpg", "examples/ギルドの受付嬢ですが/Girumasu_3.jpg"],
	True, 0, 0,
	"PANORAMA", 0.6, 0.1, -1, False, "GAIN_BLOCKS",
	True, False, -1,
	"Affine_Partial", "Linear", True, 5000, 0.65, 5.0, 0.5, 10000, 10000, 15, 4,
	5000, 10000, 10000,
	],
	[
	["examples/photographs1/img1.jpg", "examples/photographs1/img2.jpg", "examples/photographs1/img3.jpg", "examples/photographs1/img4.jpg"],
	True, 0, 0,
	"PANORAMA", 0.6, 0.1, -1, True, "GAIN_BLOCKS",
	True, False, -1,
	"Homography", "Linear", True, 5000, 0.5, 5.0, 0.5, 10000, 10000, 15, 4,
	5000, 10000, 10000,
	]
	]
	gr.Examples(examples, inputs=inputs, label="Example Configurations")

	# Connect button click to the function
	stitch_button.click(
	fn=run_stitching_interface,
	inputs=inputs,
	outputs=[output_gallery, output_log]
	)

	# --- Main Execution Block ---
	if __name__ == "__main__":
	print("Starting Gradio interface with selectable transformation model...")
	# Enable queue for handling multiple requests and progress updates
	demo.queue()
	# Launch the interface
	demo.launch(inbrowser=True)