ultrasound-acquisition-configuration 1.3.0

Ultrasound Acquisition Configuration file format C++ implementation and wrapping in Python and Matlab

UAC

Description

The Ultrasound Acquisition Configuration file format is a structure of data to configure ultrasound acquisition.

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

Get more informations in the Wiki about class diagram.

Requirements

To use Uac library, you need to install Urx library.

Table of Contents

• Common installation and usage in C++, MATLAB, Python.
• Build it yourself for C++, MATLAB, Python with CMake.

Use it with C++

There is no installer for C++ user. You need to build it yourself. If you don't need to read / write file, uac library is header-only.

See advanced uses for more information.

Configuration

First, you need to get Uac package with find_package. If package is not found, set Uac_DIR=INSTALL_PATH/lib/cmake/Uac-XXXYYY.

find_package(Uac REQUIRED)

You don't need to find_package(Urx REQUIRED). The Uac library will do it.

You will have access to targets:

• Uac::Uac: header-only library of the uac struct.
• Uac::UacUtils: library with helper to manipulate uac struct, including read / write in hdf5 file format.

CMake examples

find_package(HDF5 REQUIRED NAMES hdf5 COMPONENTS CXX hdf5::hdf5-static)
find_package(Uac REQUIRED)
add_executable(UacTestIo ${SRCS_FILES})
target_link_libraries(
  UacTestIo PRIVATE Uac::Uac Uac::UacUtils hdf5::hdf5-static hdf5::hdf5_cpp-static)

Uac::UacUtils is only needed if you use helpers. If you only need the uac file format, only Uac::Uac is needed.

hdf5::hdf5-static hdf5::hdf5_cpp-static is only needed if the library has been built with HDF5 support. In this case, hdf5 has been built in static mode.

You may found a complete example of CMakeLists.txt in test/uac or in test/io folders.

C++ examples

All dynamic memory allocation should be stored in a shared_ptr.

#include <memory>

#include <uac/dataset.h>
#include <uac/probe.h>
#include <uac/utils/io/reader.h>
#include <uac/utils/io/writer.h>

auto dataset = std::make_shared<uac::Dataset>();

auto probe = std::make_shared<uac::Probe>();
probe->description = "Probe 1";
dataset->acquisition.probes.push_back(probe);

uac::utils::io::writer::saveToFile("file.uac", *dataset);

auto dataset_loaded = uac::utils::io::reader::loadFromFile("file.uac");

You may found an example for all C++ classes in file uac/utils/test/dataset_gen.h in function generateFakeDataset and much more in the official wiki.

Use it with MATLAB

See advanced uses for more information.

MATLAB installer

Uac MATLAB homepage is hosted in MATLAB File Exchange. To download the toolbox, select Download > Toolbox. It compatibles for both Windows and Linux.

You also need to install Urx toolbox from MATLAB File Exchange.

Requirements

MATLAB needs a C compiler to load the C library in Urx toolbox (i.e. Visual Studio or MinGW). To use MinGW, see [doc/matlab.md#install-mingw-c-compiler] paragraph.

Configuration

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

Examples

dataset = uac.Dataset();

probe1 = uac.Probe();
probe1.description = 'Probe 1';
excitation1 = urx.Excitation();
dataset.acquisition.excitations = [excitation1];

uac.saveToFile('test.uac', dataset);

dataset2 = uac.loadFromFile('test.uac');

You may found a complete example in file test/matlab/+uac/+UnitTests/CreateUff.m and much more in the official wiki.

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. uac.ElementGeometry.empty).

Use it with Python

Python wheel

Uac Python is hosted in Pypi.

From your Python's virtual environment, run pip install ultrasound_acquisition_configuration.

Examples

import ultrasound_acquisition_configuration as uac;

dataset = uac.Dataset()

probe1 = uac.Probe()
probe1.description = 'Probe 1'
excitation1 = urx.Excitation()
dataset.acquisition.excitations = [excitation1]

uac.saveToFile('test.uac', dataset)

dataset2 = uac.loadFromFile('test.uac')

You may found a basic example in folder test/python and much more in the official wiki.