Luna

Overview

What is Luna?

Welcome to the documentation for Luna, a suite of tools for processing Timepix3 and Timepix4 data generated by Serval. Luna simplifies processing Timepix detector outputs, converting raw data into accessible hdf5 formats for further analysis. When raw data from a Timepix3 or Timepix4 based camera from Amsterdam Scientific Instruments (ASI) is stored, the resulting file will be a binary .tpx3 or .tpx4 file. This file contains the information of each registered pixel hit (x, y, time of arrival (ToA), time over threshold (ToT)), as well as additional information, such as timestamps from the time-to-digital converters (TDCs) or additional information (for a detailed description of the raw .tpx3 data, please consult the Serval manual). The Luna software reads this data, processes the information, and outputs a file in hdf5 format.

The purpose of Luna is to make it easy for the user to read the Timepix3 or Timepix4 based data. In addition to data format conversion, basic processing steps and correction is applied. In most cases, each registered interaction (such as a photon measured using an intensifier) generates several pixel hits, making a cluster of pixel hits close to each other. Luna features two clustering algorithms that determine the boundaries of the clusters based on spatial and termporal proximity. This makes it possible to directly work with the cluster information, rather than using the hit-by-hit data native to the .tpx3 data. Timewalk correction is optionally applied to PixelHit data, which improves the time resolution.

Quickstart

To process tpx3 data from a file called tpx3_file.tpx3 using a maximum intra-cluster time span of 100ns that are a maximum of 1 pixel away from another and saving the output to tpx3_file.hdf5, a hdf5 file in the same directory.

./tpx3dump process -i "/full/path/to/tpx3_file.tpx3" -o "/full/path/to/tpx3_file.hdf5" --eps-t 100ns --eps-s 1

Installation

Luna offers cross platform support, that is Ubuntu 18, 20 or 22, Windows or MacOS. Whatever your system, extract luna from the zip file and navigate to the bin directory. Inside are the binaries you need. If you need Luna compiled for a different OS, you are welcome to request this directly from us.

Running Luna binaries

This section describes the process of executing the binary files. If you are familiar with execution of binary files you can skip this section.

On Ubuntu and MacOS

Open a terminal (Ctrl + Alt + T on Ubuntu and CMD + Spacebar type terminal on MacOS ) and cd to the directory where you unzipped Luna. Navigate to the bin directory and you can run luna with

cd </full/path/to/luna>/bin
./tpx3dump --help

On Windows

Open PowerShell or Command Prompt from the start menu and run the following:

cd <C:\full\path\to\luna>\bin
./tpx3dump.exe --help

Note

If you use a different operating system you may contact ASI with a build request and we can build Luna for your OS.

Global Installation: Add Luna to Path

If you want to have access to tpx3dump or tpx4dump from any directory you can configure the PATH environment variable. First copy the full luna distribution to somewhere other than Downloads (or the like) such as your home directory.

On Ubuntu and MacOS

Open a terminal and type nano ~/.bashrc (for Ubuntu) or nano ~/.zshrc (MacOS) and add the line

export PATH="$PATH:<path/to/luna/bin>"

For instance, if my Luna distribution was at /home/user/luna the path to use is /home/user/luna/bin. Remember that you’ll need to “source” the bashrc/zshrc for changes to take effect. You can do with with source ~/.bashrc or simply by restarting the terminal.

On Windows

Press the Win key and begin typing Environment variables. At the bottom of the next window there will be a button that says Environment Variables, click it and then double click the Path variable. You’ll be able to paste the C:\path\to\luna\bin from there. For more comprehensive instructions see here.