Skip to content

Improve/simplify README.md #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cbrnr merged 6 commits into from
Mar 20, 2026
Merged

Improve/simplify README.md #52

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3567c2a
Improve/simplify README.md
cbrnr Mar 20, 2026
ffe37e3
More tweaks
cbrnr Mar 20, 2026
54d6279
More tweaks
cbrnr Mar 20, 2026
8c12f56
Fix Markdown
cbrnr Mar 20, 2026
3b52ee3
Shorten
cbrnr Mar 20, 2026
d93bf7f
Final tweaks
cbrnr Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 43 additions & 100 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,100 +1,58 @@
# Libxdf – a C++ library for loading [XDF](https://github.com/sccn/xdf/wiki/Specifications "Extensible Data Format") files
# LibXDF – a C++ library for loading XDF files

[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active)
[![License](https://img.shields.io/github/license/xdf-modules/libxdf)](https://opensource.org/licenses/BSD-2-Clause)
LibXDF is a cross-platform C++ library for loading multimodal signals stored in [XDF](https://github.com/sccn/xdf/wiki/Specifications "Extensible Data Format") files.
It is used in the biosignal viewing application [SigViewer](https://github.com/cbrnr/sigviewer) and the LSL application [XDFStreamer](https://github.com/labstreaminglayer/App-XDFStreamer/) and can also be integrated into other C++ applications.

* [Introduction](#intro)
* [Quick-Start Guide](#quick)
* [Download](#download)
* [Documentation](#doc)
* [Reference](#reference)
* [Support](#support)

## Quick start

## <a name="intro"></a>Introduction
The source code and prebuilt binaries are available as [releases](https://github.com/Yida-Lin/libxdf/releases) (you may need to expand the list of assets to find the downloads).

Libxdf is a cross-platform C++ library for loading multimodal, multi-rate signals stored in [XDF](https://github.com/sccn/xdf/wiki/Specifications "Extensible Data Format") files.
Libxdf is used in the biosignal viewing application [SigViewer](https://github.com/cbrnr/sigviewer) and the LSL application [XDFStreamer](https://github.com/labstreaminglayer/App-XDFStreamer/). It can also be integrated into other C++ applications.

Libxdf is open-source, free, and actively maintained.

## <a name="quick"></a>Quick-Start Guide

### <a name="download"></a>Download

* Find Source and Prebuilt Binaries on the [releases page](https://github.com/Yida-Lin/libxdf/releases).
* You may need to expand the list of Assets to find the downloads.
* For Linux Debian (Ubuntu) users: `sudo dpkg -i libxdf-{version}-Linux.deb`
* For Windows and Mac users: simply extract the archive somewhere convenient.

### Building libxdf

If the release does not have assets for your platform or they do not work for you for some other reason, then
Libxdf can be conveniently built either using `qmake` or `cmake`. Configuration files for both build tools are included with the source.

To build with cmake from command prompt / terminal:
If a particular release does not have assets for your platform or they do not work for you for some other reason, then
libXDF can be built with [CMake](https://cmake.org) using the following two commands:

```sh
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=${PWD}/build/install
cmake --build build --config Release -j --target install
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=${PWD}/build/install -DCMAKE_BUILD_TYPE=Release
cmake --build build -j --target install
```

`cmake` builds a static library by default, but you can build a shared library
by setting the
[`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html)
variable (e.g. add `-DBUILD_SHARED_LIBS=ON` to the first cmake command above).
This builds and installs a static library in `./build/install`, but you can build a shared library by adding `-DBUILD_SHARED_LIBS=ON` to the first CMake command.

### Use in conjunction with [SigViewer](https://github.com/cbrnr/sigviewer)

Libxdf is a built-in component of [SigViewer](https://github.com/cbrnr/sigviewer). If you wish to build SigViewer from source, follow these steps:
## Integrating into C++ applications

1. Download `xdf.h` and `libxdf.a` from the [release](https://github.com/Yida-Lin/libxdf/releases) page.
2. Copy `xdf.h` into `sigviewer/external/include`
3. Copy `libxdf.a` into `sigviewer/external/lib`
4. Build and run Sigviewer
If you want to use libXDF in C++ applications, follow these steps:

1. Install a prebuilt binary release or build libXDF from source as described above.
2. If you use CMake, add the following lines to your `CMakeLists.txt` to find and link against libXDF:

![SigViewer using _libxdf_ to display signals in XDF files](docs/Example.png)
```CMake
find_package(libxdf REQUIRED
HINTS ${XDF_INSTALL_ROOT}
PATH_SUFFIXES share
)
target_link_libraries(${PROJECT_NAME}
PRIVATE
# ... other dependencies
XDF::xdf
)
```

Example: SigViewer using _libxdf_ to display signals in an XDF file.
If `libxdf` is not in a standard system library location, pass `-DXDF_INSTALL_ROOT=path/to/libxdf` to specify its path.
3. In your source code, `#include "xdf.h"`, instantiate an object of the `Xdf` class, and call the `load_xdf` method.

### Use in other C++ applications
For example:

1. Install a prebuilt binary release or build from source as above.
2. For CMake users:
* In your project's CMakeLists.txt, use the following snippet:
```CMake
find_package(libxdf REQUIRED
HINTS ${XDF_INSTALL_ROOT}
PATH_SUFFIXES share
)
target_link_libraries(${PROJECT_NAME}
PRIVATE
# ... other dependencies
XDF::xdf
)
```
* If the libxdf package was installed or extracted into a folder other than a standard system library folder, you will have to pass a cmake command line argument to indicate where to find it: `-DXDF_INSTALL_ROOT=path/to/libxdf`
3. In your source code, `#include "xdf.h"`, instantiate an object of the `Xdf` class and call the `load_xdf` method.
```C++
#include "xdf.h"

Example:
Xdf XDFdata;
XDFdata.load_xdf("example.xdf");
```

```C++
#include "xdf.h"
Functions must be called in a specific order. For example, calling `subtractMean` before loading data leads to undefined behavior.

Xdf XDFdata;
XDFdata.load_xdf("C:/example.xdf");
```

To resample the signals to e.g. 100Hz:

```C++
XDFdata.resample(100);
```

The functions in libxdf must be called following a certain order. For instance, if you call the `subtractMean` function before you load any data, it will cause undefined behavior.

The recommended order is shown here. Only `load_xdf` is mandatory.
The recommended order is shown below:

```C++
XDFdata.load_xdf(std::string filepath);
Expand All @@ -104,31 +62,16 @@ XDFdata.resample(int sampleRate);
XDFdata.freeUpTimeStamps();
```

Libxdf depends on third party libraries [Pugixml v1.8](http://pugixml.org/) for XML parsing and [Smarc](http://audio-smarc.sourceforge.net/) for resampling.

## <a name="doc"></a> Documentation
Detailed documentation was generated via [Doxygen](http://www.stack.nl/~dimitri/doxygen/index.html) and is available [here](docs/html/class_xdf.html).
## Documentation

## <a name="SigViewer"></a> SigViewer Online Repo
SigViewer Online Repository is [here](repository/Updates.xml).
Detailed documentation is available [here](docs/html/class_xdf.html).

## <a name="reference"></a> Reference
If you use this code in your project, please cite:
```
Yida Lin, Clemens Brunner, Paul Sajda and Josef Faller. SigViewer: Visualizing Multimodal Signals Stored in XDF (Extensible Data Format) Files. The 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society.
```
Direct link: https://arxiv.org/abs/1708.06333

Bibtex format:
```
@article{lin2017sigviewer,
title={SigViewer: visualizing multimodal signals stored in XDF (Extensible Data Format) files},
author={Lin, Yida and Brunner, Clemens and Sajda, Paul and Faller, Josef},
journal={arXiv},
pages={arXiv--1708},
year={2017}
}
```
## References

If you use libXDF in your project, please consider citing the following [conference paper](https://arxiv.org/abs/1708.06333):

> Yida Lin, Clemens Brunner, Paul Sajda and Josef Faller. *SigViewer: Visualizing Multimodal Signals Stored in XDF (Extensible Data Format) Files.* The 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society.

## <a name="support"></a>Support
[Email author](mailto:yida.lin@outlook.com) or report a new [issue](https://github.com/Yida-Lin/libxdf/issues).
LibXDF depends on third party libraries [pugixml](http://pugixml.org/) for XML parsing and [Smarc](http://audio-smarc.sourceforge.net/) for resampling.