coordinate-frame-tour

Coordinate-frame tour: pick the right frame, then transform into it

A guided front door to the SPICE coordinate-frame catalog. Heliophysics analysis lives or dies on using the right frame (RTN for solar-wind turbulence, GSE/GSM for magnetospheric work, HEEQ for mapping to the solar surface, HEE for CME propagation), and the catalog ships a per-frame use_when hint for exactly this choice. This skill turns "which frame?" into a discover → choose → transform → verify workflow over existing tools — no new tool is added (the catalog is exposed through the unified data layer, per #121/#122).

When to use

• "What coordinate frame should I use for <CME propagation / magnetospheric / solar-wind / orbit> analysis?"
• "What frames can I transform between, and what does each mean?"
• "Convert this vector / this B time series from frame A to frame B."

Tool chain (all already exist)

load_data_source(source_type="spice", source_id="frames") (discover the catalog) → choose a frame from each entry's use_when → transform_coordinates (one vector at a time) or transform_timeseries_coordinates (a fetched CSV of vectors) → verify, inside a create_spedas_analysis_bundle.

Backend (VERIFIED contract)

Frame discovery is exposed through the existing unified data layer — there is no list_coordinate_frames tool on the default surface (it was consolidated out; the catalog returns through load_data_source instead).

• load_data_source(source_type="spice", source_id="frames") returns a dict with top-level keys: frame_catalog, frame_names, supported_frame_names, note.
  • frame_catalog.frame_count (int) and frame_catalog.frames — a list of dicts, each {frame, full_name, description, use_when}. The use_when field is the frame-selection hint.
  • frame_names — canonical frame ids (e.g. J2000, ECLIPJ2000, ECLIPB1950, HCI, HEE, HAE, HEEQ, GSE, GEI, RTN).
  • supported_frame_names — frame_names plus aliases you may pass to a transform. This is a returned dict (not a stored tplot var, not a file); read the fields directly.
• transform_coordinates(vector=[x,y,z], time, from_frame, to_frame, allow_kernel_download=...) → returns a dict with output_vector as a JSON list (status: success). Single sample.
• transform_timeseries_coordinates(...) → transforms a fetched CSV/.npz of vectors between frames over a time axis (artifact in / artifact out); use it for a B or position series.
• Unknown frame → structured invalid_argument error carrying the supported frame list (don't guess a frame string — discover it first). Frame-dependent transforms may require SPICE kernels: a cold cache returns needs_confirmation/kernel_download_required; pass allow_kernel_download=True after checking/confirming via manage_data_cache(source_type="spice", action="status"). Do not route this skill through hidden source-specific kernel tools.