Tekst źródłowy strony Svarog/Users Manual/Compiling Svarog

Svarog isn't yet really distributed as a compiled package, so it is best to use the source from the repository and compile and run.

== How to download the development version ==
It's best to download the sources using [http://git-scm.com git].
  git clone git://escher.fuw.edu.pl/git/svarog
This will create directory ''svarog'' populated with the latest version.

If you can't/don't want to use ''git'', you can go to
http://escher.fuw.edu.pl/git/svarog and download one of the ''.tar.bz2'' or ''.zip'' archives using the links on the right hand side.

==Requirements==
#You will need [http://maven.apache.org/ maven].
#protoc from [http://code.google.com/apis/protocolbuffers/docs/overview.html Google Protocol Buffers] version 2.4.x
== How to compile svarog and plugins ==
Change into the directory <tt>svarog</tt> and execute
 mvn clean package

This will download the necessary maven plugins
and also some libraries needed by Svarog which are distributed separately.<BR>
Downloaded files go by default into ''~/.m2/repository''.

This command also creates a package of Svarog complete with dependencies in one file (<code>svarog/target/svarog-0.5.0-SNAPSHOT.one-jar.jar</code>).

== How to run (svarog and plugins) ==
In the toplevel ''svarog'' repository execute
  mvn -pl svarog exec:java

When run as a binary, svarog accepts the following options:

 usage: /usr/bin/svarog <options>
   -D <arg>        define java property (allowed multiple times)
   -h,--help       display help
   -m,--moltest    include test method
   -R,--reset      reset workspace settings
   -s,--nosplash   don't display splash screen

Those options can be passed to Svarog when launching Svarog using Maven by setting <tt>-Dexec.args=...</tt>. E.g.
  mvn -pl svarog exec:java -Dexec.args=--nosplash

Some options can only be set using Java properties. When using maven to launch Svarog, properties can be set using <tt>-Dproperty=value</tt>.

Useful options include:

* <tt>log4j.debug=true</tt> debug log4j configuration. This is useful to see why logging messages are displayed (or not).
* <tt>signalml.root</tt> specifies the location of the Svarog settings directory.
* <tt>svarog.security_manager=enforcing/permissive/off</tt>. The default is currently <tt>off</tt>. See javadoc:org/signalml/app/SvarogSecurityManager.html for more information.

== Accessing and generating documentation ==
Code is documented through java-docs, which can be accessed online http://signalml.org/svarog/apidocs/index.html.

This documentation can be also generated from the source tree:
  mvn install
  mvn javadoc:javadoc
The generated documents are in the directory target/site/apidocs under the source tree.

== Compiling and running just Svarog ==
If you are not working on the plugins, they don't have to be rebuilt constantly. Compile only svarog with:
  mvn -pl svarog compile
  mvn exec:java

