scilab/modules/elementary_functions/help/en_US/matrixoperations/unwrap.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) 2013 - Samuel GOUGEON
   5  *
   6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15  -->
  16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="unwrap" xml:lang="en">
  17     <refnamediv>
  18         <refname>unwrap</refname>
  19         <refpurpose>unwrap a Y(x) profile or a Z(x,y) surface. Unfold a Y(x) profile</refpurpose>
  20     </refnamediv>
  21     <refsynopsisdiv>
  22         <title>Syntaxes</title>
  23         <synopsis>unwrap() // runs some examples
  24             [U, breakPoints] = unwrap(Y)
  25             [U, breakPoints] = unwrap(Y, z_jump)
  26             [U, cuspPoints]  = unwrap(Y, "unfold")
  27             U = unwrap(Z)
  28             U = unwrap(Z, z_jump)
  29             U = unwrap(Z, z_jump, dir)
  30         </synopsis>
  31     </refsynopsisdiv>
  32     <refsection>
  33         <title>Arguments</title>
  34         <variablelist>
  35             <varlistentry>
  36                 <term>Y</term>
  37                 <listitem>
  38                     <para>Vector of real numbers: the profile to unwrap or unfold. Implicit abscissae X are assumed to be equispaced.</para>
  39                 </listitem>
  40             </varlistentry>
  41             <varlistentry>
  42                 <term>Z</term>
  43                 <listitem>
  44                     <para>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).</para>
  45                 </listitem>
  46             </varlistentry>
  47             <varlistentry>
  48                 <term>z_jump</term>
  49                 <listitem>
  50                     <para>
  51                         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 <literal>z_jump = 2*%pi</literal>. The special value <literal>z_jump = 0</literal> applies jumps equal to the average slope around each breakpoint, restoring a continuous slope over the whole profile or surface.
  52                     </para>
  53                 </listitem>
  54             </varlistentry>
  55             <varlistentry>
  56                 <term>dir</term>
  57                 <listitem>
  58                     <para>"c" | "r" | "" (default): direction along which unwrapping is performed. "c" unwraps along columns, "r" unwraps along rows, "" unwraps in both directions.</para>
  59                 </listitem>
  60             </varlistentry>
  61             <varlistentry>
  62                 <term>"unfold"</term>
  63                 <listitem>
  64                     <para>Provide this switch to unfold the given curve if it is folded, instead of unwrapping it.</para>
  65                 </listitem>
  66             </varlistentry>
  67             <varlistentry>
  68                 <term>U</term>
  69                 <listitem>
  70                     <para>
  71                         Unwrapped profile or surface, or unfolded profile. <varname>U</varname> has the same sizes as <varname>Y</varname> or <varname>Z</varname>.
  72                     </para>
  73                 </listitem>
  74             </varlistentry>
  75             <varlistentry>
  76                 <term>breakPoints, cuspPoints</term>
  77                 <listitem>
  78                     <para>
  79                         Vector of indices of points in <varname>Y</varname> where wrapping or folding has been detected and processed.
  80                     </para>
  81                 </listitem>
  82             </varlistentry>
  83         </variablelist>
  84     </refsection>
  85     <refsection>
  86         <title>Description</title>
  87         <para>UNWRAPPING</para>
  88         <para>
  89             <function>unwrap()</function> will be useful to process profiles or even surfaces wrapped for instance by a periodic and monotonic function such as
  90             <literal>Y = modulo(X,w)</literal> or <literal>Y = atan(tan(X))</literal>. It aims to somewhat invert these functions, recovering the input <literal>X</literal> over it full range instead of the limited <literal>w</literal> or <literal>[-%pi/2, %pi/2]</literal> one.
  91         </para>
  92         <para>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.
  93         </para>
  94         <para>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.
  95         </para>
  96         <para>
  97             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, <function>unwrap()</function> applies a jump equal to the average neighbouring slope, depending on each breakpoint.
  98         </para>
  99         <warning>An unwrapped profile is always defined but for a constant.</warning>
 100         <para>
 101             Unless <varname>dir</varname> is used, <function>unwrap()</function> 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.
 102         </para>
 103         <para> </para>
 104         <para>UNFOLDING</para>
 105         <para>
 106             If the <varname>"unfold"</varname> keyword is used and a profile -- not a surface -- is provided, the profile is assumed to be folded instead of being wrapped.
 107         </para>
 108         <para>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.
 109         </para>
 110         <para>
 111             Folding may occur for instance when a non-monotonic periodic function and its inverse are applied to a profile X, like with <varname>Y= acos(cos(X))</varname>. 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).
 112         </para>
 113         <para>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).</para>
 114         <warning>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.
 115         </warning>
 116         <para>Known limitations: presently, folded surfaces can't be processed.</para>
 117     </refsection>
 118     <refsection>
 119         <title>Examples</title>
 120         <para>Unwrapping or unfolding 1D profiles:</para>
 121         <programlisting role="example"><![CDATA[
 122 // 1D EXAMPLES
 123 // -----------
 124 f = scf();
 125 f.figure_size = [800 1000];
 126 f.figure_position(2) = 0;
 127 f.figure_name = "unwrap() & ""unfold""" + _(": 1-D examples ");
 128 ax = gda();
 129 ax.y_label.font_size=2;
 130 drawlater()
 131
 132 // Original 1D profile
 133 t = linspace(-4,4.2,800);
 134 alpha = t.^2 + t -1;
 135 subplot(5,2,1)
 136 titlepage("unwrap(): unwrap | unfold")
 137 subplot(5,2,2)
 138 plot(t,alpha)
 139 t2 = "$\text{Original profile: } \alpha=t^2+t-1$";
 140 ax = gca();
 141 ax.tight_limits = "on";
 142 yT = max(alpha) - strange(alpha)*0.1;
 143 xstring(0,yT,t2)
 144 e = gce();
 145 e.text_box_mode = "centered";
 146 e.font_size = 2;
 147
 148 // Loop over cases
 149 for i=1:4
 150     subplot(5,2,2*i+1)
 151     if i==1 then
 152         // Wrapping by atan(tan())
 153         ralpha = atan(tan(alpha));            // Raw recovered alpha [pi]
 154         ylabel("$atan(tan(\alpha))$")
 155         [u, K] = unwrap(ralpha, %pi);         // arctan
 156         t2 = "$\text{unwrap(Y, \%pi)}$";
 157     elseif i==2
 158         // Wrapping by modulo() + Y-shift
 159         c = (rand(1,1)-0.5)*4;
 160         ralpha = pmodulo(alpha, 5) + c;
 161         ylabel("$modulo(\alpha,\ 5)"+msprintf("%+5.2f",c)+"$")
 162         [u, K] = unwrap(ralpha, 0);
 163         t2 = "$\text{unwrap(Y, 0)}$";
 164     elseif i==3
 165         // Folding by asin(sin()) + Y-shift
 166         ralpha = 1+asin(sin(alpha));          // Raw recovered alpha [2.pi]
 167         ylabel("$1+asin(sin(\alpha))$")
 168         [u, K] = unwrap(ralpha, "unfold");
 169         t2 = "$\text{unwrap(Y,""unfold"")}$";
 170     else
 171         // Folding by acos(cos()) + a trend
 172         ralpha = 1+alpha/10+acos(cos(alpha)); // Raw recovered alpha [2.pi]
 173         ylabel("$1+\frac{\alpha}{10}+acos(cos(\alpha))$")
 174         [u, K] = unwrap(ralpha, "unfold");
 175         t2 = "$\text{unwrap(Y,""unfold"")}$";
 176     end
 177     // Plotting the profile to be processed
 178     plot(t, ralpha)
 179     // Staring the breakpoints or the cusp points on the curve:
 180     if K~=[] then
 181         plot(t(K), ralpha(K),"*")
 182     end
 183     // Plotting the processed (unwrapped/unfolded) profile:
 184     subplot(5,2,2*i+2)
 185     plot(t,u)
 186     ax = gca();
 187     ax.tight_limits = "on";
 188     // Adding a legend:
 189     yT = max(u) - strange(u)*0.2;
 190     xstring(0,yT,t2)
 191     e = gce();
 192     e.text_box_mode = "centered";
 193     e.font_size = 2;
 194 end
 195 sda();
 196 drawnow()
 197         ]]></programlisting>
 198         <scilab:image>
 199             %_unwrap()
 200         </scilab:image>
 201         <para>Unwrapping 2-D surfaces:</para>
 202         <programlisting role="example"><![CDATA[
 203 // 2-D EXAMPLES
 204 // -----------
 205 ax = gda();
 206 ax.title.font_size = 2;
 207 f = scf();
 208 f.color_map = hotcolormap(100);
 209 f.axes_size = [900 450];
 210 f.figure_position(2) = 0;
 211 f.figure_name = "unwrap()" + _(": 2-D examples");
 212 drawlater()
 213
 214 nx = 300;
 215 ny = 400;
 216 rmax = 8.8;
 217 x = linspace(-rmax/2, rmax/2, nx)-1;
 218 y = linspace(-rmax/2, rmax/2, ny)+1;
 219 [X, Y] = meshgrid(x,y);
 220 for ex=0:1   // examples
 221     // Original surface
 222         // Generating the surface
 223     if ex==0 then
 224         z = X.^2 + Y.^2;
 225     else
 226         z = sqrt(0.3+sinc(sqrt(z)*3))*17-7;
 227     end
 228     // PLotting it in 3D
 229     subplot(2,4,1+4*ex)
 230     surf(x, y, z)
 231     title("Original profile Z")
 232     e = gce();
 233     e.thickness = 0; // removes the mesh
 234     e.parent.tight_limits = "on";
 235
 236     // Wrapped surface (flat)
 237     m = 2.8;
 238     zw = pmodulo(z, m); // wraps it
 239     subplot(2,4,2+4*ex)
 240     grayplot(x, y, zw')
 241     title(msprintf("Zw = pmodulo(Z, %g)  (flat)",m))
 242     ax0 = gca();
 243     ax0.tight_limits = "on";
 244
 245     // Unwrapped surfaces (flat):
 246     // in both directions:
 247     u = unwrap(zw, 0);
 248     subplot(2,4,3+4*ex)
 249     grayplot(x, y, u')
 250     title(msprintf("unwrap(Zw, %g)  (flat)", 0))
 251     ax3 = gca();
 252     ax3.tight_limits = "on";
 253
 254     if ex==0 then
 255         direc = "r";
 256     else
 257         direc = "c";
 258     end
 259     // Along a single direction:
 260     u = unwrap(zw, m, direc);
 261     subplot(2,4,4+4*ex)
 262     grayplot(x, y, u')
 263     title(msprintf("unwrap(Zw, %g, ""%s"")  (flat)",m,direc))
 264     ax1 = gca();
 265     ax1.tight_limits = "on";
 266 end
 267 sda();
 268 drawnow()
 269         ]]></programlisting>
 270         <para/>
 271         <inlinemediaobject>
 272             <imageobject>
 273                 <imagedata fileref="../../images/unwrap_2D.png"/>
 274             </imageobject>
 275         </inlinemediaobject>
 276     </refsection>
 277     <refsection role="see also">
 278         <title>See also</title>
 279         <simplelist type="inline">
 280             <member>
 281                 <link linkend="atan">atan</link>
 282             </member>
 283             <member>
 284                 <link linkend="modulo">modulo</link>
 285             </member>
 286         </simplelist>
 287     </refsection>
 288     <refsection role="bibliography">
 289         <title>Bibliography</title>
 290         <para>
 291             <ulink url="http://siptoolbox.sourceforge.net/doc/sip-0.7.0-reference/unwrapl.html">SIP toolbox: unwrap linear</ulink>
 292         </para>
 293         <para>
 294             <ulink url="http://siptoolbox.sourceforge.net/doc/sip-0.7.0-reference/unwrapp.html">SIP toolbox: unwrap along path</ulink>
 295         </para>
 296     </refsection>
 297     <refsection role="history tag">
 298         <title>History</title>
 299         <revhistory>
 300             <revision>
 301                 <revnumber>5.5.0</revnumber>
 302                 <revdescription>unwrap() function introduced</revdescription>
 303             </revision>
 304         </revhistory>
 305     </refsection>
 306 </refentry>