Download model_cgd.py from maxwoe/image-rotation-angle-estimation: direct link, hf CLI and curl.
- Browser
- Download file 13.1 kB
-
https://huggingface.co/maxwoe/image-rotation-angle-estimation/resolve/main/model_cgd.py
- Command line
-
hf download hf://maxwoe/image-rotation-angle-estimation/model_cgd.py
-
curl -L -o model_cgd.py https://huggingface.co/maxwoe/image-rotation-angle-estimation/resolve/main/model_cgd.py
13.1 kB
| """ | |
| Circular Gaussian Distribution (CGD) for Image Orientation Estimation (Inference Only) | |
| Represents angles as probability distributions over discretized angle bins. | |
| Model output: Probability distribution over 360 angle bins (1 degree resolution) | |
| """ | |
| import math | |
| from typing import Dict, Any | |
| import torch | |
| import torch.nn as nn | |
| import torch.nn.functional as F | |
| import torchvision.transforms as transforms | |
| import pytorch_lightning as pl | |
| import timm | |
| import timm.data | |
| from PIL import Image | |
| import numpy as np | |
| from loguru import logger | |
| class CircularGaussianDistribution(nn.Module): | |
| """Circular Gaussian Distribution module for 360 degree image orientation.""" | |
| # half-width of the window of the 'local_weighted_average' decoding, in degrees | |
| LOCAL_WINDOW_DEGREES = 10.0 | |
| def __init__(self, num_bins: int = 360, sigma: float = 6.0): | |
| super().__init__() | |
| self.num_bins = num_bins | |
| self.sigma = sigma | |
| self.bin_size = 360.0 / num_bins | |
| bin_centers = torch.arange(0, 360, self.bin_size) | |
| self.register_buffer('bin_centers', bin_centers) | |
| logger.info(f"CGD: {num_bins} bins, range [0, 360), sigma={sigma}") | |
| def distribution_to_angle(self, distributions: torch.Tensor, method: str = 'argmax') -> torch.Tensor: | |
| """Extract angles from probability distributions. | |
| Args: | |
| distributions: Probability distributions [B, num_bins] | |
| method: 'argmax' (most probable bin), 'local_weighted_average' (circular mean of the | |
| bins within 10 degrees of it), 'weighted_average' or 'peak_fitting' | |
| Returns: | |
| angles: Extracted angles in degrees [B] in [0, 360) | |
| """ | |
| if method == 'argmax': | |
| peak_indices = torch.argmax(distributions, dim=1) | |
| angles = self.bin_centers[peak_indices] | |
| elif method == 'weighted_average': | |
| weights = distributions / (distributions.sum(dim=1, keepdim=True) + 1e-8) | |
| bin_angles_rad = self.bin_centers * torch.pi / 180.0 | |
| cos_components = torch.cos(bin_angles_rad) | |
| sin_components = torch.sin(bin_angles_rad) | |
| avg_cos = torch.sum(weights * cos_components.unsqueeze(0), dim=1) | |
| avg_sin = torch.sum(weights * sin_components.unsqueeze(0), dim=1) | |
| angles = torch.atan2(avg_sin, avg_cos) * 180.0 / torch.pi | |
| angles = angles % 360.0 | |
| elif method == 'peak_fitting': | |
| peak_indices = torch.argmax(distributions, dim=1) | |
| angles = torch.zeros_like(peak_indices, dtype=torch.float) | |
| for i in range(distributions.shape[0]): | |
| peak_idx = peak_indices[i].item() | |
| if 0 < peak_idx < self.num_bins - 1: | |
| y1 = distributions[i, peak_idx - 1] | |
| y2 = distributions[i, peak_idx] | |
| y3 = distributions[i, peak_idx + 1] | |
| a = 0.5 * (y1 - 2*y2 + y3) | |
| b = 0.5 * (y3 - y1) | |
| if abs(a) > 1e-8: | |
| offset = -b / (2 * a) | |
| offset = torch.clamp(offset, -0.5, 0.5) | |
| else: | |
| offset = 0 | |
| angles[i] = self.bin_centers[peak_idx] + offset * self.bin_size | |
| else: | |
| angles[i] = self.bin_centers[peak_idx] | |
| elif method == 'local_weighted_average': | |
| # Circular mean of the bins within LOCAL_WINDOW_DEGREES of the most probable bin: | |
| # sub-bin precision without the pull of a second peak elsewhere on the circle | |
| half_width = int(round(self.LOCAL_WINDOW_DEGREES / self.bin_size)) | |
| peak_indices = torch.argmax(distributions, dim=1, keepdim=True) | |
| offsets = torch.arange(-half_width, half_width + 1, device=distributions.device) | |
| index = (peak_indices + offsets) % self.num_bins | |
| weights = distributions.gather(1, index) | |
| bin_angles_rad = self.bin_centers[index] * torch.pi / 180.0 | |
| avg_cos = torch.sum(weights * torch.cos(bin_angles_rad), dim=1) | |
| avg_sin = torch.sum(weights * torch.sin(bin_angles_rad), dim=1) | |
| angles = torch.atan2(avg_sin, avg_cos) * 180.0 / torch.pi | |
| else: | |
| raise ValueError(f"Unknown extraction method: {method}") | |
| angles = angles % 360.0 | |
| return angles | |
| def get_distribution_uncertainty(self, distributions: torch.Tensor) -> torch.Tensor: | |
| """Calculate entropy-based uncertainty from distribution.""" | |
| log_probs = torch.log(distributions + 1e-8) | |
| entropy = -torch.sum(distributions * log_probs, dim=1) | |
| max_entropy = math.log(self.num_bins) | |
| return entropy / max_entropy | |
| def peak_mass(self, distributions: torch.Tensor, window_degrees: float = 10.0) -> torch.Tensor: | |
| """Probability mass within +-window_degrees of the most probable angle (circular). | |
| The raw score behind the confidence value. A second peak elsewhere, or a flat | |
| distribution, lowers it. | |
| """ | |
| half_width = int(round(window_degrees / self.bin_size)) | |
| peak_indices = torch.argmax(distributions, dim=1, keepdim=True) | |
| offsets = torch.arange(-half_width, half_width + 1, device=distributions.device) | |
| return distributions.gather(1, (peak_indices + offsets) % self.num_bins).sum(dim=1) | |
| class CGDAngleEstimation(pl.LightningModule): | |
| """CGD model for 360 degree image orientation estimation (inference only).""" | |
| def __init__( | |
| self, | |
| batch_size: int = 16, | |
| train_dir: str = "", | |
| model_name: str = "vit_tiny_patch16_224", | |
| learning_rate: float = 0.001, | |
| validation_split: float = 0.1, | |
| random_seed: int = 42, | |
| image_size: int = 224, | |
| num_bins: int = 360, | |
| sigma: float = 6.0, | |
| inference_method: str = 'argmax', | |
| loss_type: str = 'kl_divergence', | |
| test_dir=None, | |
| test_rotation_range=360.0, | |
| test_random_seed=42, | |
| ) -> None: | |
| super().__init__() | |
| self.save_hyperparameters() | |
| self.model_name = model_name | |
| self.learning_rate = learning_rate | |
| self.batch_size = batch_size | |
| self.train_dir = train_dir | |
| self.validation_split = validation_split | |
| self.random_seed = random_seed | |
| self.image_size = image_size | |
| self.num_bins = num_bins | |
| self.sigma = sigma | |
| self.inference_method = inference_method | |
| self.loss_type = loss_type | |
| # inference only: every weight comes from the checkpoint, so the ImageNet weights | |
| # of the backbone are not downloaded | |
| self.model = timm.create_model(model_name, pretrained=False, num_classes=num_bins) | |
| self.cgd = CircularGaussianDistribution(num_bins=num_bins, sigma=sigma) | |
| # {"window_degrees", "slope", "intercept"} of the checkpoint, set by from_pretrained | |
| # from config.json; None for a checkpoint whose confidence was not calibrated | |
| self.confidence_calibration = None | |
| def try_load(cls, checkpoint_path=None, **kwargs): | |
| """Load model from checkpoint.""" | |
| if checkpoint_path: | |
| logger.info(f"Loading model from checkpoint: {checkpoint_path}") | |
| model = cls.load_from_checkpoint(checkpoint_path, **kwargs) | |
| logger.info("Model loaded successfully from checkpoint") | |
| return model | |
| raise FileNotFoundError("Checkpoint file not found") | |
| def from_pretrained(cls, repo_id, model_name=None): | |
| """Load a pretrained model from HuggingFace Hub. | |
| Args: | |
| repo_id: HuggingFace repo ID (e.g. "maxwoe/image-rotation-angle-estimation") | |
| model_name: Display name or checkpoint filename from config.json. | |
| Defaults to the default model. | |
| """ | |
| import json | |
| from huggingface_hub import hf_hub_download | |
| config_path = hf_hub_download(repo_id=repo_id, filename="config.json") | |
| with open(config_path) as f: | |
| config = json.load(f) | |
| if model_name is None: | |
| model_name = config["default_model"] | |
| # Look up by display name or by filename | |
| if model_name in config["models"]: | |
| model_info = config["models"][model_name] | |
| else: | |
| model_info = None | |
| for info in config["models"].values(): | |
| if info["filename"] == model_name: | |
| model_info = info | |
| break | |
| if model_info is None: | |
| available = [i["filename"] for i in config["models"].values()] | |
| raise ValueError(f"Unknown model: {model_name}. Available: {available}") | |
| ckpt_path = hf_hub_download(repo_id=repo_id, filename=model_info["filename"]) | |
| model = cls.try_load(checkpoint_path=ckpt_path, image_size=model_info["input_size"]) | |
| model.apply_config(model_info) | |
| model.eval() | |
| return model | |
| def apply_config(self, model_info): | |
| """Take the settings of a checkpoint from its entry in config.json. | |
| "decoding" names the method that turns the output distribution into an angle | |
| (default: argmax, as in the paper), "confidence" holds the calibration of the | |
| confidence value (default: none). | |
| """ | |
| self.inference_method = model_info.get("decoding", "argmax") | |
| self.confidence_calibration = model_info.get("confidence") | |
| def forward(self, x: torch.Tensor, return_logits: bool = False) -> torch.Tensor: | |
| """Forward pass returning probability distribution over angles.""" | |
| logits = self.model(x) | |
| if return_logits: | |
| return logits | |
| return F.softmax(logits, dim=1) | |
| def confidence_from_distribution(self, distributions: torch.Tensor) -> torch.Tensor: | |
| """Confidence between 0 and 1 for each distribution of a batch. | |
| The probability mass within +-10 degrees of the predicted angle cannot exceed | |
| about 0.92, because the model is trained on Gaussian targets with sigma = 6 degrees. | |
| A logistic curve fitted on the validation split maps it to an estimate of the | |
| probability that the predicted angle is within 10 degrees of the true angle. | |
| """ | |
| calibration = self.confidence_calibration | |
| if calibration is None: | |
| raise ValueError("The confidence of this checkpoint was not calibrated. " | |
| "It is available for checkpoints with a 'confidence' entry in config.json.") | |
| mass = self.cgd.peak_mass(distributions, window_degrees=calibration["window_degrees"]) | |
| mass = mass.double().clamp(1e-6, 1 - 1e-6) | |
| return torch.sigmoid(calibration["slope"] * torch.logit(mass) + calibration["intercept"]) | |
| def predict_angle(self, image, return_confidence: bool = False): | |
| """Detect the current orientation angle of an image. | |
| Args: | |
| image: PIL Image, numpy array, or file path string. | |
| For best results, pass PIL Image or numpy array directly. | |
| return_confidence: Also return the confidence of the prediction. | |
| Returns: | |
| Predicted rotation angle in degrees [0, 360), or the tuple (angle, confidence) | |
| with a confidence between 0 and 1 if return_confidence is set. | |
| """ | |
| self.eval() | |
| if isinstance(image, str): | |
| image = Image.open(image).convert('RGB') | |
| elif isinstance(image, np.ndarray): | |
| image = Image.fromarray(image).convert('RGB') | |
| elif not isinstance(image, Image.Image): | |
| raise TypeError(f"Expected PIL Image, numpy array, or file path, got {type(image)}") | |
| else: | |
| image = image.convert('RGB') | |
| try: | |
| data_config = timm.data.resolve_model_data_config(self.hparams.model_name) | |
| data_config['crop_pct'] = 1.0 | |
| data_config['input_size'] = (3, self.image_size, self.image_size) | |
| transform = timm.data.create_transform(**data_config, is_training=False) | |
| except Exception: | |
| transform = transforms.Compose([ | |
| transforms.Resize((self.image_size, self.image_size)), | |
| transforms.ToTensor(), | |
| transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]) | |
| ]) | |
| image_tensor = transform(image).unsqueeze(0).to(self.device) | |
| with torch.no_grad(): | |
| pred_distributions = self(image_tensor) | |
| angle = self.cgd.distribution_to_angle(pred_distributions, method=self.inference_method).item() | |
| if return_confidence: | |
| return angle, self.confidence_from_distribution(pred_distributions).item() | |
| return angle | |