leafy seadragon

2006/08/27

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? _ _ _ _

Labels: bioacoustics, cetacean, dolphins, open source, whales

2006/08/23

Seadragon Technical Description

Here is a summary of the process flow from cetacean sound to human interface, the c-to-h flow (c2h), and some references to the h-to-c flow (h2c).

c = cetacean (e.g., dolphin)
h = human

The Nodes:

There are 3 major nodes in the backbone: c, c2h, and h. Each backbone node can be deployed on a single host, and a pair or all three nodes of the backbone can also be deployed on a single machine (i.e., a PC, as in the configuration which is packaged in Version 2.1). The nodes exchange data using text (UTF8) containing xml tags.

There are nodes for other components than the backbone but these are not detailed here, except to mention that some of these are for supporting a peer-to-peer network (p2p) for human users, connecting a large number of people to a single backbone, which connects to one or many cetaceans.

When the backbone nodes are deployed on different hosts, then the data exchange takes place over TCP/IP sockets, and when two nodes are on the same host then the data exchange takes place within Java objects and between different threads, not involving sockets.

The 3 backbone nodes design, chosen a few years ago, allows us, for example, to have an underwater system composed of two hosts, one for the handheld human interface (hosting the h node) and the other device hosting the c2h node and the c node. Such a system is feasible with off-the-shelf parts today (or shortly, with some testing and debugging). The Seadragon software is configured to run on multiple hosts by using properties in files that it reads at startup. For the proposed underwater system, the same software would be used for an h node on its own host and for the c and c2h nodes on another host, these two installations just use different properties at startup. This feature, among others, is given by the generic Leafy API.

The Data Flows:

The c2h flow between backbone nodes is: c to c2h to h (these are nodes inside the application).

The h2c flow is: h to c2h to c.

The flow between backbone nodes is the same whether the nodes are hosted on different hosts or on the same host. Seadragon also supports other nodes than backbone nodes and these are for peer-to-peer networks, including end points which are cell phones.

Back to the data fow: The c node is in charge of the cetacean interface: it emits underwater sounds to cetaceans and it acquires underwater sounds. In the h2c flow, it receives data from the c2h node (in text form), then converts it to voltage levels representation (numbers) and then to actual voltage (analog) and these voltage levels go to a hydrophone (e.g., a piezo-electric cristal) that converts the voltages to vibrations (sound).

The c-to-h Flow:

In the c2h flow, the c node acquires sounds as voltage levels (numbers), using FFT, it converts 1024 voltage numbers to a single frequency value (Hz or cycles per second) and sends the data (a single frequency value) to the c2h node for processing, i.e., for the attempt at recognition.

The c2h flow summary: sound --> hydrophone (part of a c node) --> voltage --> analog-to-digital --> voltage levels --> FFT --> frequency value --> send text (single frequency value) --> c2h node: assembly of frequency values into a series (i.e., a whistle) --> pattern matching --> signal object in lexicon (new or old) --> send text --> h node: writing the text to the human user in the msg window.

The h-to-c Flow:

The other data flow is h-to-c, human to cetacean (h2c), and it is similar to the reverse of the c2h flow but does not involve frequency pattern matching because the human user can only emit a whistle which is already present in the lexicon and the human user has to use the unique text name of the whistle. One could say that there is the simpler text name matching in this flow, but no frequency matching.

Whistle Recognition: Pattern Matching

The most complex part of the whole thing is the assembly of frequency values into a series (i.e., a complete whistle) in the c2h flow. This involves, for example, the recognition of the start and the end of a whistle and the completion of the data in between, prior to comparing it with signals in the lexicon (in memory). This process must be extremely efficient and it took me many months to fine tune because the quantity of this data in real time is huge (10 or 40 per second now) and I would like to process even more, ideally maybe 100 frequency values per second.

