grdwindinversion 0.3.8__tar.gz → 1.0.0__tar.gz

grdwindinversion-1.0.0/.gitattributes

@@ -0,0 +1,4 @@
+* text=auto
+*.py text eol=lf
+*.js text eol=lf
+*.md text eol=lf

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/.github/workflows/ci.yml

@@ -53,8 +53,8 @@ jobs:
               id: cache
               with:
                   path: ./test_data
-                  key: test-data-v4
-                  restore-keys: test-data-v4
+                  key: test-data-v6
+                  restore-keys: test-data-v6
 
               # Download test data if not already cached
             - name: Download test data
@@ -67,6 +67,8 @@ jobs:
                   unzip /tmp/l1.zip -d ./test_data/
                   wget https://cloud.ifremer.fr/index.php/s/RgloaQ8gi8svYOe/download -O /tmp/auxiliary.zip
                   unzip /tmp/auxiliary.zip -d ./test_data/
+                  wget https://cloud.ifremer.fr/index.php/s/oEUYYFqpYXELr7U/download -O /tmp/masks.zip
+                  unzip /tmp/masks.zip -d ./test_data/
               timeout-minutes: 200 # Adjust depending on the size of your data
 
               # Set up xsar configuration
@@ -81,15 +83,7 @@ jobs:
             - name: Setup grdwindinversion configuration
               run: |
                   mkdir -p ~/.grdwindinversion
-                  echo "'ecmwf_0100_1h': ./test_data/ECMWF/forecast/hourly/0100deg/netcdf_light/%Y/%j/ECMWF_FORECAST_0100_%Y%m%d%H%M_10U_10V.nc" > ~/.grdwindinversion/data_config.yaml
-                  echo "'ecmwf_0125_1h': ./test_data/ECMWF/0.125deg/1h/forecasts/%Y/%j/ecmwf_%Y%m%d%H%M.nc" >> ~/.grdwindinversion/data_config.yaml
-                  echo "unit_test_s1_product: './test_data/L1/S1A_IW_GRDH_1SDV_20210909T130650_20210909T130715_039605_04AE83_C34F.SAFE'" >> ~/.grdwindinversion/data_config.yaml
-                  echo "unit_test_rcm_product: './test_data/L1/RCM1_OK2767220_PK2769320_1_SCLND_20230930_214014_VV_VH_GRD'" >> ~/.grdwindinversion/data_config.yaml
-                  echo "unit_test_rs2_product: './test_data/L1/RS2_OK141302_PK1242223_DK1208537_SCWA_20220904_093402_VV_VH_SGF'" >> ~/.grdwindinversion/data_config.yaml
-
-                  #echo "'nc_luts_path': ./test_data/GMFS/nc_luts" >> ~/.grdwindinversion/data_config.yaml
-                  #echo "'lut_cmod7_path': './test_data/GMFS/v1.6/GMF_cmod7_official/cmod7_and_python_script'" >> ~/.grdwindinversion/data_config.yaml
-                  #echo "'lut_ms1ahw_path': './test_data/GMFS/v1.6/GMF_cmodms1ahw'" >> ~/.grdwindinversion/data_config.yaml
+                  cp tests/data_config_ci.yaml ~/.grdwindinversion/data_config.yaml
 
               # Run the tests
             - name: Run tests

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/AUTHORS.rst

@@ -5,10 +5,6 @@ Authors
 Development Lead
 ----------------
 
-* Vincent Lheureux <vincent.lheureux@ifremer.fr>
+* Vincent Lheureux <vinc.lheureux@gmail.com>
 * Antoine Grouazel <antoine.grouazel@ifremer.fr>
 
-Contributors
-------------
-
-None yet. Why not be the first?