== Troubleshooting ==
=== On Ubuntu 10.4 ===
<pre>
[INFO] Unable to find resource 'flanagan:flanagan:pom:1.0.3' in repository central (http://repo1.maven.org/maven2)
[INFO] [compiler:compile {execution: default-compile}]
[INFO] Compiling 1078 source files to /home/adam/svarog/svarog/target/classes
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Compilation failure
Unable to locate the Javac Compiler in:
  /usr/lib/jvm/java-6-openjdk/jre/../lib/tools.jar
Please ensure you are using JDK 1.4 or above and
not a JRE (the com.sun.tools.javac.Main class is required).
In most cases you can change the location of your Java
installation by setting the JAVA_HOME environment variable.
</pre>

Instaling openjdk-6-jdk (sudo apt-get install openjdk-6-jdk) helps.
[[category:Svarog]]

=== On various systems ===
<pre>
[INFO] Compilation failure

/home/svarog/tmp/s6/svarog/target/generated-sources/org/signalml/multiplexer/protocol/SvarogProtocol.java:[11,22]
org.signalml.multiplexer.protocol.SvarogProtocol.Variable is not
abstract and does not override abstract method
newBuilderForType(com.google.protobuf.GeneratedMessage.BuilderParent) in
com.google.protobuf.GeneratedMessage

/home/svarog/tmp/s6/svarog/target/generated-sources/org/signalml/multiplexer/protocol/SvarogProtocol.java:[165,24]
org.signalml.multiplexer.protocol.SvarogProtocol.Variable.Builder is not
abstract and does not override abstract method
internalGetFieldAccessorTable() in
com.google.protobuf.GeneratedMessage.Builder

/home/svarog/tmp/s6/svarog/target/generated-sources/org/signalml/multiplexer/protocol/SvarogProtocol.java:[342,22]
org.signalml.multiplexer.protocol.SvarogProtocol.VariableVector is not
abstract and does not override abstract method
newBuilderForType(com.google.protobuf.GeneratedMessage.BuilderParent) in
com.google.protobuf.GeneratedMessage
...
</pre>

<tt>protoc</tt> has wrong version. It should be 2.4.

==Installing Svarog from a Debian package (experimental)==
<ol><li>Put <tt>svarog.list</tt> in directory <tt>/etc/apt/sources.list.d/.</tt>:
<source lang="bash">sudo wget -O/etc/apt/sources.list.d/svarog.list http://escher.fuw.edu.pl/debian/svarog.list </source>
<li>Install the gpg key used to verify package signatures: 
<source lang="bash">sudo apt-key adv --keyserver pgp.mit.edu --recv-keys 46F44D47 </source>
or alternatively
<source lang="bash">wget -O- http://escher.fuw.edu.pl/debian/gpg.key | sudo apt-key add - </source>
Warning: the key will be changed, right now it is [[User:ZbyszekSzmek|my personal key]]. 
<li>Update the list of available packages with 
<source lang="bash">sudo apt-get update </source>
<li>Svarog can be installed with 
<source lang="bash">sudo apt-get install svarog </source>
</ol>


'''This package does not work on UBUNTU.'''

==Examples==
Examples of biomedical signals that can be viewed using Svarog can be found [http://brain.fuw.edu.pl/~zbyszek/eeg/dane/ here]. One can download them using <tt>wget</tt>.
<source lang="bash">wget -np -r -l5 -c http://brain.fuw.edu.pl/~zbyszek/dane</source>
'''Warning''': The files are big.
==First run==
During the first run of Svarog user makes important decisions about Svarog's appearance.
# Chooses the language Svarog is going to use &mdash; either English or Polish (Fig. <xr id="rys_1"/>). [[File:Svarog 1 uruchomienie 0.png|center|thumb|500px|<figure id="rys_1"/>Choosing language]]
# Chooses directory, where Svarog will store its configuration and files (Fig. <xr id="rys_2"/>). One can store them in <tt>signalml</tt> directory inside default home or choose custom location (Fig. <xr id="rys_3"/>).[[File:Svarog 1 uruchomienie 2.png|thumb|500px|center|<figure id="rys_2"/>Choosing location of configuration storage.]]
# To change the chosen language it is necessary to remove the <tt>signalml</tt> directory.[[File:Svarog 1 uruchomienie 3.png|thumb|500px|center|<figure id="rys_3"/>Custom location]]
#Before accessing Svarog GUI <xr id="rys_5"/>, one gets the final warning <xr id="rys_4"/>.[[File:Svarog 1 uruchomienie 4.png|thumb|800px|center|<figure id="rys_4"/>Final warning]][[File:Svarog_uruchomiony.png|thumb|800px|center|<figure id="rys_5"/>Svarog]]


==Disabling warnings==
Default Svarog warnings might be annoying. In order to disable them, choose <tt>Edit -> Preferences</tt>. Open tab <tt> Miscellaneous</tt>, choose <tt>Disable serious warning dialagos for preset operations</tt> as in Fig <xr id="fig:rys_6"/>.

[[File:Svarog preferences disable warnings.png|thumb|600px|center|<figure id="fig:rys_6"/> Disabling warnings]]

==[[Svarog/Users Manual/Loading signal|Loading signals]]==
How to load signal:
*[[Svarog/Users_Manual/Loading_signal/From file|from file]],
*[[Svarog/Users_Manual/Loading_signal/Online|streamed from a port]],
*[[Svarog/Users_Manual/Loading_signal/Online|from an amplifier]].
==[[Svarog/Users Manual/Viewing books|Viewing books]]==
How to open and browse books (representations of signals obtained by [http://en.wikipedia.org/wiki/Matching_pursuit MP decomposition]).

==[[Svarog/Users Manual/Recording|Recording signals]]==
How to record signals using Svarog.
==[[Svarog/Users_Manual/Loading_signal/Montages|Montage]]==
How to change, choose and save signal montages.
==[[Svarog/Users_Manual/Loading_signal/Filtering|Filtering]]==
How to filter the signal.
==[[Svarog/Users Manual/Tagging signal|Tagging signals]]==
How to tag an offline signal.

==[[Svarog/Users Manual/FFT|Online/Offline FFT tool]]==
How to check the frequency content using FFT.
<!--==[[Svarog/Users Manual/Plugins|Plugins]]==
How to check frequency content of a part of a signal.-->
==[[Svarog/Users Manual/MP Decomposition|Signal decomposition using Matching Pursuit]]==
How to decompose the signal using the Matching Pursuit algorithm
==[[Svarog/Users Manual/Average Evoked Potentials|Average Evoked Potentials]]==
How to compute Average Evoked Potentials using Svarog.
==[[Svarog/Users Manual/Stager|Automatic sleep staging]]==
How to automatically stage sleeps EEG, obtaining a polysomnogram.
==[[Svarog/Users Manual/Artifact|Automatic artifact detection]]==
How to perform automatic EEG artifact detection using Svarog.
==[[Svarog/Users Manual/Presets|Preset interface in Svarog]]==
Saving configuration and settings in Svarog.
==[[Svarog/Users Manual/Export to EEGLab|Export to EEGLab]]==
Svarog allows to export the currently opened signal to EEGLab.

==How to==
#[[Svarog/Users Manual/Change electrode names|Change electrode names]].
#[[Svarog/Users Manual/Check signal|Check quality of the signal received online]].
[[Category:Svarog - User manual]]
#[[Svarog/Users Manual/Add cap type|Add EEG cap type]]
<!--Mostly self-explanatory, yet contributions of users are surely welcome! :-)

=== Filters-design-window attributes (in Polish by now) ===
no więc, jak jest filtr, to on ma passband (pasmo częstotliwości, które 
przepuszcza) i stopband (pasmo częstotliwości, które filtr tłumi).
W przypadku filtru dolno/górnoprzepustowego jest po jednym takim paśmie, 
w przypadku pasmowoprzepustowego jest jedno pasmo przepustowe i dwa 
zaporowe, w przypadku zaporowego jest jedno pasmo zaporowe, dwa 
przepustowe.

Stopband attenuation [dB] - jak bardzo mają być tłumione wszystkie 
częstotliwości z pasma zaporowego (np. 40 dB)

passband ripple [dB] - jakie mogą być wahania tłumienia w paśmie 
przepustowym (idealnie by było, gdyby pasmo przepustowe nie było nigdy 
wcale tłumione, no ale filtrom jest 'łatwiej', żeby były jakieś wahania 
w tym, że w niektórych częstotliwościach sobie trochę potłumią, tak ze 3 
dB).

pomiedzy pasmem zaporowym a przepustowym jest zawsze pasmo przepustowe - 
czestotliwosci należące do niego nie są ani tak stłumione, jak chcemy 
ustawiając stopband attenuation, ani nie są tak dobrze przepusczzane jak 
chce passband ripple.

passband edge frequencies - skrajne częstotliwości z pasma przepustowego 
(z jednej strony stykaja sie z pasmem przepustowym, a z drugiej z pasmem 
przejsciowym)
stopband edge frequencies - skrajne częstotliwości z pasma zaporowego (z 
jednej strony stykają się z pasmem zaporowym, a z drugiej z pasmem 
przejściowym).

odległość pomiędzy passband edge frequency a stopband edge frequency to 
pasmo przejsciowe - im większe, tym niższy rząd filtra. 0.5 Hz to trochę 
za mało, butterworth sobie nie poradzi, ellip może już bardziej.

aha - zawsze trzeba sobie sprawdzić, czy projektant poradził sobie z 
parametrami - przy zbyt restrykcyjnych parametrach - wąskie pasmo 
(pasma) przejściowe, wysokie tłumienie w paśmie zaporowym (stopband 
attenuation), niskie tłumienie w paśmie - on może bez ostrzeżenia 
zaprojektować filtr, który nie zadziała - widać to wtedy na wykresie, 
który wygląda słabo, dlatego trzeba sobie sprawdzać wykresy do 
filtrów.

=== How to add in-built standard filters to standar-filters-list (in Polish by now) ===
jest taki plik AbstractSignalTypeConfigurer.java i tam są pododawane.

np.

filters.add(new TimeDomainSampleFilter(FilterType.LOWPASS, ApproximationFunctionType.BUTTERWORTH, new double[] {20, 0}, new double[] {30, 0}, 5.0, 20.0));

 

 

parametry to:

-typ filtra

- rodzina

- tablica częstotliwości granicznych pasma przepustowego

- tablica częstotliwości granicznych pasma zaporowego

- wahania w paśmie przepustowym

- wymagane tłumienie w paśmie zaporowym

 

jak robisz lowpassa/highpassa to z w tych tablicach ważny jest tylko pierwszy element, ale drugi też wpisz (np. 0).

 

Czasem się robi błąd - człek robi np lowpassa, a częstotliwość graniczna pasma przepustowego ustawia większą niż częstotliwość graniczna pasma zaporowego (czyli w częstotliwościach jest highpass, a w parametr pierwszy mówi, że to highpass) i analogiczne błedy dla bandpassów itd. W GUI takie coś jest zablokowane, ale w kodzie można to wpisać.
[[category:Svarog]]-->