Skip to main content

ritk_transform/transform/affine/
affine.rs

1//! Trainable affine transform.
2
3use coeus_autograd::{
4    add as add_variables, broadcast_to as broadcast_variable, matmul as matmul_variables, reshape,
5    sub as sub_variables, transpose_2d, Var,
6};
7use coeus_core::{Backend, CpuAddressableStorage, CpuAddressableStorageMut};
8use coeus_nn::Module;
9use coeus_ops::{add, broadcast_to, matmul, sub, BackendOps};
10use ritk_core::spatial::{Direction, Point, Spacing};
11use ritk_core::transform::{Resampleable, Transform};
12use ritk_image::tensor::Tensor;
13
14/// Trainable affine map `T(x) = A(x - c) + c + t`.
15#[derive(Clone)]
16pub struct AffineTransform<B: Backend + BackendOps<f32>, const D: usize> {
17    matrix: Var<f32, B>,
18    translation: Var<f32, B>,
19    center: Var<f32, B>,
20}
21
22impl<B: Backend + BackendOps<f32>, const D: usize> AffineTransform<B, D> {
23    /// Construct a trainable affine map with a fixed center.
24    ///
25    /// # Panics
26    ///
27    /// Panics unless the tensors have shapes `[D, D]`, `[D]`, and `[D]`.
28    #[must_use]
29    pub fn new(
30        matrix: Tensor<f32, B>,
31        translation: Tensor<f32, B>,
32        center: Tensor<f32, B>,
33    ) -> Self {
34        assert_eq!(
35            matrix.shape(),
36            [D, D],
37            "affine matrix must have shape [{D}, {D}]"
38        );
39        assert_eq!(
40            translation.shape(),
41            [D],
42            "affine translation must have shape [{D}]"
43        );
44        assert_eq!(center.shape(), [D], "affine center must have shape [{D}]");
45        Self {
46            matrix: Var::new(matrix, true)
47                .expect("affine transform requires backend evaluation to succeed"),
48            translation: Var::new(translation, true)
49                .expect("affine transform requires backend evaluation to succeed"),
50            center: Var::new(center, false)
51                .expect("affine transform requires backend evaluation to succeed"),
52        }
53    }
54
55    /// Construct the identity map on `backend`.
56    #[must_use]
57    pub fn identity(center: Option<Tensor<f32, B>>, backend: &B) -> Self {
58        let mut values = vec![0.0; D * D];
59        for axis in 0..D {
60            values[axis * D + axis] = 1.0;
61        }
62        Self::new(
63            Tensor::from_slice_on([D, D], &values, backend)
64                .expect("affine transform requires backend evaluation to succeed"),
65            Tensor::zeros_on([D], backend)
66                .expect("affine transform requires backend evaluation to succeed"),
67            center.unwrap_or_else(|| {
68                Tensor::zeros_on([D], backend)
69                    .expect("affine transform requires backend evaluation to succeed")
70            }),
71        )
72    }
73
74    /// Clone the current linear map.
75    #[must_use]
76    pub fn matrix(&self) -> Tensor<f32, B> {
77        self.matrix.tensor.clone()
78    }
79
80    /// Clone the current translation.
81    #[must_use]
82    pub fn translation(&self) -> Tensor<f32, B> {
83        self.translation.tensor.clone()
84    }
85
86    /// Clone the fixed center.
87    #[must_use]
88    pub fn center(&self) -> Tensor<f32, B> {
89        self.center.tensor.clone()
90    }
91
92    /// Apply the map while retaining the Coeus autograd graph.
93    ///
94    /// # Panics
95    ///
96    /// Panics when `points` is not shaped `[N, D]`.
97    #[must_use]
98    pub fn transform_variables(&self, points: &Var<f32, B>) -> Var<f32, B>
99    where
100        B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
101    {
102        let shape = points.tensor.shape();
103        assert!(
104            shape.len() == 2 && shape[1] == D,
105            "affine transform requires points shaped [N, {D}], got {shape:?}"
106        );
107        let target = vec![shape[0], D];
108        let center_row = reshape(&self.center, [1, D])
109            .expect("affine transform requires backend evaluation to succeed");
110        let translation_row = reshape(&self.translation, [1, D])
111            .expect("affine transform requires backend evaluation to succeed");
112        let center = broadcast_variable(&center_row, target.clone())
113            .expect("affine transform requires backend evaluation to succeed");
114        let translation = broadcast_variable(&translation_row, target)
115            .expect("affine transform requires backend evaluation to succeed");
116        let centered = sub_variables(points, &center)
117            .expect("affine transform requires backend evaluation to succeed");
118        let matrix_t = transpose_2d(&self.matrix)
119            .expect("affine transform requires backend evaluation to succeed");
120        let linear = matmul_variables(&centered, &matrix_t)
121            .expect("affine transform requires backend evaluation to succeed");
122        let centered_output = add_variables(&linear, &center)
123            .expect("affine transform requires backend evaluation to succeed");
124        add_variables(&centered_output, &translation)
125            .expect("affine transform requires backend evaluation to succeed")
126    }
127}
128
129impl<B: Backend + BackendOps<f32> + Default, const D: usize> Transform<B, D>
130    for AffineTransform<B, D>
131where
132    B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
133{
134    fn transform_points(&self, points: Tensor<f32, B>) -> Tensor<f32, B> {
135        let shape = points.shape();
136        assert!(
137            shape.len() == 2 && shape[1] == D,
138            "affine transform requires points shaped [N, {D}], got {shape:?}"
139        );
140        let backend = B::default();
141        let target = [shape[0], D];
142        let center_row = self.center.tensor.reshape([1, D]);
143        let translation_row = self.translation.tensor.reshape([1, D]);
144        let center = broadcast_to(&center_row, &target, &backend)
145            .expect("affine transform requires backend evaluation to succeed");
146        let translation = broadcast_to(&translation_row, &target, &backend)
147            .expect("affine transform requires backend evaluation to succeed");
148        let centered = sub(&points, &center, &backend)
149            .expect("affine transform requires backend evaluation to succeed");
150        let matrix_t = self.matrix.tensor.t();
151        let linear = matmul(&centered, &matrix_t, &backend)
152            .expect("affine transform requires backend evaluation to succeed");
153        let centered_output = add(&linear, &center, &backend)
154            .expect("affine transform requires backend evaluation to succeed");
155        add(&centered_output, &translation, &backend)
156            .expect("affine transform requires backend evaluation to succeed")
157    }
158}
159
160impl<B: Backend + BackendOps<f32>, const D: usize> Resampleable<B, D> for AffineTransform<B, D> {
161    fn resample(
162        &self,
163        _shape: [usize; D],
164        _origin: Point<D>,
165        _spacing: Spacing<D>,
166        _direction: Direction<D>,
167    ) -> Self {
168        self.clone()
169    }
170}
171
172impl<B: Backend + BackendOps<f32> + Default, const D: usize> Module<f32, B>
173    for AffineTransform<B, D>
174where
175    B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
176{
177    fn parameters(&self) -> Vec<Var<f32, B>> {
178        vec![self.matrix.clone(), self.translation.clone()]
179    }
180
181    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<f32, B>> {
182        vec![
183            coeus_autograd::Parameter::new(self.matrix.clone(), "matrix"),
184            coeus_autograd::Parameter::new(self.translation.clone(), "translation"),
185        ]
186    }
187
188    fn forward(
189        &self,
190        input: &Var<f32, B>,
191    ) -> Result<Var<f32, B>, coeus_nn::ModuleError<<B as coeus_core::ComputeBackend>::Error>> {
192        Ok(self.transform_variables(input))
193    }
194
195    fn load_parameters(&mut self, parameters: &[Var<f32, B>]) {
196        assert_eq!(
197            parameters.len(),
198            2,
199            "invariant: affine transform owns matrix and translation parameters"
200        );
201        self.matrix = parameters[0].clone();
202        self.translation = parameters[1].clone();
203    }
204}
205
206#[cfg(test)]
207#[path = "tests_affine.rs"]
208mod tests;