OpenLogbook - User's Guide

NOTICE: Unfortunately this document is rather old and may contain incorrect information. We do try to update it during summer 2006. However, use it as a reference what has worked in previous versions.

List of Figures

Introduction

OpenLogbook is an application for presenting multi-dimensional data from different kinds of experiments. This application enables a scientist to go through an experiment and review all data related to it, e.g. video streams, audio streams and log files describing e.g. equipment parameters. Parameter logs can be searched through using different search parameters.

An important aspect of the OpenLogbook concept is to ensure that as much data as possible is stored from an experiment, so that the risk of losing important data is minimized. This means that there is no preset model either for how to collect data or for what data to collect. In every experiment the basic idea is the same; gather all possible data and later on, using OpenLogbook to review the experiment, find out if there are parts that can or should be left out. This approach is new because everyone is used to cutting the information to as small as possible. Nowadays mass media is so cheap that keeping more information is not a funding question anymore. OpenLogbook is not itself used to record data. Data can be recorded by whatever means, as long as it is in a format that OpenLogbook can understand.

There are numerous uses for OpenLogbook, and physics experiments is just one of them. Basically it can be used for anything where the ability of reviewing multidimensional data is required. These might include e.g. user centered research (e.g. usability tests), medical operations (surgery etc.), teaching purposes etc.

Licensing issues

