leafy seadragon: Leafy Seadragon 2.1 User Guide

Leafy Seadragon, the first open source application to research cetacean communication by using two-way underwater acoustic interactions, was successfully demonstrated at the 3rd International Workshop on Detection and Classification of Marine Mammals using Passive Acoustics, on July 24, 2007, in Boston.

Click to enlarge. V. 2.1 recognizing whistle s2

1. Getting Started

Seadragon2dot1 is out. You can now chat with dolphins using your Mac. Works on a Mac with Java 5 or later (free download from Apple). Requires Mac OS X v. 10.4 or later.

After downloading, double-click the jar file to launch the application.

Also works with Windows, Solaris, or Unix-like systems, although with Solaris and Linux, a command file (script file) is required to launch it. (Don't use the run.bat file and the run shortcut for now.)

Downloading:

There are two jar files available (you use one): Seadragon2dot1at10fsps.jar and Seadragon2dot1at40fsps.jar. The first one is for 10 frequency samples per second (fsps) and the second one is for 40 fsps. If you have an older computer, you could use the one for 10 fsps and probably do fine.

The jar files can be downloaded from sourceforge.net here

You can also download the source code: Seadragon2dot1_src_20060818 (.zip)

Testing:

To start testing Leafy Seadragon in air, whistle s2 is a good first test. Whistle s2 comes with Leafy Seadragon, you don't have to design it.

Connect a headphones and a microphone in the RCA jacks of the machine. Do not wear the headphones. Position the microphone near the headphones.

In order to make Leafy Seadragon listen to itself, disable the self-filter by opening the Controls tab (in the right half of the main window) and by deselecting the Self-Filtering Enabled check box.

The message window should then display an item like this in the rectangle under EMITTED AND ACQUIRED SIGNALS:

3 2006.08.19-17:30:41 from Seadragon> Self-Filtering is now disabled (h emissions are processed)

The h and H characters by themselves usually stand for human, and the c's and C's stand for for cetacean (e.g., dolphin).

To emit whistle s2, type s2 in the rectangle under the Emit button and then press the Enter key of your keyboard or select the Emit button.

If the system (which includes your mic and headphones) is working properly, then Leafy Seadragon should display these two new messages (under EMITTED AND ACQUIRED SIGNALS):

4 2006.08.19-17:32:23 from H> s2
5 2006.08.19-17:32:24 from C> ((( s2 )))

The ((( ))) characters around the s2 name mean that Leafy Seadragon has recognized the whistle s2, as if it came from a dolphin. This kind of tests helps verifying that all components are working properly, from the emiting process to the recognition process, including the hydrophones, when performed with underwater whistles instead of whistles in air.

For more details on the format of whistles names, read the text in the bottom window of the Signals tab.

When using Leafy Seadragon with dolphins, it is recommended to enable self-filtering by selecting the Self-Filtering Enabled check box in the Controls tab, so that you do not confuse your emissions with those of dolphins, in the message window (EMITTED AND ACQUIRED SIGNALS).

For a detailed view of the acquired sounds, you could use the Spectrogram tab. It must first be enabled by a check box in the Controls tab.

2. The Big Picture

This document is the user guide for the free Leafy Seadragon software from http://c2h.sourceforge.net/.

This open source software supports interactive, two-way acoustic communication research with dolphins and eventually larger cetaceans. It is intended as a tool to help determine the characteristics of the acoustic communication abilities of cetaceans in a scientific manner.

In order to get started with Leafy Seadragon and experiment with listening to and emitting underwater whistles with dolphins, all you need to do is:

Download and install Leafy Seadragon (see Section 3 below for details). Most current PC or laptops are adequate.

Design your own whistles (Section 5) and try them in air by using headphones and microphone.

Do not wear the headphones for these tests.

Samples whistles are included.

http://seadragon-whistles.blogspot.com/- user guide for Leafy whistles

Use your whistles at sea with dolphins.

Replace the headphones and microphone with 2 transducers, aka. hydrophones (one of which must be designed to emit and is sometime called a projecting transducer).

You may need to insert a small battery powered amplifier between the computer and the emitting transducer (for example, an Altec Lansing model for iPods).

Make sure that you use safe sound pressure levels (Section 3.3).

Make sure that you know and respect the laws and regulations that apply to your nationality and your location. For example, it is possible that American citizens require a permit from National Marine Fisheries Services (NMFS), NOAA, in order to use Leafy Seadragon in any waters, and such a permit would be required for anyone in US waters.

Interpret the whistles emitted by dolphins in apparent relation with your emissions and reply to them (Section 4 will help).

When you close the application, the acquired signals (whistles) are written in a text file (xml) and you can use these in subsequent sessions (Section 6). All emissions and acquisitions are also written in session Report files (Section 7).

Exchange your data with other users. Support the replication of your discoveries by others. Publish your work.

3. Details to Install and Run

3.1. Installation Details

Summary: install Java and Leafy Seadragon, and run it.

3.1.1. Installing Leafy Seadragon Version 2.1

To install Leafy Seadragon 2.1, download and unzip file seadragon2dot1at40fsps.zip from http://c2h.sourceforge.net/ (follow the *Downloads* links). Alternatively, you could use file seadragon2dot1at10fsps.zip if your computer is relatively slow.

3.1.2. Installing Java 5

Leafy Seadragon requires Java 5 on your computer.

Java 5 is also called Java SE 5 Runtime Environment, and also called JRE 1.5 for historical reasons. The development environment is called JDK but you do not need the JDK for running Leafy Seadragon.

3.1.2.1. To install Java 5 for Windows, Solaris, and Linux:

To install Java 5 on Microsoft Windows, one easy way is to get it from http://java.com/ and use the installation wizard from this site.

To install the Java 5 for Solaris or Linux, go to http://java.sun.com/.

3.1.2.2. To install Java 5 for a Mac:

Since April 17, 2006, the latest version of Java 5 (aka. 1.5.0, 1.5, and 5.0) for the Mac is called by Apple J2SE 5.0 Release 4 for Mac OS X Tiger and also J2SE 5.0 Release 4 on Mac OS X v.10.4. I will call it *Release 4* in this post. Release 4 is the Apple release number for their free tool containg their Java 5 virtual machine (VM). The VM is a part of the JRE.

Release 4 can be obtained from Apple via one of 3 ways:

a. Using the Software Update function on their Mac via the Apple Menu or the System Preferences application.

b. Via Apple Support web site at http://www.apple.com/support/

c. By manual download from http://developer.apple.com/java/download/

The manual download method requires the user to register in the Developers program at Apple. Registration is free, and it requires a confirmation by email.

Apple has one version of Release 4 for the new Intel macs and one for the older PowerPC (PPC) macs. You must select the correct one for your Mac. If you're not sure, contact Apple.

After installing Release 4, the default Java version is 5 (aka. 1.5, 1.5.0, and 5.0) and not the old 1.4 or 1.3. The older 1.4 and 1.3 versions are still kept on the Mac but Seadragon does not use them. Other Java applications should work fine with Java 5 instead of 1.4 or 1.3.

On a Mac, Java 5 is installed in /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/

One may look there to verify whether one's Mac already has it or not.

3.2. To Run Leafy Seadragon Version 2.1

3.2.1. To Run Leafy Seadragon on a Mac or under Windows:

Double-click on the jar file Seadragon2dot1at40fsps.jar in folder seadragon2dot1at40fsps. Do not use file run.bat and shortcut run for now.

3.2.2. Using 40 or 10 Frequency Samples per Second:

Seadragon2dot1at40fsps.jar is for using a frequency sampling rate of 40 frequency samples per second (fsps). The other application that can be downloaded, Seadragon2dot1at10fsps.jar, is using 10 frequency samples per second. In both cases the voltage sampling rate is normally at 48,000 voltage samples per second, and 1024 voltage samples are required to calculate one frequency sample, 10 or 40 times per second.

It is often best to use the rate of 40 frequency samples per second but your PC may not be fast enough, and in this case, you should use 10 frequency samples per second. So if you are using a slower PC, e.g., less than 1 GHz processor, then use the Seadragon2dot1at10fsps.jar file (another download).

3.3. Optimization:

Leafy Seadragon is very demanding in processor time (CPU intensive), therefore it is recommended to run Seadragon by itself, i.e., ensure that no other application is running at the same time as Leafy Seadragon.

If you are familiar with the Java platform, you may also set the -Xmx and -Xms switches in a java command line in a batch file to approx. 80% of your RAM for optimized performance. File run.bat is a Windows batch file that you could use. A Mac that can use Java 5 should have no difficulties with 40 fsps.

For example, using a Windows system with 500 or so Meg of RAM, you could modify the run.bat file to contain this command:

java -Xmx400m -Xms400m -jar Seadragon2dot1at40fsps.jar

This would reserve 400 Meg of RAM when the program starts and limit the memory used to 400 Meg. Instead of the 64 Meg total by default. You must use the run.bat file to launch the program in order to use these options.

3.4. Sound Pressure Level (SPL)

Attention: Leafy Seadragon can emit loud sounds (at your command), so if you are using headphones for testing in air, adjust the volume to a safe level prior to putting them on. Failure to do so may result in hearing damage.

Leafy Seadragon software does not have its own controls to amplify or reduce the sound pressure level being emitted by the projector transducer (output hydrophone). You control the emitted sound volume levels using the PC controls. If you are using an optional amplifier between the PC and the projector transducer or speakers or headphones, then you can also use the controls on the amplifier, if any.

Dangerous Underwater SPL = 146 dB

US Navy divers are not allowed to be exposed to underwater sound pressure above 146 dB (referenced to 1 microPascal).

A Blue Whale can produce sounds at up to 180 dB (re. 1 uP).

Military high power sonars can produce bursts above 200 dB and these are considered very dangerous for mammals, including humans, cetaceans, and other species.

In the current version, the projector transducer (output hydrophone) is connected to the headphone jack of a PC or to an amplifier connected to the headphone jack. An amplifier may be required in order to communicate with dolphins at sea. For underwater emissions, the headphone jack of most PCs is assumed to produce a low and safe sound level when used without an amplifier (this is only valid for underwater emissions and for emissions in air even a PC without an amplifier may produce sound levels that can be damaging). The user is responsible for monitoring the sound pressure level being emitted, either underwater or in air.

The Spectrogram & SPL Display:

Leafy Seadragon now supports the monitoring of sound pressure levels (SPL). This function can be calibrated by the user (human) for obtaining valid SPL calculations, but the basic process will not be affected if you do not calibrate the SPL function. See SPL Calibration below.

To see the Spectrogram and SPL Measurements:

select the Controls tab,

select the SPL checkbox for Water or unselect for Air,

enter the SPL calibration value for your equipment, for water or air (see below),

select the Spectrogram & SPL Enabled checkbox,

select the Spectrogram tab.

For better performance, the spectrogram is not updated when it is not visible.

To stop the Spectrogram & SPL function:

select the Controls tab,

deselect the Spectrogram & SPL Enabled checkbox.

SPL Calibration: The SPL calibration values for water and air can be set by running the Spectrogram & SPL function in a quiet environment. The value to use in the calibration controls should be the negative of the minimum SPL measured in the quiet environment. For example, if the minimum SPL shown by Seadragon in a very quiet environment is 105 and you determine that the displayed level should be 0 dB for this environment, then enter -105 in the appropriate calibration control field (one for air, the other for water). You may need to use a pre-calibrated SPL meter instrument in order to determine the appropriate level in your test environment.

You'll notice that you can resize the Seadragon window and the contents will resize automatically. The spectrogram window should be resized with the spectrogram function turned off in order to avoid possible spurious graphic errors.

3.5. Turn on the FILTER SELF control: Stop Seadragon from listening to itself

After starting the application, it is recommended to disable the Self-Filtering function and emit a few whistles (e.g., s1, s2) to verify that the system is working properly, because Leafy Seadragon would be listening to what it is emitting and you can see what it is recognizing. For normal operation, you should enable the Self-Filtering function and therefore stopping Leafy Seadragon from displaying the whistles that it emits. You enable and disable the Self-Filtering function by going to the Controls tab and selecting or de-selecting the Self-Filtering check box. When selected, Leafy Seadragon filters itself and does not display the signals that it emits.

The Spectrogram display can be used to observe more details about the emitted and incoming sounds. The whistles emitted by Seadragon are displayed in the Spectrogram window even when the Self-Filtering function is enabled.

4. The syntax of signal names used in the message window

((( s2 ))) = Leafy Seadragon recognized an incoming signal as matching a signal named s2, the ((())) characters are used to mean recognized; signal s2 may be either man-made or cetacean-made; the human user can define her own naming technique to distinguish between the two categories, e.g., in the downloaded version all signals are man-made and they all start with s.

((( *19 ))) = this is a signal that matches the previously acquired unknow signal # 19 in this session; the asterix * means that this unknown signal is new (i.e., its first appearance is in the current session).

((( 200503262213_19 ))) = this is a signal that matches the unknow signal # 19 from session 200303262213 (March 26, 2005, 10:13 PM).

*9~3L67%*7 = unrecognized signal number 9; 3L means that it has 3 frequency values (L=length); the best matching score is 67% with the signal named *7, which is unrecognized # 7 in the current session.

*5~13L31%s10.5 = unrecognized signal number 5; it has 13 samples; its best score is 31% with man-made signal s10.5.

5. Define a New Whistle - Manually

More details are available at http://seadragon-whistles.blogspot.com/.

To create a whistle manually write a set of xml elements in the whistle file to be read by the application the next time that it is launched. This file is seadragon2dot1at40fsps\inputdata\signals\signals_to_read.xml.

An example of a set of xml elements defining a whistle:

<object class="org.leafyseadragon.jse.signal.StoredSignal">

<void property="hz10ps">

<array class="java.lang.Double" length="5">

<void index="0">

<double>1000.0</double>

</void>

<void index="1">

<double>1500.0</double>

</void>

<void index="2">

<double>1500.0</double>

</void>

<void index="3">

<double>2000.0</double>

</void>

<void index="4">

<double>2200.0</double>

</void>

</array>

</void>

<void property="signalType">

<string>LEX_SIGNAL</string>

</void>

<void property="text">

<string>s05</string>

</void>

<void property="uid">

<string>s05</string>

</void>

</object>

To save time, it is common to copy and modify an existing set of xml elements.

6. Use a Whistle Previously Acquired By Leafy Seadragon

You can easily use a whistle that was acquired by Leafy Seadragon during a previous session. This is basically a copy and paste operation on text. At the end of each session, i.e., when the user closes the application, Leafy Seadragon writes a text file containing the whistles it has in memory, including whistles it acquired during the session. Instances of this file, e.g., signals_saved_1118369700921.xml, are located in seadragon2dot1at40fsps\results\signals. In this example, the 1118369700921 number is the timestamp in milliseconds used to make the filename unique.

This type of files is a text file with xml formatting and can be used to manually select one or more whistles (aka. signals) and include these into the whistle file to be read by the application the next time that it is launched. The file read at startup is seadragon2dot1at40fsps\inputdata\signals\signals_to_read.xml. So essentially you copy a whistle from a signal_saved file to the signals_to_read.xml file.

The whistles could be from your own communication sessions or from the sessions of someone else. A whistle written in xml is defined by the lines starting from this line:

<object class="org.leafyseadragon.jse.signal.StoredSignal">

all the way to the next line containing this tag: </object>

When you select a whistle to be cut and pasted, you should change the name of the whistle by changing the content of tag for the element with property called "text" such as in:

<void property="text">

<string>200410231234_29</string>

</void>

and change it to this:

<void property="text">

<string>s21</string>

</void>

So now Leafy Seadragon will write s21 in the Messages window (Emitted and Acquired) when it acquires the signal and you type s21 to emit this whistle. You may wish to classify the copied signal as a LEX_SIGNAL by including this element in it's xml:

<void property="signalType">

<string>LEX_SIGNAL</string>

</void>

You may also wish to edit the frequency values of the whistle to suit your experimental design. The frequency values for rate 40 per second are written in the element with property="hz40ps", and the frequency values for rate 10 per second are in element with property="hz10ps". You can either edit both sets of frequency samples in a consistent manner or delete one set and edit the other set, and Seadragon will calculate the other set if needed. You may also remove the xml tags from the acquired whistle that are not needed for the whistle to be read. These unneeded tags are:

<void property="creationMillis">

<void property="histInitialHzSamplingPerSec">

<void property="histVoltSamplingPerSec">

<void property="score">

7. Files to Document Your Communication Sessions

Leafy Seadragon writes 3 types of xml files that are important to document your communication session, particularily the Session Report file which contain the messages of the session and the Signals files which contain entire signal data sets. These files are written in different folders in folder seadragon2dot1at40fsps\results. For example, Report files are written in folder reports in folder results.

Session Report, Properties, and Signals files can easily be shared with other researchers as they are text files with xml tags. Logs files are not meant to be shared but they also can be.

Properties files are implemented in version 2.1.

8. Files Housekeeping

For some types of files, Leafy Seadragon writes a new file at the end of each session in the corresponding folder, and these must be cleaned up once in a while so that your hard disk does not get full. These files are in the folders in results.

Log files, in folder results\logs, do not need to be cleaned up because Leafy Seadragon does the housekeeping automatically for this type of files. To do this, Leafy Seadragon keeps the total size of all log files to less than a preset value by deleting the older file when the maximum space is reached. You may copy any of these files to another location if you wish to keep any of these log files permanently.

9. Main Features

Double-clickable jar to support Mac OS X v. 10.4.4 or later.

Live spectrogram display - since v. 2.

Live Sound Pressure Level measurement - since v. 2.

Predefined whistles in editable text file (xml) - since 1.0

Session whistles stored in editable Signals text file (xml) - since 1.0

Session Report text file (xml) written during each communication session, contains all messages

Improved displayed whistles names - since 1.0

Single machine (standalone) or multiple machines configurations (only the backbone configuration is supported in the current version)

Standalone configuration successfully tested under Windows XP laptops and desktops (including a laptop with AMD Athlon 64, 512 MB); the current release package is configured for standalone operation (on a single computer).

Entirely written in Java - requires Java SE 5 (which is free from Sun Microsystems for Windows, Unix, and Linux systems and from Apple for Macintosh computers).

Uses common built-in audio interface (e.g., Windows Direct Audio, Microsoft Advance AC97 Audio); normally no need for additional audio hardware.

Input hydrophone in microphone jack, output hydrophone in headphone jack (you purchase your hydrophones from a third party, not from us; we don't sell anything)

Maximum effective whistle frequency: 11 kHz (could be increased with special audio hardware in future version)

Adjustable minimum whistle frequency, e.g., 400 Hz or 1 kHz. Signals at a lower frequency than this are considered noise and filtered out.

48,000 voltage samples per second (fixed in this version)

Choice of two frequency sampling rates: 10 and 40 frequency samples per second (fsps) - new since 1.0. The 10 fsps rate is for slower PCs.

Filters short signals as background noise: less than 2/10 second long (adjustable) - since 1.0 (0.9.5)

Optionally filters whistles that it emitted so that emissions are not echoed in the display window - since 1.0

Extensive auto diagnostics

EMAIL SUPPORT: sergemasse1 a-t yahoo d-o-t com

License: CPL - Common Public License - commercial use is allowed without fee. Soon to be changed to GPL.

10. Resources

Java Runtime Environment for Windows (free): http://java.com/

Java for a Mac: http://www.apple.com/

C2h project for Leafy Seadragon: http://c2h.sourceforge.net/

Whistles creation guide and exchange blog: http://seadragon-whistles.blogspot.com/

A manufacturer of an emitting hydrophone: http://www.aquarianaudio.com/, the H1 model (not free, but not expensive). You can use your favorite hydrophones and projector transducers with Leafy.

See the other links of the right side of this web page.

Mac and the Mac logo are trademarks of Apple Computer, Inc., registered in the U.S. and other countries.

==========
Technorati: whale cetacean dolphin cetaceans whales dolphins
==========
Like this post? _ _ _ _