Skip to main content

ritk_transform/transform/affine/
rigid.rs

1//! Trainable rigid transform.
2
3use coeus_autograd::{
4    add as add_variables, broadcast_to as broadcast_variable, cat as cat_variables, cos,
5    matmul as matmul_variables, mul as mul_variables, neg as neg_variable, reshape, sin, slice,
6    sub as sub_variables, transpose_2d, Var,
7};
8use coeus_core::{Backend, CpuAddressableStorage, CpuAddressableStorageMut};
9use coeus_nn::Module;
10use coeus_ops::{add, broadcast_to, cat, matmul, sub, BackendOps};
11use ritk_core::spatial::{Direction, Point, Spacing};
12use ritk_core::transform::{Resampleable, Transform};
13use ritk_image::tensor::Tensor;
14
15/// Rotation and translation about a fixed center.
16///
17/// Two-dimensional rotations use one angle. Three-dimensional rotations use
18/// `(x, y, z)` Euler angles with `R = Rz * Ry * Rx`.
19#[derive(Clone)]
20pub struct RigidTransform<B: Backend + BackendOps<f32>, const D: usize> {
21    translation: Var<f32, B>,
22    rotation: Var<f32, B>,
23    center: Var<f32, B>,
24}
25
26impl<B: Backend + BackendOps<f32> + Default, const D: usize> RigidTransform<B, D>
27where
28    B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
29{
30    /// Construct a trainable rigid transform.
31    ///
32    /// # Panics
33    ///
34    /// Panics unless `D` is in `1..=4`, translation and center are `[D]`, and
35    /// rotation is `[1]` for 2-D or `[3]` for 3-D.
36    #[must_use]
37    pub fn new(
38        translation: Tensor<f32, B>,
39        rotation: Tensor<f32, B>,
40        center: Tensor<f32, B>,
41    ) -> Self {
42        assert!(
43            (1..=4).contains(&D),
44            "rigid transform supports dimensions 1 through 4"
45        );
46        assert_eq!(
47            translation.shape(),
48            [D],
49            "rigid translation must have shape [{D}]"
50        );
51        assert_eq!(center.shape(), [D], "rigid center must have shape [{D}]");
52        let angles = if D == 3 { 3 } else { 1 };
53        assert_eq!(
54            rotation.shape(),
55            [angles],
56            "rigid rotation must have shape [{angles}] for dimension {D}"
57        );
58        Self {
59            translation: Var::new(translation, true)
60                .expect("rigid transform requires backend evaluation to succeed"),
61            rotation: Var::new(rotation, true)
62                .expect("rigid transform requires backend evaluation to succeed"),
63            center: Var::new(center, false)
64                .expect("rigid transform requires backend evaluation to succeed"),
65        }
66    }
67
68    /// Construct the identity transform.
69    #[must_use]
70    pub fn identity(center: Option<Tensor<f32, B>>, backend: &B) -> Self {
71        Self::new(
72            Tensor::zeros_on([D], backend)
73                .expect("rigid transform requires backend evaluation to succeed"),
74            Tensor::zeros_on([if D == 3 { 3 } else { 1 }], backend)
75                .expect("rigid transform requires backend evaluation to succeed"),
76            center.unwrap_or_else(|| {
77                Tensor::zeros_on([D], backend)
78                    .expect("rigid transform requires backend evaluation to succeed")
79            }),
80        )
81    }
82
83    /// Clone the current translation.
84    #[must_use]
85    pub fn translation(&self) -> Tensor<f32, B> {
86        self.translation.tensor.clone()
87    }
88
89    /// Clone the current Euler-angle parameter.
90    #[must_use]
91    pub fn rotation(&self) -> Tensor<f32, B> {
92        self.rotation.tensor.clone()
93    }
94
95    /// Clone the fixed center.
96    #[must_use]
97    pub fn center(&self) -> Tensor<f32, B> {
98        self.center.tensor.clone()
99    }
100
101    /// Materialize the homogeneous `[D + 1, D + 1]` matrix.
102    #[must_use]
103    pub fn matrix(&self) -> Tensor<f32, B> {
104        let backend = B::default();
105        let rotation = self.build_rotation_matrix();
106        let center_col = self.center.tensor.reshape([D, 1]);
107        let rotated_center = matmul(&rotation, &center_col, &backend)
108            .expect("rigid transform requires backend evaluation to succeed")
109            .reshape([D]);
110        let translated_center = add(&self.translation.tensor, &self.center.tensor, &backend)
111            .expect("rigid transform requires backend evaluation to succeed");
112        let offset = sub(&translated_center, &rotated_center, &backend)
113            .expect("rigid transform requires backend evaluation to succeed")
114            .reshape([D, 1]);
115        let top = cat(&[&rotation, &offset], 1)
116            .expect("rigid transform requires backend evaluation to succeed");
117        let mut bottom = vec![0.0; D + 1];
118        bottom[D] = 1.0;
119        let bottom = Tensor::from_slice_on([1, D + 1], &bottom, &backend)
120            .expect("rigid transform requires backend evaluation to succeed");
121        cat(&[&top, &bottom], 0).expect("rigid transform requires backend evaluation to succeed")
122    }
123
124    /// Materialize the `[D, D]` rotation matrix.
125    #[must_use]
126    pub fn build_rotation_matrix(&self) -> Tensor<f32, B> {
127        self.rotation_matrix_variables().tensor
128    }
129
130    /// Apply the transform while retaining the Coeus autograd graph.
131    #[must_use]
132    pub fn transform_variables(&self, points: &Var<f32, B>) -> Var<f32, B> {
133        let shape = points.tensor.shape();
134        assert!(
135            shape.len() == 2 && shape[1] == D,
136            "rigid transform requires points shaped [N, {D}], got {shape:?}"
137        );
138        let target = vec![shape[0], D];
139        let center_row = reshape(&self.center, [1, D])
140            .expect("rigid transform requires backend evaluation to succeed");
141        let translation_row = reshape(&self.translation, [1, D])
142            .expect("rigid transform requires backend evaluation to succeed");
143        let center = broadcast_variable(&center_row, target.clone())
144            .expect("rigid transform requires backend evaluation to succeed");
145        let translation = broadcast_variable(&translation_row, target)
146            .expect("rigid transform requires backend evaluation to succeed");
147        let centered = sub_variables(points, &center)
148            .expect("rigid transform requires backend evaluation to succeed");
149        let rotation_vars = self.rotation_matrix_variables();
150        let rotation_t = transpose_2d(&rotation_vars)
151            .expect("rigid transform requires backend evaluation to succeed");
152        let rotated = matmul_variables(&centered, &rotation_t)
153            .expect("rigid transform requires backend evaluation to succeed");
154        let centered_output = add_variables(&rotated, &center)
155            .expect("rigid transform requires backend evaluation to succeed");
156        add_variables(&centered_output, &translation)
157            .expect("rigid transform requires backend evaluation to succeed")
158    }
159
160    fn rotation_matrix_variables(&self) -> Var<f32, B> {
161        if D == 3 {
162            let x = slice(&self.rotation, &[(0, 1)])
163                .expect("rigid transform requires backend evaluation to succeed");
164            let y = slice(&self.rotation, &[(1, 2)])
165                .expect("rigid transform requires backend evaluation to succeed");
166            let z = slice(&self.rotation, &[(2, 3)])
167                .expect("rigid transform requires backend evaluation to succeed");
168            let cx = cos(&x).expect("rigid transform requires backend evaluation to succeed");
169            let sx = sin(&x).expect("rigid transform requires backend evaluation to succeed");
170            let cy = cos(&y).expect("rigid transform requires backend evaluation to succeed");
171            let sy = sin(&y).expect("rigid transform requires backend evaluation to succeed");
172            let cz = cos(&z).expect("rigid transform requires backend evaluation to succeed");
173            let sz = sin(&z).expect("rigid transform requires backend evaluation to succeed");
174
175            let r11 = mul_variables(&cz, &cy)
176                .expect("rigid transform requires backend evaluation to succeed");
177            let r12_lhs = mul_variables(
178                &mul_variables(&cz, &sy)
179                    .expect("rigid transform requires backend evaluation to succeed"),
180                &sx,
181            )
182            .expect("rigid transform requires backend evaluation to succeed");
183            let r12_rhs = mul_variables(&sz, &cx)
184                .expect("rigid transform requires backend evaluation to succeed");
185            let r12 = sub_variables(&r12_lhs, &r12_rhs)
186                .expect("rigid transform requires backend evaluation to succeed");
187            let r13_lhs = mul_variables(
188                &mul_variables(&cz, &sy)
189                    .expect("rigid transform requires backend evaluation to succeed"),
190                &cx,
191            )
192            .expect("rigid transform requires backend evaluation to succeed");
193            let r13_rhs = mul_variables(&sz, &sx)
194                .expect("rigid transform requires backend evaluation to succeed");
195            let r13 = add_variables(&r13_lhs, &r13_rhs)
196                .expect("rigid transform requires backend evaluation to succeed");
197            let r21 = mul_variables(&sz, &cy)
198                .expect("rigid transform requires backend evaluation to succeed");
199            let r22_lhs = mul_variables(
200                &mul_variables(&sz, &sy)
201                    .expect("rigid transform requires backend evaluation to succeed"),
202                &sx,
203            )
204            .expect("rigid transform requires backend evaluation to succeed");
205            let r22_rhs = mul_variables(&cz, &cx)
206                .expect("rigid transform requires backend evaluation to succeed");
207            let r22 = add_variables(&r22_lhs, &r22_rhs)
208                .expect("rigid transform requires backend evaluation to succeed");
209            let r23_lhs = mul_variables(
210                &mul_variables(&sz, &sy)
211                    .expect("rigid transform requires backend evaluation to succeed"),
212                &cx,
213            )
214            .expect("rigid transform requires backend evaluation to succeed");
215            let r23_rhs = mul_variables(&cz, &sx)
216                .expect("rigid transform requires backend evaluation to succeed");
217            let r23 = sub_variables(&r23_lhs, &r23_rhs)
218                .expect("rigid transform requires backend evaluation to succeed");
219            let r31 =
220                neg_variable(&sy).expect("rigid transform requires backend evaluation to succeed");
221            let r32 = mul_variables(&cy, &sx)
222                .expect("rigid transform requires backend evaluation to succeed");
223            let r33 = mul_variables(&cy, &cx)
224                .expect("rigid transform requires backend evaluation to succeed");
225            matrix_from_rows(&[[&r11, &r12, &r13], [&r21, &r22, &r23], [&r31, &r32, &r33]])
226        } else if D == 2 {
227            let angle = slice(&self.rotation, &[(0, 1)])
228                .expect("rigid transform requires backend evaluation to succeed");
229            let cosine =
230                cos(&angle).expect("rigid transform requires backend evaluation to succeed");
231            let sine = sin(&angle).expect("rigid transform requires backend evaluation to succeed");
232            let negative_sine = neg_variable(&sine)
233                .expect("rigid transform requires backend evaluation to succeed");
234            matrix_from_rows(&[[&cosine, &negative_sine], [&sine, &cosine]])
235        } else {
236            Var::new(
237                Tensor::eye_on(D, &B::default())
238                    .expect("rigid transform requires backend evaluation to succeed"),
239                false,
240            )
241            .expect("rigid transform requires backend evaluation to succeed")
242        }
243    }
244}
245
246pub(super) fn matrix_from_rows<T, B, const D: usize>(rows: &[[&Var<T, B>; D]; D]) -> Var<T, B>
247where
248    T: coeus_core::Scalar,
249    B: Backend + BackendOps<T> + Default,
250    B::DeviceBuffer<T>: CpuAddressableStorage<T> + CpuAddressableStorageMut<T>,
251{
252    let rows = rows
253        .iter()
254        .map(|row| {
255            let cells = row
256                .iter()
257                .map(|cell| {
258                    reshape(cell, [1, 1])
259                        .expect("rigid transform requires backend evaluation to succeed")
260                })
261                .collect::<Vec<_>>();
262            let references = cells.iter().collect::<Vec<_>>();
263            cat_variables(&references, 1)
264                .expect("rigid transform requires backend evaluation to succeed")
265        })
266        .collect::<Vec<_>>();
267    let references = rows.iter().collect::<Vec<_>>();
268    cat_variables(&references, 0).expect("rigid transform requires backend evaluation to succeed")
269}
270
271impl<B: Backend + BackendOps<f32> + Default, const D: usize> Transform<B, D>
272    for RigidTransform<B, D>
273where
274    B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
275{
276    fn transform_points(&self, points: Tensor<f32, B>) -> Tensor<f32, B> {
277        let shape = points.shape();
278        assert!(
279            shape.len() == 2 && shape[1] == D,
280            "rigid transform requires points shaped [N, {D}], got {shape:?}"
281        );
282        let backend = B::default();
283        let target = [shape[0], D];
284        let center_row = self.center.tensor.reshape([1, D]);
285        let translation_row = self.translation.tensor.reshape([1, D]);
286        let center = broadcast_to(&center_row, &target, &backend)
287            .expect("rigid transform requires backend evaluation to succeed");
288        let translation = broadcast_to(&translation_row, &target, &backend)
289            .expect("rigid transform requires backend evaluation to succeed");
290        let centered = sub(&points, &center, &backend)
291            .expect("rigid transform requires backend evaluation to succeed");
292        let rotation_t = self.build_rotation_matrix().t();
293        let rotated = matmul(&centered, &rotation_t, &backend)
294            .expect("rigid transform requires backend evaluation to succeed");
295        let centered_output = add(&rotated, &center, &backend)
296            .expect("rigid transform requires backend evaluation to succeed");
297        add(&centered_output, &translation, &backend)
298            .expect("rigid transform requires backend evaluation to succeed")
299    }
300}
301
302impl<B: Backend + BackendOps<f32>, const D: usize> Resampleable<B, D> for RigidTransform<B, D> {
303    fn resample(
304        &self,
305        _shape: [usize; D],
306        _origin: Point<D>,
307        _spacing: Spacing<D>,
308        _direction: Direction<D>,
309    ) -> Self {
310        self.clone()
311    }
312}
313
314impl<B: Backend + BackendOps<f32> + Default, const D: usize> Module<f32, B> for RigidTransform<B, D>
315where
316    B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
317{
318    fn parameters(&self) -> Vec<Var<f32, B>> {
319        vec![self.translation.clone(), self.rotation.clone()]
320    }
321
322    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<f32, B>> {
323        vec![
324            coeus_autograd::Parameter::new(self.translation.clone(), "translation"),
325            coeus_autograd::Parameter::new(self.rotation.clone(), "rotation"),
326        ]
327    }
328
329    fn forward(
330        &self,
331        input: &Var<f32, B>,
332    ) -> Result<Var<f32, B>, coeus_nn::ModuleError<<B as coeus_core::ComputeBackend>::Error>> {
333        Ok(self.transform_variables(input))
334    }
335
336    fn load_parameters(&mut self, parameters: &[Var<f32, B>]) {
337        assert_eq!(
338            parameters.len(),
339            2,
340            "invariant: rigid transform owns translation and rotation parameters"
341        );
342        self.translation = parameters[0].clone();
343        self.rotation = parameters[1].clone();
344    }
345}
346
347#[cfg(test)]
348#[path = "tests_rigid.rs"]
349mod tests;