===================
Telescope Profiles
===================

Telescope profiles define how FITS keywords are mapped to canonical
field names, what unit conversions to apply, and observatory metadata.

Profile Format
--------------

Profiles are YAML files in the ``profiles/`` directory:

.. code-block:: yaml

   name: ccat
   version: 2

   match_rules:
     - TELESCOP: "CCAT"
     - TELESCOP: "FYST"

   keyword_map:
     mjd: MJD-OBS
     elevation: ELEVATIO
     azimuth: AZIMUTH
     signal_freq: OBSFREQ
     sobsmode: SOBSMODE
     otf_lon_base: LAMOFF
     otf_lon_pixel: PIXOFFX
     otf_lat_base: BETOFF
     otf_lat_pixel: PIXOFFY

   unit_conversions:
     signal_freq: MHz_to_Hz
     elevation: deg_to_rad
     otf_lon: arcsec_to_deg

   inject:
     observatory: CCAT
     site_latitude_deg: -22.9586
     site_longitude_deg: -67.7875
     site_altitude_m: 5612.0

   defaults:
     freq_off: 0.0
     tcold: 77.0

   atm_table:
     freq_min_ghz: 200.0
     freq_max_ghz: 1200.0
     freq_step_mhz: 1.0
     pwv_low_mm: 0.05
     pwv_high_mm: 0.50

Profile Auto-Detection
-----------------------

When no ``--profile`` override is given, profiles are tested against
the first FITS file's header in alphabetical order. The first profile
whose ``match_rules`` all match is selected. If none match,
``generic.yaml`` is used as fallback.

Embedded Profiles
-----------------

Profiles are embedded at compile time via ``include_str!`` in
``zarr-fits-core/src/embedded_profiles.rs``. This means the binary
works without an external ``profiles/`` directory.

Current profiles:

- ``ccat.yaml`` — CCAT/FYST telescope
- ``sofia_upgreat.yaml`` — SOFIA/upGREAT airborne observatory
- ``generic.yaml`` — fallback for unknown telescopes

Adding a New Telescope
-----------------------

1. Create ``profiles/<telescope_name>.yaml``
2. Define ``match_rules`` for auto-detection from FITS headers
3. Map all required keywords in ``keyword_map``
4. Set ``inject`` fields for observatory metadata
5. Add the file to ``embedded_profiles.rs``:

   .. code-block:: rust

      pub const NEW_TELESCOPE_YAML: &str =
          include_str!("../../../profiles/new_telescope.yaml");

      pub const ALL: &[(&str, &str)] = &[
          ("sofia_upgreat.yaml", SOFIA_UPGREAT_YAML),
          ("ccat.yaml", CCAT_YAML),
          ("new_telescope.yaml", NEW_TELESCOPE_YAML),  // ← add
          ("generic.yaml", GENERIC_YAML),
      ];

6. Rebuild and test with sample FITS data

**Implementation:** ``zarr-fits-core/src/profile.rs``