picmaker rewrite: modernize repo, decompose god module, add tests/docs/CI

[rfrenchseti]

Summary

This PR merges the cumulative work of branch picmaker_rewrite into main. Treat it as one changeset — every commit is part of the same modernization effort. The work spans repo packaging, a complete decomposition of the legacy picmaker.py god module, a comprehensive test suite with byte-identical snapshot regression coverage, full user / developer / API documentation, and an activated CI pipeline that runs lint, type-checking, security scans, doc builds, and the test matrix across nine OS/Python combinations on every push.

The legacy import path from picmaker.picmaker import … continues to work and resolves to the same function objects as from picmaker import … (identity-equal, gated by tests/test_api_compat.py).

Repo modernization

The repository now follows the standard SETI/PDS Rings Node rms-* project layout with a real src/-layout package, pyproject.toml as the single source of truth, and reproducible dev workflow.

• pyproject.toml carries the real description, keywords, runtime-dependency floors pinned to currently-installed versions (astropy>=7.2.0, numpy>=2.4.4, pillow>=12.2.0, scipy>=1.17.1, plus the sibling SETI packages), and dev extras (mypy, bandit, vulture, pip-audit). pyroma . scores 10/10.
• requires-python raised to 3.11+ (astropy 7.x requires it; the target-version = "py311" in ruff and the classifier list match).
• [project.scripts] flipped from picmaker.picmaker:main to picmaker.cli:main.
• setuptools_scm writes the package version to src/picmaker/_version.py at build time; the runtime resolves it via importlib.metadata.version('rms-picmaker') with a _version.py fallback.
• src/picmaker/py.typed is now actually on disk (the marker was declared in [tool.setuptools.package-data] but missing).
• scripts/run-all-checks.sh is the canonical orchestrator. Defaults are now ENABLE_RUFF_CHECK=true, ENABLE_MYPY=true, ENABLE_PYTEST=true, ENABLE_SPHINX=true, plus pyroma and pymarkdown.

New directory structure / file structure for the old god module

src/picmaker/picmaker.py was ~3,500 lines containing the entire library — CLI, pipeline, readers, writers, image enhancement, geometry, color handling, instrument-specific filter dispatch, and a TIFF16 driver. It has been decomposed into per-concern leaf modules and an instruments/ subpackage:

src/picmaker/
├── __init__.py          # public API re-exports (53 symbols in __all__)
├── cli.py               # argparse entry point (was optparse)
├── pipeline.py          # find_common_path / process_images / images_to_pics
├── options.py           # PicmakerOptions dataclass (new — owns mutex/value validation)
├── io.py                # reader cascade (Pickle → numpy → VICAR → FITS → PDS3 → PIL)
├── enhance.py           # fill_zebra_stripes, get_limits, apply_colormap, apply_gamma
├── geometry.py          # circle_mask, slice_array, crop_array, rotate_array_rgb,
│                        # get_size, resize_image, wrap_image, pad_image
├── color.py             # tinted_colormap (delegates to instruments.lookup)
├── pil_utils.py         # array_to_pil, pil_to_array, write_pil
├── _filters.py          # FILTER_DICT + filter_image
├── _rgb.py              # wavelength→RGB tables (leaf, no internal imports — cycle break)
├── colornames.py        # X11 color-name table (cleaned, typed, public)
├── tiff16.py            # 16-bit grayscale/RGB/palette TIFF I/O (cleaned, typed)
├── picmaker.py          # alternate import path; re-export shim (53 names)
├── py.typed
└── instruments/
    ├── __init__.py      # dispatch (matches → tint_for) over registered modules
    ├── cassini.py       # 4-method protocol implementation
    ├── voyager.py
    ├── galileo.py
    ├── hst.py
    └── nh.py            # New Horizons MVIC

The new instrument subpackage replaces the previous block of if instrument == 'CASSINI': ... elif instrument == 'VOYAGER': ... control flow scattered through the god module. Each instrument is now a self-contained module implementing a uniform 4-method protocol — detect_vicar, detect_fits, matches, tint_for — and the dispatch tables in io.read_one_image_array and color.tinted_colormap are data rather than control flow. The protocol is documented in docs/dev/adding_an_instrument.rst along with a step-by-step recipe for adding a new mission.

