<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is part of the Scilab time frequency toolbox.
This file must be used under the terms of the  terms of the GNU General Public License 
as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Copyright (c) 1996 by CNRS (France).
-->



<refentry xml:id="sigmerge" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:scilab="http://www.scilab.org"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">

  <refnamediv>
    <refname>sigmerge</refname>
	<refpurpose>Add two signals with given energy ratio in dB</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      SIG = sigmerge(X1, X2)
      SIG = sigmerge(X1, X2, RATIO)
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>	X1, X2 :</term>
        <listitem>
          <para>real or complex vectors of same sizes: the input signals.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	RATIO  :</term>
        <listitem>
          <para>a real scalar: the Energy ratio in deciBels (default : 0 dB).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	X      :</term>
        <listitem>
          <para>a real or complex vector with same sizes as X1 and X2: the output signal.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>
    <para>
      sigmerge adds two signals so that a given energy ratio expressed
      in deciBels is satisfied.
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    sig = fmlin(64,0.01,0.05,1); 
    noise = hilbert(rand(64,1,'normal'));
    SNR = 15; // dB
    x = sigmerge(sig,noise,SNR);
    //Check SNR
    Esig = mean(abs(sig).^2); 
    Enoise = mean(abs(x-sig).^2);

    10*log10(Esig/Enoise)
    ]]></programlisting>
  </refsection>

  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>H. Nahrstaedt - Aug 2010</member>
      <member>F. Auger, July 1995.</member>
    </simplelist>
  </refsection>
</refentry>
