Code Familiarization Plan

This is a study plan for a developer who has just cloned the repository and wants to come up to speed on RMS-NAV in the most efficient order. Each stage lists documentation pages to read and source modules to inspect alongside them. The earlier stages are prerequisites for the later ones; the later stages can be read more selectively once the core pipeline makes sense.

The plan does not explain the code — it sequences it. Read each documentation page first, then look at the corresponding source. Every class, function, and module name below is a hyperlink into the API reference; click through to jump straight to the autodoc page (and from there to the [source] link to the file itself).

Stage 1 — Orientation

Goal: understand what the package does, the repository layout, and the top-level architecture. Skim only — do not try to absorb every detail.

README.md — PyPI-facing summary of what rms-nav is and the installation / quick-start commands.
Introduction — environment variables, CLI entry points, test / lint / docs commands, CI / release process.
Navigation Overview — the six-subsystem architectural sketch and the per-image data flow.
Class Hierarchy — the inheritance graph and the shared base classes the rest of the manual assumes.

Stage 2 — Cross-cutting foundations

Goal: understand the shared infrastructure every subsystem depends on (configuration, logging, the universal base class, common helpers).

Config and Static Data — how YAML defaults are layered, the Config singleton, and the static-data citation policy.
Developer Guide: Logging — pdslogger usage, section conventions, and the rule against bare print.
nav.config — config loader and module-level logger:
- nav.config.config
- nav.config.logger
src/nav/config_files/ — the bundled YAML defaults (numeric-prefix load order); not autodoc’d since it is data, not code.
nav.support — cross-cutting helpers. Start with these two; the rest can be browsed on demand:
- nav.support.nav_base — NavBase, the shared base providing config and logger.
- nav.support.types

Stage 3 — Inputs: datasets, observations, features

Goal: understand how an image goes from a file path on disk to an in-memory Observation (from oops) carrying the per-pixel features that the rest of the pipeline consumes.

Observations — DataSet enumeration, the ObsSnapshotInst per-instrument hierarchy, and the NavFeature dataclass / feature-type taxonomy.
nav.dataset — file enumeration. The per-mission subclasses share the DataSet / DataSetPDS3 bases:
nav.obs — observation wrappers. The per-instrument ObsInst subclasses share the ObsSnapshotInst base:
nav.feature:
- nav.feature.feature — the NavFeature dataclass itself.
- nav.feature.feature_type — the feature-type taxonomy.
- nav.feature.geometry
- nav.feature.flags
- nav.feature.composition
- nav.feature.reliability

Stage 4 — First end-to-end pipeline: `NavModelBody` + `BodyLimbNav`

Goal: walk one image end-to-end through the simplest possible model / technique pair, plus the minimum slice of orchestrator, annotations, and driver code needed to produce the JSON metadata and summary PNG. Body-limb navigation is the canonical reference distance-transform pipeline and the smallest of the autonomous techniques.

Read in this order:

Model

Navigation Models — what a NavModel is and the three methods every subclass implements:
Bodies — the body-model family.
Body Navigation Model — NavModelBody in detail.
nav.nav_model.nav_model — abstract base, registry, and build_models_for_obs().
nav.nav_model.body_shape — body shape support.
nav.nav_model.nav_model_body_base — shared body-annotation helpers (NavModelBodyBase).
nav.nav_model.nav_model_body — the catalog-driven body model (NavModelBody).

Technique

Navigation Techniques — what a NavTechnique is, the registry, and the prior-free / prior-required two-pass split.
Image Derivatives (Shared Gradient and Edge DT) — gradient and edge-distance-transform images shared by every DT technique.
DT Fitting (Shared Polyline-vs-Image Fitter) — the coarse-NCC + Levenberg- Marquardt + Tukey biweight machinery the limb / terminator / ring-edge techniques all share.
Body Limb Fit (BodyLimbNav) — the body-limb technique itself.
nav.nav_orchestrator.image_derivatives — the per-image derivative builder.
nav.nav_technique.nav_technique — abstract base + registry (NavTechnique).
nav.nav_technique.dt_fitting — shared DT-fitting helpers.
nav.nav_technique.nav_technique_body_limb — the technique implementation (BodyLimbNav).

Orchestrator (minimum slice)

Orchestrator Subsystem — the orchestrator package map.
Per-Image State (NavContext) — the per-image dataclass every model and technique reads / writes (NavContext).
Orchestrator (NavOrchestrator) — NavOrchestrator: the two-pass driver loop. (Skim — feasibility / confidence / ensemble are covered in Stage 5.)
Final Output (NavResult) — the final per-image result envelope (NavResult).
nav.nav_orchestrator — read these three first; the rest are picked up in Stage 5:

