Add quaternion validator with configurable tolerances, enhance coreml validation with detailed stats, add PIL-based image preprocessing, introduce batch/image-specific validation functions, update CLI flags for input/output handling.

convert.py

@@ -15,6 +15,7 @@ import coremltools as ct
 import numpy as np
 import torch
 import torch.nn as nn
+from PIL import Image
 
 # Import SHARP model components
 from sharp.models import PredictorParams, create_predictor
@@ -481,11 +482,176 @@ def convert_to_coreml_with_preprocessing(
     return mlmodel
 
 
+class QuaternionValidator:
+    """Validator for quaternion comparisons with configurable tolerances and outlier analysis."""
+
+    DEFAULT_ANGULAR_TOLERANCES = {
+        "mean": 0.01,
+        "p99": 0.5,
+        "p99_9": 2.0,
+        "max": 15.0,
+    }
+
+    def __init__(
+        self,
+        angular_tolerances: dict[str, float] | None = None,
+        enable_outlier_analysis: bool = True,
+        outlier_thresholds: list[float] | None = None,
+    ):
+        """Initialize validator with tolerances.
+
+        Args:
+            angular_tolerances: Dict with keys 'mean', 'p99', 'p99_9', 'max' for angular diffs in degrees.
+            enable_outlier_analysis: Whether to perform detailed outlier analysis.
+            outlier_thresholds: List of angle thresholds for outlier counting.
+        """
+        self.angular_tolerances = angular_tolerances or self.DEFAULT_ANGULAR_TOLERANCES.copy()
+        self.enable_outlier_analysis = enable_outlier_analysis
+        self.outlier_thresholds = outlier_thresholds or [5.0, 10.0, 15.0]
+
+    @staticmethod
+    def canonicalize_quaternion(q: np.ndarray) -> np.ndarray:
+        """Canonicalize quaternion to ensure consistent representation.
+
+        Ensures the quaternion with the largest absolute component is positive.
+        This handles the sign ambiguity where q and -q represent the same rotation.
+
+        Args:
+            q: Quaternion array of shape (..., 4)
+
+        Returns:
+            Canonicalized quaternion array.
+        """
+        abs_q = np.abs(q)
+        max_component_idx = np.argmax(abs_q, axis=-1, keepdims=True)
+        selector = np.zeros_like(q)
+        np.put_along_axis(selector, max_component_idx, 1.0, axis=-1)
+        max_component_sign = np.sum(q * selector, axis=-1, keepdims=True)
+        return np.where(max_component_sign < 0, -q, q)
+
+    @staticmethod
+    def compute_angular_differences(
+        quats1: np.ndarray, quats2: np.ndarray
+    ) -> tuple[np.ndarray, dict[str, float]]:
+        """Compute angular differences between two sets of quaternions.
+
+        Args:
+            quats1: First set of quaternions shape (N, 4)
+            quats2: Second set of quaternions shape (N, 4)
+
+        Returns:
+            Tuple of (angular_differences in degrees, statistics dict)
+        """
+        # Normalize quaternions
+        norm1 = np.linalg.norm(quats1, axis=-1, keepdims=True)
+        norm2 = np.linalg.norm(quats2, axis=-1, keepdims=True)
+        quats1_norm = quats1 / np.clip(norm1, 1e-12, None)
+        quats2_norm = quats2 / np.clip(norm2, 1e-12, None)
+
+        # Canonicalize both
+        quats1_canon = QuaternionValidator.canonicalize_quaternion(quats1_norm)
+        quats2_canon = QuaternionValidator.canonicalize_quaternion(quats2_norm)
+
+        # Compute dot products for both q·q and q·(-q) to handle sign ambiguity
+        dot_products = np.sum(quats1_canon * quats2_canon, axis=-1)
+        dot_products_flipped = np.sum(quats1_canon * (-quats2_canon), axis=-1)
+
+        # Take the maximum absolute dot product (handle sign ambiguity)
+        dot_products = np.maximum(np.abs(dot_products), np.abs(dot_products_flipped))
+        dot_products = np.clip(dot_products, 0.0, 1.0)
+
+        # Compute angular differences
+        angular_diff_rad = 2.0 * np.arccos(dot_products)
+        angular_diff_deg = np.degrees(angular_diff_rad)
+
+        # Compute statistics
+        stats = {
+            "mean": float(np.mean(angular_diff_deg)),
+            "std": float(np.std(angular_diff_deg)),
+            "min": float(np.min(angular_diff_deg)),
+            "max": float(np.max(angular_diff_deg)),
+            "p50": float(np.percentile(angular_diff_deg, 50)),
+            "p90": float(np.percentile(angular_diff_deg, 90)),
+            "p99": float(np.percentile(angular_diff_deg, 99)),
+            "p99_9": float(np.percentile(angular_diff_deg, 99.9)),
+        }
+
+        return angular_diff_deg, stats
+
+    def analyze_outliers(
+        self, angular_diff_deg: np.ndarray
+    ) -> dict[str, dict[str, int | float]]:
+        """Analyze outliers in angular differences.
+
+        Args:
+            angular_diff_deg: Array of angular differences in degrees.
+
+        Returns:
+            Dict with outlier statistics for each threshold.
+        """
+        if not self.enable_outlier_analysis:
+            return {}
+
+        outlier_stats = {}
+        total = len(angular_diff_deg)
+
+        for threshold in self.outlier_thresholds:
+            count = int(np.sum(angular_diff_deg > threshold))
+            outlier_stats[f">{threshold}°"] = {
+                "count": count,
+                "percentage": (count / total) * 100.0 if total > 0 else 0.0,
+            }
+
+        return outlier_stats
+
+    def validate(
+        self,
+        pt_quaternions: np.ndarray,
+        coreml_quaternions: np.ndarray,
+        image_name: str = "Unknown",
+    ) -> dict:
+        """Validate Core ML quaternions against PyTorch quaternions.
+
+        Args:
+            pt_quaternions: PyTorch quaternion outputs.
+            coreml_quaternions: Core ML quaternion outputs.
+            image_name: Name of the image being validated.
+
+        Returns:
+            Dict with validation results including status, stats, and outliers.
+        """
+        angular_diff_deg, stats = self.compute_angular_differences(
+            pt_quaternions, coreml_quaternions
+        )
+        outlier_stats = self.analyze_outliers(angular_diff_deg)
+
+        # Check tolerances
+        passed = True
+        failure_reasons = []
+
+        for key, tolerance in self.angular_tolerances.items():
+            if key in stats and stats[key] > tolerance:
+                passed = False
+                failure_reasons.append(
+                    f"{key} angular {stats[key]:.4f}° > tolerance {tolerance:.4f}°"
+                )
+
+        return {
+            "image": image_name,
+            "passed": passed,
+            "failure_reasons": failure_reasons,
+            "stats": stats,
+            "outliers": outlier_stats,
+            "num_gaussians": len(angular_diff_deg),
+        }
+
+
 def validate_coreml_model(
     mlmodel: ct.models.MLModel,
     pytorch_model: RGBGaussianPredictor,
     input_shape: tuple[int, int] = (1536, 1536),
     tolerance: float = 0.01,
+    angular_tolerances: dict[str, float] | None = None,
 ) -> bool:
     """Validate Core ML model outputs against PyTorch model.
 
@@ -494,6 +660,7 @@ def validate_coreml_model(
         pytorch_model: The original PyTorch model.
         input_shape: Input image shape (height, width).
         tolerance: Maximum allowed difference between outputs.
+        angular_tolerances: Dict with keys 'mean', 'p99', 'p99_9', 'max' for angular diffs in degrees.
 
     Returns:
         True if validation passes, False otherwise.
@@ -527,14 +694,13 @@ def validate_coreml_model(
     }
     coreml_outputs = mlmodel.predict(coreml_inputs)
 
-    # Debug: Print shapes and keys
     LOGGER.info(f"PyTorch outputs shapes: {[o.shape for o in pt_outputs]}")
     LOGGER.info(f"Core ML outputs keys: {list(coreml_outputs.keys())}")
 
-    # Compare outputs with per-output tolerances
+    # Output configuration
     output_names = ["mean_vectors_3d_positions", "singular_values_scales", "quaternions_rotations", "colors_rgb_linear", "opacities_alpha_channel"]
 
-    # Define tighter tolerances per output type
+    # Define tolerances per output type
     tolerances = {
         "mean_vectors_3d_positions": 0.001,
         "singular_values_scales": 0.0001,
@@ -543,12 +709,17 @@ def validate_coreml_model(
         "opacities_alpha_channel": 0.005,
     }
 
-    # Angular tolerances for quaternions (in degrees)
-    angular_tolerances = {
-        "mean": 0.01,
-        "p99": 0.5,
-        "max": 10.0,
-    }
+    # Use provided angular tolerances or defaults
+    if angular_tolerances is None:
+        angular_tolerances = {
+            "mean": 0.01,
+            "p99": 0.1,
+            "p99_9": 1.0,
+            "max": 5.0,
+        }
+
+    # Initialize quaternion validator
+    quat_validator = QuaternionValidator(angular_tolerances=angular_tolerances)
 
     all_passed = True
 
@@ -565,7 +736,7 @@ def validate_coreml_model(
     LOGGER.info(f"Z-coordinate difference - max: {z_diff.max():.6f}, mean: {z_diff.mean():.6f}, std: {z_diff.std():.6f}")
     LOGGER.info("=================================")
 
-    # Collect validation results for table output
+    # Collect validation results
     validation_results = []
 
     for i, name in enumerate(output_names):
@@ -588,14 +759,233 @@ def validate_coreml_model(
         coreml_output = coreml_outputs[coreml_key]
         result = {"output": name, "passed": True, "failure_reason": ""}
 
+        # Special handling for quaternions
+        if name == "quaternions_rotations":
+            # Use the new QuaternionValidator
+            quat_result = quat_validator.validate(pt_output, coreml_output, image_name="Random")
+            
+            result.update({
+                "max_diff": f"{quat_result['stats']['max']:.6f}",
+                "mean_diff": f"{quat_result['stats']['mean']:.6f}",
+                "p99_diff": f"{quat_result['stats']['p99']:.6f}",
+                "p99_9_diff": f"{quat_result['stats']['p99_9']:.6f}",
+                "max_angular": f"{quat_result['stats']['max']:.4f}",
+                "mean_angular": f"{quat_result['stats']['mean']:.4f}",
+                "p99_angular": f"{quat_result['stats']['p99']:.4f}",
+                "passed": quat_result["passed"],
+                "failure_reason": "; ".join(quat_result["failure_reasons"]) if quat_result["failure_reasons"] else "",
+                "quat_stats": quat_result["stats"],
+                "outliers": quat_result["outliers"],
+            })
+            if not quat_result["passed"]:
+                all_passed = False
+        else:
+            diff = np.abs(pt_output - coreml_output)
+            output_tolerance = tolerances.get(name, tolerance)
+            result.update({
+                "max_diff": f"{np.max(diff):.6f}",
+                "mean_diff": f"{np.mean(diff):.6f}",
+                "p99_diff": f"{np.percentile(diff, 99):.6f}",
+                "tolerance": f"{output_tolerance:.6f}"
+            })
+            if np.max(diff) > output_tolerance:
+                result["passed"] = False
+                result["failure_reason"] = f"max diff {np.max(diff):.6f} > tolerance {output_tolerance:.6f}"
+                all_passed = False
+
+        validation_results.append(result)
+
+    # Output validation results as markdown table
+    LOGGER.info("\n### Validation Results\n")
+    LOGGER.info("| Output | Max Diff | Mean Diff | P99 Diff | P99.9 Diff | Angular Diff (°) | Status |")
+    LOGGER.info("|--------|----------|-----------|----------|------------|------------------|--------|")
+
+    for result in validation_results:
+        output_name = result["output"].replace("_", " ").title()
+        if "max_angular" in result:
+            angular_info = f"{result['max_angular']} / {result['mean_angular']} / {result['p99_angular']}"
+            p99_9 = result.get("p99_9_diff", "-")
+            status = "✅ PASS" if result["passed"] else f"❌ FAIL"
+            LOGGER.info(f"| {output_name} | {result['max_diff']} | {result['mean_diff']} | {result['p99_diff']} | {p99_9} | {angular_info} | {status} |")
+        else:
+            status = "✅ PASS" if result["passed"] else f"❌ FAIL"
+            LOGGER.info(f"| {output_name} | {result['max_diff']} | {result['mean_diff']} | {result['p99_diff']} | - | - | {status} |")
+    LOGGER.info("")
+
+    # Output quaternion outlier analysis if available
+    for result in validation_results:
+        if "outliers" in result and result["outliers"]:
+            LOGGER.info("### Quaternion Outlier Analysis\n")
+            LOGGER.info(f"| Threshold | Count | Percentage |")
+            LOGGER.info("|-----------|-------|------------|")
+            for threshold, data in result["outliers"].items():
+                LOGGER.info(f"| {threshold} | {data['count']} | {data['percentage']:.4f}% |")
+            LOGGER.info("")
+
+    return all_passed
+
+
+def load_and_preprocess_image(
+    image_path: Path,
+    target_size: tuple[int, int] = (1536, 1536),
+) -> torch.Tensor:
+    """Load and preprocess an input image for SHARP inference.
+
+    Args:
+        image_path: Path to the input image file.
+        target_size: Target (height, width) for resizing.
+
+    Returns:
+        Preprocessed image tensor of shape (1, 3, H, W) in range [0, 1].
+    """
+    LOGGER.info(f"Loading image from {image_path}")
+    
+    # Load image using PIL
+    image = Image.open(image_path)
+    
+    # Convert to RGB if needed (handle grayscale or RGBA)
+    if image.mode != "RGB":
+        image = image.convert("RGB")
+    
+    original_size = image.size  # (width, height)
+    LOGGER.info(f"Original image size: {original_size}")
+    
+    # Resize to target size if different
+    if (image.width, image.height) != target_size:
+        LOGGER.info(f"Resizing to {target_size[1]}x{target_size[0]}")
+        image = image.resize((target_size[1], target_size[0]), Image.BILINEAR)
+    
+    # Convert to numpy array and normalize to [0, 1]
+    image_np = np.array(image, dtype=np.float32) / 255.0
+    
+    # Transpose to (C, H, W) and add batch dimension
+    # PIL images are (W, H, C), numpy is (H, W, C)
+    image_np = image_np.transpose(2, 0, 1)  # (3, H, W)
+    image_tensor = torch.from_numpy(image_np).unsqueeze(0)  # (1, 3, H, W)
+    
+    LOGGER.info(f"Preprocessed image shape: {image_tensor.shape}, range: [{image_tensor.min():.4f}, {image_tensor.max():.4f}]")
+    
+    return image_tensor
+
+
+def validate_with_image(
+    mlmodel: ct.models.MLModel,
+    pytorch_model: RGBGaussianPredictor,
+    image_path: Path,
+    input_shape: tuple[int, int] = (1536, 1536),
+) -> bool:
+    """Validate Core ML model outputs against PyTorch model using a real input image.
+
+    Args:
+        mlmodel: The Core ML model to validate.
+        pytorch_model: The original PyTorch model.
+        image_path: Path to the input image file.
+        input_shape: Expected input image shape (height, width).
+
+    Returns:
+        True if validation passes, False otherwise.
+    """
+    LOGGER.info("=" * 60)
+    LOGGER.info("Validating Core ML model against PyTorch with real image")
+    LOGGER.info("=" * 60)
+    
+    # Load and preprocess the input image
+    test_image = load_and_preprocess_image(image_path, input_shape)
+    test_disparity = np.array([1.0], dtype=np.float32)
+    
+    # Run PyTorch model
+    traceable_wrapper = SharpModelTraceable(pytorch_model)
+    traceable_wrapper.eval()
+    
+    with torch.no_grad():
+        pt_outputs = traceable_wrapper(test_image, torch.from_numpy(test_disparity))
+    
+    LOGGER.info(f"PyTorch outputs shapes: {[o.shape for o in pt_outputs]}")
+    
+    # Run Core ML model
+    test_image_np = test_image.numpy()
+    coreml_inputs = {
+        "image": test_image_np,
+        "disparity_factor": test_disparity,
+    }
+    coreml_outputs = mlmodel.predict(coreml_inputs)
+    
+    LOGGER.info(f"Core ML outputs keys: {list(coreml_outputs.keys())}")
+    
+    # Output configuration
+    output_names = ["mean_vectors_3d_positions", "singular_values_scales", "quaternions_rotations", "colors_rgb_linear", "opacities_alpha_channel"]
+    
+    # Define tolerances per output type for real image validation
+    # Using p99-based tolerances to handle outliers better
+    tolerances = {
+        "mean_vectors_3d_positions": 1.2,
+        "singular_values_scales": 0.01,
+        "quaternions_rotations": 5.0,
+        "colors_rgb_linear": 0.01,
+        "opacities_alpha_channel": 0.05,
+    }
+    
+    # Angular tolerances for quaternions (in degrees)
+    angular_tolerances = {
+        "mean": 0.1,
+        "p99": 1.0,
+        "max": 15.0,
+    }
+    
+    all_passed = True
+    
+    # Log input image statistics
+    LOGGER.info(f"\n=== Input Image Statistics ===")
+    LOGGER.info(f"Image path: {image_path}")
+    LOGGER.info(f"Image shape: {test_image.shape}")
+    LOGGER.info(f"Image range: [{test_image.min():.4f}, {test_image.max():.4f}]")
+    LOGGER.info(f"Image mean: {test_image.mean(dim=[1,2,3]).tolist()}")
+    LOGGER.info("=" * 30)
+    
+    # Depth/position analysis
+    pt_positions = pt_outputs[0].numpy()
+    coreml_key = [k for k in coreml_outputs.keys() if "mean_vectors" in k][0]
+    coreml_positions = coreml_outputs[coreml_key]
+    
+    LOGGER.info("\n=== Depth/Position Statistics ===")
+    LOGGER.info(f"PyTorch positions - Z range: [{pt_positions[..., 2].min():.4f}, {pt_positions[..., 2].max():.4f}], mean: {pt_positions[..., 2].mean():.4f}, std: {pt_positions[..., 2].std():.4f}")
+    LOGGER.info(f"CoreML positions - Z range: [{coreml_positions[..., 2].min():.4f}, {coreml_positions[..., 2].max():.4f}], mean: {coreml_positions[..., 2].mean():.4f}, std: {coreml_positions[..., 2].std():.4f}")
+    
+    z_diff = np.abs(pt_positions[..., 2] - coreml_positions[..., 2])
+    LOGGER.info(f"Z-coordinate difference - max: {z_diff.max():.6f}, mean: {z_diff.mean():.6f}, std: {z_diff.std():.6f}")
+    LOGGER.info("=================================\n")
+    
+    # Collect validation results
+    validation_results = []
+    
+    for i, name in enumerate(output_names):
+        pt_output = pt_outputs[i].numpy()
+        
+        # Find matching Core ML output
+        coreml_key = None
+        if name in coreml_outputs:
+            coreml_key = name
+        else:
+            # Try partial match
+            for key in coreml_outputs:
+                base_name = name.split('_')[0]
+                if base_name in key.lower():
+                    coreml_key = key
+                    break
+            if coreml_key is None:
+                coreml_key = list(coreml_outputs.keys())[i]
+        
+        coreml_output = coreml_outputs[coreml_key]
+        result = {"output": name, "passed": True, "failure_reason": ""}
+        
         # Special handling for quaternions
         if name == "quaternions_rotations":
             pt_quat_norm = np.linalg.norm(pt_output, axis=-1, keepdims=True)
             pt_output_normalized = pt_output / np.clip(pt_quat_norm, 1e-12, None)
-
+            
             coreml_quat_norm = np.linalg.norm(coreml_output, axis=-1, keepdims=True)
             coreml_output_normalized = coreml_output / np.clip(coreml_quat_norm, 1e-12, None)
-
+            
             def canonicalize_quaternion(q):
                 abs_q = np.abs(q)
                 max_component_idx = np.argmax(abs_q, axis=-1, keepdims=True)
@@ -603,22 +993,30 @@ def validate_coreml_model(
                 np.put_along_axis(selector, max_component_idx, 1, axis=-1)
                 max_component_sign = np.sum(q * selector, axis=-1, keepdims=True)
                 return np.where(max_component_sign < 0, -q, q)
-
+            
             pt_output_canonical = canonicalize_quaternion(pt_output_normalized)
             coreml_output_canonical = canonicalize_quaternion(coreml_output_normalized)
-
+            
             diff = np.abs(pt_output_canonical - coreml_output_canonical)
             dot_products = np.sum(pt_output_canonical * coreml_output_canonical, axis=-1)
-            dot_products = np.clip(np.abs(dot_products), 0.0, 1.0)
+            dot_products_flipped = np.sum(pt_output_canonical * (-coreml_output_canonical), axis=-1)
+            # Take the absolute value and ensure we compare q with -q if needed
+            # This handles the sign ambiguity: q and -q represent the same rotation
+            dot_products = np.where(
+                np.abs(dot_products) > np.abs(dot_products_flipped),
+                np.abs(dot_products),
+                np.abs(dot_products_flipped)
+            )
+            dot_products = np.clip(dot_products, 0.0, 1.0)
             angular_diff_rad = 2 * np.arccos(dot_products)
             angular_diff_deg = np.degrees(angular_diff_rad)
             max_angular = np.max(angular_diff_deg)
             mean_angular = np.mean(angular_diff_deg)
             p99_angular = np.percentile(angular_diff_deg, 99)
-
+            
             quat_passed = True
             failure_reasons = []
-
+            
             if mean_angular > angular_tolerances["mean"]:
                 quat_passed = False
                 failure_reasons.append(f"mean angular {mean_angular:.4f}° > {angular_tolerances['mean']:.4f}°")
@@ -628,7 +1026,7 @@ def validate_coreml_model(
             if max_angular > angular_tolerances["max"]:
                 quat_passed = False
                 failure_reasons.append(f"max angular {max_angular:.4f}° > {angular_tolerances['max']:.4f}°")
-
+            
             result.update({
                 "max_diff": f"{np.max(diff):.6f}",
                 "mean_diff": f"{np.mean(diff):.6f}",
@@ -643,7 +1041,7 @@ def validate_coreml_model(
                 all_passed = False
         else:
             diff = np.abs(pt_output - coreml_output)
-            output_tolerance = tolerances.get(name, tolerance)
+            output_tolerance = tolerances.get(name, 0.01)
             result.update({
                 "max_diff": f"{np.max(diff):.6f}",
                 "mean_diff": f"{np.mean(diff):.6f}",
@@ -654,24 +1052,197 @@ def validate_coreml_model(
                 result["passed"] = False
                 result["failure_reason"] = f"max diff {np.max(diff):.6f} > tolerance {output_tolerance:.6f}"
                 all_passed = False
-
+        
         validation_results.append(result)
-
+    
     # Output validation results as markdown table
-    if validation_results:
-        LOGGER.info("\n### Validation Results\n")
-        LOGGER.info("| Output | Max Diff | Mean Diff | P99 Diff | Angular Diff (°) | Status |")
-        LOGGER.info("|--------|----------|-----------|----------|------------------|--------|")
-
-        for result in validation_results:
-            output_name = result["output"].replace("_", " ").title()
-            if "max_angular" in result:
-                angular_info = f"{result['max_angular']} / {result['mean_angular']} / {result['p99_angular']}"
-            else:
-                angular_info = "-"
-            status = "✅ PASS" if result["passed"] else f"❌ FAIL"
-            LOGGER.info(f"| {output_name} | {result['max_diff']} | {result['mean_diff']} | {result['p99_diff']} | {angular_info} | {status} |")
-        LOGGER.info("")
+    LOGGER.info("\n### Image Validation Results\n")
+    LOGGER.info(f"| Output | Max Diff | Mean Diff | P99 Diff | Angular Diff (°) | Status |")
+    LOGGER.info(f"|--------|----------|-----------|----------|------------------|--------|")
+    
+    for result in validation_results:
+        output_name = result["output"].replace("_", " ").title()
+        if "max_angular" in result:
+            angular_info = f"{result['max_angular']} / {result['mean_angular']} / {result['p99_angular']}"
+        else:
+            angular_info = "-"
+        status = "✅ PASS" if result["passed"] else f"❌ FAIL"
+        LOGGER.info(f"| {output_name} | {result['max_diff']} | {result['mean_diff']} | {result['p99_diff']} | {angular_info} | {status} |")
+    LOGGER.info("")
+    
+    return all_passed
+
+
+def validate_with_image_set(
+    mlmodel: ct.models.MLModel,
+    pytorch_model: RGBGaussianPredictor,
+    image_paths: list[Path],
+    input_shape: tuple[int, int] = (1536, 1536),
+) -> bool:
+    """Validate Core ML model against PyTorch using multiple input images.
+
+    Args:
+        mlmodel: The Core ML model to validate.
+        pytorch_model: The original PyTorch model.
+        image_paths: List of paths to input images for validation.
+        input_shape: Expected input image shape (height, width).
+
+    Returns:
+        True if all validations pass, False otherwise.
+    """
+    LOGGER.info("=" * 60)
+    LOGGER.info(f"Validating Core ML model with {len(image_paths)} images")
+    LOGGER.info("=" * 60)
+
+    # Angular tolerances for image validation (more lenient than random validation)
+    # Real images have more variation than random noise
+    angular_tolerances = {
+        "mean": 0.2,
+        "p99": 2.0,
+        "p99_9": 5.0,
+        "max": 25.0,
+    }
+
+    # Initialize quaternion validator
+    quat_validator = QuaternionValidator(angular_tolerances=angular_tolerances)
+
+    all_passed = True
+    image_results = []
+
+    for image_path in image_paths:
+        if not image_path.exists():
+            LOGGER.error(f"Input image not found: {image_path}")
+            all_passed = False
+            continue
+
+        LOGGER.info(f"\n--- Validating with {image_path.name} ---")
+
+        # Run validation for this image
+        passed = validate_with_single_image(
+            mlmodel, pytorch_model, image_path, input_shape, quat_validator
+        )
+        image_results.append({"image": image_path.name, "passed": passed})
+
+        if not passed:
+            all_passed = False
+
+    # Output summary table
+    LOGGER.info("\n" + "=" * 60)
+    LOGGER.info("### Multi-Image Validation Summary")
+    LOGGER.info("=" * 60)
+    LOGGER.info(f"| Image | Status |")
+    LOGGER.info("|-------|--------|")
+
+    for result in image_results:
+        status = "✅ PASS" if result["passed"] else "❌ FAIL"
+        LOGGER.info(f"| {result['image']} | {status} |")
+
+    LOGGER.info("")
+
+    return all_passed
+
+
+def validate_with_single_image(
+    mlmodel: ct.models.MLModel,
+    pytorch_model: RGBGaussianPredictor,
+    image_path: Path,
+    input_shape: tuple[int, int],
+    quat_validator: QuaternionValidator | None = None,
+) -> bool:
+    """Validate with a single image using the new QuaternionValidator.
+
+    Args:
+        mlmodel: The Core ML model to validate.
+        pytorch_model: The original PyTorch model.
+        image_path: Path to the input image file.
+        input_shape: Expected input image shape.
+        quat_validator: Optional QuaternionValidator instance.
+
+    Returns:
+        True if validation passes, False otherwise.
+    """
+    # Load and preprocess the input image
+    test_image = load_and_preprocess_image(image_path, input_shape)
+    test_disparity = np.array([1.0], dtype=np.float32)
+
+    # Run PyTorch model
+    traceable_wrapper = SharpModelTraceable(pytorch_model)
+    traceable_wrapper.eval()
+
+    with torch.no_grad():
+        pt_outputs = traceable_wrapper(test_image, torch.from_numpy(test_disparity))
+
+    # Run Core ML model
+    test_image_np = test_image.numpy()
+    coreml_inputs = {
+        "image": test_image_np,
+        "disparity_factor": test_disparity,
+    }
+    coreml_outputs = mlmodel.predict(coreml_inputs)
+
+    # Output configuration
+    output_names = ["mean_vectors_3d_positions", "singular_values_scales", "quaternions_rotations", "colors_rgb_linear", "opacities_alpha_channel"]
+
+    # Tolerances for real image validation
+    tolerances = {
+        "mean_vectors_3d_positions": 1.2,
+        "singular_values_scales": 0.01,
+        "colors_rgb_linear": 0.01,
+        "opacities_alpha_channel": 0.05,
+    }
+
+    # Use provided validator or create default
+    if quat_validator is None:
+        quat_validator = QuaternionValidator()
+
+    # Log input image statistics
+    LOGGER.info(f"Image: {image_path.name}, shape: {test_image.shape}, range: [{test_image.min():.4f}, {test_image.max():.4f}]")
+
+    # Collect validation results
+    all_passed = True
+
+    for i, name in enumerate(output_names):
+        pt_output = pt_outputs[i].numpy()
+
+        # Find matching Core ML output
+        coreml_key = None
+        if name in coreml_outputs:
+            coreml_key = name
+        else:
+            for key in coreml_outputs:
+                base_name = name.split('_')[0]
+                if base_name in key.lower():
+                    coreml_key = key
+                    break
+            if coreml_key is None:
+                coreml_key = list(coreml_outputs.keys())[i]
+
+        coreml_output = coreml_outputs[coreml_key]
+
+        if name == "quaternions_rotations":
+            # Use QuaternionValidator
+            quat_result = quat_validator.validate(pt_output, coreml_output, image_name=image_path.name)
+
+            LOGGER.info(f"Quaternions: mean={quat_result['stats']['mean']:.4f}°, p99={quat_result['stats']['p99']:.4f}°, max={quat_result['stats']['max']:.4f}°")
+
+            # Output outlier analysis
+            if quat_result["outliers"]:
+                for threshold, data in quat_result["outliers"].items():
+                    LOGGER.info(f"  {threshold}: {data['count']} ({data['percentage']:.4f}%)")
+
+            if not quat_result["passed"]:
+                LOGGER.warning(f"  ⚠️ Quaternion validation failed: {'; '.join(quat_result['failure_reasons'])}")
+                all_passed = False
+        else:
+            diff = np.abs(pt_output - coreml_output)
+            output_tolerance = tolerances.get(name, 0.01)
+            max_diff = np.max(diff)
+
+            LOGGER.info(f"{name}: max_diff={max_diff:.6f}, mean_diff={np.mean(diff):.6f}")
+
+            if max_diff > output_tolerance:
+                LOGGER.warning(f"  ⚠️ {name} failed: max_diff {max_diff:.6f} > tolerance {output_tolerance:.6f}")
+                all_passed = False
 
     return all_passed
 
@@ -726,6 +1297,31 @@ def main():
         action="store_true",
         help="Enable verbose logging",
     )
+    parser.add_argument(
+        "--input-image",
+        type=Path,
+        default=None,
+        action="append",
+        help="Path to input image for validation (can be specified multiple times, requires --validate)",
+    )
+    parser.add_argument(
+        "--tolerance-mean",
+        type=float,
+        default=None,
+        help="Custom mean angular tolerance in degrees (default: 0.01 for random, 0.1 for images)",
+    )
+    parser.add_argument(
+        "--tolerance-p99",
+        type=float,
+        default=None,
+        help="Custom P99 angular tolerance in degrees (default: 0.5 for random, 1.0 for images)",
+    )
+    parser.add_argument(
+        "--tolerance-max",
+        type=float,
+        default=None,
+        help="Custom max angular tolerance in degrees (default: 15.0)",
+    )
 
     args = parser.parse_args()
 
@@ -764,7 +1360,21 @@ def main():
 
     # Validate if requested
     if args.validate:
-        validation_passed = validate_coreml_model(mlmodel, predictor, input_shape)
+        if args.input_image:
+            # Validate with one or more real input images
+            validation_passed = validate_with_image_set(mlmodel, predictor, args.input_image, input_shape)
+        else:
+            # Validate with random input (default behavior)
+            # Build custom angular tolerances from CLI args
+            angular_tolerances = None
+            if args.tolerance_mean or args.tolerance_p99 or args.tolerance_max:
+                angular_tolerances = {
+                    "mean": args.tolerance_mean if args.tolerance_mean else 0.01,
+                    "p99": args.tolerance_p99 if args.tolerance_p99 else 0.5,
+                    "p99_9": 2.0,
+                    "max": args.tolerance_max if args.tolerance_max else 15.0,
+                }
+            validation_passed = validate_coreml_model(mlmodel, predictor, input_shape, angular_tolerances=angular_tolerances)
 
         if validation_passed:
             LOGGER.info("✓ Validation passed!")

sharp.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:9bb25d6180e305984d1faeda322c433079999895ea78fda5ea9fe02d63d92bd3
+oid sha256:c36e0aa4ffde76052412f2c399cd140781e614ba732c33e9b72b9f8d7d1fe002
 size 938777

sharp.mlpackage/Manifest.json

@@ -1,18 +1,18 @@
 {
     "fileFormatVersion": "1.0.0",
     "itemInfoEntries": {
-        "B664B39D-DCBF-4A11-A7D6-74633C44EFCF": {
-            "author": "com.apple.CoreML",
-            "description": "CoreML Model Specification",
-            "name": "model.mlmodel",
-            "path": "com.apple.CoreML/model.mlmodel"
-        },
-        "D768A76E-EC7C-4ED0-91C5-FF591F7D5359": {
+        "8EBB39F7-795C-4451-A2EE-090F6695386A": {
             "author": "com.apple.CoreML",
             "description": "CoreML Model Weights",
             "name": "weights",
             "path": "com.apple.CoreML/weights"
+        },
+        "97AA1BE5-373D-4A1B-B3DF-74F91F8B0AFE": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
         }
     },
-    "rootModelIdentifier": "B664B39D-DCBF-4A11-A7D6-74633C44EFCF"
+    "rootModelIdentifier": "97AA1BE5-373D-4A1B-B3DF-74F91F8B0AFE"
 }

test.ply

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:20c37e93b212cb2fee9cfbebf4b1abffb15baacf38e7983364f07a228be7ab14
+oid sha256:b08f5a8cc6f1afffae48c257f0bf51b5f66dc0a13ff02aca16fc8ffe0a9d7f4f
 size 33030941