OpenLogbook itself is released under BSD-licence(see

). This product includes software developed by the Apache Software Foundation (http://www.apache.org/). The Apache Software License can be found in

Installing and running OpenLogbook

General requirements

Before you can start using OpenLogbook you have to install Java 2 JRE version 1.4 or greater on your machine. If you want to compile the source code version of OpenLogbook you have to install Java 2 SDK. OpenLogbook also uses JMF (Java Media Framework) version 2.1.1 to display multimedia data. These can both be downloaded from
http://java.sun.com/j2se/downloads.html. After installing these OpenLogbook will work without any further installations. OpenLogbook itself doesn't set any other software or hardware requirements. See

for notes about installing JMF in Windows environment.

Following environment variables have to be set:

$JAVA_HOME: This should point to your Java installation directory.
$JMFHOME: This should point to your JMF installation directory.

OpenLogbook sets the correct CLASSPATH itself, so it doesn't need to be set by the user.

Java Media Framework (JMF) requires the following minimum hardware:

200 MHz Pentium, 160 MHz PowerPC, or 166 MHz UltraSparc.
At least 64 MB RAM
Soundcard

Using the binary version

Linux-environment

If you have the binary version of the software, the openlogbook.zip-package contains everything needed to run the software, except tools described in

. First unpack the zip file into a directory you wish the openlogbook to work from, by issuing the command unzip openlogbook.zip. After unpacking the file, you can start the program by running the openlogbook script, openlogbook.sh.

Windows-environment

First unpack the zip file into a directory you wish the openlogbook to work from. You can use e.g. WinZip for doing that. After unpacking the file, you can start the program by running the openlogbook script, openlogbook.bat.

Using the source code version

Linux-environment

Running OpenLogbook on a Linux platform doesn't require any special configuration, just run ``Build.sh run'' in the code-directory.

To make a distribution version of the software, run ``Build.sh dist''. This will create a file called ``openlogbook.zip'', which is similar to the binary version as described in .

Windows-environment

Currently there seems to be some problems with Java version 1.4.1. To be certain that the software works as well as possible, please use Java version 1.4.0.

When installing the JMF its installer prompts you whether you want to install some files to the system directory. Answer ``yes'' to this.

Before starting to compile the program you have to change the accompanying build.xml file, which can be found in the code-directory. In the entry for including jmf libraries you have to change the fileset entry to the following: <fileset dir="${jmf.home}/lib/">. Alternatively, you can just copy everything from $JMFHOME/lib/ext to $JMFHOME/lib/.

To compile and run the software, run ``Build.bat run'' in the code-directory.

To make a distribution version of the software, run ``Build.bat dist''. This will create a file called ``openlogbook.zip'', which is similar to the binary version as described in .

Removing OpenLogbook

All you need to do to remove OpenLogbook is to delete the openlogbook.jar, or in case of the source code distribution, delete the source code tree. Java and JMF are not part of OpenLogbook, so you can keep them if you need them otherwise, or delete them as well.

User Interface

**Figure:** OpenLogbook in action
$\includegraphics[width=0.9\columnwidth]{action.eps}$

Menu bar

All main functions can be controlled through the drop-down menu bar. It contains several different menus, each of which will be further detailed below. Actions' short keys are shown in parentheses after the corresponding action.

File

New Project (CTRL-N): This action creates a new project by initialising required components.
Open Project (CTRL-O): This action lets the user open an existing project. A new window will be opened with which the user can either browse files or give the file's name directly.
Close Project (CTRL-W): This actions closes the currently open project.
Save (CTRL-S): This action saves an experiment that the user has already saved.
Save As: This action saves an experiment by first prompting the user for a file name to use.
Exit: This action exits the program, first querying the user whether he/she wants to save the project data before exiting.

**Figure:** File menu
$\includegraphics[width=0.3\columnwidth]{filemenu.eps}$

Edit

Undo (CTRL-Z): This action undos the last text editing action that you have committed.
Redo (CTRL-Y): This action redos the last undo action that you have committed.
Cut (CTRL-X): This action cuts the selected area of text and deletes it.
Copy (CTRL-C): This action copies the selected area without deleting it.
Paste (CTRL-V): This action pastes the current text on the clipboard.
Preferences: Shows preference dialog for the program. Not implemented yet.

**Figure:** Edit menu
$\includegraphics[width=0.3\columnwidth]{editmenu.eps}$

Project

Hotspots (CTRL-H): This action opens the hot spot manager window. See section for more information on this feature.
Main controller (CTRL-M): This action opens the main controller. See section for more information on this feature.
Synchronize (CTRL-E)
Text logger (CTRL-T): This action opens the text logger. See section for more information on this feature.
Add files... (CTRL-F): This action allows you to add files to the current project.
Remove files... (CTRL-R): This action allows you to remove files from the current project.
Show/hide files: This action allows you to display files in the main window, or remove them from it. Removing a window with this action doesn't remove it from the project, but just from the main window.
Project properties (CTRL-P): This opens the project properties window. See for more information.

**Figure:** Project menu
$\includegraphics[width=0.5\columnwidth]{projectmenu.eps}$

Windows

Cascade: Sorts subwindows inside the OpenLogbook main window.

**Figure:** Windows menu
$\includegraphics[width=0.15\columnwidth]{windowsmenu.eps}$

Help

About OpenLogbook: This action displays some general information about the OpenLogbook program.

**Figure:** Help menu
$\includegraphics[width=0.3\columnwidth]{helpmenu.eps}$

Main window

All windows are opened into the main window area. Each window can be individually moved, resized, minimized and maximized. There are three buttons in the upper right corner of a window. The leftmost minimizes the window. The window will appear as a small box in the bottom left corner of the main window. Clicking on that window displays the window again. The middle button maximizes the window. The window will resize itself to cover the whole main window. This can be useful if e.g. some specific part of an image is carefully observed on a small screen. The rightmost button closes the window. It disappears from the main window. If you want to open it again in the main window, you have to choose ``Show/hide files'' from the Project-menu and then choose the corresponding file from the submenu which opens.

There can also be buttons in the lower right corner of media file windows in case of video and audio files. Both video and audio files have a button in the utmost right which looks like a ladder. When pressed, this button displays information about the file, which is partly media type dependent. If the file is an audio file there is also a button which displays a loudspeaker. Clicking this button will mute the audio file.

Project properties

Project properties window can be opened by choosing ``Project properties'' from the Project-menu. This opens a window which displays different properties of the project, e.g. the author and description of the project, media files and wrapper files (see

for more information on these).

**Figure:** Properties dialog
$\includegraphics[width=0.8\columnwidth]{props.eps}$

Handling project data

Loading a project

A project can be loaded by choosing ``Open project'' from the File-menu (or by pressing CTRL-O). This will open a file dialog from which you can choose the project xml file.

Saving a project

If you haven't saved your project previously, you have to choose ``Save As'' from the File-menu (or press CTRL-SHIFT-S) to save your project. If you have an already saved project, you can either choose ``Save'' (or press CTRL-S) to save it using the same name, or ``Save As'' to save the project using a new name.

Adding files

Files can be added to the project by choosing ``Add files...'' from the Project-menu. This action opens a window where you can choose the file you wish to add. You also have to choose the proper file type for the software to be able to handle the file. Each media file is opened into its own window, which is placed in the main window.

Removing files

Files can be removed from the project by choosing ``Remove files...'' from the Project-menu. This action opens a new window with media and wrapper files visible. This can be delected by selecting a file and then pressing the ``Delete selected file'' button. You can also remove files from the project properties window, which can be opened by choosing ``Project properties'' from the Project-menu. The interface is similar to the previous method.

Recording an experiment

OpenLogbook is not used to record the whole experiment. It's main purpose in the recording of an experiment is to provide the capability of recording hot spots (see section

) and text comments (see section

) throughout the experiment. Actual video, audio, and parameter data have to be recorded through other means. OpenLogbook will also be used to provide the reference time frame for later handling of experiment data. This means that when starting an experiment, the OpenLogbook is used to record the experiment time. Hot spots and text comments are synchronized to this time. This base time can change after the recording has been made, if files that are longer than the base time are added to the experiment. See section