src/picmaker/picmaker.py collapsed from 3,493 lines to a 103-line re-export shim. The pipeline algorithms (limits, gamma, colormap, etc.) are preserved verbatim so the byte-identical snapshot tests stay green; the structural changes are the module split, the argparse migration, and the bug fixes (below).

Documentation

The project now has a full Sphinx documentation set under docs/:

• User Guide (docs/user_guide.rst) — overview, install (pip / pipx), quick start, full CLI reference organized by --help group, input-format cascade, per-instrument tints (Cassini, Voyager, Galileo, HST, NH MVIC), output formats, the enhancement and geometry pipelines, the --versions form, programmatic usage examples, troubleshooting.
• Developer Guide (docs/developer_guide.rst + docs/dev/*.rst) — index page with a nested toctree of six per-section files:
  • dev/repository_overview.rst — purpose, layout, dev-environment setup.
  • dev/module_layout.rst — module-by-module description with per-symbol Sphinx cross-references.
  • dev/pipeline.rst — Mermaid flowchart and walk-through from CLI entry through the reader cascade, enhancement, geometry, and PIL write.
  • dev/running_tests.rst — pytest invocation, snapshot regeneration.
  • dev/adding_an_instrument.rst — the 4-method protocol + 7-step recipe.
  • dev/releasing.rst — one-time PyPI trusted-publisher setup + cut-a-release flow.
• API reference (docs/module.rst) — autodoc per leaf module, plus a "Public API" section listing every name in picmaker.__all__ organized by topic. Source-code GitHub links at the top of each section.
• Docstrings: every public function/class in the new module set has a Google-style docstring with Parameters: / Returns: / Raises: sections wrapped at 90 columns (project convention from .cursor/rules/python_best_practices.mdc).
• docs/conf.py configures intersphinx mappings (python, numpy, matplotlib, PIL, astropy, sphinx, pytest), nitpick handling for sibling-package types, and show-inheritance for autodoc.

Both sphinx-build -W -b html and sphinx-build -n -b html are zero-warning clean and run in CI.

Test suite

• 352 test functions in 38 test files; pytest collects 471 tests (parametrization expands the function count).
• Coverage: 90.31%, with [tool.coverage.report].fail_under = 90 enforced by pytest --cov. Per-module coverage ranges from 87% (io.py, pipeline.py) to 100% (__init__.py).
• pytest filterwarnings = ["error"] is in pyproject.toml, so any new ResourceWarning / DeprecationWarning fails CI.

The test suite is organized in three layers, each pinning the rewrite against the pre-refactor behavior in a different way:

Black-box tests

Subprocess-driven CLI tests in tests/test_cli.py and the alias / --versions / --overlap / mutex tests. The key compatibility gate is tests/fixtures/.baseline-flags.txt — a snapshot of every long flag emitted by the legacy optparse build of picmaker --help, captured before the rewrite. The argparse rewrite has to match this set byte for byte, and tests/test_cli.py::test_help_flags_match_baseline runs that check on every CI build. .baseline-help.txt is a companion snapshot of the full help text. tests/test_cli.py::test_user_guide_documents_every_cli_flag also asserts every flag appears in the User Guide, so a new CLI flag with no docs now fails CI.

White-box tests

Per-module unit tests targeting each branch in each leaf module. The post-decomposition coverage gains are visible at the module level — cli.py 5%→91%, io.py 50%→87%, pipeline.py 50%→87%, pil_utils.py 66%→98%, enhance.py 69%→90%, geometry.py 70%→90%, per-instrument modules 67–83%→96–100%. Tests assert exact numeric outputs (analytically-computed RGB volumes, exact (lo, hi) tuples from get_limits) rather than loose shape checks, so future refactors cannot silently change pipeline math.

Integration tests

tests/test_pipeline.py exercises images_to_pics end-to-end against every instrument fixture with combinations of gamma, percentile stretch, tint, rotation, --movie, 16-bit TIFF output, and --hst ACS/WFC/WFPC2 branches. tests/test_io.py and tests/test_io_cascade.py exercise the reader cascade across every supported format, including the malformed-input paths that must reach the cascade-end OSError("Unrecognized image file format ...").

Snapshot regression — byte-identical compatibility with the original picmaker

tests/fixtures/expected/ contains 63 byte-identical output snapshots (7 instrument fixtures × 9 representative option combos: default, gamma2, pct5_95, colormap_red_blue, tint, rot90, frame_128_pad, frame_max_50, twobytes_tiff). The snapshots were generated before the god-module decomposition. tests/test_snapshots.py is parametrized across SNAPSHOTS and asserts byte equality of every produced output against the committed fixture. Any change to the enhancement, geometry, or color pipeline that perturbs a single output byte fails this test.

The generator (tests/fixture_recipes/generate_snapshots.py) is itself committed and re-run in CI by the Snapshot freshness check step. The check runs the generator and asserts git diff --exit-code is clean on tests/fixtures/expected/ and tests/snapshots_index.py. Silent drift in the pipeline (e.g., a pillow-version-driven JPEG quantizer change) will fail this step.

Compatibility enforcement going forward

• tests/test_api_compat.py — asserts identity-equality between picmaker.X and picmaker.picmaker.X for all 53 public names, so the legacy import path can never silently diverge.
• tests/fixtures/.baseline-flags.txt — pinned via test_help_flags_match_baseline.
• tests/test_happy_path_no_warnings.py — runs the default images_to_pics path and asserts no WARNING-level log records are emitted, so accidentally introducing a deprecation chirp in the default path fails CI.
• Snapshot freshness CI step (above) — drift in committed snapshots vs. regenerated output fails the build.

Bugs fixed

Latent / dormant bugs surfaced and fixed during the rewrite. None are scope creep; each was found by the new test suite, mypy strict, ruff, bandit, vulture, or a Sphinx build:

• read_one_image_array palette branch: return IOError(...) constructed the exception but never raised it — fell through silently to array_to_pil() with palette data lost. Now raises.
• process_images --movie branch: if proceed: referenced a nonexistent local. Reworked to read option_dicts[0]['proceed'] with an assert-now-raise ValueError invariant check (the previous assert was stripped under python -O).
• read_pds_labeled_image_array was raising AttributeError on every PDS3 file — it called the removed pdsparser.PdsOffsetPointer and node.name/node.value API. Rewritten to use the current dict-style label[key] plus the <pname>_offset / <pname>_unit companion keys.
• tiff16.py: missing raise on the version-byte mismatch (the function silently accepted non-TIFF files with a valid II/MM byte order but wrong version field). Regression test added.
• tiff16.WriteTiff16: palette != None raised ValueError under modern numpy (ambiguous truth). Fixed to is not None.
• tiff16.WriteTiff16 / ReadTiff16: file-handle leaks — open(...) was not wrapped in with. Fix surfaced by pytest filterwarnings = ["error"] catching the ResourceWarning.
• tiff16.WriteTiff16: silently produced a big-endian file for any byteorder value other than 'little'. Now validated against {'native', 'little', 'big'} (case-insensitive) and raises ValueError otherwise.
• io.read_one_image_array: FITS handle was not closed when the HST mosaic / obj branches raised. Now opened in a with pyfits.open(...) as hdulist: block.
• colornames.ColorNames.lookup used eval(...). Replaced with ast.literal_eval. Also: stopped shadowing the builtin tuple local; raises KeyError on partial regex matches instead of returning a misleading partial-color tuple. Two new tests pin the boundary.
• pil_utils._one_pil_to_array ignored rescale=True for 'L'-mode PIL images. Now returns a float in [0, 1].
• pipeline.find_common_path had a Windows path-separator bug — switched to os.path.commonpath, then later switched to os.path.splitdrive-based root detection so Windows drive-only roots (C:\\) are recognized alongside POSIX /.
• geometry.py: a stray list.append(_resize_one_image(...)) was calling the unbound class method on list instead of result.append(...). The errant # type: ignore[call-arg] covering this was removed.
• io.read_one_image_array lose-traceback: except IOError as e: raise e deleted from the pickle branch (replaced with the cascade-end OSError chained from ExceptionGroup('No reader matched', cascade_errors) so per-reader failure causes survive for diagnosis).
• Mutable defaults: strip=[] and pointer=['IMAGE'] in images_to_pics / get_outfile are now None with the list normalized inside the function.
• Pillow deprecation: Image.FLIP_* / Image.ROTATE_* → Image.Transpose.* (25 call sites in tiff16.py); Image.NEAREST / Image.LANCZOS → Image.Resampling.NEAREST / Image.Resampling.LANCZOS.
• from struct import * in tiff16.py narrowed to from struct import pack, unpack.
• warnings.warn in get_outfile now passes UserWarning explicitly.
• HST tint dispatcher: print('******UNKNOWN FILTER:', ...) → logger.warning(...).
• traceback.print_tb(...) → logger.exception(...) in the pipeline (deterministic ordering under pytest -n auto).
• Shebangs dropped from tiff16.py and colornames.py.

Public API changes

• from picmaker import X is now the canonical import path. picmaker.__init__ re-exports the 53 public names. from picmaker.picmaker import X continues to work and resolves to the same object (identity-equal).
• New picmaker.options.PicmakerOptions dataclass — owns all post-normalization mutex / value-validity checks via validate(). Both cli._normalize_and_validate and pipeline.images_to_pics delegate to it.
• New picmaker.io.ReadResult NamedTuple (array3d, default_is_up, filter_info) returned by the reader cascade. Positional unpacking still works; .array3d attribute access now also works.
• New picmaker.io.FilterInfo type alias for the (inst_host, inst_id, filter_name) | None union.
• picmaker.io.ObjectSelector type alias replaces Any in read_image_array / read_one_image_array signatures.
• pipeline.images_to_pics filter= kwarg renamed to filter_name= (it was shadowing the builtin). The CLI --filter flag is unchanged via dest='filter_name'.
• [project.scripts] entry point: picmaker = picmaker.cli:main (was picmaker.picmaker:main).
• CLI: optparse → argparse. Every flag spelling preserved, including the underscore aliases (--alt_strip, --alt_pointer, --gapsize, --gapcolor, --trimzeros, --frame_max). Two argparse semantics differences are documented in tests:
  • argparse emits lowercase usage: (optparse used Usage:).
  • argparse does not accept the mixed --option=N M form for nargs=2; use the space-separated form.
• pil_to_array for 'L'-mode PIL images with rescale=True now returns a float array in [0, 1] instead of the raw uint8 array. (Behavior change to match documented contract.)
• ColorNames.lookup: list-style [r, g, b] parses are now normalized to a tuple before returning, so the two bracketing styles ((r, g, b) and [r, g, b]) produce identical output. Return annotation narrowed from Any to tuple[int, int, int].

Issues filed during the process

All open in the GitHub issue tracker, labeled by A-* (kind), Priority N, Effort N, B-* (area):

• Adopt pytest filterwarnings = ['error']; track Pillow get_flattened_data migration #9 — Adopt pytest filterwarnings = ['error']; track Pillow get_flattened_data migration (the remaining Pillow getdata ignore).
• rescale=True is ignored by pil_to_array for 'L' mode PIL images #10 — rescale=True is ignored by pil_to_array for 'L'-mode PIL images. (Fix landed in this PR; tracker kept for visibility.)
• Prune the picmaker.picmaker BC shim exports #11 — Prune the picmaker.picmaker BC shim exports once external callers have migrated.
• Split pipeline.images_to_pics and cli.main into smaller helpers #12 — Split pipeline.images_to_pics and cli.main into smaller helpers and complete the RORO migration.
• Derive instruments.{VICAR,FITS}_INSTRUMENTS from a single canonical list #13 — Derive instruments.{VICAR,FITS}_INSTRUMENTS from a single canonical list rather than two parallel sequences.
• Rename picmaker.io to avoid shadowing the stdlib io module #14 — Rename picmaker.io to avoid shadowing the stdlib io module.
• Make instrument FILTER_DICT / FILTER_NAMES private; rely on BC aliases #15 — Make instrument FILTER_DICT / FILTER_NAMES private; rely on the BC aliases.
• Stop mutating argparse.Namespace inside cli._normalize_and_validate #16 — Stop mutating argparse.Namespace inside cli._normalize_and_validate (return a new object instead).
• Standardize on pathlib.Path throughout cli.py, pipeline.py, io.py #17 — Standardize on pathlib.Path throughout cli.py, pipeline.py, io.py.
• Vectorize enhance.fill_zebra_stripes (replace Python pixel loop) #18 — Vectorize enhance.fill_zebra_stripes (replace the Python pixel loop).
• Expand CI lint job to the full 3.11/3.12/3.13 matrix #19 — Expand the CI lint job to the full 3.11 / 3.12 / 3.13 matrix (currently the lint job pins 3.11).
• Magic-byte dispatch for read_one_image_array (perf) #20 — Magic-byte dispatch for read_one_image_array to avoid the try-each-reader cascade (perf).
• HST tint_for: NICMOS polariser branch unreachable in practice #21 — HST tint_for: the NICMOS polariser branch is unreachable in practice; either remove or document.
• Rename WriteTiff16 / ReadTiff16 to snake_case #22 — Rename WriteTiff16 / ReadTiff16 to snake_case (the lone remaining ruff N802 per-file ignore).

CI

.github/workflows/run-tests.yml is fully active on pull_request, push to main, a weekly schedule, and workflow_dispatch. Two jobs run on every event:

Lint job (ubuntu-latest, Python 3.11):

• ruff check src tests — explicit rule set E, F, W, I, UP, B, SIM, C4, A, N, PT, RUF.
• mypy src tests — strict = true across both source and test trees.
• bandit -c pyproject.toml -r src -q.
• vulture src.
• sphinx-build -W -b html docs docs/_build — promotes any Sphinx warning to a fatal error.
• pymarkdown scan docs/ .cursor/ README.md CONTRIBUTING.md.
• pip-audit . against the project's declared dependencies (not the active env).

Test job — matrix of [ubuntu-latest, macos-latest, windows-latest] × [3.11, 3.12, 3.13] = 9 jobs:

• pytest --cov=picmaker --cov-report=xml -n auto tests — enforces fail_under = 90.
• Snapshot freshness check (ubuntu, py3.13 only): re-runs tests/fixture_recipes/generate_snapshots.py and asserts git diff --exit-code is clean.
• Codecov upload (ubuntu, py3.13, non-fork).

All currently green.

Release process

.github/workflows/publish_to_pypi.yml and publish_to_test_pypi.yml use PyPI Trusted Publishers / OIDC — no PYPI_API_TOKEN secret is stored. The publish jobs fire on release: published and bind to GitHub Environments named pypi / testpypi so PyPI can verify the OIDC claim.

Outstanding manual steps before the first publish (documented in docs/dev/releasing.rst):

1. On https://pypi.org/manage/account/publishing/, add a pending publisher: project name rms-picmaker, the GitHub owner / repo (case-sensitive), workflow filename publish_to_pypi.yml, environment name pypi. The pending-publisher form is needed because the project has never been uploaded — the per-project settings page does not exist yet and will return 404. PyPI promotes the pending publisher to a regular one on the first successful upload.
2. Repeat on https://test.pypi.org/manage/account/publishing/ with workflow filename publish_to_test_pypi.yml and environment name testpypi. TestPyPI is a separate registry with its own name reservations.
3. In the GitHub repo, Environments → New environment pypi (and testpypi).
4. To cut the first release: ensure CI is green, git tag v0.1.0 && git push --tags, create a GitHub Release pointing at the tag — the workflow fires automatically. Dry-run against TestPyPI via the manual workflow_dispatch trigger of publish_to_test_pypi.yml first if desired.

The package version itself is provided by setuptools_scm (driven by the git tag), so the tag is the only source of truth — no __version__ literal to bump.

Other things a future developer should know

• Project conventions live in .cursor/rules/*.mdc (all alwaysApply: true). python_best_practices.mdc is the load-bearing one: 100-col lines, Google-style docstrings wrapped at 90, pathlib over os.path, logging over print, no mutable defaults, no shadowed builtins, ≤3 positional args then keyword-only, raise … from to preserve tracebacks, __all__ + py.typed for any new public surface.
• scripts/run-all-checks.sh is the canonical orchestrator. It knows the project's RUN_* / ENABLE_* gating and runs the checks in parallel by default. Use -s for sequential, -c for code-only, -d for docs-only, or pick a single check with --pytest, --ruff-check, etc.
• Ruff quote style is single quotes (tool.ruff.format.quote-style = "single"). ruff format --check is configured but not enforced in CI — the project does not auto-run ruff format.
• Mypy is strict = true and runs against src and tests. The only remaining # type: ignore in the project is in tests/test_color.py for a deliberate non-string lookup that exercises the TypeError branch.
• Adding a new instrument is documented end-to-end in docs/dev/adding_an_instrument.rst. The four-method protocol is detect_vicar, detect_fits, matches, tint_for. Register the new module in instruments/__init__.py; the dispatch table picks it up automatically.
• Fixture recipes live in tests/fixture_recipes/ (one *.recipe.py per fixture, plus regenerate_all.py and generate_snapshots.py); the generated binaries live in tests/fixtures/. Recipes are committed so the binary blobs are reproducible from source.
• picmaker.picmaker is kept as a re-export shim so external scripts that import from picmaker.picmaker import images_to_pics (or any of the 53 public names) continue to work. Issue Prune the picmaker.picmaker BC shim exports #11 tracks pruning it after a migration period.
• CODEBASE_REVIEW.md, CODEBASE_CRITIQUE.md, TEST_SUITE_CRITIQUE.md are local working notes and are no longer git-tracked. They remain in the working tree for reference but are not part of the deliverable.
• CODE_OF_CONDUCT.md at the repo root is referenced by docs/code_of_conduct.md's :include: directive — do not move it.

Test plan

• CI green on this PR (lint job + 9-cell test matrix + snapshot freshness).
• scripts/run-all-checks.sh -s clean locally.
• Spot-check the rendered docs (Sphinx -W already gates this in CI).
• Confirm from picmaker import images_to_pics and from picmaker.picmaker import images_to_pics both resolve in a fresh interpreter and is each other.
• Before the first PyPI upload, walk through the four manual steps in docs/dev/releasing.rst.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Complete CLI implementation with extensive processing options (scaling, enhancement, geometry, colormaps, filters, tinting).
  • Multi-instrument support for astronomy missions (Cassini, Galileo, HST, New Horizons, Voyager).
  • Image enhancement and geometry tools (gamma correction, colormap application, cropping, resizing, padding).

• Documentation

  • Comprehensive README with getting-started examples, feature overview, and troubleshooting.
  • User guide covering installation, CLI reference, supported formats, and enhancements.
  • Developer guide including pipeline architecture, module layout, and release procedures.
  • Code of Conduct added.

• Chores

  • Upgraded minimum Python version from 3.10 to 3.11.
  • Migrated PyPI publishing to OIDC-based trusted publishers.
  • Expanded CI workflows (linting, type-checking, multi-platform testing).

• Tests

  • Comprehensive test suite with 80+ test modules covering CLI, I/O, instruments, and pipeline.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

The PR restructures rms-picmaker as a properly architected Python package with a public API, modular CLI, comprehensive documentation, and modern CI/CD. It raises the minimum Python version to 3.11, implements OIDC-based PyPI publishing, introduces modular CLI and pipeline components, defines a standardized instrument-detection interface across five providers (Cassini, Galileo, HST, New Horizons, Voyager), and adds extensive test coverage for all new functionality and branching paths.

Changes

Package API Definition and Core Refactoring

Layer / File(s)	Summary
Public API and module initialization src/picmaker/__init__.py, src/picmaker/options.py, src/picmaker/cli.py	Establishes the package-level public API with re-exports and __all__, introduces PicmakerOptions dataclass centralizing option validation, and wires the complete CLI entry point with parser construction, option normalization/mutex enforcement, error handling, and batch/versioned processing support.
Pipeline and orchestration src/picmaker/pipeline.py, tests/test_pipeline.py, tests/test_pipeline_branches.py	Implements images_to_pics end-to-end processing with per-file read/transform/write orchestration, PDS3 label pointer resolution, HST mosaic handling, error propagation vs logging, movie-mode shared-limits reuse, and process_images multi-file batch orchestration; comprehensive tests cover happy paths, option incompatibilities, error handling, HST branches, and edge cases.
Image I/O cascade and format support src/picmaker/io.py, tests/test_io.py, tests/test_io_cascade.py, tests/test_io_extra.py, tests/test_pds3_reader.py, tests/test_pds3_reader_branches.py	Implements cascading format detection (pickle → numpy → VICAR → FITS → PIL/TIFF16 → PDS3) with per-format failure aggregation, FITS HDU/object selection with HST mosaicking, PDS3 label parsing with record/byte addressing and prefix/suffix handling, output filename derivation with replace policies, and comprehensive format/cascade/edge-case testing.
Enhancement pipeline src/picmaker/enhance.py, tests/test_enhance.py, tests/test_enhance_branches.py	Provides histogram/percentile-based stretch limit computation with optional trimming and median filtering, percentile interpolation from cumulative histograms, grayscale-to-color LUT mapping with optional histogram shading and out-of-range coloring, gamma correction, and zebra stripe edge filling; tests cover limit computation, colormap application, and gamma transformations.
Geometry and sizing utilities src/picmaker/geometry.py, tests/test_geometry.py, tests/test_geometry_branches.py, tests/test_geometry_extra.py	Implements slicing/masking/cropping arrays, circle masking, rotation/flipping, and complex sizing logic (unwrapped vs wrapped layouts, frame constraints, wrap-ratio decisions); provides wrapping (image-to-sections-with-gaps), padding-to-frame, and resizing with mode-dependent resampling; tests cover all sizing branches, wrap/pad orchestration, and rotation variants.
PIL and 16-bit TIFF bridging src/picmaker/pil_utils.py, src/picmaker/tiff16.py, tests/test_pil_utils.py, tests/test_pil_utils_branches.py, tests/test_tiff16.py, tests/test_tiff16_branches.py	Provides bidirectional NumPy↔PIL conversion with 16-bit grayscale/RGB support and optional rescaling, and implements 16-bit TIFF reading/writing with palette and transpose support; tests cover round-trips, mode handling, and endianness/transpose behaviors.
Color and filter selection src/picmaker/_filters.py, src/picmaker/_rgb.py, src/picmaker/color.py, src/picmaker/colornames.py, tests/test_color.py, tests/test_filters_branches.py, tests/test_tinted_colormap.py, tests/test_unknown_filter_warning.py	Introduces filter dispatch and PIL filter application, wavelength-to-RGB tabulation via spline interpolators, filter-info normalization and delegation to per-instrument tinting, and RGB color-name lookup with safe parsing (replacing unsafe eval with ast.literal_eval); tests cover filter dispatch, color lookup, and instrument-specific tint inference.
Instrument detection and filter tinting src/picmaker/instruments/__init__.py, src/picmaker/instruments/{cassini,galileo,hst,nh,voyager}.py, tests/test_instruments_branches.py, tests/test_hst_filter_tuple_normalization.py	Defines the 4-function instrument protocol (detect_vicar, detect_fits, matches, tint_for), registers five concrete instrument modules with per-format detection and filter-specific RGB tinting (including Cassini ISS substring matching, HST wavelength inference with scaling/pinning rules, and instrument-specific fallback colormap paths); tests cover detection branches, tint fallback logic, and filter-specific behaviors.

Documentation and Build Infrastructure

Layer / File(s)	Summary
User and developer documentation docs/, docs/user_guide.rst, docs/dev/pipeline.rst, docs/dev/module_layout.rst, docs/dev/adding_an_instrument.rst, README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md	Adds comprehensive end-user guide with installation/CLI reference/troubleshooting, developer guide with pipeline flowchart/module layout/release procedures, instrument onboarding instructions, and updates core project docs to reflect Python 3.11+ requirement and actual feature set.
Sphinx configuration and API reference docs/conf.py, docs/module.rst, docs/index.rst	Extends autodoc settings for inheritance display, adds intersphinx mappings for upstream library docs, suppresses unresolved cross-reference warnings, and restructures module documentation from minimal autodoc to comprehensive per-module sections.
CI/CD and publish workflows .github/workflows/run-tests.yml, .github/workflows/publish_to_pypi.yml, .github/workflows/publish_to_test_pypi.yml	Expands test matrix to cover macOS/Windows and Python 3.11–3.13 with parallel execution and snapshot freshness checks, adds linting/security checks (ruff/mypy/bandit/vulture/pip-audit) with defaults enabled, and implements OIDC-based trusted publishing replacing password-based credentials.
Packaging and tooling configuration pyproject.toml, scripts/run-all-checks.sh, .cursor/rules/python_best_practices.mdc	Updates Python requirement to 3.11, specifies minimum-version runtime dependencies, enables mypy/ruff/sphinx by default, adds bandit/vulture security tooling, and updates cursor rules and CI defaults to reflect 3.11+ baseline.

Test Suite and Fixtures

Layer / File(s)	Summary
Core test infrastructure and fixtures tests/conftest.py, tests/fixture_recipes/, tests/snapshots_index.py, tests/fixtures/	Introduces pytest fixtures for fixture/expected directory paths and deterministic test arrays, creates comprehensive fixture-generation recipes (VICAR/FITS/pickle/NumPy/PDS3 samples plus corrupt files for error-path testing), auto-generates snapshot metadata indexing test variants, and populates baseline CLI flag and help text fixtures.
CLI and API compatibility tests tests/test_cli.py, tests/test_cli_unit.py, tests/test_api_compat.py, tests/test_alt_strip_alias.py, tests/test_help_*.txt	Tests CLI help output, flag parsing, option normalization/validation, mutual exclusion enforcement, subprocess entry-point invocation, kebab/snake-case alias equivalence, and backward-compatibility identity assertions for all re-exported symbols.
Pipeline and orchestration tests tests/test_pipeline.py, tests/test_pipeline_branches.py, tests/test_snapshots.py, tests/test_versions_override.py, tests/test_frame_max.py, tests/test_happy_path_no_warnings.py	Covers happy-path conversions across all fixtures with option combinations, error handling (mutex/missing files/corrupt data), movie-mode behavior, HST instrument-specific branches, --versions multi-run semantics, frame-max capping, and warning-free defaults.
Component unit tests tests/test_enhance*.py, tests/test_geometry*.py, tests/test_io*.py, tests/test_pil_utils*.py, tests/test_tiff16*.py, tests/test_color.py, tests/test_instruments_branches.py, tests/test_zebra.py, tests/test_paths.py, tests/test_mutable_defaults.py	Systematic unit coverage for enhancement (limits/colormaps/gamma/zebra), geometry (slicing/cropping/wrapping/padding/resizing/rotation), I/O (format cascade/FITS/PDS3), PIL utils (array↔PIL round-trips), TIFF16 (grayscale/RGB/palette/transpose), color lookup, instrument detection/tinting, and API invariants (mutable default prevention).

---

Estimated Code Review Effort

🎯 5 (Critical) | ⏱️ ~120 minutes

---

Possibly Related PRs

• SETI/rms-picmaker#7: Directly related decomposition of the same monolithic modules (cli.py, pipeline.py, io.py, enhance.py, geometry.py, instruments/*, tests) into the modular structure introduced here.
• SETI/rms-picmaker#8: Related documentation and CI/packaging alignment with the same Python 3.11 baseline, OIDC workflow updates, and docs/conf.py changes.
• SETI/rms-picmaker#4: Related packaging and CI modernization (pyproject.toml, workflows, scripts/run-all-checks.sh) establishing the same baseline and tooling configuration.