scilab/modules/elementary_functions/help/en_US/matrixmanipulation/flipdim.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) 2008 - INRIA - Farid BELAHCENE
   5  * Copyright (C) 2013, 2016 - Samuel GOUGEON : 5.5.0 extensions, page overhauled
   6  *
   7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   8  *
   9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  11  * This file was originally licensed under the terms of the CeCILL v2.1,
  12  * and continues to be available under such terms.
  13  * For more information, see the COPYING file which you should have received
  14  * along with this program.
  15  *
  16  -->
  17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  18     xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
  19     xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
  20     xmlns:scilab="http://www.scilab.org" xml:id="flipdim" xml:lang="en">
  21     <refnamediv>
  22         <refname>flipdim</refname>
  23         <refpurpose>reverses the order of (blocks of) rows, columns, pages.. of a matrix or hypermatrix</refpurpose>
  24     </refnamediv>
  25     <refsynopsisdiv>
  26         <title>Syntax</title>
  27         <synopsis>
  28             y = flipdim(x, dim)
  29             y = flipdim(x, dim, blockSize)
  30         </synopsis>
  31     </refsynopsisdiv>
  32     <refsection role="parameters">
  33         <title>Arguments</title>
  34         <variablelist>
  35             <varlistentry>
  36                 <term>x, y</term>
  37                 <listitem>
  38                     <para>
  39                         vectors, matrices, or hypermatrices of any regular data type.
  40                         <varname>y</varname> gets the sizes of <varname>x</varname>.
  41                     </para>
  42                 </listitem>
  43             </varlistentry>
  44             <varlistentry>
  45                 <term>dim</term>
  46                 <listitem>
  47                         <para>
  48                             positive integer : index of the dimension / direction of <literal>x</literal>
  49                             along which the order of <varname>x</varname> components must be inverted.
  50                         </para>
  51                 </listitem>
  52             </varlistentry>
  53             <varlistentry>
  54                 <term>blockSize</term>
  55                 <listitem>
  56                     <para>
  57                         a positive integer, sub-multiple of <literal>size(x,dim)</literal>:
  58                         number of rows, of columns, of pages etc in each block. Default value = 1
  59                     </para>
  60                 </listitem>
  61             </varlistentry>
  62         </variablelist>
  63     </refsection>
  64     <refsection role="description">
  65         <title>Description</title>
  66         <para>
  67             <literal>flipdim(x, 1)</literal> inverts the order of
  68             <emphasis role="italic">rows</emphasis> in the matrix or hypermatrix
  69             <varname>x</varname>.
  70         </para>
  71         <para>
  72             <literal>flipdim(x, 2)</literal> inverts the order of
  73             <emphasis role="italic">columns</emphasis> of <varname>x</varname>.
  74         </para>
  75         <para>
  76             <literal>flipdim(x, 3)</literal> inverts the order of
  77             <emphasis role="italic">pages</emphasis> in the hypermatrix
  78             <varname>x</varname>. Etc.
  79         </para>
  80         <para>
  81             The optional parameter <literal>blockSize</literal> allows splitting
  82             <varname>x</varname> in <literal>size(x,1)/blockSize</literal> blocks
  83             of <varname>blockSize</varname> rows (<literal>dim=1</literal>),
  84             or in <literal>size(x,2)/blockSize</literal> blocks of <varname>blockSize</varname>
  85             columns (<literal>dim=2</literal>), etc (<literal>dim>2</literal>)
  86             and to invert their order.
  87             In each block, the order of components (rows, columns, pages etc)
  88             is unchanged.
  89         </para>
  90     </refsection>
  91     <refsection role="examples">
  92         <title>Examples</title>
  93         <programlisting role="example"><![CDATA[
  94 // Example 1: flip x rows (= components along the first dimension)
  95 x = [1 2 3 4; 5 6 7 8]
  96 y = flipdim(x, 1)
  97
  98 // Example 2: flip x columns (= components along the second dimension)
  99 y = flipdim(x, 2)
 100
 101 // Example 3: flip x pages (= components along the third dimension)
 102 x = matrix(1:24, [3 2 4])
 103 y = flipdim(x, 3)
 104
 105 // Example 4: the first example with complex
 106 x = [1+%i 2*%i 3 4; 5 6-%i 7 8*%pi*%i]
 107 y = flipdim(x, 1)
 108
 109 // Integer-encoded numbers:
 110 x = int16(grand(4, 3, 2, "uin", -9, 9))
 111 y = flipdim(x, 1)
 112
 113 // Booleans:
 114 x = (grand(3, 4, "uin", -9, 9) > 0)
 115 y = flipdim(x, 2)
 116
 117 // Texts:
 118 x = matrix(strsplit("a":"x", 1:23), 4, 6);
 119 x = x+x
 120 flipdim(x, 2)
 121
 122 // Polynomials:
 123 x = inv_coeff(grand(3, 9, "uin", 0, 3), 2)
 124 flipdim(x, 1)
 125
 126 // Rationals:
 127 n = inv_coeff(grand(3, 9, "uin", 0, 3), 2);
 128 d = inv_coeff(grand(3, 9, "uin", 0, 3), 2);
 129 r = n./d
 130 flipdim(r, 2)
 131  ]]></programlisting>
 132         <para>
 133             Examples using <literal>blockSize</literal> :
 134         </para>
 135         <programlisting role="example"><![CDATA[
 136 X = [0 1 2 3 4 5 6 7 8 9 10 11];
 137 flipdim(X, 2, 2) // => [10 11   8 9   6 7   4 5   2 3   0 1] // Block size = 2.
 138 flipdim(X, 2, 3) // => [9 10 11   6 7 8   3 4 5   0 1 2]
 139 flipdim(X, 2, 4) // => [8 9 10 11   4 5 6 7   0 1 2 3]
 140 flipdim(X, 2, 6) // => [6 7 8 9 10 11   0 1 2 3 4 5]
 141
 142 // Error if blockSize does not divide the targeted dimension of x.
 143 y = flipdim(x, 2, 5); // size(X) = [1 12] and blockSize=5 does not divide 12.
 144  ]]></programlisting>
 145     <para>Example of results:</para>
 146     <screen><![CDATA[
 147 --> x
 148  x  =
 149  -5 -2  0  9
 150   0 -7 -6  9
 151  -1 -8 -7  8
 152
 153 --> flipdim(x, 1)
 154  ans  =
 155  -1 -8 -7  8
 156   0 -7 -6  9
 157  -5 -2  0  9
 158
 159 --> flipdim(x, 2)
 160  ans  =
 161   9  0 -2 -5
 162   9 -6 -7  0
 163   8 -7 -8 -1
 164 ]]></screen>
 165     <para></para>
 166     <screen><![CDATA[
 167 --> x
 168  x  =
 169 (:,:,1)
 170   9  4 -3
 171  -4 -8 -3
 172
 173 (:,:,2)
 174   5  8  9
 175   4  4  9
 176
 177 --> flipdim(x, 3)
 178  ans  =
 179 (:,:,1)
 180   5  8  9
 181   4  4  9
 182
 183 (:,:,2)
 184   9  4 -3
 185  -4 -8 -3
 186 ]]></screen>
 187     <para></para>
 188     <screen><![CDATA[
 189 --> x
 190  x  =
 191  -2  3 -5  9 -4 -8
 192   2  8  4 -9  6 -6
 193  -9  8  3  4 -3  4
 194
 195 --> flipdim(x, 2, 2)
 196  ans  =
 197  -4 -8 -5  9 -2  3
 198   6 -6  4 -9  2  8
 199  -3  4  3  4 -9  8
 200
 201 --> flipdim(x, 2, 3)
 202  ans  =
 203   9 -4 -8 -2  3 -5
 204  -9  6 -6  2  8  4
 205   4 -3  4 -9  8  3
 206 ]]></screen>
 207     </refsection>
 208     <refsection role="see also">
 209         <title>See also</title>
 210         <simplelist type="inline">
 211             <member>
 212                 <link linkend="fftshift">fftshift</link>
 213             </member>
 214             <member>
 215                 <link linkend="ifftshift">ifftshift</link>
 216             </member>
 217             <member>
 218                 <link linkend="colon">colon</link>
 219             </member>
 220         </simplelist>
 221     </refsection>
 222     <refsection role="history">
 223         <title>History</title>
 224         <revhistory>
 225             <revision>
 226                 <revnumber>5.5.0</revnumber>
 227                 <revremark>
 228                     <itemizedlist>
 229                         <listitem>
 230                             Extension to all regular data types: booleans, integers,
 231                             strings, polynomials, rationals, graphic handles, etc.
 232                         </listitem>
 233                         <listitem>
 234                             New input argument <literal>blockSize</literal> to flip
 235                             <literal>x</literal> blockwise.
 236                         </listitem>
 237                     </itemizedlist>
 238                 </revremark>
 239             </revision>
 240         </revhistory>
 241     </refsection>
 242 </refentry>