{grdwindinversion-0.3.8/grdwindinversion.egg-info → grdwindinversion-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grdwindinversion
-Version: 0.3.8
+Version: 1.0.0
 Summary: Package to perform Wind inversion from GRD Level-1 SAR images
 Author-email: Antoine Grouazel <antoine.grouazel@ifremer.fr>
 License: MIT

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/ci/requirements/environment.yaml

@@ -1,8 +1,10 @@
 name: grdwindinversion-tests
 channels:
     - conda-forge
+
 dependencies:
     - python=3.10
+
     # development
     - ipython
     - pre-commit
@@ -11,23 +13,23 @@ dependencies:
     - isort
     - black
     - dask-labextension
+
     # testing
     - pytest
     - pytest-reportlog
     - hypothesis
     - coverage
+
     # I/O
     - rioxarray
     - h5netcdf
     - zarr
-    - scipy
+
     # data
-    - xarray
+    - dask <2025
+
     - xarray-datatree
-    - dask
-    - numpy
-    - pandas
-    - shapely
+
     # processing
     - more-itertools
     - tqdm

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/docs/algorithm.rst

@@ -1,4 +1,4 @@
 Algorithm description
 =====================
 
-TODO
+TODO

grdwindinversion-1.0.0/docs/configuration.rst

@@ -0,0 +1,215 @@
+=============
+Configuration
+=============
+
+Configuration Files Implementation Guide
+=========================================
+
+Overview
+--------
+
+The ``grdwindinversion`` configuration system uses two types of YAML files:
+
+1. **data_config.yaml**: Paths to data sources (ancillary, , LUTs, masks)
+2. **config_*.yaml**: Processing parameters specific to each satellite
+
+Configuration System Architecture
+----------------------------------
+
+Loading Hierarchy
+~~~~~~~~~~~~~~~~~
+
+The ``data_config.yaml`` file is loaded with the following priority:
+
+.. code-block:: text
+
+    1. ~/.grdwindinversion/data_config.yaml  (user local configuration)
+    2. ./local_data_config.yaml              (project local configuration)
+    3. <package>/data_config.yaml            (package default configuration)
+
+Accessing Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from grdwindinversion.load_config import getConf
+
+    # Get the global configuration dictionary
+    config = getConf()
+
+    # Access data paths
+    ecmwf_path = config["ecmwf_0100_1h"]
+    nc_luts_path = config["nc_luts_path"]
+
+data_config.yaml Structure
+---------------------------
+
+1. Meteorological Data Paths (ancillary)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    ancillary_sources:
+      ecmwf:
+        - name: 'ecmwf_0100_1h'
+          path: '/path/to/ecmwf/0.100deg/%Y/%j/ECMWF_FORECAST_0100_%Y%m%d%H%M_10U_10V.nc'
+        - name: 'ecmwf_0125_1h'
+          path: '/path/to/ecmwf/0.125deg/%Y/%j/ecmwf_%Y%m%d%H%M.nc'
+      era5:
+        - name: 'era5_0250_1h'
+          path: '/path/to/era5/%Y/%m/era_5-copernicus__%Y%m%d.nc'
+
+**Priority System**:
+
+When multiple models are configured for the same source (e.g., both ``ecmwf_0100_1h`` and ``ecmwf_0125_1h``),
+the function tries each model in the order listed and uses the first one for which a file exists.
+For example, with the configuration above, ``ecmwf_0100_1h`` will be tried first, and ``ecmwf_0125_1h``
+will be used as a fallback if the first file is not available.
+
+**Metadata Preservation**:
+
+The selected ancillary source name and full path are automatically stored in the output dataset attributes:
+- ``ancillary_source``: Name of the selected model (e.g., ``ecmwf_0100_1h``)
+- ``ancillary_source_path``: Full path to the selected file
+
+**Template Format**: Uses Python datetime format codes
+
+- ``%Y``: Year (4 digits)
+- ``%j``: Day of year (001-366)
+- ``%m``: Month (01-12)
+- ``%d``: Day of month (01-31)
+- ``%H``: Hour (00-23)
+- ``%M``: Minute (00-59)
+
+2. LUT Paths (Look-Up Tables)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    nc_luts_path: '/path/to/luts/'
+    lut_cmod7_path: '/path/to/cmod7_lut.nc'
+
+3. Masks Configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    masks:
+      land:
+        - name: 'gshhsH'
+          path: '/path/to/gshhs/GSHHS_h_L1.shp'
+        - name: 'custom_land'
+          path: '/path/to/custom_land.shp'
+      ice:
+        - name: 'iceSource'
+          path: '/path/to/ice_mask.shp'
+
+**Mask Notes**:
+
+- The ``_mask`` suffix is automatically appended to variable names
+- Multiple masks per category are supported
+
+config_*.yaml Structure
+-----------------------
+
+Global Parameters (root level)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    no_subdir: True                          # Don't create subdirectories in output
+    winddir_convention: "meteorological"     # Wind direction convention
+    add_gradientsfeatures: False             # Add gradient/streak features
+    add_nrcs_model: False                    # Add NRCS from model (forced to False)
+    overwrite: False                         # Overwrite existing files
+
+Recommended Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Use ``config_prod_v3.yaml`` as the default configuration file.**
+
+This configuration includes:
+
+- Support for all Sentinel-1 satellites (S1A, S1B, S1C, S1D)
+- Support for RS2 and RCM satellites
+- Automatic handling of S1 EW calibration changes (July 2019) with latest GMFs
+
+Satellite-Specific Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each satellite section includes:
+
+.. code-block:: yaml
+
+    S1A:
+      # Geophysical Model Functions
+      GMF_HH_NAME: "nc_lut_gmf_cmod5n_Rhigh_hh_mouche1"
+      GMF_VV_NAME: "gmf_cmod5n"
+      GMF_VH_NAME: "gmf_s1_v2"
+      dsig_VH_NAME: "gmf_s1_v2"
+      dsig_cr_step: "nrcs"                    # Polarization mixing step
+
+      # Automatic handling of S1 EW recalibration (after 2019-07-31)
+      S1_EW_calG>20190731:
+        GMF_VH_NAME: "gmf_s1_v3_ew_rec"
+        dsig_VH_NAME: "dsig_wspd_s1_ew_rec_v3"
+        dsig_cr_step: "wspd"
+
+      # Processing parameters
+      apply_flattening: True                  # NESZ correction
+      recalibration: False                    # Kersten recalibration
+      ancillary: "ecmwf"                      # Meteorological data
+      inc_step: 0.1                           # Incidence angle step (°)
+      wspd_step: 0.1                          # Wind speed step (m/s)
+      phi_step: 1.0                           # Azimuth step (°)
+      resolution: "high"
+
+Configuration Examples
+----------------------
+
+Configuration with Recalibration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+File: ``config_prod_recal.yaml``
+
+.. code-block:: yaml
+
+    no_subdir: True
+    winddir_convention: "meteorological"
+    add_gradientsfeatures: False
+    add_nrcs_model: False
+
+    S1A:
+        GMF_VV_NAME: "gmf_cmod5n"
+        GMF_VH_NAME: "gmf_s1_v2"
+        recalibration: True  # Enable Kersten recalibration formula
+        # ... other parameters ...
+
+**Usage**: Applies recalibration correction to NRCS data before inversion.
+
+
+Multi-GMFS Version Configuration (S1 v3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+File: ``config_prod_v3.yaml``
+
+.. code-block:: yaml
+
+    no_subdir: True
+    winddir_convention: "meteorological"
+    add_gradientsfeatures: False
+    add_nrcs_model: False
+
+    S1A:
+        GMF_VV_NAME: "gmf_cmod5n"
+        GMF_VH_NAME: "gmf_s1_v2"
+        # Standard configuration
+        # ...
+
+        # Configuration for EW products with calG after 2019-07-31
+        S1_EW_calG>20190731:
+            GMF_VV_NAME: "gmf_cmod5n_v3"
+            GMF_VH_NAME: "gmf_s1_v3"
+            # ... adapted parameters ...
+
+**Usage**: Automatically handles different S1 calibration versions.

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/docs/examples/streaks-display.ipynb

@@ -213,14 +213,14 @@
     "    fig = plt.figure(figsize=(10, 9))\n",
     "    ax = plt.axes(projection=ccrs.PlateCarree())\n",
     "\n",
-    "    # Calculer les composantes u et v à partir des angles streaks_dir\n",
+    "    # Calculer les composantes u et v \u00e0 partir des angles streaks_dir\n",
     "    u, v, u_norm, v_norm = get_uv_from_dir(streaks_dir)\n",
     "\n",
     "    # Display streaks direction\n",
     "    #ax.quiver(longitude, latitude, u_norm, v_norm, edgecolors='k',  norm=norm, pivot= 'mid', scale_units='xy', scale=4., zorder=10, width=0.1/25,transform = ccrs.PlateCarree(), color = 'red', label = 'owiWindStreaks')\n",
     "    ax.quiver(longitude, latitude, u_norm, v_norm, edgecolors='k',  norm=norm, pivot= 'mid', scale_units='xy', scale=8., zorder=10, width=0.1/25,transform = ccrs.PlateCarree(), color = 'red', label = 'owiWindStreaks')\n",
     "\n",
-    "    # Display ancillary wind direction\n",
+    "    #\u00a0Display ancillary wind direction\n",
     "    #ax.quiver(lons, lats, u_norm_ancillary, v_norm_ancillary, edgecolors='k',  norm=norm, pivot= 'mid', scale_units='xy', scale=4., zorder=10, width=0.1/25,transform = ccrs.PlateCarree(), color='blue', label = \"owiAncillaryWindDirection\")\n",
     "    ax.quiver(lons, lats, u_norm_ancillary, v_norm_ancillary, edgecolors='k',  norm=norm, pivot= 'mid', scale_units='xy', scale=8., zorder=10, width=0.1/25,transform = ccrs.PlateCarree(), color='blue', label = \"owiAncillaryWindDirection\")\n",
     "\n",
@@ -316,9 +316,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0"
+   "version": "3.10.15"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/docs/examples/wind-inversion-from-grd.ipynb

@@ -72,7 +72,7 @@
    "source": [
     "import grdwindinversion\n",
     "import os\n",
-    "config_file_s1 = os.path.join(os.path.dirname(grdwindinversion.__file__),'config_prod.yaml')\n",
+    "config_file_s1 = os.path.join(os.path.dirname(grdwindinversion.__file__),'config_prod_v3.yaml')\n",
     "grdwindinversion.__file__\n",
     "print(os.path.exists(config_file_s1))"
    ]
@@ -94,8 +94,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "outfile,outds = makeL2(input_file,out_folder, config_path=config_file_s1,overwrite=True)\n",
-    "outds"
+    "out_file, outputds, return_status = makeL2(input_file,out_folder, config_path=config_file_s1,overwrite=True)\n",
+    "outputds"
    ]
   },
   {
@@ -105,13 +105,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "outds.owiWindSpeed.plot() "
+    "outputds.owiWindSpeed.plot() "
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "env_xsar",
    "language": "python",
    "name": "python3"
   },

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/docs/index.rst