for more information on this.

The basic procedure when beginning to record a new experiment is to choose ``New Project'' from the File-menu (or press CTRL-N). This opens a dialog where you can give your project an author and a description (see figure ). After you have filled this information in, press OK. The main controller will be opened automatically in the main window. Before you start recording, you should also open the Hotspot Manager and Text logger so that they are ready when you begin the actual recording. A basic setup for recording can be seen in figure . When you want to begin recording, simply press the ``Record''-button in the main slider. When you are finished, press ``Stop'' to stop recording. See sections and for more information on how to record hot spots and text comments.

**Figure:** New project dialog
$\includegraphics[width=0.9\columnwidth]{new_project.eps}$

**Figure:** Basic recording setup
$\includegraphics[width=0.9\columnwidth]{record_view.eps}$

Reviewing the project

When you have recorded an experiment, and added the relevant media files, you can ``review'' your project by playing it. The most convenient way is to open all media files, log files etc. and use the main controller to ``play'' the project (see figure

). For more information on the main controller, see

. You can use the main controller to start playing all media files simultaneously. If you want to play just one media file independently of the others, you can use its own individual controllers, which are displayed in its own window. After you have played an individual file, it will be out of synchronization. It can be resynchronized with the main controller by just clicking the ``play'' button from the main controller.

Using the Main Controller

Main controller is used to control the experiment time. When creating a new project, the main controller displays two control buttons, ``Record'' and ``Stop''. These are used to record the experiment. When an experiment has been recorded, the main controller will display three control buttons, ``Play'', ``Pause'', and ``Stop''.

The main controller shows the current position and the total length of the project in the slider. You can change the unit of time by choosing the desired unit using the drop-down menu on the right.

**Figure:** Main controller
$\includegraphics[width=0.7\columnwidth]{main_controller.eps}$

Using the Hotspot Manager

Hot spot manager lets you to easily record hot spots. You can also use this manager to add, remove and modify hot spots after the recording has been done. The Hot Spot Manager shows all existing hot spots, with the time of recording on the left column and comments on the right column. Hot spots are automatically ordered by their time of recording.

**Figure:** Hot spot manager
$\includegraphics[width=0.9\columnwidth]{hotspots.eps}$

Recording hot spots

When recording an experiment, clicking ``New hotspot'' opens a new dialog for a hot spot. The moment you press the button sets the time for the hot spot. You can then either add a comment for the hot spot and press ``Enter'' to save the hot spot, or you can just leave the dialog open and add comments later on. Pressing ``Cancel'' closes the dialog and cancels the addition of the hot spot. Note that after entering the hot spot, it can still be modified afterwards. There's no limit on how many hot spot dialogs you can have open simultaneously.

