gps-denied-desktop/docs/02_components/helpers/h07_image_rotation_utils_spec.md

Image Rotation Utils Helper

Interface Definition

Interface Name: IImageRotationUtils

Interface Methods

class IImageRotationUtils(ABC):
    @abstractmethod
    def rotate_image(self, image: np.ndarray, angle: float, center: Optional[Tuple[int, int]] = None) -> np.ndarray:
        pass
    
    @abstractmethod
    def calculate_rotation_from_points(self, src_points: np.ndarray, dst_points: np.ndarray) -> float:
        pass
    
    @abstractmethod
    def normalize_angle(self, angle: float) -> float:
        pass
    
    @abstractmethod
    def compute_rotation_matrix(self, angle: float, center: Tuple[int, int]) -> np.ndarray:
        pass

Component Description

Image rotation operations, angle calculations from point shifts.

API Methods

rotate_image(image: np.ndarray, angle: float, center: Optional[Tuple[int, int]] = None) -> np.ndarray

Description: Rotates image around center.

Implementation: Uses cv2.getRotationMatrix2D + cv2.warpAffine

Parameters:

• angle: Degrees (0-360)
• center: Rotation center (default: image center)

Returns: Rotated image (same dimensions)

---

calculate_rotation_from_points(src_points: np.ndarray, dst_points: np.ndarray) -> float

Description: Calculates rotation angle from point correspondences.

Input: (N, 2) arrays of matching points

Algorithm:

1. Compute centroids
2. Calculate angle from centroid shifts
3. Return angle in degrees

Use Case: Extract precise angle from LiteSAM homography

---

normalize_angle(angle: float) -> float

Description: Normalizes angle to 0-360 range.

Formula:

angle = angle % 360
if angle < 0:
    angle += 360

---

compute_rotation_matrix(angle: float, center: Tuple[int, int]) -> np.ndarray

Description: Computes 2D rotation matrix.

Returns: 2×3 affine transformation matrix

Dependencies

External: opencv-python, numpy

Test Cases

1. Rotate 90° → image rotated correctly
2. Calculate angle from points → accurate angle
3. Normalize 370° → 10°
4. Rotation matrix → correct transformation