feat: differentiability proof - CNN learns inverse 3D rotations

[divital-coder]

Summary

Adds a differentiability proof script (examples/differentiability_proof.jl) that demonstrates MedImages.jl's 3D rotation is usefully differentiable by training a CNN+MLP to learn inverse rotations via gradient descent.

Results

Metric	Value
Baseline L2 loss (no correction)	0.004906
Final L2 loss (trained model, 50 epochs)	0.001535
Improvement over baseline	68.7%

Epoch     Avg Train Loss      Avg Test Loss     
1         0.004512            0.004823          
10        0.004083            0.004647          
20        0.003473            0.003768          
30        0.001469            0.001566          
40        0.001421            0.001521          
50        0.001401            0.001535          

Pipeline

1. Data generation: Synthetic 3D line images (16³), rotated using MedImages.rotate_mi with random ±30° angles on 3 axes
2. CNN+MLP (Flux.jl): Processes rotated image → predicts 3 Euler angles
3. Differentiable rotation: Pure Julia rotation matrices (sin/cos) + trilinear interpolation, with exact angle gradients via ForwardDiff Jacobian in a ChainRulesCore rrule
4. L2 loss between de-rotated image and original drives training
5. Loss decreases → rotation is usefully differentiable ✓

Technical Notes

• Angle gradients: exact via ForwardDiff (forward-mode AD, 3 passes per backward)
• Network gradients: Zygote (reverse-mode AD) through Flux CNN+MLP
• MedImages' interpolate_pure already computes coordinate gradients via Enzyme — making rotate_mi itself angle-differentiable only requires rewriting the rotation matrix construction in pure Julia (removing @non_differentiable annotations)
• Adds Flux and ForwardDiff as dependencies for the example script

Run

~/.julia/juliaup/julia-1.11.6+0.x64.linux.gnu/bin/julia --project examples/differentiability_proof.jl

Test plan

• Script runs end-to-end on Julia 1.11.6
• Loss decreases significantly (68.7% improvement)
• Gradients flow through: L2 loss → interpolation → rotation angles → CNN/MLP

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds a differentiability proof example (examples/differentiability_proof.jl) that demonstrates MedImages.jl's 3D rotation operations are usefully differentiable by training a CNN+MLP to learn inverse rotations via gradient descent. The example implements a standalone differentiable rotation using pure Julia (Euler rotation matrices + trilinear interpolation) with ForwardDiff-based angle gradients, achieving a 68.7% improvement in L2 loss over the baseline across 50 training epochs. This serves as a proof-of-concept showing that rotation operations can be made angle-differentiable, complementing MedImages' existing coordinate-differentiable interpolation.

Changes:

• Adds comprehensive differentiability proof script with synthetic 3D line data generation, custom differentiable rotation implementation, CNN+MLP model, and training loop
• Adds Flux (v0.16.9) and ForwardDiff (v1.3.2) as main package dependencies for the example
• Updates Manifest.toml with all transitive dependencies required by Flux and ForwardDiff

Reviewed changes

Copilot reviewed 1 out of 3 changed files in this pull request and generated 2 comments.

File	Description
examples/differentiability_proof.jl	Complete differentiability proof script implementing data generation, standalone differentiable 3D rotation (Euler matrices + trilinear interpolation), CNN+MLP model, and training loop to demonstrate that rotation is usefully differentiable
Project.toml	Adds Flux and ForwardDiff to dependencies with version constraints
Manifest.toml	Updates with all transitive dependencies for Flux and ForwardDiff

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.