From 3567c2a4fc28aa0b742dcec675d983068f81a37e Mon Sep 17 00:00:00 2001 From: Clemens Brunner Date: Fri, 20 Mar 2026 11:57:22 +0100 Subject: [PATCH 1/6] Improve/simplify README.md --- README.md | 123 +++++++++++++++--------------------------------------- 1 file changed, 33 insertions(+), 90 deletions(-) diff --git a/README.md b/README.md index 084c114..695acef 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,31 @@ -# 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) +## Introduction -* [Introduction](#intro) -* [Quick-Start Guide](#quick) - * [Download](#download) -* [Documentation](#doc) -* [Reference](#reference) -* [Support](#support) +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. +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. -## Introduction +## Quick-Start Guide -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. +The source code and prebuilt binaries are available on the [releases page](https://github.com/Yida-Lin/libxdf/releases) (you may need to expand the list of assets to find the downloads). -Libxdf is open-source, free, and actively maintained. +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: -## Quick-Start Guide +1. Configure: `cmake -S . -B build -DCMAKE_INSTALL_PREFIX=${PWD}/build/install -DCMAKE_BUILD_TYPE=Release` +2. Build and install into `./build/install`: `cmake --build build -j --target install` -### Download +This builds a static library in `./build/install`, but you can build a shared library by adding `-DBUILD_SHARED_LIBS=ON` to the first CMake command above. -* 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 +## Using libXDF in C++ applications -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. +If you want to use libXDF in C++ applications, follow these steps: -To build with cmake from command prompt / terminal: +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: -```sh -cmake -S . -B build -DCMAKE_INSTALL_PREFIX=${PWD}/build/install -cmake --build build --config Release -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). - -### 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: - -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 - - -![SigViewer using _libxdf_ to display signals in XDF files](docs/Example.png) - -Example: SigViewer using _libxdf_ to display signals in an XDF file. - -### Use in other C++ applications - -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} @@ -74,27 +37,22 @@ Example: SigViewer using _libxdf_ to display signals in an XDF file. 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. -Example: + If `libxdf` was installed or extracted into a folder other than a standard system library folder, you will have to pass `-DXDF_INSTALL_ROOT=path/to/libxdf` to indicate where to find it. +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" + For example: -Xdf XDFdata; -XDFdata.load_xdf("C:/example.xdf"); -``` + ```C++ + #include "xdf.h" -To resample the signals to e.g. 100Hz: + Xdf XDFdata; + XDFdata.load_xdf("C:/example.xdf"); + ``` -```C++ -XDFdata.resample(100); -``` +Functions in libXDF must be called following a certain order. For instance, calling the `subtractMean` function before loading any data will result in undefined behavior. -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 here: ```C++ XDFdata.load_xdf(std::string filepath); @@ -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. -## 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 -## SigViewer Online Repo -SigViewer Online Repository is [here](repository/Updates.xml). +Detailed documentation is available [here](docs/html/class_xdf.html). -## 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 this code 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. -## 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. From ffe37e31781f5486512c2fc8421974a927682e08 Mon Sep 17 00:00:00 2001 From: Clemens Brunner Date: Fri, 20 Mar 2026 11:59:49 +0100 Subject: [PATCH 2/6] More tweaks --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 695acef..727cfb3 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ # LibXDF – a C++ library for loading XDF files -## Introduction - 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. 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. -## Quick-Start Guide +## Quick start The source code and prebuilt binaries are available on the [releases page](https://github.com/Yida-Lin/libxdf/releases) (you may need to expand the list of assets to find the downloads). @@ -19,7 +17,7 @@ libXDF can be built with [CMake](https://cmake.org) using the following two comm This builds a static library in `./build/install`, but you can build a shared library by adding `-DBUILD_SHARED_LIBS=ON` to the first CMake command above. -## Using libXDF in C++ applications +## Integrating into C++ applications If you want to use libXDF in C++ applications, follow these steps: From 54d6279849fffb8f2b666b518121e3223ec6c664 Mon Sep 17 00:00:00 2001 From: Clemens Brunner Date: Fri, 20 Mar 2026 12:02:18 +0100 Subject: [PATCH 3/6] More tweaks --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 727cfb3..2e76eae 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,22 @@ # LibXDF – a C++ library for loading XDF files 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. -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. +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. ## Quick start -The source code and prebuilt binaries are available on the [releases page](https://github.com/Yida-Lin/libxdf/releases) (you may need to expand the list of assets to find the downloads). +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). 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: -1. Configure: `cmake -S . -B build -DCMAKE_INSTALL_PREFIX=${PWD}/build/install -DCMAKE_BUILD_TYPE=Release` -2. Build and install into `./build/install`: `cmake --build build -j --target install` +```sh +cmake -S . -B build -DCMAKE_INSTALL_PREFIX=${PWD}/build/install -DCMAKE_BUILD_TYPE=Release +cmake --build build -j --target install +``` -This builds a static library in `./build/install`, but you can build a shared library by adding `-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. ## Integrating into C++ applications From 8c12f56e75643aa29517b773c1e1d87411fd02c1 Mon Sep 17 00:00:00 2001 From: Clemens Brunner Date: Fri, 20 Mar 2026 12:03:25 +0100 Subject: [PATCH 4/6] Fix Markdown --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 2e76eae..7627f0b 100644 --- a/README.md +++ b/README.md @@ -26,17 +26,17 @@ 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: - ```CMake - find_package(libxdf REQUIRED - HINTS ${XDF_INSTALL_ROOT} - PATH_SUFFIXES share - ) - target_link_libraries(${PROJECT_NAME} - PRIVATE - # ... other dependencies - XDF::xdf - ) - ``` + ```CMake + find_package(libxdf REQUIRED + HINTS ${XDF_INSTALL_ROOT} + PATH_SUFFIXES share + ) + target_link_libraries(${PROJECT_NAME} + PRIVATE + # ... other dependencies + XDF::xdf + ) + ``` If `libxdf` was installed or extracted into a folder other than a standard system library folder, you will have to pass `-DXDF_INSTALL_ROOT=path/to/libxdf` to indicate where to find it. 3. In your source code, `#include "xdf.h"`, instantiate an object of the `Xdf` class, and call the `load_xdf` method. From 3b52ee36334189eba0a3128391eb659e0ea80106 Mon Sep 17 00:00:00 2001 From: Clemens Brunner Date: Fri, 20 Mar 2026 12:04:50 +0100 Subject: [PATCH 5/6] Shorten --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7627f0b..c305d01 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ If you want to use libXDF in C++ applications, follow these steps: ) ``` - If `libxdf` was installed or extracted into a folder other than a standard system library folder, you will have to pass `-DXDF_INSTALL_ROOT=path/to/libxdf` to indicate where to find it. + 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. For example: From d93bf7fefe8bd9663243c9f08b86fc55ab50d222 Mon Sep 17 00:00:00 2001 From: Clemens Brunner Date: Fri, 20 Mar 2026 12:08:35 +0100 Subject: [PATCH 6/6] Final tweaks --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c305d01..2934f63 100644 --- a/README.md +++ b/README.md @@ -47,12 +47,12 @@ If you want to use libXDF in C++ applications, follow these steps: #include "xdf.h" Xdf XDFdata; - XDFdata.load_xdf("C:/example.xdf"); + XDFdata.load_xdf("example.xdf"); ``` -Functions in libXDF must be called following a certain order. For instance, calling the `subtractMean` function before loading any data will result in undefined behavior. +Functions must be called in a specific order. For example, calling `subtractMean` before loading data leads to undefined behavior. -The recommended order is shown here: +The recommended order is shown below: ```C++ XDFdata.load_xdf(std::string filepath); @@ -70,7 +70,7 @@ Detailed documentation is available [here](docs/html/class_xdf.html). ## References -If you use this code in your project, please consider citing the following [conference paper](https://arxiv.org/abs/1708.06333): +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.