Question regarding SPURT unwrapping and pre-processing (Goldstein filtering) in _unwrap.py

[sccdyuyu]

Hi dolphin developers,I've been using the dolphin framework for phase unwrapping with the SPURT method. However, I recently noticed that my unwrapped results contain large, unnatural color blocks (likely due to isolated connected components or $2\pi$ phase jump errors in noisy regions).

While investigating the possible causes, I looked into the src/dolphin/unwrap/_unwrap.py script and noticed that the SPURT method appears to bypass the built-in preprocessing steps. Specifically, in the run() function:

if unwrap_options.unwrap_method == UnwrapMethod.SPURT:
        if temporal_coherence_filename is None:
            raise ValueError("temporal coherence required for spurt unwrapping")
        unw_paths, conncomp_paths = unwrap_spurt(...)
        for f in unw_paths:
            io.set_raster_units(f, "radians")
        return unw_paths, conncomp_paths

Because the function returns early here, it skips the single-interferogram unwrap() function entirely. Consequently, the run_goldstein (Goldstein filtering) and run_interpolation steps are not applied to the inputs when using SPURT, unlike other methods such as SNAPHU.
I have a few questions regarding this design choice:
Is this bypass intentional? Does the SPURT algorithm mathematically require the raw, unfiltered wrapped phase as input, or is this simply a workflow routing choice?
Best practices for noisy data: Given that high noise in my original interferograms might be causing the large disconnected color blocks, is it recommended to apply Goldstein filtering before passing the interferograms into the SPURT workflow?
If pre-filtering is recommended, is there a built-in way to trigger run_goldstein for SPURT within the current UnwrapOptions config, or should I manually run a separate filtering step beforehand?
Thanks in advance for your time and for the great work on this tool!

[scottstanie]

Hi, very reasonable question, and one that's hard to guess without k owing the details of spurt.

• spurt overrides your requested interferogram network to always do nearest 3. It needs to be a planar graph, so you can't pick an arbitrary one
• spurt also needs the input to have zero phase closure around each triplet. If you Goldstein filtered each interferogram, this would break
• spurt gets around decorrelation by picking a small, sparse subset of points to unwrap on an irregular grid. In that way, it has a very different philosophy than Goldstein filtering each interferogram and running a 2d unwrap.
• if your data is very large and coherent at many points (like a sentinel frame with more than 20% of the points passing the coherence mask), I would recommend one of the other unwrappers. Spurt has a memory problem for very large frames with many 10s of millions of points. It works great for smaller areas where you can hold it all in memory
• on that note, I do note recommend the tiling right now. I have found that to be less reliable than spurt itself when you can unwrap without any tiling.

What's the size of your area and what is the percentage with greater than, say, 0.7 temporal coherence?

[sccdyuyu]

Hi Scott,

Thanks again for the detailed explanation about SPURT. I would like to follow up with more specific information from our case and ask for your advice.

We are testing SPURT over a mountainous canyon area with steep topography, vegetation, layover/shadow, and many low-coherence patches.

To answer your previous question about size and temporal coherence:

• output strides: y=3, x=6
• looked raster size: 4333 x 4830, about 20.9 million pixels
• valid area: about 33.5% of the looked raster

For the phase-linking metrics:

• temporal coherence > 0.7: about 4.3% of the full looked raster, or about 12.8% of the valid area
• similarity > 0.7: about 16.1% of the full looked raster, or about 47.9% of the valid area
• temporal coherence > 0.7 OR similarity > 0.7: about 18.5% of the full looked raster, or about 55.1% of the valid area

I attached a figure showing these three masks side by side:

1. temporal coherence > 0.7
2. similarity > 0.7
3. the final SPURT mask using TC OR similarity

From the Dolphin source code, my understanding is that SPURT builds the point-selection mask in dolphin/unwrap/_unwrap_3d.py roughly as:

temp_coh = io.load_gdal(temporal_coherence_filename, masked=True).filled(0)
temp_coh_mask = temp_coh > options.temporal_coherence_threshold
combined_mask = temp_coh_mask

