import cv2 import numpy as np from pathlib import Path import json
def analyze_color_consistency(image_dir: str) -> dict:
"""Analyze color consistency across a set of images"""
stats = []
for img_path in sorted(Path(image_dir).glob("*.jpg")):
img = cv2.imread(str(img_path))
if img is None:
continue
# Convert to LAB color space (closer to human perception)
lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
l, a, b = cv2.split(lab)
stats.append({
"file": img_path.name,
"L_mean": float(l.mean()),
# Luminance mean
"L_std": float(l.std()),
# Luminance std
"a_mean": float(a.mean()),
# Green-red axis mean
"b_mean": float(b.mean()),
# Blue-yellow axis mean
"rgb_mean": img.mean(axis=(0,1)).tolist(),
})
# Coefficient of variation across frames
L_values = [s["L_mean"] for s in stats]
a_values = [s["a_mean"] for s in stats]
b_values = [s["b_mean"] for s in stats]
report = {
"total_frames": len(stats),
"brightness_range": max(L_values) - min(L_values),
"brightness_cv": np.std(L_values) / np.mean(L_values),
# Coefficient of variation
"color_a_range": max(a_values) - min(a_values),
"color_b_range": max(b_values) - min(b_values),
"needs_correction": False,
"severity": "none"
}
# Decide whether correction is needed
if report["brightness_range"] > 30:
report["needs_correction"] = True
report["severity"] = "high"
elif report["brightness_range"] > 15:
report["needs_correction"] = True
report["severity"] = "medium"
elif report["color_a_range"] > 10 or report["color_b_range"] > 10:
report["needs_correction"] = True
report["severity"] = "low"
return report
# Usage example report = analyze_color_consistency("./frames/") print(json.dumps(report, indent=2)) # brightness_range > 30 -> correction required # brightness_range 15-30 -> correction recommended # brightness_range < 15 and color range < 10 -> can skip

import cv2 import numpy as np from pathlib import Path
def estimate_illuminant_gray_world(img: np.ndarray) -> np.ndarray:
"""Estimate illuminant color temperature using the gray-world assumption"""
avg_b = img[:,:,0].mean()
avg_g = img[:,:,1].mean()
avg_r = img[:,:,2].mean()
avg_all = (avg_b + avg_g + avg_r) / 3
gains = np.array([avg_all/avg_b, avg_all/avg_g, avg_all/avg_r])
return gains
def apply_white_balance(img: np.ndarray, gains: np.ndarray) -> np.ndarray:
"""Apply white-balance gains"""
result = img.astype(np.float32)
result[:,:,0] *= gains[0]
# B
result[:,:,1] *= gains[1]
# G
result[:,:,2] *= gains[2]
# R
return np.clip(result, 0, 255).astype(np.uint8)
def unify_white_balance(image_dir: str, output_dir: str, method: str = "reference"):
"""
Unify white balance
method:
- "reference": use the first frame as reference
- "median": use the median across all frames as reference
- "daylight": force D65 daylight white balance
"""
Path(output_dir).mkdir(parents=True, exist_ok=True)
paths = sorted(Path(image_dir).glob("*.jpg"))
if method == "reference":
# Use the first frame's white balance as the target
ref_img = cv2.imread(str(paths[0]))
target_gains = estimate_illuminant_gray_world(ref_img)
elif method == "median":
# Median gains across all frames
all_gains = []
for p in paths:
img = cv2.imread(str(p))
all_gains.append(estimate_illuminant_gray_world(img))
target_gains = np.median(all_gains, axis=0)
elif method == "daylight":
# D65 daylight: assume perfect white balance = unit gains per channel
target_gains = np.array([1.0, 1.0, 1.0])
for p in paths:
img = cv2.imread(str(p))
current_gains = estimate_illuminant_gray_world(img)
# Correction factor from current WB to target WB
correction = target_gains / current_gains
corrected = apply_white_balance(img, correction)
cv2.imwrite(str(Path(output_dir) / p.name), corrected,
[cv2.IMWRITE_JPEG_QUALITY, 98])
print(f"Processed {len(paths)} images, output to {output_dir}")
# Usage unify_white_balance("./frames/", "./frames_wb/", method="median")

