Skip to main content

ritk_transform/transform/affine/
scale.rs

1//! Trainable axis-aligned scale transform.
2
3use coeus_autograd::{
4    add as add_variables, broadcast_to as broadcast_variable, mul as mul_variables, reshape,
5    sub as sub_variables, Var,
6};
7use coeus_core::{Backend, CpuAddressableStorage, CpuAddressableStorageMut};
8use coeus_nn::Module;
9use coeus_ops::{add, broadcast_to, mul, sub, BackendOps};
10use ritk_core::transform::Transform;
11use ritk_image::tensor::Tensor;
12
13/// Scale about a fixed center: `T(x) = scale * (x - center) + center`.
14#[derive(Clone)]
15pub struct ScaleTransform<B: Backend + BackendOps<f32>, const D: usize> {
16    scale: Var<f32, B>,
17    center: Var<f32, B>,
18}
19
20impl<B: Backend + BackendOps<f32>, const D: usize> ScaleTransform<B, D> {
21    /// Construct a trainable scale parameter and fixed center.
22    ///
23    /// # Panics
24    ///
25    /// Panics unless both tensors have shape `[D]`.
26    #[must_use]
27    pub fn new(scale: Tensor<f32, B>, center: Tensor<f32, B>) -> Self {
28        assert_eq!(scale.shape(), [D], "scale parameter must have shape [{D}]");
29        assert_eq!(center.shape(), [D], "scale center must have shape [{D}]");
30        Self {
31            scale: Var::new(scale, true)
32                .expect("scale transform requires backend evaluation to succeed"),
33            center: Var::new(center, false)
34                .expect("scale transform requires backend evaluation to succeed"),
35        }
36    }
37
38    /// Construct the identity scale.
39    #[must_use]
40    pub fn identity(center: Option<Tensor<f32, B>>, backend: &B) -> Self {
41        Self::new(
42            Tensor::ones_on([D], backend)
43                .expect("scale transform requires backend evaluation to succeed"),
44            center.unwrap_or_else(|| {
45                Tensor::zeros_on([D], backend)
46                    .expect("scale transform requires backend evaluation to succeed")
47            }),
48        )
49    }
50
51    /// Clone the current scale factors.
52    #[must_use]
53    pub fn scale(&self) -> Tensor<f32, B> {
54        self.scale.tensor.clone()
55    }
56
57    /// Clone the fixed center.
58    #[must_use]
59    pub fn center(&self) -> Tensor<f32, B> {
60        self.center.tensor.clone()
61    }
62
63    /// Apply the scale while retaining the Coeus autograd graph.
64    #[must_use]
65    pub fn transform_variables(&self, points: &Var<f32, B>) -> Var<f32, B>
66    where
67        B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
68    {
69        let shape = points.tensor.shape();
70        assert!(
71            shape.len() == 2 && shape[1] == D,
72            "scale transform requires points shaped [N, {D}], got {shape:?}"
73        );
74        let target = vec![shape[0], D];
75        let center_row = reshape(&self.center, [1, D])
76            .expect("scale transform requires backend evaluation to succeed");
77        let scale_row = reshape(&self.scale, [1, D])
78            .expect("scale transform requires backend evaluation to succeed");
79        let center = broadcast_variable(&center_row, target.clone())
80            .expect("scale transform requires backend evaluation to succeed");
81        let scale = broadcast_variable(&scale_row, target)
82            .expect("scale transform requires backend evaluation to succeed");
83        let centered = sub_variables(points, &center)
84            .expect("scale transform requires backend evaluation to succeed");
85        let scaled = mul_variables(&centered, &scale)
86            .expect("scale transform requires backend evaluation to succeed");
87        add_variables(&scaled, &center)
88            .expect("scale transform requires backend evaluation to succeed")
89    }
90}
91
92impl<B: Backend + BackendOps<f32> + Default, const D: usize> Transform<B, D>
93    for ScaleTransform<B, D>
94where
95    B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
96{
97    fn transform_points(&self, points: Tensor<f32, B>) -> Tensor<f32, B> {
98        let shape = points.shape();
99        assert!(
100            shape.len() == 2 && shape[1] == D,
101            "scale transform requires points shaped [N, {D}], got {shape:?}"
102        );
103        let backend = B::default();
104        let target = [shape[0], D];
105        let center_row = self.center.tensor.reshape([1, D]);
106        let scale_row = self.scale.tensor.reshape([1, D]);
107        let center = broadcast_to(&center_row, &target, &backend)
108            .expect("scale transform requires backend evaluation to succeed");
109        let scale = broadcast_to(&scale_row, &target, &backend)
110            .expect("scale transform requires backend evaluation to succeed");
111        let centered = sub(&points, &center, &backend)
112            .expect("scale transform requires backend evaluation to succeed");
113        let scaled = mul(&centered, &scale, &backend)
114            .expect("scale transform requires backend evaluation to succeed");
115        add(&scaled, &center, &backend)
116            .expect("scale transform requires backend evaluation to succeed")
117    }
118}
119
120impl<B: Backend + BackendOps<f32> + Default, const D: usize> Module<f32, B> for ScaleTransform<B, D>
121where
122    B::DeviceBuffer<f32>: CpuAddressableStorage<f32> + CpuAddressableStorageMut<f32>,
123{
124    fn parameters(&self) -> Vec<Var<f32, B>> {
125        vec![self.scale.clone()]
126    }
127
128    fn named_parameters(&self) -> Vec<coeus_autograd::Parameter<f32, B>> {
129        vec![coeus_autograd::Parameter::new(self.scale.clone(), "scale")]
130    }
131
132    fn forward(
133        &self,
134        input: &Var<f32, B>,
135    ) -> Result<Var<f32, B>, coeus_nn::ModuleError<<B as coeus_core::ComputeBackend>::Error>> {
136        Ok(self.transform_variables(input))
137    }
138
139    fn load_parameters(&mut self, parameters: &[Var<f32, B>]) {
140        assert_eq!(
141            parameters.len(),
142            1,
143            "invariant: scale transform owns one parameter"
144        );
145        self.scale = parameters[0].clone();
146    }
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152    use coeus_core::SequentialBackend;
153
154    #[test]
155    fn scales_about_fixed_center() {
156        let backend = SequentialBackend;
157        let transform = ScaleTransform::<SequentialBackend, 2>::new(
158            Tensor::from_slice_on([2], &[2.0, 2.0], &backend).expect("test tensor is valid"),
159            Tensor::from_slice_on([2], &[1.0, 1.0], &backend).expect("test tensor is valid"),
160        );
161        let points = Tensor::from_slice_on([2, 2], &[1.0, 1.0, 2.0, 2.0], &backend)
162            .expect("test tensor is valid");
163
164        let transformed = transform.transform_points(points);
165
166        assert_eq!(transformed.as_slice(), &[1.0, 1.0, 3.0, 3.0]);
167    }
168}