[guijacquemet]

Stacked on #213 (itself on #212 and #211). The base is claude/z-projection-convert, so the diff shows only this PR; GitHub retargets as the earlier ones merge.

What changed

Fourth PR of the plan for #176 (design: MorphoFeature docs/restart/designs/pp176-z-projection-design-2026-11-07.md; owner answers of 2026-11-07). The command line of the recorded Z projection:

morphobricks-preprocessing convert EXP --to FOLDER --axes ZCYX --project max|mean|sum [--z-range 2:10]
                                  [--masks FOLDER] [--output FOLDER] [--memory-limit 2GiB] [--exclude PATH]

• --project has no default method: --project alone, --project median or --project MAX is a parser error ("--project needs a method: max, mean or sum. There is no default: choose the one that fits your analysis."), exit 2, nothing read.
• --z-range START:STOP is zero-based and half-open for the whole experiment (4:5 is the single slice 4); it is checked at parse time (whole numbers, 0 <= START < STOP); without --project it is refused (exit 2); a range an image does not have is projection_z_range_outside naming the short images (exit 1, nothing written).
• The masks folder (--masks, or the one the run recorded in --output) is scanned from headers for 3-D masks, which stop the projection; 2-D masks do not.
• Output: what was written ("max projections of slices 1:4, written as 2-D OME-TIFF: 2 images"), the record path and its SHA-256, then the next commands for a new output folder, by default <--to>_MorphoBricks_Preprocessing (the projected copies are a different source, a new description lineage; the text says the design and the pixel sizes are entered again), with --axes of the copies (CYX). --output still names where the runs on the originals recorded their masks.
• z_stack_not_supported now names the command instead of Fiji: "Make 2-D projected copies first: convert EXPERIMENT --to FOLDER --axes ROLES --project max|mean|sum (the originals are only read), then run on the copies; or exclude these images." (check, run and convert without --project still refuse a Z-stack, so nothing is projected implicitly.)
• ConversionResult.projection carries the record's method and range. Two parser-building helpers keep add_convert_parser under the 60-line rule.
• Docs: user guide (command, next commands, z_stack_not_supported row), contract §2, README, CHANGELOG.

Regression test

tests/test_cli_projection.py (16 tests). The regression is test_convert_project_makes_copies_the_run_accepts: without --project a Z-stack is refused with the new message and nothing is written; with --project max --z-range 1:4 the copies equal stack[1:4].max(axis=0), the record says max (1, 4), the printed check and run commands name the new folder and --axes CYX, and following them (check, design --confirm-all, run) writes plane_histograms.csv. Others: the parser errors, --z-range forms, a range that does not fit, 3-D vs 2-D masks, another method into the same folder.

• On the old code (the tip of Z projection 3/6: plan and write projected copies (part of #176) #213): 16 failed, 0 passed (unrecognized arguments: --project max, and the old hint).
• On this branch: 16 passed. tests/test_2d_planes_only.py asserted the old hint ("Z Project"); it now asserts --project max|mean|sum.

Checks

python tools/check.py: Ruff, formatting and code rules clean; 4335 passed, 4 skipped, 2 warnings. The base (#213) gives 4319 passed, 4 skipped, 2 warnings; the difference is the 16 new tests. The 4 skips are the pre-existing ones (case-insensitive file system x3, file modes x1).

Not in this series yet

• PR 5 (run side: manifest projection, RunInputs.projection, masks_on_projected_images, report text) is not started. It needs run_inputs.py, the manifest and the run modules that the open PRs Re-pin the vendored Spec to b197ac1; reserved names apply to used_ids.channels #208, Run integration of the published experiment description (Stage 1, PR 11) #209 and Semantic RunInputs from a published description (Stage 1, PR 12) #210 are changing (Run integration of the published experiment description (Stage 1, PR 11) #209 moves RunInputs code into new modules); doing it now would conflict. It should follow once those merge.
• PR 6 (notebook card) and PR 7 (homogeneity key) are not started. OME-Zarr stacks are refused (projection_zarr_not_supported, see Z projection 3/6: plan and write projected copies (part of #176) #213).

Series: 1 pure module (#211), 2 record v3 (#212), 3 plan and write (#213), 4 CLI (this PR), 5 run side, 6 notebook card.

---

Generated by Claude Code