@@ -1,49 +1,52 @@
 Welcome to grdwindinversion's documentation!
 ============================================
 
+``grdwindinversion`` is a Python package for wind inversion from SAR imagery.
 
+Quick Links
+-----------
+
+* :doc:`installation` - Installation instructions
+* :doc:`usage` - Usage guide
+* :doc:`configuration` - Configuration reference
 
 Examples
-........
+--------
 
 .. note::
     With `recommended installation`_ you will be able to download and execute those examples in `jupyter notebook`_.
 
+* :doc:`examples/wind-inversion-from-grd` - Wind inversion from GRD data
+* :doc:`examples/streaks-display` - Display wind streaks features
 
-* :doc:`examples/wind-inversion-from-grd`
-
-Functions description
-.....................
-
-* :doc:`modules`
-
+API Reference
+-------------
 
+* :doc:`modules` - Complete API documentation
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+   :hidden:
 
    ../README
    installation
    usage
+   configuration
    examples/wind-inversion-from-grd
    examples/streaks-display
-
    algorithm
    modules
    contributing
    authors
    history
 
-
-
-
 Indices and tables
 ==================
+
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 
-
 .. _jupyter notebook: https://jupyter.org/
-.. _recommended installation: installation.html
+.. _recommended installation: installation.html

{grdwindinversion-0.3.8 → grdwindinversion-1.0.0}/docs/installation.rst