Pattern matching is performed in the c2h node. Once an incoming whistle's start and end have been determined (not trivial), then the frequencies of the incoming whistle are compared with the frequencies of the signals present in the lexicon. A score is calculated for each comparisons. If the score is outside the acceptable limit than this match is abandoned and the incoming whistle is compared with another whistle in the lexicon. After this process, a best match is obtained or no match. If we have a match, then the name of the whistle from the lexicon is sent to the h node. If no match, then the incoming whistle is given a unique name (by the system), the whistle is added to the lexicon, and the name is sent to the h node.

2006/08/19

Chat with Dolphins on your Mac

Seadragon2dot1 is out.

Double-click on the jar file to launch the application.

Works on a Mac with Java 5 (free download from Apple). Requires Mac OS X v. 10.4.4 or later.

(Also works with Windows with Java 5 from http://java.com/)

Downloads:

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 http://sourceforge.net/projects/c2h/

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

Testing:

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

I connect a headphones and a microphone in the RCA jacks of the machine. I do not wear the headphones. I position the microphone near the headphones.

In order to make 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 (i.e., 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 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 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 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.

2006/08/12

Seadragon on the Mac

For Seadragon on Windows, please go to the post titled Seadragon 2 - User Guide below.

I recently worked on the issue of Seadragon on a Mac and here's what I have for now:

1. As of today, Macs don't come with Java 5 (aka. 1.5.0, 1.5, and 5.0) out of the box, contrary to what I may have written recently, but one can get Java 5 from Apple for free. Details in item 4 below.

2. The current version of Seadragon, version 2, requires some techie adaptation in order to package it on a Mac. The best tool for this is probably Xcode, free from Apple. The current version of Seadragon does not need to be recompiled, just packaged for the Mac, but it would be hard for a non-developer to do. The simpler Jar Bundler tool from Apple may also be used for packaging Seadragon 2. Alternatively, a developer experienced on Unix could just modify the run.bat file to make a shell executable (e.g., replace the ;'s by :'s and do chmod -x) and then run the application from a command line window. A user had done this about 2 years ago on his Mac with Seadragon 1.

3. I am starting work on a version of Seadragon that will be launched on a Mac simply by double-clicking the jar file, but it may not be ready for another week or two. With this future version, the users will unzip the download file (I think their Safari browser does the unzipping) and then they would double-click the jar file, that's it. The icon of the jar file would not be customized but it should work.

4. Java 5 for Seadragon on a Mac:

The Mac must have MacOS X v.10.4 (or later). Users need to upgrade their OS from Apple if they have an older version of MacOS.

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 tool containg their Java 5 virtual machine (VM).

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.

So until the double-clickable jar is available, one may have some work to do to prepare one's Mac.

Technorati: whale cetacean dolphin
cetaceans whales dolphins
Mac
Apple Computer
MacOS X
Macintosh Computer

2006/01/11

Seadragon 2 - User Guide

1. Introduction

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

This open source software is designed to support 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 Seadragon and experiment with listening to and emitting underwater whistles with dolphins, all you need to do is:

Download and install Seadragon (see Section 2 below). Most current laptops are adequate.
Design your own whistles (Section 3) and try them in air by using headphones and microphone.

Do not wear the headphones for these tests.
Samples whistles are included.

Use your whistles at sea with dolphins.

Replace the headphones and microphone with 2 transducers (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 2.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 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 2.5 will help).
When you close the application, the acquired signals are written in a text file (xml) and you can use these in subsequent sessions (Section 4). All emissions and acquisitions are also written in a session report file (Section 5).

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

2. Install and Run

2.1. Install

Summary: install Seadragon, install Java, and run one of the batch files (under Windows) in seadragon2\run\standalone.

Details:

To install Seadragon, download and unzip file seadragon2_build_20060401a.zip from http://c2h.sourceforge.net/ (follow the *Downloads* links).

Seadragon requires that you have previously installed Java 5 on your computer.

To install Java 5, also called Java SE 5 runtime environment (and also called JRE 1.5, for historical reasons), 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 JRE for Solaris or Linux, go to http://java.sun.com/.

As of April 2006, Mac users still needed to consult Apple for upgrading their system to Java 5. As of approximately June 2006, Java 5 is the default version in MacOS X 10.4 but Java 5 still needs to be installed by the user because Java 5 is not in Macintoshes out of the box. The installation of Java 5 and Seadragon 2 on a Mac may require some help from Apple tech support. Once Java 5 is installed, the user can unzip the Seadragon 2 download file from c2h and modify the run.bat file to launch the application (replace ; by : and set it to be executable).

2.2. To run Seadragon under Windows:

Use either file run10.bat or file run40.bat from folder seadragon2\run\standalone.

File run10.bat is for using a frequency sampling rate of 10 frequency samples per second and file run40.bat is for using 40 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.

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 Seadragon. You may also set the -Xmx and -Xms switches in the java command line in the batch file to approx. 80% of your RAM for optimized performance.

Once you have installed Java 5, then execute one of these two batch files, for example, by double clicking on the file icon.

If you are running at 10 frequency samples per second and would like to run at 40 frequency samples per second, or vice versa, then you must stop the application and re-launch it with the other batch file.

For the Macintosh, Solaris, and Linux, the runXX.bat files can be edited by changing the "\" slashes and ";" characters to their Apple (and Uni*) equivalent, "/" and ":".

2.3. Sound Pressure Level (SPL)

Attention: 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.

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.

The Spectrogram & SPL Display:

Seadragon now supports the monitoring of sound pressure levels (SPL). This function must be calibrated by the user (human). See SPL Calibration below.

To see the Spectrogram and SPL Measurements:

select the Controls tab,
select the 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.

2.4. 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 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 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, Seadragon filters itself and does not display the signals that it emits.

2.5. The syntax of signal names used in the msg window:

((( s2 ))) = 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.

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

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

3. Define a New Whistle - Manually

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: seadragon2\run\standalone\lib\signals\signals_to_read.xml.

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

<object class="org.leafyseadragon.j2se.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.

4. Use a Whistle Previously Acquired By Seadragon

You can easily use a whistle that was acquired by 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, 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 seadragon2\run\standalone\results\signals and the 1118369700921 number is a 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 seadragon2\run\standalone\lib\signals\signals_to_read.xml. So essentially you copy a whistle from the signal_saved file to the signals_to_read 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.j2se.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 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>

<void property="creationMillis">
<void property="histInitialHzSamplingPerSec">
<void property="histVoltSamplingPerSec">
<void property="score">

5. Files to Document Your Communication Sessions

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 seadragon2\run\standalone\results. For example, Report files are written in folder reports in folder seadragon2\run\standalone\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 not fully implemented in the current version of the software.

6. Files Housekeeping

For some types of files, 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 seadragon2\run\standalone\results.

Log files, in folder results\logs, do not need to be cleaned up because Seadragon does the housekeeping automatically for this type of files. To do this, 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.

7. Main Features:

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). Java SE 5 Runtime Environment (JRE) for Windows can be installed from http://java.com.
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 dot com
Apple Macintosh: This version probably works with Apple's current release of its Java Runtime and that requires Mac OS X 10.4. Seadragon has not been tested with it yet. The Seadragon runtime package may need to be adapted to fit in Apple's system.
License: CPL - Common Public License - commercial use is allowed without fee.

8. Resources

An excellent forum on bioacoustics can be joined using the instructions from http://cetus.pmel.noaa.gov/AB/ABbioList.html

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

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

A manufacturer of an emitting hydrophone, the H1 model (not free, but not expensive): http://www.aquarianaudio.com/

The links of the right side of this web page.

Technorati: whale cetacean dolphin
cetaceans whales dolphins

2006/01/09

Dolphin diary

Dolphin diary - The interaction of an Australian with wild dolphins.

ORCINUS ORCA COLLECTIVE

ORCINUS ORCA COLLECTIVE A blog mostly on North American West Coast Orcas.