======== **Luna** ======== .. toctree:: :hidden: self 1_usage/usage 2_concepts/concepts 3_examples/examples ************ **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), exposure time boundaries 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 a clustering algorithm that combines the information of all pixel hits within the cluster. 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 as well as cluster 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. .. code-block:: bash # process mode ./tpx3dump process -i "/full/path/to/tpx3_file.tpx3" -o "/full/path/to/tpx3_file.hdf5" --eps-t 100ns --eps-s 1 **Installation** ================ Luna is built for systems running 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. **Running Luna binaries** ================= This section describes the process of executing the binary files, which is similar as for any binary on your system. 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 .. code-block:: bash cd /bin ./tpx3dump --help **On Windows** Open PowerShell or Command Prompt from the start menu and run the following: .. code-block:: powershell cd /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. **Adding 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 .. code-block:: bash export PATH="$PATH:" 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 `_.