healpix_analyse.healpix_interp
==============================

.. py:module:: healpix_analyse.healpix_interp

.. autoapi-nested-parse::

   get_interp_val — interpolation bilinéaire sur une grille HEALPix (NESTED)
   via healpix-geo pour les conversions de coordonnées.

   Équivalent à healpy.get_interp_val / get_interp_weights.

   Deux régimes, selon `ellipsoid` :

   - ellipsoid="sphere" (défaut) : reproduit EXACTEMENT l'algorithme RING de
     référence de healpy (`T_Healpix_Base::get_interpol`, healpix_base.cc),
     transcrit ici en pur NumPy (aucune dépendance à `healpy` au runtime).
     Les 4 pixels renvoyés sont rigoureusement identiques à
     `healpy.get_interp_weights(nside, lon, lat, lonlat=True, nest=True)`
     (schéma NESTED, obtenu par conversion RING->NESTED via
     `healpix_geo.ring.to_nested`) ; les poids concordent à ~1e-12 près
     (bruit de calcul flottant inévitable tant qu'on ne relie pas le même
     binaire C++ — largement sous la précision utile de n'importe quelle
     application scientifique).

   - ellipsoid != "sphere" (ex. "WGS84") : healpy n'a aucune notion
     d'ellipsoïde, donc "identique à healpy" n'a pas de sens dans ce cas.
     On délègue alors directement à `healpix_geo.nested.bilinear_interpolation`,
     qui implémente une interpolation bilinéaire géométriquement correcte
     (vérifiée indépendamment, voir la discussion qui a mené à ce fichier) et
     supporte nativement les ellipsoïdes de référence.

   Dépendances :
       pip install healpix-geo  # inclut cdshealpix comme dépendance
       pip install numpy

   Auteurs : Claude (Anthropic)



Attributes
----------

.. autoapisummary::

   healpix_analyse.healpix_interp.depth


Functions
---------

.. autoapisummary::

   healpix_analyse.healpix_interp.get_interp_weights
   healpix_analyse.healpix_interp.get_interp_val


Module Contents
---------------

.. py:function:: get_interp_weights(lon: numpy.ndarray, lat: numpy.ndarray, depth: int, ellipsoid: str = 'sphere') -> tuple[numpy.ndarray, numpy.ndarray]

   Renvoie les 4 cellules HEALPix et leurs poids d'interpolation bilinéaire
   pour chaque position (lon, lat).

   Pour ellipsoid="sphere" (défaut), les résultats (pixels ET poids) sont
   rigoureusement identiques à
   ``healpy.get_interp_weights(nside, lon, lat, lonlat=True, nest=True)``
   (aux erreurs d'arrondi flottant près, ~1e-12) : c'est un portage direct
   de l'algorithme RING de référence de healpy, pas une réinvention
   géométrique approximative.

   Pour un ellipsoïde non-sphérique, il n'existe pas de "référence healpy"
   (healpy ne connaît que la sphère) : on utilise alors
   ``healpix_geo.nested.bilinear_interpolation``, qui implémente une
   interpolation bilinéaire correcte sur la grille NESTED en tenant compte
   de l'ellipsoïde choisi.

   :Parameters: * **lon** (:py:class:`np.ndarray`, :py:class:`shape (N,)`) -- Longitudes en degrés.
                * **lat** (:py:class:`np.ndarray`, :py:class:`shape (N,)`) -- Latitudes en degrés.
                * **depth** (:py:class:`int`) -- Profondeur HEALPix (nside = 2**depth).
                * **ellipsoid** (:py:class:`str`, *optional*) -- Ellipsoïde de référence : "sphere" (défaut, identique à healpy) ou
                  "WGS84", "GRS80", etc. Voir la doc de healpix-geo pour la liste.

   :returns: * **pixels** (:py:class:`np.ndarray` of :py:class:`uint64`, :py:class:`shape (N`, :py:class:`4)`) -- Indices des 4 cellules HEALPix (schéma NESTED).
             * **weights** (:py:class:`np.ndarray` of :py:class:`float64`, :py:class:`shape (N`, :py:class:`4)`) -- Poids bilinéaires correspondants. Chaque ligne somme à 1.

   :raises ValueError: Si lon et lat n'ont pas la même forme.


.. py:function:: get_interp_val(hpx_map: numpy.ndarray, lon, lat, depth: int, ellipsoid: str = 'sphere') -> numpy.ndarray

   Interpolation bilinéaire d'une carte HEALPix aux coordonnées géographiques.

   Équivalent à healpy.get_interp_val(m, theta, phi, nest=True, lonlat=True)
   mais utilise healpix-geo pour les projections, ce qui permet de travailler
   sur des ellipsoïdes de référence (ex. WGS84).

   :Parameters: * **hpx_map** (:py:class:`np.ndarray`, :py:class:`shape (12 * 4**depth,)`) -- Carte HEALPix en ordre NESTED.
                * **lon** (:py:class:`float ou np.ndarray`) -- Longitude(s) en degrés.
                * **lat** (:py:class:`float ou np.ndarray`) -- Latitude(s) en degrés.
                * **depth** (:py:class:`int`) -- Profondeur HEALPix (nside = 2**depth).
                * **ellipsoid** (:py:class:`str`, *optional*) -- Ellipsoïde de référence : "sphere" (défaut) ou "WGS84", etc.

   :returns: :py:class:`np.ndarray ou float` -- Valeurs interpolées. Scalaire si lon/lat sont scalaires, sinon array de
             même forme que lon/lat.

   .. admonition:: Examples

      >>> import numpy as np
      >>> from healpix_interp import get_interp_val
      >>>
      >>> depth = 3
      >>> nside  = 2**depth
      >>> npix   = 12 * nside**2
      >>> hpx_map = np.arange(npix, dtype=float)
      >>>
      >>> # Point unique
      >>> val = get_interp_val(hpx_map, lon=45.0, lat=30.0, depth=depth)
      >>> print(val)
      >>>
      >>> # Grille de points
      >>> lons = np.linspace(0, 360, 50)
      >>> lats = np.linspace(-80, 80, 40)
      >>> lon_grid, lat_grid = np.meshgrid(lons, lats)
      >>> vals = get_interp_val(hpx_map, lon_grid, lat_grid, depth=depth)
      >>> print(vals.shape)  # (40, 50)
      >>>
      >>> # Avec ellipsoïde WGS84
      >>> vals_wgs84 = get_interp_val(
      ...     hpx_map, lon=2.3522, lat=48.8566, depth=depth, ellipsoid="WGS84"
      ... )

   .. admonition:: Notes

      La carte hpx_map doit contenir exactement 12 * 4**depth éléments et être
      en ordre NESTED (le schéma utilisé par healpix-geo).
      
      Si votre carte est en ordre RING (healpy), convertissez-la d'abord :
          import healpy as hp
          hpx_map_nested = hp.reorder(hpx_map_ring, r2n=True)


.. py:data:: depth
   :value: 5