Package: kamui
KamuiKamui is a python package for robust and accurate phase unwrapping on 2-D, 3-D, or sparse data.Kamui unwrap the phases by viewing the data points as vertices $V$ connected with edges $E$ and solving the following integer linear programming (ILP) problem:\min_{k} w^T |k|,\text{s.t.} Ak = -A\frac{x}{2\pi},where $k_{i \in [0, M)} \in \mathbb{Z}$ is the edge ambiguities to be computed, $w_{i \in [0, M)} \in \mathbb{R}^+$ is the weights, $x_{i \in [0, M)} = (V_v - V_u + \pi) \pmod {2\pi} - \pi |  (u, v) = E_i$ is the pseudo phase derivatives, $M = |E|$.
$A_{ij} \in \{-1, 0, 1\} | i \in [0, N) \cap j \in [0, M)$ and $N$ is the number of elementary cycles enclosed by $E$.This formulation is based on the fact that the true phase differences, $2\pi k + x$, should fulfill the irrotationality constraint, which means the summation of phase derivatives of each elementary cycles is zero.
This is the general form of the network programming approach proposed in the paper "A novel phase unwrapping method based on network programming".Unwrapping phase with Kamui can be computationally heavy due to the fact that ILP is NP-hard.
Acceleration techniques, such as dividing the graph into subgraphs, will be implemented in the future.Installationpip install kamuiKamui also providesPUMA, a fast and robust phase unwrapping algorithm based on graph cuts as an alternative.
To install PUMA, runpip install kamui[extra]However, it uses the original maxflow implementation by Vladimir Kolmogorov with GPL license.
Please follow the licensing instruction inPyMaxflowif you use this version of Kamui.UsageFor regular 2-D or 3-D data such as interferograms, usekamui.unwrap_dimensional:importnumpyasnpdefunwrap_dimensional(x:np.ndarray,start_pixel:Optional[Union[Tuple[int,int],Tuple[int,int,int]]]=None,use_edgelist:bool=False,**kwargs)->np.ndarray:"""Unwrap the phase of a 2-D or 3-D array.Parameters----------x : 2-D or 3-D np.ndarrayThe phase to be unwrapped.start_pixel : (2,) or (3,) tuplethe reference pixel to start unwrapping.Default to (0, 0) for 2-D data and (0, 0, 0) for 3-D data.use_edgelist : boolWhether to use the edgelist method.Default to False.kwargs : dictOther arguments passed to `kamui.unwrap_arbitrary`.Returns-------np.ndarrayThe unwrapped phase of the same shape as x."""For sparse data, usekamui.unwrap_arbitrary:importnumpyasnpdefunwrap_arbitrary(psi:np.ndarray,edges:np.ndarray,simplices:Iterable[Iterable[int]]=None,method:str="ilp",period:float=2*np.pi,start_i:int=0,**kwargs,)->np.ndarray:"""Unwrap the phase of arbitrary data.Parameters----------psi : 1D np.ndarray of shape (P,)The phase (vertices) to be unwrapped.edges : 2-D np.ndarray of shape (M, 2)The edges of the graph.simplices : Iterable[Iterable[int]] of length (N,)Each element is a list of vertices that form a simplex (a.k.a elementary cycle).The connections should be consistent with the edges.This is also used to compute automatic weights for each edge.If not provided and method is "ilp", an edgelist-based ILP solver will be used without weighting.method : strThe method to be used. Valid options are "ilp" and "gc", where "gc" correponds to PUMA.Default to "ilp".period : floatThe period of the phase.Default to 2 * np.pi.start_i : intThe index of the reference vertex to start unwrapping.Default to 0.kwargs : dictOther arguments passed to the solver.Returns-------np.ndarrayThe unwrapped phase of the same shape as psi."""ExamplesWIP.TODOsubgraph divisionedges-based custom weightingvertices-based custom weightingReferencesscikit-image/scikit-image/#4622my medium blogpostA novel phase unwrapping method based on network programmingPhase Unwrapping via Graph CutsEdgelist phase unwrapping algorithm for time series InSAR analysisTime Series Phase Unwrapping Based on Graph Theory and Compressed Sensing