Ultrasound Raw data eXchange

Ultrasound Raw data eXchange file format C++ implementation and wrapping in Python and Matlab

URX

Download your Windows or Linux MATLAB Toolbox from https://github.com/moduleus/urx/releases.

Be sure to click on "Show all XX assets" and select your toolbox (urx-X.Y.Z-linux-amd64.mltbx for Linux or urx-X.Y.Z-win-amd64.mltbx for Windows).

Description

The Ultrasound Raw data eXchange file format is a structure of data to store ultrasound acquisition.

You may use it with various languages (C++, Python and MATLAB).

Get more informations in the Wiki about class diagram.

C++

CMakeAvailable files

All CMake files will be installed in INSTALL_PATH/lib/cmake/Urx-XXXYYY/ with:

• XXX: the version of the Urx library,
• YYY: empty if library has been built in shared mode, "_static" if library is static.

Configuration

First, you need to get Urx package with find_package.

find_package(Urx REQUIRED)

You will have access to targets:

• Urx::Urx: header-only library of the urx struct.
• Urx::UrxUtils: library with helper to manipulate urx struct, including read / write in hdf5 file format.

Usage

add_executable(UrxTestIo ${SRCS_FILES}) target_link_libraries( UrxTestIo PRIVATE Urx::Urx Urx::UrxUtils ${HDF5_CXX_LIBRARIES})

Urx::UrxUtils is only needed if you use helpers. If you only need the urx file format, only Urx::Urx is needed.

HDF5_CXX_LIBRARIES is only needed if the library has been built with HDF5 support.

You may found a complete example in test/urx or in test/io folders.C++Available files

All files will be installed in :

• INSTALL_PATH/include/Urx-XXXYYY/ (headers),
• INSTALL_PATH/lib (static libraries),
• INSTALL_PATH/bin (executables and libraries for Windows only).

Usage

All dynamic memory allocation should be stored in a shared_ptr.

#include <memory>#include <urx/dataset.h>auto dataset = std::make_shared<urx::Dataset>(); auto probe = std::make_shared<urx::Probe>(); probe->description = "Probe 1"; dataset->acquisition.probes.push_back(probe); urx::utils::io::writer::saveToFile("file.urx", *dataset); auto dataset_loaded = urx::utils::io::reader::loadFromFile("file.urx");

You may found a complete example in file urx/utils/io/test/io.h in function generateFakeDataset.

MATLAB

Available files

All MATLAB files will be installed in :

- `INSTALL_PATH/share/Urx-XXXYYY/matlab` (scripts), - `INSTALL_PATH/lib` (static libraries), - `INSTALL_PATH/bin` (shared libraries for Windows only). C++ compiler

You need a C++ compiler.

If you have an error like MATLAB:mex:NoCompilerFound_link_Win64 or No supported compiler was found, run mex -setup c -v and mex -setup c++ -v.

Example of full error message

If you want to use a free compiler, follow the next steps:

• Download MinGW-w64 from https://www.mingw-w64.org/downloads. You may use LLVM-MinGW at Github https://github.com/mstorsjo/llvm-mingw/releases and get the latest release from the file llvm-mingw-YYYYMMDD-msvcrt-x86_64.zip.
• Extract it and install it on c:\llvm-mingw-YYYYMMDD-msvcrt-x86_64 (path c:\llvm-mingw-YYYYMMDD-msvcrt-x86_64\bin must exist) or anywhere but don't use path with space inside.
• In MATLAB, run:

setenv('MW_MINGW64_LOC', 'C:/llvm-mingw-YYYYMMDD-msvcrt-x86_64') mex -setup c -v mex -setup c++ -v

Check you have a message Found installed compiler 'MinGW64 Compiler (C++)'..

Configuration

If you are using Urx from MATLAB toolkit, you just have to enable Unicode if you need it (feature('DefaultCharacterSet','UTF-8');).

If you built Urx from source, before using Urx in MATLAB, you first need to:

• allow utf-8 caracters,
• load the urx library.

addpath([pwd 'INSTALL_PATH/share/Urx-XXXYYY/matlab']); feature('DefaultCharacterSet','UTF-8'); urx.LibBinding.getInstance([path to libUrxMatlabBinding.so], [path to INSTALL_PATH/include/Urx-XXXYYY/urx/matlab/bindings.h], {[path to INSTALL_PATH/include/Urx-XXXYYY]}, {});

⚠ When invoking urx.LibBinding.getInstance the first time, environment variable HDF5_DISABLE_VERSION_CHECK is set. MATLAB have it's own version of HDF5 library. Under Linux it will conflict with the one from Urx.

If you try to use dataset.saveToFile(...) or urx.Dataset.loadFromFile(...) without setting HDF5_DISABLE_VERSION_CHECK, MATLAB will crash with error: Headers are 1.8.23, library is 1.8.12.

Example of full error message

Urx must use the same version (at least major / minor number) than the one from MATLAB (here 1.8).

Why is there a problem? Under Linux, the same symbol from two differents libraries are merged. So you can't know which one will be used. By setting HDF5_DISABLE_VERSION_CHECK to 1, you are disabling version check. Under Windows, the operating system keeps symbols from different libraries separate.

Usage

dataset = urx.Dataset(); probe1 = urx.Probe(); probe1.description = 'Probe 1'; dataset.acquisition.excitations = [excitation1]; dataset.saveToFile('test.urx'); dataset2 = urx.Dataset.loadFromFile('test.urx');