@@ -32,13 +32,13 @@ You can either clone the public repository:
 
 .. code-block:: console
 
-    $ git clone git://github.com/agrouaze/grdwindinversion
+    $ git clone git://github.com/umr-lops/grdwindinversion
 
 Or download the `tarball`_:
 
 .. code-block:: console
 
-    $ curl -OJL https://github.com/agrouaze/grdwindinversion/tarball/master
+    $ curl -OJL https://github.com/umr-lops/grdwindinversion/tarball/master
 
 Once you have a copy of the source, you can install it with:
 
@@ -47,5 +47,5 @@ Once you have a copy of the source, you can install it with:
     $ python setup.py install
 
 
-.. _Github repo: https://github.com/agrouaze/grdwindinversion
-.. _tarball: https://github.com/agrouaze/grdwindinversion/tarball/master
+.. _Github repo: https://github.com/umr-lops/grdwindinversion
+.. _tarball: https://github.com/umr-lops/grdwindinversion/tarball/master

grdwindinversion-1.0.0/docs/modules.rst

@@ -0,0 +1,51 @@
+#######################################
+Application Programming Interface (API)
+#######################################
+
+..
+    to document functions, add them to __all__ in ../grdwindinversion/__init__.py
+
+Core Processing
+===============
+
+Wind Inversion
+--------------
+
+.. automodule:: grdwindinversion.inversion
+    :members: inverse, makeL2, makeL2asOwi, getSensorMetaDataset, getOutputName, inverse_dsig_wspd, addMasks_toMeta, mergeLandMasks, processLandMask, getAncillary, preprocess, process_gradients, transform_winddir
+    :show-inheritance:
+
+Configuration Management
+------------------------
+
+.. automodule:: grdwindinversion.load_config
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Gradient Features
+-----------------
+
+.. automodule:: grdwindinversion.gradientFeatures
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Utilities
+=========
+
+General Utilities
+-----------------
+
+.. automodule:: grdwindinversion.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Memory Management
+-----------------
+
+.. automodule:: grdwindinversion.utils_memory
+    :members:
+    :undoc-members:
+    :show-inheritance:

grdwindinversion-1.0.0/docs/usage.rst

@@ -0,0 +1,96 @@
+=====
+Usage
+=====
+
+Python API
+----------
+
+To use grdwindinversion in a project::
+
+    import grdwindinversion
+
+
+Configuration Setup
+-------------------
+
+To define the path where the ECMWF files used for wind inversion (or any supported ancillary wind)::
+
+    cp ./grdwindinversion/data_config.yaml ./grdwindinversion/local_data_config.yaml
+    # Then edit the file
+    vi ./grdwindinversion/local_data_config.yaml
+
+See :doc:`configuration` for detailed configuration options.
+
+
+Command-Line Interface
+----------------------
+
+Basic Usage
+~~~~~~~~~~~
+
+Process a SAR image with wind inversion:
+
+.. code-block:: bash
+
+    SAR_L1-to-L2_wind_processor \
+      --input_file /path/to/S1A_*.SAFE \
+      --config_file /path/to/config_prod_v3.yaml \
+      --outputdir /path/to/output/ \
+      --resolution 1000m \
+      --overwrite \
+      --verbose
+
+Command-Line Options
+~~~~~~~~~~~~~~~~~~~~
+
+``--input_file``
+    Path to SAR L1 product (SAFE format for Sentinel-1)
+
+``--config_file``
+    Configuration file to use (recommended: ``config_prod_v3.yaml``)
+
+``--outputdir``
+    Output directory for L2 wind products
+
+``--resolution``
+    Output resolution (e.g., ``1000m``, ``500m``)
+
+``--overwrite``
+    Overwrite existing output files
+
+``--verbose``
+    Enable verbose output
+
+
+Examples
+--------
+
+With default configuration:
+
+.. code-block:: bash
+
+    SAR_L1-to-L2_wind_processor \
+      --input_file S1A_EW_GRDM_1SDH_*.SAFE \
+      --config_file config_prod_v3.yaml \
+      --outputdir ./output/ \
+      --resolution 1000m
+
+With recalibration:
+
+.. code-block:: bash
+
+    SAR_L1-to-L2_wind_processor \
+      --input_file S1A_EW_GRDM_1SDH_*.SAFE \
+      --config_file config_prod_recal.yaml \
+      --outputdir ./output/ \
+      --resolution 1000m
+
+With wind streaks features:
+
+.. code-block:: bash
+
+    SAR_L1-to-L2_wind_processor \
+      --input_file S1A_EW_GRDM_1SDH_*.SAFE \
+      --config_file config_prod_streaks.yaml \
+      --outputdir ./output/ \
+      --resolution 1000m

grdwindinversion-1.0.0/grdwindinversion/__init__.py

@@ -0,0 +1,17 @@
+from importlib.metadata import version
+from grdwindinversion.inversion import inverse, makeL2, makeL2asOwi, getSensorMetaDataset
+from grdwindinversion.load_config import getConf
+
+__all__ = [
+    "inverse",
+    "makeL2",
+    "makeL2asOwi",
+    "getSensorMetaDataset",
+    "getConf",
+    "inversion",
+]
+
+try:
+    __version__ = version("grdwindinversion")
+except Exception:
+    __version__ = "999"