Modifying hot spots

After a hot spot has been created it can easily be modified using the same Hot Spot Manager.

To adjust the hot spot's recording time, double click on the appropriate hot spot's left column, which is showing the time. Then just enter a new value. The hot spot will automatically move to it's proper place in the list, which is sorted by time.

To modify the comments, click on the appropriate hot spot's right column, which is showing its comments. Then you can modify the comments.

To delete a hot spot, first choose it by clicking on the time field of the hot spot and then press ``Delete selected hotspot(s)''. If you want, you can choose several hot spots at the same time by dragging the mouse pointer over several hot spots.

You can change the unit of time by pressing the button with a drop-down menu on the right.

Using the Text logger

When recording an experiment you might want to add some comments, which are not neccessarily related to hot spots. The Text logger lets you do that. It consists of two parts, the bottom row is for inserting a comment. The larger text area above shows all comments which have been recorded. These are sorted by time. When recording an experiment, you can add a new comment by simply clicking on the bottom row, and then inserting your comment. After you're finished writing the comment, just press enter to save it. When you're finished recording comments, you can save the comment log by pressing ``Save''.

The log comments are saved into a separate file. When creating a new logger from the Project menu, the filename is prompted. Later the log file is automatically saved and loaded with the rest of the project.

**Figure:** Text logger
$\includegraphics[width=0.7\columnwidth]{logger.eps}$

Displaying parameter log files

You can view all parameters by adding a log file (see section

) to your project. This opens a new window with all parameters visible as a table. There are two possible views to the parameter data.

When showing all parameters as a table, time is displayed in the first column, and each parameter in their own columns after that (see figure ). You can change the position of the columns by clicking on them and dragging them to their new place. When you're ``playing'' your project, the row to show the current time gets automatically selected in the parameter log.

When viewing parameter values corresponding to the current time (see figure ), all parameters are shown as a simple name-value list. When ``playing'' the project, these values are updated as time advances.

You can change the unit of time by choosing the desired unit using the drop-down menu on the right.

**Figure:** Parameter log view 1
$\includegraphics[width=0.7\columnwidth]{gundata1.eps}$

**Figure:** Parameter log view 2
$\includegraphics[width=0.7\columnwidth]{gundata2.eps}$

Using Parameter Search

With parameter search you can efficiently search parameter log files using different parameter values. First choose the file you wish to be searched. Then you can choose the attribute that you wish to focus the search on, using the drop-down menu on the left. Then you can choose the comparator to use, and give the treshold value. You can also chain commands using ``AND'', ``OR'', and ``NOT'' operators. Following comparators can be used:

< (Smaller-than)
= (Equals)
> (Larger-than)
>= (Larger-or-equal)
!= (Is-not)
<= (Smaller-or-equal)
contains (Contains)

**Figure:** Parameter search
$\includegraphics[width=0.9\columnwidth]{search.eps}$

Displaying search results

When applying a search on a file, those entries that fulfill the search parameters are displayed in a new window. This window is similar to the one that is used to show parameter logs, but this window only contains specific entries from the search. This means that you can view the search results as you can view normal parameter logs as explained in

Synchronizing data

Each data can be individually synchronized to the project base time using the synchronization tool. This can be opened by choosing ``Synchronize'' from the Project-menu. This opens a window which shows the synchronization data of all files. The filename and offset are shown for each data file. Initially each data file has no offset at all(offset set to 0 seconds). This can be adjusted for each data file using its slider on the right. The offset describes the relation between the start of the base time and the start of the data file. E.g. if the offset is set to -10, it means that when playing starts, the data file starts from 10 seconds further, i.e. its starting point is moved ten seconds back in time (which takes it to -10 seconds related to the base time starting point).

You can change the unit of time by choosing the desired unit using the drop-down menu on the bottom.

