Update readme and don't output area projection metadata

CHANGELOG.md

@@ -6,6 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/)
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0]
+
+### Changed
+* Update readme with docker instructions and layer info.
+
+### Removed
+* Output of area projection metadata.
+* Prototype polar grid support in favor of full support via the new docker image.
+
 ## [0.4.0]
 
 ### Changed

README.md

@@ -8,18 +8,33 @@ A python library for creating ISCE3-based RTCs for multiple SAR data sources
 > [!IMPORTANT]
 > All credit for this library's RTC algorithm goes to Gustavo Shiroma and the JPL [OPERA](https://www.jpl.nasa.gov/go/opera/about-opera/) and [ISCE3](https://github.com/isce-framework/isce3) teams. This package merely allows others to use their algorithm with a wider set of SAR data sources. The RTC algorithm utilized by this package is described in [Shiroma et al., 2023](https://doi.org/10.1109/TGRS.2022.3147472).
 
-## Usage
+## Dataset Support
 MultiRTC allows users to create RTC products from SLC data for multiple SAR sensor platforms, and provides utilities for assessing the resulting products. All utilities can be accessed via CLI pattern `multirtc SUBCOMMAND ARGS`, with the primary subcommand `multirtc rtc`.
 
-Currently the list of supported datasets includes:
-
-Full RTC:
-- [Sentinel-1 Burst SLCs](https://www.earthdata.nasa.gov/data/catalog/alaska-satellite-facility-distributed-active-archive-center-sentinel-1-bursts-version)
-- [Capella SICD SLCs](https://www.capellaspace.com/earth-observation/data)
-- [ICEYE SICD SLCs](https://sar.iceye.com/5.0/productFormats/slc/)
+Below is a list of relevant SAR data sources and their support status:
+
+| Mission    | File Format | Image Mode        | Image Grid Type | Status      |
+|------------|-------------|-------------------|-----------------|-------------|
+| Sentinel-1 | SAFE        | Burst IW          | Range Doppler   | Supported   |
+| Sentinel-1 | SAFE        | Full-frame IW     | Range Doppler   | Unsupported |
+| Sentinel-1 | SAFE        | Burst EW          | Range Doppler   | Unsupported |
+| Sentinel-1 | SAFE        | Full-frame EW     | Range Doppler   | Unsupported |
+| Capella    | SICD        | Spotlight         | Polar           | Supported\* |
+| Capella    | SICD        | Sliding Spotlight | Range Doppler   | Supported   |
+| Capella    | SICD        | Stripmap          | Range Doppler   | Supported   | 
+| Iceye      | SICD        | Dwell             | Range Doppler   | Supported   | 
+| Iceye      | SICD        | Spotlight         | Range Doppler   | Supported   | 
+| Iceye      | SICD        | Sliding Spotlight | Range Doppler   | Supported   |
+| Iceye      | SICD        | Stripmap          | Range Doppler   | Supported   |
+| Iceye      | SICD        | Scan              | Range Doppler   | Supported   |
+| Umbra      | SICD        | Dwell             | Polar           | Supported\* |
+| Umbra      | SICD        | Spotlight         | Polar           | Supported\* |
+
+I have done my best to accurately reflect the support status of each SAR image type, but please let me know if I have made any mistakes. Note that some commercial datasets used to use polar instead of range doppler image grids for specific images modes. This table is based on the image grid types currently being used.
+
+\*Polar image grid support is implemented via the [approach detailed by Piyush Agram](https://arxiv.org/abs/2503.07889v1) in his recent technical note. I have implemented his method in a fork of the main ISCE3 repo, which you can view [here](https://github.com/forrestfwilliams/isce3/tree/pfa). The long-term plan is to merge this into the main ISCE3 repo but until that is complete, polar grid support is only available via this project's `pfa`-suffixed docker containers. See the running via docker section for more details.
 
-Geocode Only:
-- [UMBRA SICD SLCs](https://help.umbra.space/product-guide/umbra-products/umbra-product-specifications)
+## Usage
 
 To create an RTC, use the `multirtc` CLI entrypoint using the following pattern:
 
@@ -30,8 +45,38 @@ Where `PLATFORM` is the name of the satellite platform (currently `S1`, `CAPELLA
 
 Output RTC pixel values represent gamma0 power.
 
-### Current Umbra Implementation
-Currently, the Umbra processor only supports basic geocoding and not full RTC processing. ISCE3's RTC algorithm is only designed to work with Range Migration Algorithm (RMA) focused SLC products, but Umbra creates their data using the Polar Format Algorithm (PFA). Using an [approach detailed by Piyush Agram](https://arxiv.org/abs/2503.07889v1) to adapt RMA approaches to the PFA image geometry, we have developed a workflow to geocode an Umbra SLC but there is more work to be done to implement full RTC processing. Since full RTC is not yet implemented, Umbra geocoded pixel values represent sigma0 power.
+### Running via Docker
+In addition to the main python interface, I've also provided an experimental docker container that contains full support for polar grid format SICD data. Encapsulating this functionality in a docker container is ncessary for now because it requires re-compiling a development version of ISCE3. The docker container can be run using a similar interface, with exception of needing to pass your EarthData credentials and the need to pass a mounted volume with an `input` and `output` directory inside:
+
+```bash
+docker run -it --rm \
+    -e EARTHDATA_USERNAME=YOUR_USERNAME_HERE \
+    -e EARTHDATA_PASSWORD=YOUR_PASSWORD_HERE \
+    -v ~/LOCAL_PATH/PROJECT:/home/conda/PROJECT \
+    ghcr.io/forrestfwilliams/multirtc:VERSION.pfa \
+    rtc PLATFORM SLC-GRANULE --resolution RESOLUTION --work-dir PROJECT
+```
+The local `project1` directory can be a name of your choosing and should have the structure:
+```
+PROJECT/
+    |--input/
+        |--input.slc (if needed)
+    |--output/
+```
+If you're encountering `permission denied` errors when running the container, make sure other users are allowed to read/write to your project directory (`chmod -R a+rwX ~/LOCAL_PATH/PROJECT`).
+
+### Output Layers
+MultiRTC outputs one main RTC image and seven metadata images as GeoTIFFs. All layers follow the naming schema `{FILEID}_{DATASET}.tif`, with the main RTC image omiting the `_{DATASET}` component. The layers are as follows:
+- `FILEID.tif`: The radiometric and terrain corrected backscatter data in gamma0 radiometry.
+- `FILEID_incidence_angle.tif`: The angle between the LOS vector and the ellipsoid normal at the target.
+- `FILEID_interpolated_dem.tif`: The DEM used of calculating layover/shadow.
+- `FILEID_local_incidence_angle.tif`: The angle between the LOS vector and terrain normal vector at the target.
+- `FILEID_mask.tif`: The layover/shadow mask. `0` is no shadow or shadow, `1` is shadow, `2` is layover and `3` is layover and shadow.
+- `FILEID_number_of_looks.tif`: The number of radar samples used to compute each output image pixel.
+- `FILEID_rtc_anf_gamma0_to_beta0.tif`: The conversion values needed to normalize the gamma0 backscatter to beta0.
+- `FILEID_rtc_anf_gamma0_to_sigma0.tif`: The conversion values needed to normalize the gamma0 backscatter to sigma0.
+
+More information on the metadata images can be found in the OPERA RTC Static Product guide on the [OPERA RTC Product website](https://www.jpl.nasa.gov/go/opera/products/rtc-product/).
 
 ### DEM options
 Currently, only the OPERA DEM is supported. This is a global Height Above Ellipsoid DEM sourced from the [COP-30 DEM](https://portal.opentopography.org/raster?opentopoID=OTSDEM.032021.4326.3). In the future, we hope to support a wider variety of automatically retrieved and user provided DEMs.

src/multirtc/create_rtc.py

@@ -2,6 +2,7 @@
 import logging
 import os
 import time
+from pathlib import Path
 
 import isce3
 import numpy as np
@@ -143,7 +144,8 @@ def compute_correction_lut(
     rg_lut = isce3.core.LUT2d(
         bistatic_delay.x_start, bistatic_delay.y_start, bistatic_delay.x_spacing, bistatic_delay.y_spacing, tropo
     )
-
+    [x.unlink() for x in Path(scratch_path).glob('*.hdr') if x.is_file()]
+    [x.unlink() for x in Path(scratch_path).glob('*.rdr') if x.is_file()]
     return rg_lut, az_lut
 
 
@@ -388,10 +390,10 @@ def save_intermediate_geocode_files(
     names = [
         LAYER_NAME_LOCAL_INCIDENCE_ANGLE,
         LAYER_NAME_INCIDENCE_ANGLE,
-        LAYER_NAME_PROJECTION_ANGLE,
-        LAYER_NAME_RTC_ANF_PROJECTION_ANGLE,
-        # LAYER_NAME_RANGE_SLOPE, # FIXME
         LAYER_NAME_DEM,
+        # LAYER_NAME_PROJECTION_ANGLE,
+        # LAYER_NAME_RTC_ANF_PROJECTION_ANGLE,
+        # LAYER_NAME_RANGE_SLOPE, # FIXME
     ]
     raster_objs = []
     for name in names:
@@ -408,10 +410,10 @@ def save_intermediate_geocode_files(
     (
         local_incidence_angle_raster,
         incidence_angle_raster,
-        projection_angle_raster,
-        rtc_anf_projection_angle_raster,
-        # range_slope_raster, # FIXME
         interpolated_dem_raster,
+        # projection_angle_raster,
+        # rtc_anf_projection_angle_raster,
+        # range_slope_raster, # FIXME
     ) = raster_objs
 
     # TODO review this (Doppler)!!!
@@ -432,9 +434,9 @@ def save_intermediate_geocode_files(
         dem_interp_method_enum,
         incidence_angle_raster=incidence_angle_raster,
         local_incidence_angle_raster=local_incidence_angle_raster,
-        projection_angle_raster=projection_angle_raster,
-        simulated_radar_brightness_raster=rtc_anf_projection_angle_raster,
         interpolated_dem_raster=interpolated_dem_raster,
+        # projection_angle_raster=projection_angle_raster,
+        # simulated_radar_brightness_raster=rtc_anf_projection_angle_raster,
         # range_slope_angle_raster=range_slope_raster, # FIXME
     )
     for obj in output_obj_list:

src/multirtc/multirtc.py

@@ -8,7 +8,7 @@
 
 from multirtc import dem
 from multirtc.base import Slc
-from multirtc.create_rtc import pfa_prototype_geocode, rtc
+from multirtc.create_rtc import rtc
 from multirtc.rtc_options import RtcOptions
 from multirtc.sentinel1 import S1BurstSlc
 from multirtc.sicd import SicdPfaSlc, SicdRzdSlc
@@ -85,7 +85,10 @@ def run_multirtc(platform: str, granule: str, resolution: int, work_dir: Path) -
         )
         rtc(slc, geogrid, opts)
     else:
-        pfa_prototype_geocode(slc, geogrid, dem_path, output_dir)
+        raise NotImplementedError(
+            'RTC creation is not supported for this input. For polar grid support, use the multirtc docker image:\n'
+            'https://github.com/forrestfwilliams/MultiRTC/pkgs/container/multirtc'
+        )
 
 
 def create_parser(parser):