Output: annotations, metadata, summary PNG, top-level driver

Annotations — the summary-PNG overlay system.
JSON Curation (build_metadata_dict) — projecting NavResult into the JSON metadata block.
nav.annotation — annotation primitives, plus combine logic (combine()):
nav.nav_orchestrator.curator — the metadata-dict builder (build_metadata_dict()).
nav.navigate_image_files — the top-level per-image driver called by nav_offset (navigate_image_files()).
src/main/nav_offset.py — the CLI dispatch module that wires it up (the src/main/ tree is not part of the autodoc API surface).

Stage 5 — Orchestrator round-trip: feasibility, confidence, diagnostics, ensemble

Goal: understand how individual technique results are gated, calibrated, classified, and combined into the single per-image answer the orchestrator returns.

Feasibility Reporting (Shared NavFeasibilityReport) — when a technique declines to run and how the reason is reported.
Confidence Calibration (Shared Sigmoid-of-Linear Combination) — calibrated [0, 1] confidence per technique.
Per-Technique Diagnostics (Shared Dataclass Family) — the typed diagnostics dataclass attached to each technique result.
Ensemble Combine (ensemble + EnsembleConfig) — the ensemble() combine that reconciles per-technique results into the final offset.
Image Classifier (NavImageClassifier) — per-image classification feeding feasibility / weighting.
Per-Instrument Settings (InstrumentSettings) — per-instrument tunables the orchestrator threads through.
Reproducibility Envelope (Provenance) — the provenance record carried through the pipeline.
Per-Feature Post-Mortem (NavFeatureSummary) — the per-image feature-summary dataclass.
Technique-side helpers:
Orchestrator-side helpers:
nav.support.status_reason — the shared status-reason enum.

Stage 6 — Remaining models and their techniques

Goal: extend the picture from Stage 4 to every other registered model and every other technique. Each subsection pairs a model with the techniques that consume its features, in roughly increasing order of complexity.

Titan (model only)

Titan — the Titan family.
Titan Navigation Model — NavModelTitan (registered placeholder; emits no features pending a haze-aware extractor).
nav.nav_model.nav_model_titan

Manual

Manual Navigation (NavTechniqueManual) — the interactive PyQt6 driver.
nav.nav_technique.nav_technique_manual
nav.ui.manual_nav_dialog
nav.ui.library_entry
The nav.ui.common module is internal and not autodoc’d.

Stage 7 — Simulated images

Goal: understand the synthetic-image renderer and the simulated-image sibling of each model family. These are used both by nav_create_simulated_image and by tests.

Simulated Star Navigation Model
Simulated Body Navigation Model
Simulated Ring Navigation Model
Simulated Titan Navigation Model
nav.nav_model.nav_model_body_simulated
nav.nav_model.nav_model_rings_simulated
nav.sim — the synthetic-image renderer:
src/nav/dataset/dataset_sim.py and src/nav/obs/obs_inst_sim.py — the simulated-image dataset and observation wrappers (not autodoc’d).

Stage 8 — Calibration and regression

Goal: understand how confidence calibration is anchored to a curated cohort of real images, and how per-instrument camera-rotation correction is calibrated.

Image Library — the operator-curated regression cohort (tests/integration/image_library/), sidecar schema, and baseline workflow.
Camera-rotation correction — per-instrument camera-rotation correction.
tests/integration/ — the integration suite that consumes the image library.

Stage 9 — Downstream products

Goal: understand the products built on top of a navigated image — mosaics / reprojections, per-pixel backplanes, and PDS4 bundles.

Reprojection Internals — body and ring mosaicing plus the thread-safety constraints.
nav.reproj — reprojection core:
src/reproj_cli/ — CLI-only helpers shared by the mosaic drivers (not part of the importable nav API and not autodoc’d).
Backplanes — per-pixel geometry product generation.
src/backplanes/ — driven by nav_backplanes (not autodoc’d in the nav API surface).
PDS4 Bundle Generation — PDS4 bundle assembly.
src/pds4/ — driven by nav_create_bundle; per-dataset hooks live on the DataSet subclasses introduced in Stage 3 (this tree is not autodoc’d either).

Stage 10 — Extending and conventions

Goal: be ready to make changes. Read these once at the end so the conventions land on top of a working mental model of the code.

Extending the System — how to add a new instrument, dataset, model, or technique (the registry hooks each subsystem exposes).
Best Practices — line length, docstring style, ruff / mypy expectations, commit conventions.
src/main/ — CLI dispatch modules for every entry point listed in [project.scripts] (not autodoc’d).
The PyQt6 mosaic viewer; read after nav.ui.manual_nav_dialog from Stage 6:
Contributing — the contributor checklist that gates every PR.