**Figure:** Synchronizer
$\includegraphics[width=0.9\columnwidth]{synchronise.eps}$

What are wrappers?

Wrappers are a sort of an interface to different types of parameter data. Wrappers handle the conversion of these different types of parameter data into a format that OpenLogbook can understand. One example of a parameter file type is the Comma Separated Values (CSV) file. Each type of parameter file requires its own wrapper. At the moment OpenLogbook only supports CSV files. List of wrappers and the file types they support can be found in

Bugs and suggestions

Known bugs and suggestions for future functionality can be found in [3].

Bug reporting

If you discover a bug in the software please report this bug to our development team. We will try to fix bugs as quickly as possible. You can submit a bug to our email address openlogbook-dev@motha.tky.hut.fi. Please include a description of the problem and the hardware and software environment in which it occurred.

Bibliography

1

Homepages of the project course
http://www.soberit.hut.fi/T-76.115/

2

OpenLogbook project webpages for the course T-76.115
http://motha.tky.hut.fi/openlogbook/

3

Status Report http://motha.tky.hut.fi/openlogbook/delivery/status_report.pdf

Appendices

List of shortcuts

Table: Shortcuts

Shortcut	Explanation
CTRL-F	Add files
CTRL-C	Copy text
CTRL-X	Cut text
CTRL-H	Hotspots
CTRL-M	Main controller
CTRL-N	New project
CTRL-O	Open project
CTRL-V	Paste text
CTRL-P	Project properties
CTRL-Y	Redo edit
CTRL-R	Remove files
CTRL-S	Save
CTRL-SHIFT-S	Save As
CTRL-T	Text logger
CTRL-Z	Undo edit
CTRL-E	Synchronize
CTRL-W	Close project

List of supported parameter file types

Comma Separated Values (CSV)

List of supported media file types

AIFF (.aiff)
AVI (.avi)
GSM (.gsm)
HotMedia (.mvr)
MIDI (.mid)
MPEG-1 Video (.mpg)
MPEG Layer II Audio (.mp2)
MPEG Layer III Audio (.mp3)
QuickTime (.mov)
Sun Audio (.au)
Wave (.wav)

BSD-license

Taken from http://www.debian.org/misc/bsd.license

Copyright (c) 2002 Helsinki Institute of Physics (http://www.hip.fi)
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Apache Software License

Taken from http://jakarta.apache.org/log4j/LICENSE.txt

============================================================================
                  The Apache Software License, Version 1.1
============================================================================

   Copyright (C) 1999 The Apache Software Foundation. All rights reserved.
 
Redistribution and use in source and binary forms, with or without modifica-
tion, are permitted provided that the following conditions are met:
 
1. Redistributions of  source code must  retain the above copyright  notice,
   this list of conditions and the following disclaimer.
 
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
 
3. The end-user documentation included with the redistribution, if any, must
   include  the following  acknowledgment:  "This product includes  software
   developed  by the  Apache Software Foundation  (http://www.apache.org/)."
   Alternately, this  acknowledgment may  appear in the software itself,  if
   and wherever such third-party acknowledgments normally appear.
 
4. The names "log4j" and  "Apache Software Foundation"  must not be used to
   endorse  or promote  products derived  from this  software without  prior
   written permission. For written permission, please contact
   apache@apache.org.
 
5. Products  derived from this software may not  be called "Apache", nor may
   "Apache" appear  in their name,  without prior written permission  of the
   Apache Software Foundation.
 
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
(INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
This software  consists of voluntary contributions made  by many individuals
on  behalf of the Apache Software  Foundation.  For more  information on the 
Apache Software Foundation, please see <http://www.apache.org/>.

OpenLogbook for users

OpenLogbook - User's Guide

General requirements

Using the binary version

Windows-environment

Menu bar

Project properties

Loading a project

Saving a project

Adding files

Removing files

Recording an experiment

Reviewing the project

Using the Main Controller

Using the Hotspot Manager

Using the Text logger

Displaying parameter log files

What are wrappers?

List of supported parameter file types

List of supported media file types

BSD-license

Apache Software License