unwrap unwrap a Y(x) profile or a Z(x,y) surface. Unfold a Y(x) profile Syntaxes unwrap() // runs some examples [U, breakPoints] = unwrap(Y) [U, breakPoints] = unwrap(Y, z_jump) [U, cuspPoints] = unwrap(Y, "unfold") U = unwrap(Z) U = unwrap(Z, z_jump) U = unwrap(Z, z_jump, dir) Arguments Y Vector of real numbers: the profile to unwrap or unfold. Implicit abscissae X are assumed to be equispaced. Z Matrix of real numbers: the surface to unwrap. Implicit abscissae (X,Y) are assumed to be cartesian and equispaced (constant steps may be different along X versus along Y). z_jump Scalar real positive number used in unwrapping mode: the jump's height applied at breakpoints, performing the unwrapping. Only its absolute value is considered. The jump actually applied has the sign of the slope on both sides of each breakpoint. The default value is z_jump = 2*%pi. The special value z_jump = 0 applies jumps equal to the average slope around each breakpoint, restoring a continuous slope over the whole profile or surface. dir "c" | "r" | "" (default): direction along which unwrapping is performed. "c" unwraps along columns, "r" unwraps along rows, "" unwraps in both directions. "unfold" Provide this switch to unfold the given curve if it is folded, instead of unwrapping it. U Unwrapped profile or surface, or unfolded profile. U has the same sizes as Y or Z. breakPoints, cuspPoints Vector of indices of points in Y where wrapping or folding has been detected and processed. Description UNWRAPPING unwrap() will be useful to process profiles or even surfaces wrapped for instance by a periodic and monotonic function such as Y = modulo(X,w) or Y = atan(tan(X)). It aims to somewhat invert these functions, recovering the input X over it full range instead of the limited w or [-%pi/2, %pi/2] one. A breakpoint of a wrapped profile is detected as a point where slopes on both neighbouring sides of the point are almost equal but much smaller (in absolute value) from and opposite to the slope at the considered point: at the point, there is a jump breaking and opposed to the neighbouring slope. This detection strategy avoids considering any particular level as a wrapping one. It allows to process wrapped profiles to which a constant (or even a trend) has been added afterwards. Unwrapping consists in reducing every detected jump and somewhat restoring a continuous slope (initially assumed to be so). At each point, it is performed by applying a Y-shift on a whole side of the profile, with respect to the other. The Y-shift may be the same for all breakpoints, as provided by the user. If the user specifies a null Y-shift, unwrap() applies a jump equal to the average neighbouring slope, depending on each breakpoint. An unwrapped profile is always defined but for a constant. Unless dir is used, unwrap() applied to a surface unwraps its first column. Each point of this one is then taken as reference level for unwrapping each line starting with it. UNFOLDING If the "unfold" keyword is used and a profile -- not a surface -- is provided, the profile is assumed to be folded instead of being wrapped. At a folding point -- or "cusp point" --, the profile is continuous, but its slope is broken: the slope has almost the same absolute value on both sides of the point, but is somewhat opposed from one side to the other. Folding may occur for instance when a non-monotonic periodic function and its inverse are applied to a profile X, like with Y= acos(cos(X)). Recovering X from Y is quite more difficult than if it was wrapped. Indeed, some ambiguous situations may exist, like when the profile is tangentially folded on one of its quasi-horizontal sections (if any). When a cusp point is detected, a) one side of the profile starting from it is opposed (upside down), and b) the continuity of the profile and of its slope are preserved and retrieved at the considered point (this may need adding a small jump by the local slope). The slope on the left edge of the input profile is used as starting reference. The unfolded profile may be upside down with respect to the original true one. In addition, as for unwrapping, it is defined but for a constant. Known limitations: presently, folded surfaces can't be processed. Examples Unwrapping or unfolding 1D profiles: %_unwrap() Unwrapping 2-D surfaces: See also atan modulo Bibliography SIP toolbox: unwrap linear SIP toolbox: unwrap along path History 5.5.0 unwrap() function introduced