Katherine Control Library

The Katherine control library contains a working implementation of UDP-based communication protocol. It may be used to control and receive data from Timepix3 using Katherine readouts.

This git repository contains 3 libraries in total:

libkatherine, a C library,
libkatherinexx, a C++ header-only wrapper,
katherine, a Python wrapper package.

At the present time, the library is multi-platform. The implementation supports the following platforms:

Platform	CI Status
Linux
macOS
Windows

Usage

Getting Started

The following simple code snippets in C, C++ and Python, respectively, show the intended usage of the library. The code prints the chip ID of a read-out at a given IP address.

// C example
#include <stdio.h>
#include <katherine/katherine.h>

int main() {
  const char *ip_addr = "192.168.1.142";

  katherine_device_t dev;
  katherine_device_init(&dev, ip_addr);   // Ignoring return code.

  char chip_id[KATHERINE_CHIP_ID_STR_SIZE];
  katherine_get_chip_id(&dev, chip_id);   // Ignoring return code.
  printf("Device %s has chip id: %s\n", ip_addr, chip_id);

  katherine_device_fini(&dev);
}

// C++ example
#include <iostream>
#include <katherinexx/katherinexx.hpp>

int main() {
  const std::string ip_addr{"192.168.1.142"};

  katherine::device dev{ip_addr};
  const std::string chip_id = dev.chip_id();   // Exception can be thrown here.
  std::cout << "Device " << address << " has chip id: " << chip_id << std::endl;
}

# Python example
from katherine import Device

ip_addr = '192.168.1.142'

dev = Device(ip_addr)
chip_id = dev.get_chip_id()   # OSError can be raised here.
print('Device %s has chip id: %s' % (ip_addr, chip_id))

More Examples

To show advanced usage of all provided libraries, several commented example programs and scripts are included in the repository. They can be either found in the examples/ subdirectory for each library, or in the table below:

C	C++	Python	Purpose
kfind	kfindxx	kfind.py	Locate Katherine readouts in given IP address range.
krun	krunxx	krun.py	Configure & perform data-driven acquisition.

Full Documentation

The contents of the C library use in-code and Javadoc-style documentation. Pre-built documentation may be found in the docs/ directory. Upon changes, the Doxygen tool can recreate its contents.

High-level overview may be found in the Chapter 3 of the thesis.

Wrappers

For the reasons of redundancy, the provided wrappers are deliberately not documented. Since their programming interface models that of libkatherine, corresponding functions can be easily identified (usually just by adding the prefix katherine_).

Build Notes

The project uses CMake 3 build system. It can be configured, built and installed by standard CMake commands. In case of doubt, check the Travis configuration file for examples of build commands for individual platforms.

For convenience, here's a minimal out-of-source-directory build script example:

mkdir build && cd build
cmake ..
make

(note that in CMake projects, different build tools can be used instead of GNU Makefiles, e.g. ninja)

The CMake project also defines several options. They can be defined in the CMake cache, by environment variables or using the -D<option>=<value> options.

Option	Default Value	Meaning
`BUILD_CXX`	`ON`	Enables building C++ binaries (see requirements)
`BUILD_PYTHON`	`OFF`	Enables building Python extension (see requirements)
`BUILD_EXAMPLES`	`ON`	Enables building example programs

For optimal performance, consider also configuring standard CMake options such as CMAKE_BUILD_TYPE which configures the compiler optimization policies or include additional debug information. See CMake docs for more information.

C library (libkatherine)

The C library uses the following dependencies:

C11 standard library,
Version for *nix systems:
- POSIX threads (pthread),
- BSD socket interface,
Version for Win32 systems:
- Windows Sockets API (WSA) 2.2 (in ws2_32.dll),
- Windows Synchronization Primitives (in kernel32.dll).

C++ wrapper

The C++ wrapper uses the following dependencies:

C++14 standard library,
libkatherine (the C library)

Since the wrapper is header-only, there are no produced binaries and all calls are directly forwarded to libkatherine.

Python wrapper

The Python wrapper uses the following dependencies:

Python 3.5,
Cython compiler 0.29,
libkatherine (the C library)

The wrapper generates an extension module which can be loaded and used by any script. Its file name is derived from platform and Python version. Upon successful build, the file can be located inside the CMake build directory at path: ./python/build/lib.{PLATFORM}-{ARCH}-{PYTHON_VERSION}/. While in Linux systems, the file has .so extension (e.g. katherine.cpython-37m-x86_64-linux-gnu.so), in Windows the file's extension is .pyd (e.g. katherine.cp37-win_amd64.pyd).

Note: Before using the Python wrapper, make sure that the interpeter has access to all the required files. Specifically:

The extension module is located in one of the PYTHONPATH directories.
The libkatherine.so library file (or katherine.dll in Windows) is located in one of the LD_LIBRARY_PATH directories (or PATH directories in Windows).

If these conditions are not satisfied, you are likely going to encounter to ModuleNotFoundError in the first case and ImportError in the second.

Be also aware that you can change the variables directly from Python without having to alter their values on system-wide level. This is especially useful in Windows environments. Here's an example script:

import sys
import os

ext_path = '<directory containing extension module>'
lib_path = '<directory containing katherine library file>'

# Alter environment to include the extension module
sys.path.append(ext_path)

# Alter environment to include the library
if os.name == 'nt':
  # use semicolon on Windows systems
  os.environ['PATH'] += ';%s;' % lib_path
else:
  # use different variable and colon on *nix systems
  os.environ['LD_LIBRARY_PATH'] += ':%s:' % lib_path

try:
  import katherine
  dev = katherine.Device('192.168.1.145')
except ModuleNotFoundError:
  print('Something wrong with ext_path')
except ImportError:
  print('Something wrong with lib_path')

If you get linker errors during Cython build phase, check that the target architectures of the katherine library and the python extension modules are the same. In Windows environment, Cython prefers 64-bit MSVC by default, so it is necessary to choose the "Win64" generator in CMake configuration.

Copyright

Contents of this library are provided for use under the conditions of the MIT License (see LICENSE).

Citing

If you use this library in your academic work, please make sure you include a correct citation of my thesis, in which was this library originally developed and tested.

If you use BibTeX, you can use the following code:

  @THESIS{Manek2018_CUNI,
    author={P. Mánek},
    title={A system for 3D localization of gamma sources using Timepix3-based Compton cameras},
    year={2018},
    institution={Faculty of Mathematics and Physics, Charles University},
    type={Master's thesis}
  }

Contributors

I would like to thank the following people and institutions for their help in the development of this library:

Petr Burian, University of West Bohemia,
Jan Broulím, Institute of Experimental and Applied Physics CTU,
Lukáš Meduna, Institute of Experimental and Applied Physics CTU,
Jakub Begera, Institute of Experimental and Applied Physics CTU,
Felix Lehner, Physikalisch-Technische Bundesanstalt.

simonspa / libkatherine