if similarity_filename and options.similarity_threshold:
    sim = io.load_gdal(similarity_filename, masked=True).filled(0)
    sim_mask = sim > options.similarity_threshold
    combined_mask = combined_mask | sim_mask

if mask_filename:
    nodata_mask = io.load_gdal(mask_filename).astype(bool)
    combined_mask = combined_mask & nodata_mask

So my understanding is:

SPURT selection mask = valid_mask AND (TC > threshold OR similarity > threshold)

This is the main reason for my question: TC > 0.7 is sparse, but once similarity > 0.7 is included, the selected mask becomes much denser.

We also compared SPURT results before and after changing the SPURT thresholds:

before: temporal_coherence_threshold = 0.25, similarity_threshold = 0.25
after: temporal_coherence_threshold = 0.7, similarity_threshold = 0.7
both cases were run with no Goldstein filtering, no interpolation, and no tiling

I attached a second figure showing several unwrapped interferograms before/after the threshold change, plus the difference image. Some blocky phase jumps / unstable areas remain, and we are trying to understand whether this is due to the mask density, phase-linking settings, poor acquisitions, interpolation choices, or whether SPURT is simply not the best unwrapper for this type of scene.

I have four questions:

Given these percentages, would you consider this scene suitable for SPURT? If TC > 0.7 is only about 12.8% of the valid area, but TC > 0.7 OR similarity > 0.7 is about 55.1% of the valid area, is that still within the “small, sparse subset” regime where SPURT is expected to work well?

For mountainous canyon areas, do you have any practical guidance on phase-linking parameters such as half_window, shp_method, and shp_alpha? For example, is a larger half_window usually helpful for stabilizing covariance estimation, or can it over-smooth across terrain/land-cover boundaries and make SPURT less reliable? Are there typical ranges you would recommend testing?

Since the SPURT mask uses both temporal coherence and similarity, how should the two thresholds usually be balanced? Should similarity_threshold usually be stricter than temporal_coherence_threshold, because similarity can admit many more pixels? For example, would something like this make more sense in a mountainous canyon scene?

temporal_coherence_threshold: 0.7
similarity_threshold: 0.8  # or 0.9

There is also an interpolation option in the SPURT workflow. I understand this is different from Goldstein filtering, but could interpolation still make SPURT less stable by modifying wrapped phases or creating artificial bridges across low-quality areas? If interpolation is recommended, should the interpolation thresholds be similar to the SPURT selection thresholds, or should they be stricter/looser?
In short, I am trying to understand whether our current issue is more likely caused by:

too many similarity-selected pixels entering the irregular grid,
phase-linking parameters such as half_window / SHP settings,
poor acquisitions in the time series,
interpolation choices,
or SPURT not being the best unwrapper for mountainous canyon scenes.
Thanks again for your guidance.

[scottstanie]

thanks for the detail! A few quick thoughts

• The ~7 million valid pixels for the whole valid area is actually pretty small and doable with spurt on a machine with ~30-40 GB (i dont know the exact number, it is certainly doable on even smaller machines if you unwrapped only 1 spatial ifg at a time)
• But... the 0.7 temporal cohernece looks super sparse indeed... How many total dates did you have/what was the ministack_size used? As you pointed it, there are clearly a bunch of unwrapping errors all over...

is this a snowy area? I see you are including data into december through March. It's possible it might work, but in our testing for OPERA on snowy areas (see figure 9 https://arxiv.org/pdf/2511.12051 ), the default settings had terrible coherence and was full of unwrapping errors. The only thing that helped get possibly-usable results were

1. turn up the half_window to average more pixels
2. remove any possibly snowy areas that might be in your input data stack
   before we did that, al lthe fiddlying with filtering/unwrapper settings didn't make a difference. the snowy/heavily vegetated areas were just causing garbage in the interferograms.

again, not sure since I dont know this area yet, but I would trust the lower temporal coherence more than i would trust the high phase similarity. there were a few areas (like northern alaska) where the temporal coherence was like, but phase similarity high, that had very suspect results. if you want to see how we altered some of the dolphin defaults, check out https://github.com/opera-adt/disp-s1/tree/main/configs/overrides-data