spindoctor.navigate_image_files

Top-level driver that navigates a single image and writes results.

Given an observation class and an ImageFiles batch of size one, this module reads the image, builds a NavOrchestrator configured with the caller’s model and technique filters, runs orchestrator.navigate(obs), and writes the curated metadata (and a summary PNG when requested) to nav_results_root.

This is the function sd_offset and sd_offset_cloud_tasks invoke once per image. Errors from image loading, missing SPICE coverage, or unexpected exceptions during navigation are captured into the output metadata so the driver always returns a structured result (never a raised exception that crashes the worker process).

build_metadata_from_result(result: NavResult, image_path: Path, image_name: str, *, instrument: str, camera: str | None = None, image_shape: tuple[int, int] | None = None, timing: dict[str, Any] | None = None) → dict[str, Any][source]

Build the JSON metadata dict from a NavResult.

Used by both the autonomous pipeline and the manual-nav driver so a manually-picked offset writes the same _metadata.json schema.

Parameters:

  • result – NavResult to curate.

  • image_path – Absolute path to the source image; written to the observation.image_path field.

  • image_name – Basename of the source image; written to the observation.image_name field.

  • instrument – Registered instrument name for the observation class (see spindoctor.obs.obs_class_to_inst_name()); written to the observation.instrument field.

  • camera – The camera that took the image (ObsInst.camera, e.g. 'NAC'); written to the observation.camera field. None omits the field.

  • image_shape – (v, u) pixel dimensions of the loaded image data; written to the observation.image_shape field. None omits the field.

  • timing – Run-timing section from build_timing_section(); written to the top-level timing field. None omits the field.

build_timing_section(start: datetime, end: datetime) → dict[str, Any][source]

Build the timing metadata section from run start and end moments.

Every metadata document carries this section so downstream statistics (sd_stats_ingest / sd_stats_report) can aggregate per-image run times.

Parameters:

  • start – Timezone-aware run start (captured before the image load).

  • end – Timezone-aware run end (captured after navigation, or at error time).

Returns:

Dict with start_iso8601 and end_iso8601 (UTC ISO8601 strings) and elapsed_s (float seconds).

navigate_image_files(obs_class: type[ObsSnapshotInst], image_files: ImageFiles, nav_results_root: FCPath, *, nav_models: list[str] | None = None, nav_techniques: list[str] | None = None, write_output_files: bool = True, log_arguments: Namespace | None = None) → tuple[bool, dict[str, Any]][source]

Navigate one image batch and optionally write the result files.

Top-level driver. Reads the image, asks every registered NavModel subclass to construct whatever instances apply to the observation, runs the orchestrator with the caller’s model and technique filters, and writes _metadata.json plus _summary.png if requested.

Parameters:

  • obs_class – Concrete ObsSnapshotInst subclass for the mission.

  • image_files – ImageFiles batch. Exactly one image per batch is supported; calling code should split larger batches.

  • nav_results_root – Directory to write _metadata.json and _summary.png results to. May be a FileCache URL.

  • nav_models – Glob-pattern list selecting which NavModel instances run; None means all. Patterns may use a leading ! for exclusion.

  • nav_techniques – Glob-pattern list selecting which NavTechnique instances run. None means all.

  • write_output_files – When True, write the metadata JSON and summary PNG; when False, perform a dry run and return the metadata dict only.

  • log_arguments – Parsed CLI arguments used to resolve the per-image log-file level. None defaults to the configured INFO level.

Returns:

Tuple (success, metadata) where success is True for an ok NavResult.status and False otherwise. metadata is the curated JSON-friendly dict.

write_summary_png(obs: ObsSnapshotInst, result: NavResult, png_path: FCPath, logger: Any) → None[source]

Composite the source image with the orchestrator’s annotation overlay.

Thin driver around spindoctor.support.summary_png.render_annotated_summary_rgb(); writes the resulting RGB to png_path as a PNG.

Parameters:

  • obs – Observation snapshot used as the background.

  • result – Navigation result; offset_px shifts the overlay to the best-fit pose, annotations carries every NavModel’s overlay.

  • png_path – Destination path; supports FCPath URLs.

  • logger – pdslogger to emit one INFO line on success.