You may found a complete example in file test/matlab/+urx/+UnitTests/FileFromScratch.m.Important note

Some field are optional or can be empty (see C++ UML diagram). If you want to unassign a value, don't use [] but use empty method of the class (i.e. urx.ElementGeometry.empty).

Python

Usage

import ultrasound_rawdata_exchange as urx; dataset = urx.Dataset() probe1 = urx.Probe() probe1.description = 'Probe 1'dataset.acquisition.excitations = [excitation1] urx.saveToFile('test.urx', dataset) dataset2 = urx.loadFromFile('test.urx')

You may found a basic usage in folder test/python.

Build it with CMake

See .gitlab-ci.yml file for various examples.Windows

Under Windows, you need to explicitly set Visual Studio generator.

cmake.exe -S root_path -B CI -G "Visual Studio 17 2022" -A x64Linux

cmake -S . -B CI

Common features

• Install path

Set -DCMAKE_INSTALL_PREFIX= variable to define the installation path.

• Debug or Release

If you use a single build type generator (like Makefile in Linux), you need to set CMAKE_BUILD_TYPE to Debug or Release.

• Static or dynamic libraries

Set BUILD_SHARED_LIBS to OFF or ON.

Note that you should set BUILD_SHARED_LIBS to OFF if you want to build MATLAB or Python buiding.

Be sure to use a vcpkg triplet with the same shared / static link option.

• Use external 3rd party with vcpkg

vcpkg is a package manager. You first need to clone it with git clone https://github.com/microsoft/vcpkg.git.

Also, be sure that submodule vcpkg-registry is initialized with git submodule update --init --recursive.

Then pass the arguments below. ⚠ If you use cmake-gui, be sure to set these variables BEFORE running configure once. Otherwise, you need to reset cache.

Windows:

-DCMAKE_TOOLCHAIN_FILE="vcpkg_path/scripts/buildsystems/vcpkg.cmake"-DVCPKG_TARGET_TRIPLET=x64-wsmep -DVCPKG_HOST_TRIPLET=x64-wsmep -DVCPKG_OVERLAY_TRIPLETS=vcpkg-registry/triplets"

Linux with static libraries (make sure that BUILD_SHARED_LIBS is set to OFF).

-DCMAKE_TOOLCHAIN_FILE="vcpkg_path/scripts/buildsystems/vcpkg.cmake"-DVCPKG_TARGET_TRIPLET=x64-linux -DVCPKG_HOST_TRIPLET=x64-linux -DVCPKG_OVERLAY_TRIPLETS=vcpkg-registry/triplets

We provide various triplet with following syntax:

• w for Windows,
• l for Linux,
• d for Linux dynamic (will be static otherwise),
• sm for Windows static with /MD option (will be dynamic otherwise). See VCPKG_CRT_LINKAGE,
• e to pass environment variable for Windows. See VCPKG_ENV_PASSTHROUGH,
• p to pass Python3_EXECUTABLE to vcpkg via VCPKG_Python3_EXECUTABLE environment variable.
• Enable HDF5

This feature is needed to read / write urx structure to file.

Set WITH_HDF5 to OFF or ON.

• Enable Python binding

Set WITH_PYTHON to OFF or ON.

You can also set WITH_PYTHON_WHL to ON if you want to generate wheel package without using pip wheel.

• Enable MATLAB binding

Set WITH_MATLAB to OFF or ON.

You don't need to have MATLAB installed on your computer to build the MATLAB binding.

• Build with Clang

You need to set lots of CMake variables and use CMake 3.29 if you want to use CMAKE_LINKER_TYPE variable.

-DCMAKE_C_COMPILER=/usr/bin/clang-17-DCMAKE_CXX_COMPILER=/usr/bin/clang++-17-DCMAKE_AR=/usr/bin/llvm-ar-17-DCMAKE_AS=/usr/bin/llvm-as-17-DCMAKE_RANLIB=/usr/bin/llvm-ranlib-17-DCMAKE_LINKER_TYPE=LLD

You may found various command to build Urx in file .gitlab-ci.yml.

Build it with pip wheel

Using vcpkg

You may generate wheel archive by launching pip wheel . from the root directory of the project.

The setup.py file support the following options:

• CMAKE_TOOLCHAIN_FILE to set vcpkg path (repository cloned if option is not given),
• cmake_build_type to set CMAKE_BUILD_TYPE in CMake (Release by default),
• vcpkg_triplet to set vcpkg triplet (guessed if omited),

You can also set CMake variable with -DVARIABLE=VALUE.

Example:

python.exe -m pip install . --config-settings="--global-option=CMAKE_TOOLCHAIN_FILE=vcpkg_path/scripts/buildsystems/vcpkg.cmake"--config-settings="--global-option=cmake_build_type=RelWithDebInfo"--config-settings="--global-option=vcpkg_triplet=x64-wsmrep"--config-settings="--global-option=-DBUILD_SHARED_LIBS=OFF"--config-settings="--global-option=-DWITH_HDF5=ON"-v

See build:windows-python and build:ubuntu-python in .gitlab-ci.yml file for real examples.

Without vcpkg

If you want to disable vcpkg and use you own 3rd party library (that you already built), you can set DISABLE_VCPKG to ON and set all XXX_DIR CMake variable (path of the CMake files of the 3rd party).

See CMake target UrxPythonWheel in python/CMakeLists.txt file for real example.