Expose Makefile animation parameters in makeMovie (#218)

Add framerate, magick_density, magick_resize_x, and magick_resize_y
keyword arguments so users can override the PhysiCell Makefile's
FRAMERATE, MAGICK_DENSITY, MAGICK_RESIZE_X, and MAGICK_RESIZE_Y
variables when generating a movie, instead of being stuck with
whatever the Makefile hardcodes.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: drbergman

PRD.md

@@ -294,6 +294,29 @@
 
 ---
 
+## Feature: Movie Generation
+
+**One-line description:** Render a simulation's SVG snapshots into a movie via the PhysiCell Makefile's `jpeg`/`movie` targets.
+
+**Priority:** Should-have
+
+**Behavioral specification:**
+- `makeMovie(simulation_id)` invokes `make jpeg` then `make movie` in `physicellDir()`, deletes the intermediate JPEGs, and leaves `out.mp4` in the simulation's output folder.
+- `makeMovie(T::AbstractTrial)` / `makeMovie(out::PCMMOutput)` batch this over every simulation in the trial/output.
+- Keyword arguments `framerate`, `magick_density`, `magick_resize_x`, `magick_resize_y` forward directly to the Makefile's `FRAMERATE`, `MAGICK_DENSITY`, `MAGICK_RESIZE_X`, `MAGICK_RESIZE_Y` variables (`movie`/`jpeg` targets respectively). Each defaults to `missing`, in which case the Makefile's own default for that variable is used unchanged.
+- `magick_path`/`ffmpeg_path` locate the ImageMagick/FFmpeg executables; `verbose` prints the underlying `make` command output.
+
+**Acceptance criteria:**
+- Omitting the new framerate/density/resize keywords reproduces the exact previous behavior (Makefile defaults).
+- Passing any of the four keywords changes the corresponding `make` invocation's variable assignment and is reflected in the produced movie.
+- Re-running `makeMovie` when `out.mp4` already exists is a no-op (`false` return), regardless of these keywords.
+
+**Edge cases:**
+- No `s*.svg` files in the output folder → warn and skip (`false` return), independent of these keywords.
+- ImageMagick or FFmpeg not discoverable on `PATH` → throws `ErrorException`.
+
+---
+
 ## Feature: Post-Processing Hook & Quantities of Interest
 
 **One-line description:** Let users compute per-simulation quantities of interest (QoIs) from intact output via a `post_processor` callback, and guarantee that PCMM's destructive pruning runs only after that callback.

README.md

@@ -90,6 +90,7 @@ julia> out = run(inputs, dv; n_replicates = 3) # 3 replicates per apoptosis rate
   - [x] Ready-made PhysiCell QoI builder (`populationCountQoI`) so a `post_processor` can be a one-liner — per-cell-type counts at the final snapshot or any indexed save
 - [x] Intracellular model support (custom data, rules)
 - [x] IC cell and IC ECM file management
+- [x] Movie generation via the PhysiCell Makefile (`makeMovie`) — configurable `framerate`, `magick_density`, `magick_resize_x`/`magick_resize_y` keyword arguments
 
 ### Remaining
 

docs/src/man/analyzing_output.md

@@ -236,6 +236,29 @@ agent_ids = DataFrame(ID=[a.id for a in connected_components_1]) # get the IDs f
 component_df = rightjoin(cells_df, agent_ids, on=:ID) # join on the agent IDs, keeping only the rows in the connected component
 ```
 
+## Movies
+
+[`makeMovie`](@ref) uses the PhysiCell Makefile to turn a simulation's SVG snapshots into `output/out.mp4`, deleting the intermediate JPEGs afterward. It requires ImageMagick and FFmpeg to be discoverable — on `PATH`, via `PCMM_IMAGEMAGICK_PATH`/`PCMM_FFMPEG_PATH`, or passed directly as `magick_path`/`ffmpeg_path`.
+
+```julia
+makeMovie(1)          # simulation 1 -> output/out.mp4
+makeMovie(sampling)   # every simulation in a trial
+makeMovie(out)        # every simulation in a `run` result
+```
+
+The Makefile's own animation variables are exposed as keyword arguments. Omit any of them to keep that Makefile's default:
+
+| Keyword | Makefile variable | Typical default |
+|---|---|---|
+| `framerate` | `FRAMERATE` | 24 |
+| `magick_density` | `MAGICK_DENSITY` | 96 |
+| `magick_resize_x` | `MAGICK_RESIZE_X` | 1024 |
+| `magick_resize_y` | `MAGICK_RESIZE_Y` | 1024 |
+
+```julia
+makeMovie(1; framerate=10, magick_density=48, magick_resize_x=512, magick_resize_y=512)
+```
+
 ## Post-processing during a run
 
 Everything above analyzes output *after* a run finishes. `run` also accepts a `post_processor` keyword: a callback invoked once per successful simulation, right after it finishes and before PhysiCellModelManager.jl prunes any output — so the callback always sees the intact output folder, however aggressive your `prune_options` are.

docs/src/man/examples.md

@@ -119,6 +119,14 @@ using Plots
 plot(Simulation(1); include_cell_type_names=["cd8", "cancer"])
 ```
 
+## Make a movie from a simulation's snapshots
+
+Use `makeMovie` to render a simulation's SVG snapshots into `out.mp4` via the PhysiCell Makefile. Override `framerate`, `magick_density`, `magick_resize_x`, or `magick_resize_y` to change frame rate or JPEG resolution/density; omit any to keep the Makefile's default. → [Analyzing output](@ref)
+
+```julia
+makeMovie(1; framerate=10, magick_resize_x=512, magick_resize_y=512)
+```
+
 ## Extract per-cell time series
 
 Use `cellDataSequence` to pull a labeled quantity for every cell across time. → [Analyzing output](@ref)

progress.md

@@ -5,6 +5,27 @@
 
 ---
 
+## 2026-07-08 — Expose Makefile animation parameters (`framerate`, `magick_density`, `magick_resize_x/y`) in `makeMovie`
+
+### Motivation
+`makeMovie` (`src/movie.jl`) only ever forwarded `OUTPUT=` to the PhysiCell Makefile's `jpeg`/`movie` targets, even though that Makefile also reads `FRAMERATE`, `MAGICK_DENSITY`, `MAGICK_RESIZE_X`, `MAGICK_RESIZE_Y` (defaults 24 fps / 96 dpi / 1024×1024). Users had no way to control frame rate or JPEG resolution/density from Julia.
+
+### Design
+- Added four new keyword arguments to `makeMovie(simulation_id::Int; ...)`, each `Union{Missing,Int}=missing`, mirroring the existing `magick_path`/`ffmpeg_path` sentinel pattern already in this function rather than inventing a new convention.
+- Each is only appended as a `"VAR=value"` string to the relevant `Cmd` when not `missing` — an unset keyword falls through to whatever the target project's own Makefile defines for that variable, rather than PCMM silently overriding a user's project-level Makefile customization.
+- `framerate` targets the `movie` command; `magick_density`, `magick_resize_x`, `magick_resize_y` target the `jpeg` command (matches which Makefile target actually reads which variable).
+- `makeMovie(T::AbstractTrial; kwargs...)` / `makeMovie(T::PCMMOutput; kwargs...)` needed no changes — they already forward `kwargs...` untouched.
+
+### Testing
+Extended `test/test-scripts/MovieTests.jl` with a case passing non-default values for all four new keywords and confirming `out.mp4` is still produced; existing no-kwargs path is unchanged and still covered.
+
+### Docs
+- `docs/src/lib/movie.md` needed no edit — it's an `@autodocs` page over `movie.jl`, so the updated docstring flows through automatically.
+- Added a "Movies" section to `docs/src/man/analyzing_output.md` (before "Post-processing during a run") documenting `makeMovie` and a table mapping each new keyword to its Makefile variable and default.
+- Added a matching recipe to the `examples.md` cookbook, linking back to that new section, following the existing task → minimal code → link pattern.
+
+---
+
 ## 2026-07-08 — Task B: `populationCountQoI`, a ready-made `post_processor` builder
 
 ### Motivation

src/movie.jl

@@ -26,6 +26,10 @@ There are three ways to allow this function to find these dependencies:
 - `magick_path::Union{Missing,String}`: The path to the ImageMagick executable. If not provided, uses `simulator().path_to_magick`.
 - `ffmpeg_path::Union{Missing,String}`: The path to the FFmpeg executable. If not provided, uses `simulator().path_to_ffmpeg`.
 - `verbose::Bool`: If `true`, prints the output of the commands used to generate the movie. Default is `false`.
+- `framerate::Union{Missing,Int}`: Frames per second, forwarded to the Makefile's `FRAMERATE` variable. If not provided, uses the Makefile's own default.
+- `magick_density::Union{Missing,Int}`: JPEG rendering density (dpi), forwarded to the Makefile's `MAGICK_DENSITY` variable. If not provided, uses the Makefile's own default.
+- `magick_resize_x::Union{Missing,Int}`: JPEG resize width, forwarded to the Makefile's `MAGICK_RESIZE_X` variable. If not provided, uses the Makefile's own default.
+- `magick_resize_y::Union{Missing,Int}`: JPEG resize height, forwarded to the Makefile's `MAGICK_RESIZE_Y` variable. If not provided, uses the Makefile's own default.
 
 # Example
 ```julia
@@ -38,8 +42,12 @@ makeMovie(sampling) # make movies for all simulations in the sampling
 out = run(sampling) # run the sampling
 makeMovie(out) # make movies for all simulations in the output
 ```
+```julia
+makeMovie(123; framerate=10, magick_density=48, magick_resize_x=512, magick_resize_y=512)
+```
 """
-function makeMovie(simulation_id::Int; magick_path::Union{Missing,String}=simulator().path_to_magick, ffmpeg_path::Union{Missing,String}=simulator().path_to_ffmpeg, verbose::Bool=false)
+function makeMovie(simulation_id::Int; magick_path::Union{Missing,String}=simulator().path_to_magick, ffmpeg_path::Union{Missing,String}=simulator().path_to_ffmpeg, verbose::Bool=false,
+    framerate::Union{Missing,Int}=missing, magick_density::Union{Missing,Int}=missing, magick_resize_x::Union{Missing,Int}=missing, magick_resize_y::Union{Missing,Int}=missing)
     assertInitialized()
     path_to_output_folder = joinpath(trialFolder(Simulation, simulation_id), "output")
     if isfile("$(path_to_output_folder)/out.mp4")
@@ -67,9 +75,16 @@ function makeMovie(simulation_id::Int; magick_path::Union{Missing,String}=simula
         movie_generated = false
         return movie_generated
     end
-    cmd = Cmd(`make jpeg OUTPUT=$(path_to_output_folder)`; env=env, dir=physicellDir())
+    jpeg_args = ["make", "jpeg", "OUTPUT=$(path_to_output_folder)"]
+    ismissing(magick_density) || push!(jpeg_args, "MAGICK_DENSITY=$(magick_density)")
+    ismissing(magick_resize_x) || push!(jpeg_args, "MAGICK_RESIZE_X=$(magick_resize_x)")
+    ismissing(magick_resize_y) || push!(jpeg_args, "MAGICK_RESIZE_Y=$(magick_resize_y)")
+    cmd = Cmd(Cmd(jpeg_args); env=env, dir=physicellDir())
     verbose ? run(cmd) : quietRun(cmd)
-    cmd = Cmd(`make movie OUTPUT=$(path_to_output_folder)`; env=env, dir=physicellDir())
+
+    movie_args = ["make", "movie", "OUTPUT=$(path_to_output_folder)"]
+    ismissing(framerate) || push!(movie_args, "FRAMERATE=$(framerate)")
+    cmd = Cmd(Cmd(movie_args); env=env, dir=physicellDir())
     verbose ? run(cmd) : quietRun(cmd)
     movie_generated = true
     jpgs = readdir(joinpath(trialFolder(Simulation, simulation_id), "output"), sort=false)

test/test-scripts/MovieTests.jl

@@ -9,10 +9,17 @@ if Sys.isapple()
     @test makeMovie(1; verbose=true) === false
     @test makeMovie(run(Simulation(1)); verbose=true) |> isnothing #! makeMovie on the PCMMOutput object
 
-    #! Test that makeMovie returns false if no SVGs are found
     sim = Simulation(1)
     inputs = sim.inputs
     variation_id = sim.variation_id
+
+    #! Test that the framerate/magick_density/magick_resize_x/magick_resize_y kwargs still produce a movie
+    custom_params_sim = Simulation(inputs, variation_id)
+    run(custom_params_sim)
+    @test makeMovie(custom_params_sim.id; framerate=10, magick_density=48, magick_resize_x=256, magick_resize_y=256)
+    @test isfile(joinpath(PhysiCellModelManager.dataDir(), "outputs", "simulations", string(custom_params_sim.id), "output", "out.mp4"))
+
+    #! Test that makeMovie returns false if no SVGs are found
     new_sim = Simulation(inputs, variation_id)
     out = run(new_sim)