feat: align series of images (#54)

Also re-uses photometry if available to improve performance

Closes: #52

Methods now include:

```julia
align_frames(img_from, img_to; ...)
align_frames(img_froms, img_to; ...)

# Convenience function for aligning imgs[2:end] onto imgs[1]
align_frames(imgs; ...)
```

`img`s can be image data or a photometry table

---------

Co-authored-by: Chris Garling <chris.t.garling@gmail.com>

Author: icweaver

src/warp.jl

@@ -34,11 +34,41 @@ function align_frames(img_from, img_to; warp_function = warp, kwargs...)
     tfm, _ = find_transform(img_from, img_to; kwargs...)
 
     # Step 6: Apply the transform (from => to)
-    warp_img = apply_transform(tfm, img_from, img_to; warp_function = warp)
+    warp_img = apply_transform(tfm, img_from, img_to; warp_function)
 
     return warp_img
 end
 
+"""
+    align_frames(img_froms::AbstractVector{<:AbstractArray}, img_to; [warp_function], kwargs...)
+
+Align each image in `img_froms` to the single reference image `img_to`.
+
+The photometry on `img_to` is computed once (during the alignment of the first frame) and reused for every subsequent frame, which is substantially cheaper than invoking the scalar [`align_frames`](@ref) method once per `img_from`.
+
+Returns a vector of warped images, one per element of `img_froms`. Accepts the same keyword arguments as the scalar method.
+"""
+function align_frames(img_froms::AbstractVector{<:AbstractArray}, img_to; warp_function = warp, kwargs...)
+    # Bootstrap: solve the first frame normally so we can capture `phot_to`
+    # and reuse it (via the precomputed-Table `get_phot` dispatch) on every
+    # subsequent frame without redoing photometry on `img_to`.
+    tfm_first, params_ref = find_transform(first(img_froms), img_to; kwargs...)
+    phot_to = params_ref.phot_to
+
+    map(enumerate(img_froms)) do (i, img_from)
+        tfm = i == 1 ? tfm_first : first(find_transform(img_from, phot_to; kwargs...))
+        apply_transform(tfm, img_from, img_to; warp_function)
+    end
+end
+
+"""
+    align_frames(imgs::AbstractVector{<:AbstractArray}; kwargs...)
+
+Convenience method that takes the first image of `imgs` as the reference (`img_to`) and aligns the remaining `length(imgs) - 1` images to it. Equivalent to `align_frames(@view(imgs[2:end]), first(imgs); kwargs...)`.
+"""
+align_frames(imgs::AbstractVector{<:AbstractArray}; kwargs...) =
+    align_frames(@view(imgs[2:end]), first(imgs); kwargs...)
+
 """
     apply_transform(tfm, img_from, img_to; warp_function = warp)
 
@@ -99,7 +129,7 @@ end
 Compute the transformation needed to align `img_from` onto `img_to`, assuming both images are related via a rigid
 (or similarity, when `scale = true`) transformation. Automatically called by [`align_frames`](@ref).
 
-If `img_from` or `img_to` is instead passed as a list of (x, y) coordinates for the given sources, then the photometry step will be skipped for that image.
+If `img_from` or `img_to` is instead passed as a vector of `(x, y)` coordinates for the given sources, then the photometry step will be skipped for that image. This allows use of precomputed coordinate lists. A previously computed photometry [`Table`](https://typedtables.juliadata.org/stable/man/reference/#TypedTables.Table) (e.g. extracted from a prior `find_transform` result via `params.phot_to`) can also be passed in place of either image, which is useful when aligning a series of frames to a single reference image without recomputing its photometry on every call.
 
 # Parameters
 
@@ -157,3 +187,4 @@ end
 
 get_phot(img::AbstractMatrix; kwargs...) = _photometry(img; kwargs...)
 get_phot(coords::AbstractVector; kwargs...) = Table(; xcenter = first.(coords), ycenter = last.(coords)), ()
+get_phot(phot::Table; kwargs...) = phot, ()

test/test-functions.jl

@@ -38,6 +38,36 @@ end
     @test img_aligned ≈ img_to
 end
 
+@testset "align_frames (vector input reuses phot_to)" begin
+    using Astroalign: align_frames
+
+    img_to = Data.img_to
+    img_from = Data.img_from
+    opts = (; box_size = 1, ap_radius = 1, min_fwhm = (0.1, 0.1))
+
+    expected = align_frames(img_from, img_to; opts...)
+    aligned = align_frames([img_from, img_from, img_from], img_to; opts...)
+
+    @test length(aligned) == 3
+    @test all(a -> a ≈ expected, aligned)
+    @test all(a -> a ≈ img_to, aligned)
+end
+
+@testset "align_frames (single-arg convenience: first is reference)" begin
+    using Astroalign: align_frames
+
+    img_to = Data.img_to
+    img_from = Data.img_from
+    opts = (; box_size = 1, ap_radius = 1, min_fwhm = (0.1, 0.1))
+
+    expected = align_frames([img_from, img_from], img_to; opts...)
+    aligned = align_frames([img_to, img_from, img_from]; opts...)
+
+    @test length(aligned) == 2
+    @test aligned[1] ≈ expected[1]
+    @test aligned[2] ≈ expected[2]
+end
+
 @testset "find_transform" begin
     using Astroalign: find_transform
 
@@ -55,6 +85,30 @@ end
     @test tfm.translation ≈ [-3.0, 0.0]
 end
 
+@testset "find_transform reuses precomputed phot" begin
+    using Astroalign: find_transform
+
+    img_to = Data.img_to
+    img_from = Data.img_from
+    opts = (; box_size = 1, ap_radius = 1, min_fwhm = (0.1, 0.1))
+
+    tfm_ref, params_ref = find_transform(img_from, img_to; opts...)
+
+    # Passing the precomputed phot_to Table in place of img_to must yield the
+    # same transform without rerunning photometry on img_to.
+    tfm_reuse, params_reuse = find_transform(img_from, params_ref.phot_to; opts...)
+    @test tfm_reuse.linear ≈ tfm_ref.linear
+    @test tfm_reuse.translation ≈ tfm_ref.translation
+    @test params_reuse.phot_to === params_ref.phot_to
+    @test params_reuse.phot_to_params == ()
+
+    # Symmetric: precomputed phot_from also works.
+    tfm_both, params_both = find_transform(params_ref.phot_from, params_ref.phot_to; opts...)
+    @test tfm_both.linear ≈ tfm_ref.linear
+    @test tfm_both.translation ≈ tfm_ref.translation
+    @test params_both.phot_from_params == ()
+end
+
 @testset "photometry" begin
     using Astroalign: _photometry, PSF