Metadata-Version: 2.1
Name: ultrasound-rawdata-exchange
Version: 1.4.0
Summary: Ultrasound Raw data eXchange file format C++ implementation and wrapping in Python and Matlab
License: MIT License
Project-URL: Homepage, https://moduleus.com
Project-URL: Documentation, https://github.com/moduleus/urx/wiki
Project-URL: Repository, https://github.com/moduleus/urx.git
Project-URL: Issues, https://github.com/moduleus/urx/issues
Project-URL: Changelog, https://github.com/moduleus/urx/wiki/changelog
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft
Classifier: Operating System :: Unix
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python
Classifier: Topic :: File Formats
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cmake-build-extension==0.6.1
Requires-Dist: numpy==1.24.4; python_version == "3.8"
Requires-Dist: numpy==1.26.4; python_version == "3.9"
Requires-Dist: numpy==2.1.3; python_version == "3.10"
Requires-Dist: numpy==2.3.4; python_version >= "3.11"
Requires-Dist: parameterized==0.9.0
Requires-Dist: filelock==3.16.1; python_version == "3.8"
Requires-Dist: filelock==3.19.1; python_version == "3.9"
Requires-Dist: filelock==3.20.0; python_version >= "3.10"
Requires-Dist: cmake==3.31.1
Requires-Dist: gitdb==4.0.11
Requires-Dist: GitPython==3.1.43
Requires-Dist: ninja==1.11.1.2
Requires-Dist: packaging
Requires-Dist: setuptools==75.3.0; python_version == "3.8"
Requires-Dist: setuptools==75.6.0; python_version >= "3.9"
Requires-Dist: setuptools-scm==8.1.0
Requires-Dist: smmap==5.0.1

# URX

## 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](./wiki) about class diagram.

## Table of Contents

  * Common installation and usage in [C++](#use-it-with-c), [MATLAB](#use-it-with-matlab), [Python](#use-it-with-python).
  * Build it yourself for C++, MATLAB, Python with [CMake](doc/cpp.md#build).

## Use it with C++

There is no installer for C++ user. You need to [build](doc/cpp.md#build) it yourself. If you don't need to read / write file, urx library is header-only.

See [advanced uses](doc/cpp.md) for more information.

### Configuration

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

```cmake
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.

### CMake examples

```cmake
find_package(HDF5 REQUIRED NAMES hdf5 COMPONENTS CXX hdf5::hdf5-static)
find_package(Urx REQUIRED)
add_executable(UrxTestIo ${SRCS_FILES})
target_link_libraries(
  UrxTestIo PRIVATE Urx::Urx Urx::UrxUtils hdf5::hdf5-static hdf5::hdf5_cpp-static)
```

`Urx::UrxUtils` is only needed if you use helpers. If you only need the urx file format, only `Urx::Urx` 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/urx` or in `test/io` folders.

### C++ examples

All dynamic memory allocation should be stored in a `shared_ptr`.

```cpp
#include <memory>

#include <urx/dataset.h>
#include <urx/probe.h>
#include <urx/utils/io/reader.h>
#include <urx/utils/io/writer.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 an example for all C++ classes in file `urx/utils/test/dataset_gen.h` in function `generateFakeDataset` and much more in the official wiki.

## Use it with MATLAB

See [advanced uses](doc/matlab.md) for more information.

### MATLAB installer

Urx MATLAB homepage is hosted in [MATLAB File Exchange](https://fr.mathworks.com/matlabcentral/fileexchange/176398-ultrasound-raw-data-exchange). To download the toolbox, select `Download` > `Toolbox`. It compatibles for both Windows and Linux.

### 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 Urx from MATLAB toolbox, you just have to enable Unicode if you need it (`feature('DefaultCharacterSet','UTF-8');`).

### Examples

```MATLAB
dataset = urx.Dataset();

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

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

dataset2 = urx.loadFromFile('test.urx');
```

You may found a complete example in file `test/matlab/+urx/+UnitTests/FileFromScratch.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. `urx.ElementGeometry.empty`).

## Use it with Python

See [advanced uses](doc/python.md) for more information.

### Python wheel

Urx Python is hosted in [Pypi](https://pypi.org/project/ultrasound-rawdata-exchange/).

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

### Examples

```python
import ultrasound_rawdata_exchange as urx;

dataset = urx.Dataset()

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

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

dataset2 = urx.loadFromFile('test.urx')
```

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

