Update docs

nHackel · nHackel · commit 542c535ebd89 · 2024-12-10T17:37:15.000+01:00
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -7,6 +7,7 @@ ImageGeoms = "9ee76f2b-840d-4475-b6d6-e485c9297852"
 ImagePhantoms = "71a99df6-f52c-4da1-bd2a-69d6f37f3252"
 LinearOperatorCollection = "a4a2c56f-fead-462a-a3ab-85921a5f2575"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+Observables = "510215fc-4207-5dde-b226-833fc4488ee2"
 RadonKA = "86de8297-835b-47df-b249-c04e8db91db5"
 RegularizedLeastSquares = "1e9c538a-f78c-5de5-8ffb-0b6dbe892d23"
 
diff --git a/docs/make.jl b/docs/make.jl
@@ -36,9 +36,9 @@ makedocs(
             "Iterative Reconstruction Result" => "generated/example/5_iterative_result.md",
         ],
         "How to" => Any[
-            #"Construct RecoPlan" => "generated/howto/reco_plan.md",
-            #"Caching" => "generated/howto/caching.md",
-            #"Listeners" => "generated/howto/listeners.md",
+            "Serialization" => "generated/howto/serialization.md",
+            "Caching" => "generated/howto/caching.md",
+            "Observables" => "generated/howto/observables.md",
         ],
         #"API Reference" => Any["Solvers" => "API/solvers.md",
         #"Regularization Terms" => "API/regularization.md"],
diff --git a/docs/src/example_intro.md b/docs/src/example_intro.md
@@ -3,7 +3,8 @@ In this example we will implement a small image reconstruction package with the
 
 Most of the desired functionality is already implemented in various Julia packages. Our reconstruction packages now needs to properly connect these packages and transform the data into the appropriate formats for each package. 
 
-The example is intended for developers of reconstruction packages that use `AbstractImageReconstruction`. End-users of such a package can consult the result sections of the example to see the high-level interface of `AbstractImagerReconstruction` and should otherwise consult the documentation of the concrete reconstruction package itself.
+!!! note
+    The example is intended for developers of reconstruction packages that use `AbstractImageReconstruction`. End-users of such a package can consult the result sections of the example to see the high-level interface of `AbstractImagerReconstruction` and should otherwise consult the documentation of the concrete reconstruction package itself.
 
 ## Installation
 We can install `AbstractImageReconstruction` using the Julia package manager. Open a Julia REPL and run the following command:
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -8,9 +8,9 @@ AbstractImageReconstruction.jl is a Julia package that serves as the core API fo
 
 ## Features
 
-* Variety of optimization algorithms optimized for least squares problems
 * Storing, loading and manipulating of reconstruction algorithms with (partially) set parameters
-* Attaching callback listeners to parameters
+* Attaching callbacks to parameters changes with Observables.jl
+* Transparent caching of intermediate reconstruction results
 
 ## Installation
 
diff --git a/docs/src/literate/example/1_interface.jl b/docs/src/literate/example/1_interface.jl
@@ -12,6 +12,7 @@
 
 # For our package we extend these abstract types with our own abstract subtypes:
 using AbstractImageReconstruction
+export AbstractRadonAlgorithm, AbstractRadonParameters, AbstractRadonPreprocessingParameters, AbstractRadonReconstructionParameters, AbstractDirectRadonAlgorithm, AbstractIterativeRadonAlgorithm, RadonPreprocessingParameters # hide
 abstract type AbstractRadonAlgorithm <: AbstractImageReconstructionAlgorithm end
 abstract type AbstractRadonParameters <: AbstractImageReconstructionParameters end
 
diff --git a/docs/src/literate/example/2_direct.jl b/docs/src/literate/example/2_direct.jl
@@ -1,5 +1,6 @@
 include("../../literate/example/1_interface.jl") #hide
 using RadonKA #hide
+export AbstractDirectRadonReconstructionParameters, RadonFilteredBackprojectionParameters, RadonBackprojectionParameters, DirectRadonParameters, DirectRadonAlgorithm #hide
 
 # # Direct Reconstruction
 # To implement our direct reconstruction algorithms we need to define a few more methods and types. We will start by defining the parameters for the backprojection and for the filtered backprojection. Afterwards we can implement the algorithm itself.