import cv2 import numpy as np from pathlib import Path
def match_histogram_lab(source: np.ndarray, reference: np.ndarray) -> np.ndarray:
"""
Histogram matching in LAB space (matches the L channel only)
Keeps color information intact, only aligns brightness distribution
"""
src_lab = cv2.cvtColor(source, cv2.COLOR_BGR2LAB).astype(np.float32)
ref_lab = cv2.cvtColor(reference, cv2.COLOR_BGR2LAB).astype(np.float32)
# Mean-variance match on L only (gentler than full histogram matching)
src_l = src_lab[:,:,0]
ref_l = ref_lab[:,:,0]
# Linear transform: align source L mean and variance to the reference
src_mean, src_std = src_l.mean(), src_l.std()
ref_mean, ref_std = ref_l.mean(), ref_l.std()
# Avoid division by zero
if src_std < 1e-6:
src_std = 1e-6
matched_l = (src_l - src_mean) * (ref_std / src_std) + ref_mean
src_lab[:,:,0] = np.clip(matched_l, 0, 255)
result = cv2.cvtColor(src_lab.astype(np.uint8), cv2.COLOR_LAB2BGR)
return result
def batch_exposure_align(image_dir: str, output_dir: str):
"""Batch exposure alignment using the median-brightness frame as reference"""
Path(output_dir).mkdir(parents=True, exist_ok=True)
paths = sorted(Path(image_dir).glob("*.jpg"))
# Per-frame brightness
brightness = []
for p in paths:
img = cv2.imread(str(p))
lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
brightness.append(lab[:,:,0].mean())
# Pick the median-brightness frame as reference
median_idx = np.argsort(brightness)[len(brightness)//2]
reference = cv2.imread(str(paths[median_idx]))
print(f"Reference frame: {paths[median_idx].name} (L_mean={brightness[median_idx]:.1f})")
for i, p in enumerate(paths):
img = cv2.imread(str(p))
# Only correct when delta exceeds the threshold (avoid unnecessary processing)
if abs(brightness[i] - brightness[median_idx]) > 5:
img = match_histogram_lab(img, reference)
cv2.imwrite(str(Path(output_dir) / p.name), img,
[cv2.IMWRITE_JPEG_QUALITY, 98])
print(f"Exposure alignment complete, processed {len(paths)} frames")
batch_exposure_align("./frames_wb/", "./frames_aligned/")

Format: JPEG (quality 95-98%) or TIFF (lossless) or PNG Color space: sRGB (mandatory! Do not use Adobe RGB or ProPhoto RGB) Resolution: keep original, do not resize Sharpening: OFF (output sharpening alters edge pixels) Metadata: keep all (focal-length info in EXIF is critical for SfM) File naming: keep the original sequence numbers so ordering is preserved

def verify_correction(original_dir: str, corrected_dir: str):
"""Compare consistency metrics before and after correction"""
report_before = analyze_color_consistency(original_dir)
report_after = analyze_color_consistency(corrected_dir)
print("=" * 50)
print("Before vs after correction")
print("=" * 50)
print(f"Brightness range: {report_before['brightness_range']:.1f} -> {report_after['brightness_range']:.1f}")
print(f"Brightness CV:
{report_before['brightness_cv']:.4f} -> {report_after['brightness_cv']:.4f}")
print(f"Chroma a range: {report_before['color_a_range']:.1f} -> {report_after['color_a_range']:.1f}")
print(f"Chroma b range: {report_before['color_b_range']:.1f} -> {report_after['color_b_range']:.1f}")
# Improvement rate
brightness_improvement = (1 - report_after['brightness_range'] /
max(report_before['brightness_range'], 0.01)) * 100
print(f" Brightness consistency improvement: {brightness_improvement:.0f}%")
if report_after['brightness_range'] < 15 and report_after['color_a_range'] < 8:
print("✅ Within target after correction, ready for SfM")
else:
print("⚠️ Still drifting, inspect the outlier frames")
verify_correction("./frames/", "./frames_aligned/")

#!/usr/bin/env python3 """ 06_color_consistency.py Inktoys · Color Grading & Consistency automation script Batch color correction for JPEG/PNG frames (use Lightroom for RAW files) """
import cv2 import numpy as np from pathlib import Path import argparse import json import shutil
class ColorConsistencyPipeline:
def __init__(self, input_dir: str, output_dir: str,
wb_method: str = "median",
brightness_threshold: float = 5.0,
skip_if_consistent: bool = True):
self.input_dir = Path(input_dir)
self.output_dir = Path(output_dir)
self.wb_method = wb_method
self.brightness_threshold = brightness_threshold
self.skip_if_consistent = skip_if_consistent
self.output_dir.mkdir(parents=True, exist_ok=True)
def analyze(self) -> dict:
"""Step 1: analyze current consistency"""
print("[1/4] Analyzing color consistency...")
stats = []
paths = sorted(self.input_dir.glob("*.jpg")) + \
sorted(self.input_dir.glob("*.png"))
for p in paths:
img = cv2.imread(str(p))
if img is None:
continue
lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
l, a, b = cv2.split(lab)
stats.append({
"path": p,
"L_mean": float(l.mean()),
"a_mean": float(a.mean()),
"b_mean": float(b.mean()),
})
L_vals = [s["L_mean"] for s in stats]
a_vals = [s["a_mean"] for s in stats]
b_vals = [s["b_mean"] for s in stats]
self.stats = stats
self.report = {
"total_frames": len(stats),
"L_range": max(L_vals) - min(L_vals),
"L_cv": np.std(L_vals) / np.mean(L_vals),
"a_range": max(a_vals) - min(a_vals),
"b_range": max(b_vals) - min(b_vals),
}
needs_wb = self.report["a_range"] > 8 or self.report["b_range"] > 8
needs_exposure = self.report["L_range"] > 15
self.report["needs_wb"] = needs_wb
self.report["needs_exposure"] = needs_exposure
print(f"
Frame count: {len(stats)}")
print(f"
Brightness range: {self.report['L_range']:.1f} ({'needs correction' if needs_exposure else 'OK'})")
print(f"
Chroma range: a={self.report['a_range']:.1f}, b={self.report['b_range']:.1f} "
f"({'needs correction' if needs_wb else 'OK'})")
return self.report
def correct_white_balance(self):
"""Step 2: white balance unification"""
if not self.report["needs_wb"] and self.skip_if_consistent:
print("[2/4] White balance already consistent, skipping")
return
print(f"[2/4] Unifying white balance (method={self.wb_method})...")
# Compute target gains
all_gains = []
for s in self.stats:
img = cv2.imread(str(s["path"]))
avg = img.mean(axis=(0,1))
avg_all = avg.mean()
gains = avg_all / (avg + 1e-6)
all_gains.append(gains)
if self.wb_method == "median":
target_gains = np.median(all_gains, axis=0)
elif self.wb_method == "reference":
target_gains = all_gains[0]
else:
# daylight
target_gains = np.array([1.0, 1.0, 1.0])
for i, s in enumerate(self.stats):
img = cv2.imread(str(s["path"])).astype(np.float32)
correction = target_gains / (all_gains[i] + 1e-6)
img *= correction[np.newaxis, np.newaxis, :]
img = np.clip(img, 0, 255).astype(np.uint8)
out_path = self.output_dir / s["path"].name
cv2.imwrite(str(out_path), img, [cv2.IMWRITE_JPEG_QUALITY, 98])
print(f"
Processed {len(self.stats)} frames")
def align_exposure(self):
"""Step 3: exposure alignment"""
if not self.report["needs_exposure"] and self.skip_if_consistent:
print("[3/4] Exposure already consistent, skipping")
return
print("[3/4] Aligning exposure...")
# Use white-balance-corrected images if available
source_dir = self.output_dir if any(self.output_dir.iterdir()) else self.input_dir
paths = sorted(source_dir.glob("*.jpg")) + sorted(source_dir.glob("*.png"))
# Compute brightness and pick the median frame
brightness = []
for p in paths:
img = cv2.imread(str(p))
lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
brightness.append(lab[:,:,0].mean())
median_idx = np.argsort(brightness)[len(brightness)//2]
ref = cv2.imread(str(paths[median_idx]))
ref_lab = cv2.cvtColor(ref, cv2.COLOR_BGR2LAB).astype(np.float32)
ref_L_mean = ref_lab[:,:,0].mean()
ref_L_std = ref_lab[:,:,0].std()
for i, p in enumerate(paths):
if abs(brightness[i] - brightness[median_idx]) <= self.brightness_threshold:
# Delta below threshold, copy directly
if source_dir != self.output_dir:
shutil.copy2(str(p), str(self.output_dir / p.name))
continue
img = cv2.imread(str(p))
lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB).astype(np.float32)
src_L_mean = lab[:,:,0].mean()
src_L_std = lab[:,:,0].std() + 1e-6
lab[:,:,0] = (lab[:,:,0] - src_L_mean) * (ref_L_std / src_L_std) + ref_L_mean
lab[:,:,0] = np.clip(lab[:,:,0], 0, 255)
result = cv2.cvtColor(lab.astype(np.uint8), cv2.COLOR_LAB2BGR)
cv2.imwrite(str(self.output_dir / p.name), result,
[cv2.IMWRITE_JPEG_QUALITY, 98])
print(f"
Reference frame: {paths[median_idx].name}")
print(f"
Processed {len(paths)} frames")
def verify(self) -> dict:
"""Step 4: verify the correction"""
print("[4/4] Verifying correction result...")
paths = sorted(self.output_dir.glob("*.jpg")) + \
sorted(self.output_dir.glob("*.png"))
L_vals, a_vals, b_vals = [], [], []
for p in paths:
img = cv2.imread(str(p))
lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
l, a, b = cv2.split(lab)
L_vals.append(l.mean())
a_vals.append(a.mean())
b_vals.append(b.mean())
final_report = {
"L_range": max(L_vals) - min(L_vals),
"a_range": max(a_vals) - min(a_vals),
"b_range": max(b_vals) - min(b_vals),
"L_cv": np.std(L_vals) / np.mean(L_vals),
}
passed = final_report["L_range"] < 15 and \
final_report["a_range"] < 10 and \
final_report["b_range"] < 10
print(f"
Post-correction brightness range: {final_report['L_range']:.1f}")
print(f"
Post-correction chroma range: a={final_report['a_range']:.1f}, b={final_report['b_range']:.1f}")
print(f"
{'✅ Passed! Ready for SfM' if passed else '⚠️ Still drifting, manual inspection recommended'}")
return final_report
def run(self):
"""Run the complete pipeline"""
print("=" * 60)
print("Inktoys · Color Grading & Consistency")
print("=" * 60)
self.analyze()
if not self.report["needs_wb"] and not self.report["needs_exposure"]:
if self.skip_if_consistent:
print(" ✅ Footage is already color-consistent; copying directly to output")
for s in self.stats:
shutil.copy2(str(s["path"]), str(self.output_dir / s["path"].name))
return
self.correct_white_balance()
self.align_exposure()
self.verify()
print(" " + "=" * 60)
print("Done! Output directory:", self.output_dir)
print("=" * 60)
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="3DGS footage color consistency processing")
parser.add_argument("input", help="Input image directory")
parser.add_argument("output", help="Output image directory")
parser.add_argument("--wb-method", choices=["median","reference","daylight"],
default="median", help="White balance method")
parser.add_argument("--threshold", type=float, default=5.0,
help="Brightness delta threshold (no correction below this)")
parser.add_argument("--force", action="store_true",
help="Force correction (even if already consistent)")
args = parser.parse_args()
pipeline = ColorConsistencyPipeline(
args.input, args.output,
wb_method=args.wb_method,
brightness_threshold=args.threshold,
skip_if_consistent=not args.force
)
pipeline.run()

# Basic usage python 06_color_consistency.py ./frames/ ./frames_corrected/
# Force correction + use the first frame as the white-balance reference python 06_color_consistency.py ./frames/ ./frames_corrected/ --wb-method reference --force
# Looser threshold (correct only frames with large drift) python 06_color_consistency.py ./frames/ ./frames_corrected/ --threshold 10

# Mixed-lighting scenes: only enforce inter-frame consistency, not intra-frame uniformity # Use the "reference" method, anchored on the frame that contains the most scene information pipeline = ColorConsistencyPipeline(
"./frames/", "./frames_corrected/",
wb_method="reference",
# Avoid daylight, keep the scene-lighting signature
brightness_threshold=3.0
# Stricter threshold )

COLMAP matching failed? +-- Check: did you grade? │
+-- Yes -> rerun COLMAP on the original frames for comparison │
│
+-- Originals succeed -> over-graded, lighten the parameters │
│
+-- Originals also fail -> issue is not the grading, check other chapters │
+-- No -> grading is not the cause +-- Check: did you use any local adjustments? │
+-- Yes -> remove all local adjustments immediately +-- Check: did you apply a LUT or preset? │
+-- Yes -> remove it, keep only basic adjustments +-- Check: is the export color space sRGB?
+-- No -> re-export as sRGB