Repository overview
===================

``rms-picmaker`` is a SETI / PDS Ring-Moon Systems Node tool that
converts binary astronomy images (PDS3-labeled, VICAR, FITS, plus a
handful of common raster formats) into JPEG, PNG, BMP, GIF, or TIFF
files. It ships as both a command-line tool (the ``picmaker`` console
script) and an importable Python library (``import picmaker``).

The project is a single Python package under ``src/picmaker/`` with a
small flat module layout (no deep sub-packages except for the
:mod:`~picmaker.instruments` subpackage). The CLI is a thin layer
around the library: every ``--flag`` binds to a keyword argument of
:func:`picmaker.pipeline.images_to_pics`, and the validation rules
that gate both surfaces live in one place
(:class:`~picmaker.options.PicmakerOptions`).

Setting up a development environment
------------------------------------

Clone the repository and create a virtual environment in the project
root. The scripts under :file:`scripts/` and the lint / type / test
configuration all expect the venv to live at ``./venv``::

   git clone https://github.com/SETI/rms-picmaker.git
   cd rms-picmaker
   python -m venv venv
   source venv/bin/activate          # On Windows: venv\Scripts\activate
   pip install -e ".[dev]"

The ``[dev]`` extra pulls in the test runner, linters, type checker,
documentation builder, and packaging audit tools used by
:file:`scripts/run-all-checks.sh` and CI. Once installed, a fast
end-to-end check is::

   bash scripts/run-all-checks.sh

Layout
------

.. code-block:: text

   rms-picmaker/
   ├── src/picmaker/             # Importable Python package.
   │   ├── __init__.py           # Public API re-exports + __version__.
   │   ├── picmaker.py           # Alternate import path; re-exports the same names as __init__.py.
   │   ├── cli.py                # argparse CLI; builds option_dict; dispatches.
   │   ├── pipeline.py           # process_images + images_to_pics (the pipeline).
   │   ├── options.py            # PicmakerOptions dataclass + validate().
   │   ├── io.py                 # Reader cascade + output-path helpers.
   │   ├── enhance.py            # Intensity stretch / gamma / colormap.
   │   ├── geometry.py           # Slice / crop / rotate / size / wrap / pad.
   │   ├── color.py              # Per-filter tint dispatch (mission-agnostic).
   │   ├── pil_utils.py          # numpy ↔ PIL bridges + write_pil.
   │   ├── _filters.py           # PIL ImageFilter dispatch table.
   │   ├── _rgb.py               # Wavelength → RGB lookup tables (private).
   │   ├── tiff16.py             # 16-bit TIFF reader / writer (legacy).
   │   ├── colornames.py         # X11 color-name lookup (legacy).
   │   ├── instruments/          # Per-mission detectors + tint chains.
   │   │   ├── __init__.py
   │   │   ├── cassini.py        # Cassini ISS.
   │   │   ├── voyager.py        # Voyager ISS.
   │   │   ├── galileo.py        # Galileo SSI.
   │   │   ├── hst.py            # HST (WFC3 / ACS / WFPC2 / NICMOS).
   │   │   └── nh.py             # New Horizons MVIC.
   │   ├── py.typed              # PEP 561 typed-package marker.
   │   └── _version.py           # Auto-generated by setuptools_scm.
   ├── tests/                    # pytest suite (471 tests).
   │   ├── conftest.py
   │   ├── fixtures/             # Binary fixtures + .baseline-*.txt + expected/.
   │   ├── fixture_recipes/      # Scripts that regenerate every fixture.
   │   └── test_*.py
   ├── docs/                     # Sphinx documentation tree.
   │   ├── conf.py
   │   ├── index.rst
   │   ├── user_guide.rst
   │   ├── developer_guide.rst   # Index page for this guide.
   │   ├── dev/                  # Sub-pages of the developer guide.
   │   └── module.rst
   ├── scripts/
   │   └── run-all-checks.sh     # Local lint + type + test orchestrator.
   ├── pyproject.toml            # Single source of truth for build + tools.
   ├── README.md
   ├── CONTRIBUTING.md
   └── CODE_OF_CONDUCT.md