@@ -33,7 +34,7 @@ AbstractImageReconstruction.process(::Type{<:AbstractDirectRadonAlgorithm}, para
 # ## Algorithm
 # The direct reconstruction algorithm has essentially no state to store between reconstructions and thus only needs its parameters as fields. We want our algorithm to accept any combination of our preprocessing and direct reconstruction parameters.
 # This we encode in a new type:
-Base.@kwdef struct DirectRadonParameters{P, R} <: AbstractRadonParameters where {P<:AbstractRadonPreprocessingParameters, R<:AbstractDirectRadonReconstructionParameters}
+Base.@kwdef struct DirectRadonParameters{P <: AbstractRadonPreprocessingParameters, R <: AbstractDirectRadonReconstructionParameters} <: AbstractRadonParameters
   pre::P
   reco::R
 end
@@ -44,7 +45,7 @@ function AbstractImageReconstruction.process(algoT::Type{<:AbstractDirectRadonAl
 end
 
 # Now we can define the algorithm type itself. Algorithms are usually constructed with one argument passing in the user parameters:
-mutable struct DirectRadonAlgorithm{D} <: AbstractDirectRadonAlgorithm where D <: DirectRadonParameters
+mutable struct DirectRadonAlgorithm{D <: DirectRadonParameters} <: AbstractDirectRadonAlgorithm
   parameter::D
   output::Channel{Any}
   DirectRadonAlgorithm(parameter::D) where D = new{D}(parameter, Channel{Any}(Inf))
diff --git a/docs/src/literate/example/3_direct_result.jl b/docs/src/literate/example/3_direct_result.jl
@@ -1,4 +1,4 @@
-include("../../literate/example/example_include.jl") #hide
+include("../../literate/example/example_include_all.jl") #hide
 
 # # Direct Reconstruction Result
 # Now that we have implemented our direct reconstruction algorithm, we can use it to reconstruct for example the first three images of our time series.
diff --git a/docs/src/literate/example/4_iterative.jl b/docs/src/literate/example/4_iterative.jl
@@ -1,5 +1,6 @@
 include("../../literate/example/1_interface.jl") #hide
 using RadonKA #hide
+export AbstractIterativeRadonReconstructionParameters, IterativeRadonReconstructionParameters, IterativeRadonParameters, IterativeRadonAlgorithm #hide
 
 # # Iterative Reconstruction
 # In this section we implement a more complex iterative reconstruction algorithm. 
@@ -38,14 +39,14 @@ end
 
 # ## Algorithm
 # Similar to the direct reconstruction algorithm, we want our iterative algorithm to accept both preprocessing and reconstruction parameters. We will encode this in a new type:
-Base.@kwdef struct IterativeRadonParameters{P, R} <: AbstractRadonParameters where {P<:AbstractRadonPreprocessingParameters, R<:AbstractIterativeRadonReconstructionParameters}
+Base.@kwdef struct IterativeRadonParameters{P<:AbstractRadonPreprocessingParameters, R<:AbstractIterativeRadonReconstructionParameters} <: AbstractRadonParameters 
   pre::P
   reco::R
 end
 # Instead of defining essentially the same struct again, we could also define a more generic one and specify the supported reconstruction parameter as type constraints in the algorithm constructor.
 
 # Unlike the direct reconstruction algorithm, the iterative algorithm has to store the linear operator. We will store it as a field in the algorithm type:
-mutable struct IterativeRadonAlgorithm{D} <: AbstractIterativeRadonAlgorithm where D <: IterativeRadonParameters
+mutable struct IterativeRadonAlgorithm{D <: IterativeRadonParameters} <: AbstractIterativeRadonAlgorithm
   parameter::D
   op::Union{Nothing, AbstractLinearOperator}
   output::Channel{Any}
@@ -69,7 +70,7 @@ function AbstractImageReconstruction.process(algo::IterativeRadonAlgorithm, para
   return process(AbstractIterativeRadonAlgorithm, params, op, data)
 end
 
-# As it stands our algorithm is not type stable. To fix this, we would need to know the element type during construction. Which is possible with a different parameterization of the algorithm. We will not do this here.
+# Our algorithm is not type stable. To fix this, we would need to know the element type of the sinograms during construction. Which is possible with a different parameterization of the algorithm. We will not do this here.
 # Often times the performance impact of this is negligible as the critical sections are in the preprocessing or the iterative solver, especially since we still dispatch on the operator.
 
 # To finish up the implementation we need to implement the `put!`, `take!` and `parameters` functions:
@@ -79,4 +80,4 @@ function Base.put!(algo::IterativeRadonAlgorithm, data::AbstractArray{T, 4}) whe
     put!(algo.output, process(algo, algo.parameter, data))
   end
 end
-AbstractImageReconstruction.parameter(algo::IterativeRadonAlgorithm) = algo.parameter
+AbstractImageReconstruction.parameter(algo::IterativeRadonAlgorithm) = algo.parameter
diff --git a/docs/src/literate/example/5_iterative_result.jl b/docs/src/literate/example/5_iterative_result.jl
@@ -1,4 +1,4 @@
-include("../../literate/example/example_include.jl") #hide
+include("../../literate/example/example_include_all.jl") #hide
 
 # # Iterative Reconstruction Result
 # We can now use the iterative algorithms to reconstruct the first three images of our time series.
diff --git a/docs/src/literate/example/example_include_all.jl b/docs/src/literate/example/example_include_all.jl
@@ -0,0 +1,2 @@
+include("../../literate/example/example_include_module.jl")
+include("../../literate/example/example_include_data.jl")
diff --git a/docs/src/literate/example/example_include_data.jl b/docs/src/literate/example/example_include_data.jl
@@ -1,8 +1,6 @@
-include("../../literate/example/1_interface.jl") 
-include("../../literate/example/2_direct.jl") 
-include("../../literate/example/4_iterative.jl") 
-using RadonKA, ImagePhantoms, ImageGeoms, CairoMakie, AbstractImageReconstruction 
+using RadonKA, ImagePhantoms, ImageGeoms, CairoMakie, AbstractImageReconstruction, RegularizedLeastSquares
 using CairoMakie 
+using .OurRadonReco
 function plot_image(figPos, img; title = "", width = 150, height = 150) 
   ax = CairoMakie.Axis(figPos[1, 1]; yreversed=true, title, width, height) 
   hidedecorations!(ax) 
@@ -28,4 +26,4 @@ for (i, intensity) in enumerate(range(params[3][end], 0.3, 5))
   local ig = ImageGeom(;dims = shape) 
   images[:, :, :, i] = phantom(axes(ig)..., ob) 
   sinograms[:, :, :, i] = Array(RadonKA.radon(images[:, :, :, i], angles)) 
-end 
+end 
diff --git a/docs/src/literate/example/example_include_module.jl b/docs/src/literate/example/example_include_module.jl
@@ -0,0 +1,12 @@
+module OurRadonReco
+
+using RadonKA, ImagePhantoms, ImageGeoms, CairoMakie, AbstractImageReconstruction, RegularizedLeastSquares
+
+
+include("../../literate/example/1_interface.jl") 
+include("../../literate/example/2_direct.jl") 
+include("../../literate/example/4_iterative.jl") 
+
+end
+
+using .OurRadonReco
diff --git a/docs/src/literate/howto/caching.jl b/docs/src/literate/howto/caching.jl
@@ -0,0 +1,69 @@
+include("../../literate/example/example_include_all.jl") #hide
+
+
+# # Caching
+# Image reconstruction algorithms can be computationally expensive. To avoid unnecessary recomputations, we can cache the results of processing steps.
+# This can be especially helpful if a user wants to change parameters of an algorithm that only impact parts of the processing.
+# We have seen a small example of caching in the `IterativeRadonAlgorithm` implementation. There the algorithm itself cached a result in its properties.
+# `AbstractImageReconstruction` provides a more general caching mechanism that can be used for any processing step. However, the caching mechanism is not enabled by default and has to be explicitly implemented by the algorithm developer.
+
+# This How-To builds on the results of the example sections.
+
+# ## ProcessResultCache
+# The caching mechanism is based on the `ProcessResultCache` type. This type wraps around a different `ÀbstractImageReconstructionParameter` and caches the result of a processing step.
+# The cache itself is connected to a `RecoPlan` and any instances build from the same plan instance share this cache and can reuse the result of the processing step.
+
+# Let's implement the `ProcessResultCache` type for the Radon preprocessing step. We first define a struct a very costly preprocessing step:
+Base.@kwdef struct CostlyPreprocessingParameters <: AbstractRadonPreprocessingParameters
+  frames::Vector{Int64} = []
+  runtime::Float64 = 1.0
+end
+function AbstractImageReconstruction.process(::Type{<:AbstractRadonAlgorithm}, params::CostlyPreprocessingParameters, data::AbstractArray{T, 4}) where {T}
+  frames = isempty(params.frames) ? (1:size(data, 4)) : params.frames
+  data = data[:, :, :, frames]
+  @info "Very costly preprocessing step"
+  sleep(params.runtime)
+  return data
+end
+
+# Now we can define a processing step that internally uses another processing step. We allow this inner parameter to be cached by considering the following `Union`:
+Base.@kwdef struct RadonCachedPreprocessingParameters{P <: AbstractRadonPreprocessingParameters} <: AbstractRadonPreprocessingParameters
+  params::Union{P, ProcessResultCache{P}}
+end
+# Note that this case is a bit artifical and a more sensible place would be the algorithm parameters themselves. However, for the case of simplicity we did not introduce the concept in the example.
+# In this artifical case we just pass the parameters to the processing step. A real implementation might do some more processing with the result of the inner processing step:
+AbstractImageReconstruction.process(algoT::Type{<:AbstractRadonAlgorithm}, params::RadonCachedPreprocessingParameters, args...) = process(algoT, params.params, args...)
+
+# We deliberaly implement the `process` function for algorithm type to avoid our cache being invalided by state changes of an algoritm instance.
+
+# Now we construct a plan for a direct reconstruction algorithm that uses the costly preprocessing step:
+pre = CostlyPreprocessingParameters(; frames = collect(1:3), runtime = 1.0)
+preCached = RadonCachedPreprocessingParameters(ProcessResultCache(pre, maxsize = 2))
+prePlan = toPlan(preCached)
+recoPlan = RecoPlan(IterativeRadonReconstructionParameters; angles = angles, shape = size(images)[1:3],
+            iterations = 10, reg = [L2Regularization(0.001), PositiveRegularization()], solver = CGNR)
+params = RecoPlan(IterativeRadonParameters; pre = prePlan, reco = recoPlan)
+plan = RecoPlan(IterativeRadonAlgorithm; parameter = params)
+
+# When we built the algorithm from the plan, the costly preprocessing step is only executed once and the result is cached and can be reused:
+algo = build(plan)
+reconstruct(algo, sinograms);
+reconstruct(algo, sinograms);
+
+# If we change the parameters of the algorithms without affecting the preprocessing step, we can still reuse the cached result:
+setAll!(plan, :iterations, 5)
+algo = build(plan)
+reconstruct(algo, sinograms);
+plan.parameter.reco.iterations == 5
+
+# `ProcessResultCache` uses a least recently used (LRU) strategy to store the results. The cache size can be set by the user and defaults to 1. If the cache is full, the least recently used result is removed from the cache.
+
+# The cache is checked with a key formed with the hash of all arguments of the processing step. `AbstractImageReconstruction` provides a default `hash` method for AbstractImageReconstructionParameters`, which hashes all properties of a parameter.
+
+# Other methods of cache invalidation are creating a new plan or manual invalidation of the cache:
+empty!(algo.parameter.pre.params)
+reconstruct(algo, sinograms);
+
+# Caches support serialization like other `RecoPlans`:
+clear!(plan)
+toTOML(stdout, plan)
diff --git a/docs/src/literate/howto/observables.jl b/docs/src/literate/howto/observables.jl
@@ -0,0 +1,63 @@
+include("../../literate/example/example_include_all.jl") #hide
+
+# # Observables
+# Observables from [Observables.jl](https://github.com/JuliaGizmos/Observables.jl) are containers which can invoke callbacks whenever their stored value is changed.
+# Each property of a `RecoPlan` is an `Òbservable` to which functions can be attached. These function listen to changes of the Observables value.
+# This can be used to store "logic" about the parameter within a plan, such as a function to update and visualize the current state of a plan or to calculate default values whenever a parameter changes.
+# In this documentation we will focus on the interaction between `RecoPlans` and `Observables`. For more details on the `Observables` API we refer to the [package](https://juliagizmos.github.io/Observables.jl/stable/) and [Makie](https://docs.makie.org/dev/explanations/Observables) documentation.
+using Observables
+plan = RecoPlan(DirectRadonAlgorithm; parameter = RecoPlan(DirectRadonParameters; 
+        pre = RecoPlan(RadonPreprocessingParameters; frames = collect(1:3)), 
+        reco = RecoPlan(RadonBackprojectionParameters; angles = angles)))
+
+# You can interact with parameters as if they are "normal" properties of a nested struct, which we shown in previous examples:
+length(plan.parameter.pre.frames) == 3
+
+# Internally, these properties are stored as `Observables` to which we can attach functions:
+on(plan.parameter.pre, :frames) do val
+  @info "Number of frames: $(length(val))"
+end
+setAll!(plan, :frames, collect(1:42))
+
+# Clearing the plan also resets the `Observables` and removes all listeners:
+clear!(plan)
+setAll!(plan, :frames, collect(1:3))
+plan.parameter.pre.frames
+
+# To directly access the Observable of a property you can use `getindex` on the plan with the property name:
+plan.parameter.pre[:frames]
+
+# `Observables` can also be used to connect two properties of a plan. For example, we can set the number of averages to the number of frames:
+on(plan.parameter.pre, :frames) do val
+  plan.parameter.pre.numAverages = length(val)
+end
+setAll!(plan, :frames, collect(1:42))
+plan.parameter.pre.numAverages
+
+# It is important to avoid circular dependencies when connecting Observables, as this can lead to infinite loops of callbacks.
+# Also note that the connection shown above will always overwrite the number of averages even if a user has set the value manually:
+plan.parameter.pre.numAverages = 5
+setAll!(plan, :frames, collect(1:42))
+plan.parameter.pre.numAverages
+
+# To connect two properties without overwriting user-prvided values, we can use the `LinkedPropertyListener` provided by `AbstractImageReconstruction`:
+clear!(plan)
+listener = LinkedPropertyListener(plan.parameter.pre, :numAverages, plan.parameter.pre, :frames) do val
+  @info "Setting default numAverages value to: $(length(val))"
+  return length(val)
+end
+plan.parameter.pre.frames = collect(1:42)
+plan.parameter.pre.numAverages = 1
+plan.parameter.pre.frames = collect(1:3)
+
+# The `LinkedPropertyListener` can also be serialized and deserialized with the plan. However, for the function to be properly serialized, it should be a named function:
+clear!(plan)
+defaultAverages(val) = length(val)
+LinkedPropertyListener(defaultAverages, plan.parameter.pre, :numAverages, plan.parameter.pre, :frames)
+plan.parameter.pre.frames = collect(1:42)
+@info plan.parameter.pre.numAverages == 42
+toTOML(stdout, plan)
+
+# To serialize custom listener one can inherit from `AbstractPlanListener` and follow the serialization How-To to implement the serialization.
+# Listener are deserialized after the plan is built and the parameters are set. This means that the listener can access the parameters of the plan and the plan itself.
+# For deserialization the listener has to implement `loadListener!(::Type{<:AbstractPlanListener}, plan::RecoPlan, field::Symbol, dict::Dict{String, Any}, args...)`.
diff --git a/docs/src/literate/howto/serialization.jl b/docs/src/literate/howto/serialization.jl

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-include("../../literate/example/example_include.jl") #hide`
	`1`	`+include("../../literate/example/example_include_all.jl") #hide`
`2`	`2`
`3`	`3`	`# # Direct Reconstruction Result`
`4`	`4`	`# Now that we have implemented our direct reconstruction algorithm, we can use it to reconstruct for example the first three images of our time series.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+include("../../literate/example/example_include_module.jl")`
	`2`	`+include("../../literate/example/example_include_data.jl")`