Add jim! (#54)

* Use `jim!`

* Standardize yml

* Add CODECOV_TOKEN

.github/workflows/CI.yml → .github/workflows/ci.yml

@@ -27,16 +27,34 @@ jobs:
         os: [ubuntu-latest, windows-latest, macOS-latest]
     steps:
       - uses: actions/checkout@v4
+
 #     - name: "Set up Julia"
       - uses: julia-actions/setup-julia@latest
         with:
           version: ${{ matrix.version }}
+
+      - name: Cache artifacts
+        uses: actions/cache@v4
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+
 #     - name: "Unit Test"
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-runtest@latest
+
 #     - name: "Cover"
       - uses: julia-actions/julia-processcoverage@v1
       - uses: codecov/codecov-action@v4
         if: ${{ matrix.version == '1' && matrix.os == 'ubuntu-latest' }}
         with:
           file: lcov.info
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

src/3d.jl

@@ -5,41 +5,42 @@ using ColorTypes: Colorant
 
 
 # 3D (or higher), built on array version
-function jim(z::AbstractArray{<:Union{Number,Colorant}} ; kwargs...)
+function jim!(pp::Plot, z::AbstractArray{<:Union{Number,Colorant}} ; kwargs...)
     zz = reshape(z, size(z,1), size(z,2), :)
     out = [@view zz[:,:,i] for i in 1:size(zz,3)]
-    return jim(out ; kwargs...)
+    return jim!(pp, out ; kwargs...)
 end
 
 
 """
-    jim(x, y, z, array3d, [title] ; kwargs...)
+    jim(x, y, z, array3d, [title] ; kwargs...) or jim!(pp::Plot, ...)
 Allow user to provide
 the "z axis" of a 3D array,
 but ignore it without warning.
 """
-function jim(
+function jim!(
+    pp::Plot,
     x::AbstractVector{<:RealU},
     y::AbstractVector{<:RealU},
     z::AbstractVector{<:RealU}, # ignored!
     f::AbstractArray ; # could be 3D array or Vector of 2D arrays
     kwargs...,
 )
-    return jim(f ; x, y, kwargs...)
+    return jim!(pp, f ; x, y, kwargs...)
 end
 
-jim(x::AbstractVector{<:RealU}, y, z, f, title::String; kwargs...) =
-    jim(x, y, z, f; title, kwargs...)
+jim!(pp::Plot, x::AbstractVector{<:RealU}, y, z, f, title::String; kwargs...) =
+    jim!(pp, x, y, z, f; title, kwargs...)
 
 
 # axes tuples
 
 """
-    jim(axes::Tuple, array, [title] ; kwargs...)
+    jim(axes::Tuple, array, [title] ; kwargs...) or jim!(pp::Plot, ...)
 Allow user to provide the `axes` of `array`.
 (Only `x = axes[1]` and `y = axes[2]` are used.)
 """
-function jim(ax::Tuple, f; kwargs...)
+function jim!(pp::Plot, ax::Tuple, f; kwargs...)
    2 ≤ length(ax) || throw("need at least 2 axes")
    if f isa Vector{<:Array}
         ndim = ndims(f[1])
@@ -50,7 +51,8 @@ function jim(ax::Tuple, f; kwargs...)
    else
         length(ax) ≤ ndims(f) || throw("axes dimension mismatch for Array")
    end
-   jim(f; x = ax[1], y = ax[2], kwargs...)
+   jim!(pp, f; x = ax[1], y = ax[2], kwargs...)
 end
 
-jim(ax::Tuple, f, title::String; kwargs...) = jim(ax, f; title, kwargs...)
+jim!(pp::Plot, ax::Tuple, f, title::String; kwargs...) =
+    jim!(pp, ax, f; title, kwargs...)

src/array.jl

@@ -1,6 +1,6 @@
 # array.jl - arrays of images
 
-export jim
+export jim!
 
 using ColorTypes: Colorant
 using Plots: plot!
@@ -19,13 +19,15 @@ _ratio(ncol, n1, n2, n3, dx::Number, dy::Number) = # units
 
 """
     jim(z::AbstractArray{<:AbstractArray{<:Union{Number,Colorant}}} ; kwargs...)
+    jim!(pp::Plot, ...)
 
 Display an array of images.
 Same arguments and options as display of a 3D stack of images.
 The argument `ratio` defaults to `/(Plots.default(:size)...)`
 and affects the default `ncol` value.
 """
-function jim(
+function jim!(
+    pp::Plot,
     z::AbstractArray{<:AbstractArray{<:Union{Number,Colorant}}} ;
     gui::Bool = jim_def[:gui],
     prompt::Bool = jim_def[:prompt],
@@ -111,9 +113,9 @@ function jim(
         y = reverse(y)
     end
 
-    p = jim(zz ; x, y, xticks, yticks, yflip,
-            gui=false, prompt=false, aspect_ratio, kwargs...,
-        )
+    jim!(pp, zz ; x, y, xticks, yticks, yflip,
+        gui=false, prompt=false, aspect_ratio, kwargs...,
+    )
 
     if n3 > 1 && line3plot # lines around each subimage
         n1 += mosaic_npad
@@ -126,7 +128,7 @@ function jim(
             fy = o -> y[end] - o * (y[2] - y[1])
         end
         function plot_box!(ox, oy)
-            plot!(p,
+            plot!(pp,
                 fx.(ox .+ [0,1,1,0,0] * n1 .- 1),
                 fy.(oy .+ [0,0,1,1,0] * n2 .- 1),
                 line = jim_def[:line3type], label="",
@@ -139,8 +141,8 @@ function jim(
         end
     end
 
-    plot!()
+    plot!(pp)
     gui && Plots.gui()
     prompt && MIRTjim.prompt()
-    return p
+    return pp
 end

src/jim.jl

@@ -4,10 +4,10 @@ jiffy image display
 2019-02-23 Jeff Fessler, University of Michigan
 =#
 
-export jim
+export jim, jim!
 
 using ColorTypes: Colorant
-using Plots: heatmap, plot, plot!, Plot
+using Plots: heatmap!, plot, plot!, Plot
 import Plots # gui
 using MosaicViews: mosaicview
 using FFTViews: FFTView
@@ -16,6 +16,15 @@ import OffsetArrays # no_offset_view
 using AxisArrays: AxisArray, axisnames, axisvalues
 #using MIRTjim: prompt
 
+"""
+    jim(args...; kwargs...)
+Create a blank plot and then call `jim!`.
+"""
+function jim(args...; kwargs...)
+    pp = plot()
+    return jim!(pp, args...; kwargs...)
+end
+
 
 _units_same(x::Real, y::Real) = false
 _units_same(x::Number, y::Number) = oneunit(x) == oneunit(y)
@@ -144,7 +153,7 @@ _fft0_axis(n::Int) = (-n÷2):(n÷2 - iseven(n))
 
 
 """
-    jim(z, ...)
+    jim(z, ...) or jim!(pp::Plot, z, ...)
 
 A jiffy image display of `z` using `heatmap`.
 
@@ -179,7 +188,8 @@ option
 out
 - returns plot handle, type `Plots.Plot`
 """
-function jim(
+function jim!(
+    pp::Plot,
     z::AbstractMatrix{<:Number} ;
     abswarn::Bool = jim_def[:abswarn],
     kwargs...,
@@ -193,20 +203,22 @@ function jim(
         abswarn && (@warn "magnitude at $(caller_name())")
         z = abs.(z) # due to Unitful complex types not being <: Complex
     end
-    return _jim(z ; kwargs...)
+    return _jim!(pp, z ; kwargs...)
 end
 
 
 """
-    jim(z::Matrix{<:Colorant}; kwargs...)
+    jim(z::Matrix{<:Colorant}; kwargs...) or jim!(pp::Plot, ...)
+    jim!(pp::Plot, ...)
 For RGB images, ignore `clim`, `color`, `x`, `y`.
 """
-function jim(
+function jim!(
+    pp::Plot,
     z::AbstractMatrix{<:Colorant} ; # RGB
     kwargs...,
 )
     xy = () # https://github.com/JuliaPlots/Plots.jl/issues/4158
-    return _jim(z ; xy, kwargs...)
+    return _jim!(pp, z ; xy, kwargs...)
 end
 
 
@@ -225,7 +237,9 @@ end
 _uniform(z::AbstractMatrix) = nothing
 
 # 2D image
-function _jim(z::AbstractMatrix ;
+function _jim!(
+    pp::Plot,
+    z::AbstractMatrix ;
     clim = _clim(z),
     color = jim_def[:color],
     colorbar = jim_def[:colorbar],
@@ -270,7 +284,7 @@ function _jim(z::AbstractMatrix ;
 
     tmp = _uniform(z) # uniform or nearly uniform image
     if !isnothing(tmp)
-        p = plot(
+        plot!(pp,
             [xlims[1]], [ylims[1]], # https://github.com/JuliaPlots/Plots.jl/issues/4576
             ;
             label="",
@@ -289,7 +303,7 @@ function _jim(z::AbstractMatrix ;
 
     else
 
-        p = heatmap(xy..., z' ;
+        heatmap!(pp, xy..., z' ;
             transpose = false,
             clim,
             color,
@@ -309,20 +323,22 @@ function _jim(z::AbstractMatrix ;
 
     gui && Plots.gui()
     prompt && MIRTjim.prompt()
-    return p
+    return pp
 end # jim
 
 
 
 # OffsetArray / OffsetMatrix
 # https://github.com/JuliaPlots/Plots.jl/issues/2410
 _axes(z,j) = axes(z,j).parent .+ axes(z,j).offset
-function jim(z::OffsetMatrix{<:Number} ;
+function jim!(
+    pp::Plot,
+    z::OffsetMatrix{<:Number} ;
     x = _axes(z,1),
     y = _axes(z,2),
     kwargs...
 )
-    jim(OffsetArrays.no_offset_view(z) ; x, y, kwargs...)
+    jim!(pp, OffsetArrays.no_offset_view(z) ; x, y, kwargs...)
 end
 
 #=
@@ -340,54 +356,58 @@ end
 
 # AxisArray / AxisMatrix
 const AxisMatrix{T} = AxisArray{T,2,D,Ax} where {T,D,Ax}
-function jim(z::AxisMatrix{<:Number} ;
+function jim!(
+    pp::Plot,
+    z::AxisMatrix{<:Number} ;
     x = axisvalues(z)[1],
     y = axisvalues(z)[2],
     xlabel = String(axisnames(z)[1]),
     ylabel = String(axisnames(z)[2]),
     kwargs...
 )
-    jim(parent(z) ; x, y, xlabel, ylabel, kwargs...)
+    jim!(pp, parent(z) ; x, y, xlabel, ylabel, kwargs...)
 end
 
 
 # Convenience methods
 
 """
-    jim(z, title::String ; kwargs...)
+    jim(z, title::String ; kwargs...) or jim!(pp::Plot, ...)
 """
-jim(z::AbstractArray, title::AbstractString ; kwargs...) =
-    jim(z ; title, kwargs...)
+jim!(pp::Plot, z::AbstractArray, title::AbstractString ; kwargs...) =
+    jim!(pp, z ; title, kwargs...)
 
 
 """
-    jim(x, y, z ; kwargs...)
+    jim(x, y, z ; kwargs...) or jim!(pp::Plot, ...)
 
 The `x` and `y` axes can be Unitful.
 """
-function jim(
+function jim!(
+    pp::Plot,
     x::AbstractVector{<:RealU},
     y::AbstractVector{<:RealU},
     z ;
     kwargs...,
 )
-    return jim(z ; x, y, kwargs...)
+    return jim!(pp, z ; x, y, kwargs...)
 end
 
 
 """
-    jim(x, y, z, title::String ; kwargs...)
+    jim(x, y, z, title::String ; kwargs...) or jim!(pp::Plot, ...)
 
 Allow `title` as positional argument for convenience.
 """
-function jim(
+function jim!(
+    pp::Plot,
     x::AbstractVector{<:RealU},
     y::AbstractVector{<:RealU},
     z,
     title::AbstractString ;
     kwargs...,
 )
-    return jim(x, y, z ; title, kwargs...)
+    return jim!(pp, x, y, z ; title, kwargs...)
 end
 
 
@@ -408,12 +428,12 @@ Subplot-type layout, where `kwargs` are passed to `plot`.
 - `gui` call `Plots.gui()` immediately?; default `false`
 - `prompt` call `prompt()` immediately?; default `false`
 """
-function jim(p::Plot, args... ;
+function jim(p1::Plot, args... ;
     gui::Bool = jim_def[:gui],
     prompt::Bool = jim_def[:prompt],
     kwargs...,
 )
-    out = plot(p, args... ; kwargs...)
+    out = plot(p1, args... ; kwargs...)
     gui && Plots.gui()
     prompt && MIRTjim.prompt()
     return out

src/tuple.jl

@@ -1,22 +1,24 @@
 # tuple.jl
 # Arrays of Tuples or Vectors
 
-export jim
+export jim!
 
 
 """
     jim(..., z::AbstractArray{<:NTuple{N,Number} where N}, ... ; kwargs...)
     jim(..., z::AbstractArray{<:AbstractVector{<:Number}}, ... ; kwargs...)
+    jim!(pp::Plot, ...)
 
 Stack Tuple or Vector along the last dimension.
 """
-function jim(
+function jim!(
+    pp::Plot,
     z::AbstractArray{<:Union{NTuple{N,Number} where N, AbstractVector{<:Number}}},
     ;
     catdims::Int = ndims(z) + 1,
     kwargs...
 )
     ntup = length(z[begin])
     zz = cat([[t[i] for t in z] for i in 1:ntup]..., dims = catdims)
-    return jim(zz ; kwargs...)
+    return jim!(pp, zz ; kwargs...)
 end