File types

Under construction

• Under construction
• Under construction
• Under construction
• Under construction
• Under construction
• Under construction
• Under construction
• Under construction
• Under construction
• Under construction
• Under construction
• Under construction

File type and extensions constants

These constants are file types and extensions. It can be used for filenames testing or with acquisition functions.

Python example:

# measure and save one 0.25 second frame to png file named "testFile.png"
dev.doSimpleAcquisition(1, 0.25, pixet.PX_FTYPE_PNG, "testFile")
dev.doSimpleAcquisition(1, 0.25, pixet.PX_FTYPE_AUTODETECT, "testFile.png")

File types and extensions constants table

File type constants	File extensions constants	Exts
PX_FTYPE_NONE	(No direct file saving – data stored only in memory)
PX_FTYPE_AUTODETECT	(FTYPE detected by extension in a filename)
PX_FTYPE_ASCII_FRAME	PX_EXT_ASCII_FRAME	"txt"
PX_FTYPE_BINARY_FRAME	PX_EXT_BINARY_FRAME	"pbf"
PX_FTYPE_MULTI_FRAME	PX_EXT_MULTI_FRAME	"pmf"
PX_FTYPE_BINARY_MULTIFRAME	PX_EXT_BINARY_MULTI_FRAME	"bmf"
PX_FTYPE_TPX3_PIXELS	PX_EXT_TPX3_PIXELS	"t3p"
PX_FTYPE_TPX3_PIXELS	PX_ASCII PX_EXT_TPX3_PIXELS_ASCII	"t3pa"
PX_FTYPE_CLUSTER_LOG	PX_EXT_CLUSTER_LOG	"clog"
PX_FTYPE_PIXEL_LOG	PX_EXT_PIXEL_LOG	"plog"
PX_FTYPE_PNG	PX_EXT_PNG	"png"
PX_FTYPE_TPX3_RAW_DATA	PX_EXT_TPX3_RAW_DATA	"t3r"
PX_FTYPE_PIXET_RAW_DATA	PX_EXT_PIXET_RAW_DATA	"prd"
PX_FTYPE_EXTERNAL	(reserved)
(description file saved automatically with pmf/txt)	PX_EXT_FRAME_DESC	"dsc"
(index file saved automatically with pmf/txt)	PX_EXT_INDEX	"idx"

Files extensions summary

txt	ASCII matrix: Text files with img lines converted to text lines with numbers separated by spaces.
pbf	Simple binary files, numbers only.
pmf	Multiple frames. Default is same as the txt, but multiple frames on top of each other. Can use BINARY flag.
t3pa	Tpx3 pixels ASCII. Text format, tab-separated columns with the header in the first row. Biggest to saving.
t3p	Tpx3 pixels. Binary format. Lower saved size, more complex to understand.
t3r	Tpx3 raw data. Fastest to saving, difficult to understand, slow to processing and can cause processing errors.
bstg	Binary settings file: Measured data with all configuration. See Binary Spectral Imaging API: BSTG files
clog, plog	Clusters/pixels logs. Text files contains clusters separated to frames with pixels lists. Historic formats for saving a data with few hited pixels in a frames.
h5	HDF5, hierarchical data format 5. Used as one of multi-frame formats.
info	Text file with "[FileInfo]" head and all metadata list.
dsc	Text file with frame index first and all metadata list.
idx	Binary index for multi-frame files. Usesfull for fast access to n-th frame.

File saving flags summary

File saving flags can do additional settings for file(s) saving.

• Can be used in saving files or in doAdvancedAcquisition python methods, for example.
• Flags can be combined.
• Default frame file settings is set of separate subframes text files, with all pixels include zeros, each subframe with idx+dsc files:

file_ToT.pmf, file_ToT.pmf.dsc, file_ToT.pmf.idx, file_ToA.pmf, file_ToA.pmf.dsc, file_ToA.pmf.idx

File saving flags

Flag constant base name	Description
PX_FRAMESAVE_BINARY	Use binary format in pmf.
PX_FRAMESAVE_SPARSEX	Index + non-zero pixels in file. # separates (sub)frs.
PX_FRAMESAVE_SPARSEXY	X, Y + non-zero pixel in file. # separates (sub)frames.
PX_FRAMESAVE_NODSC	Do not add dsc file.
PX_FRAMESAVE_NOSUBFRAMES	Do not use subframes, save main frame only.
PX_FRAMESAVE_SUBFRAMES_ONEFILE	Save all subframes to a single file.
PX_FRAMESAVE_SUBFRAMES_SAVEMAINFRAME	Save separate all subframes and main frame extra.

File extensions and flags: TXT/PBF/PMF/BMF details

The files formats

txt	Single frame in the text file.
pbf	Pixet Binary Frame - Single frame in the binary file.
pmf	Pixet Multi Frame - Multiframe file with text or binary format, depends on flags used with saving.
bmf	Binary Multi Frame - Multiframe file with binary format, depends on flags used with saving.
idx	Index for seeking - Binary array of 64b pointers to start of frames and subframes.
dsc	Description. List of all metadata for each frame and subframe. Actual device and acquisition parameters, data types, etc. The "Frame name" item can be helpful to orientation in pmf structure if the ONEFILE flag used. The Type=item is helpful to understanding the structure of data if the BINARY flag used.

Multi-files names generation

Note

All the next examples are for Timepix3, single chip, opm = TPX3_OPM_TOATOT

flags 0 (default), input filename = "name", acqCount = 1

name_ToA.txt, name_ToA.txt.dsc, name_ToT.txt, name_ToT.txt.dsc

acqCount = 6

name_0_ToA.txt, name_0_ToA.txt.dsc, name_0_ToT.txt, ...

...

name_5_ToA.txt, name_5_ToA.txt.dsc, ...

PMF note

With each pmf generating .pmf.idx binary file, other is same as TXT with acqCount = 1.

Files with flags=0

Note

All the next examples are for Timepix3, single chip, opm = TPX3_OPM_TOATOT

TXT file data, default

0 0 0 5 0 0 0 … 256 numbers (int for non-calibrated values or float if the calibration used) and enter

0 872 0 0 0 … 256 numbers (int for non-calibrated values or float if the calibration used) and enter

(256 lines)

PMF file data, default

0.00000 78.65742 0.00000 … 256 numbers (int for non-calibrated values or float if the calibration used) and enter

0.00000 0.00000 999785.5 … 256 numbers (int for non-calibrated values or float if the calibration used) and enter

(256 lines * acqCount)

The PMF.IDX files generated beside the PMFs. Contains the simple binary array of little-endian qword addresses of the each frame start. .pmf.idx example Pointers to frames at 0, 0x29, 0x52, 0x7b, 0xA4, 0xCD, ...

.pmf.idx file example

Flags influence to files

TXT file data: FRAMESAVE_SPARSEX flag

_ToA.txt file		_ToT.txt file
px index	ToA	px index	ToT
0	227212.500000	0	20
17	310685.937500	17	13
255	265487.500000	255	11
1274	105728.125000	1274	9
- Lists of all hited pixels - ToT: int for non-calibrated data or float if the calibration used

TXT file data: FRAMESAVE_SPARSEXY flag

_ToA.txt file				_ToT.txt file
X	Y	ToA	X	Y	ToT
247	3	189851.562500	247	3	16
250	4	140042.187500	250	4	12
5	9	317195.312500	5	9	5
- Lists of all hited pixels - ToT: int for non-calibrated data or float if the calibration used

PMF file data, pixet.PX_FRAMESAVE_SPARSEX(Y) flag
Same as TXT, but containing single lines with only # to separate frames

X	Y	ToA	Line description
232	139	321620.312500	frame 1, px 1
4	252	340231.250000	frame 1, px 2
#
39	0	258270.312500	frame 2, px 1
201	0	76593.750000	frame 2, px 2
92	1	268642.187500	frame 2, px 3

PX_FRAMESAVE_SUBFRAMES_ONEFILE

All the data is in one file, subframes are placed one behind the other. If the measurement result has 10 frames with 2 subframes A/B, each _n TXT file contains 2 subrfames and the PMF contains 20 frames in order:

sfr0A, sfr0B, sfr1A, sfr1B, ...

The exact order and names of type of (sub)frames is listed in the DSC file. The DSC have separate records [Fn] for all the items.

PX_FRAMESAVE_SUBFRAMES_SAVEMAINFRAME

The group of the saved files contains the main frame and all subframes. Subframe files end in _sfrName, the main frame does not. In DSC file accompanying the TXT with main frame is not the "Frame name" item.

Not applicable if combined with the ONEFILE flag.

PX_FRAMESAVE_BINARY

If the file type supports text and binary format, ex. PMF, save the binary.

Not applicable to TXT, must use PBF instead.

Data in the file are the simple array of non-calibrated 16 or 32b integers or calibrated doubles. See the DSC file for used data type.

BINARY + SPARSEXY examples:

Example of data saved if flags BINARY+SPARSEXY used

DSC files details

The first 3 lines have special functions:

1. File type selection
2. Index of the frame in this file
3. Arrangement and type of the data

Other lines are a list of metadata items separated by blank lines.
In txt.dsc and pbf.dsc, end of the frame is end of the file.
In the pmf.dsc, next item 2 and 3 and frame or subframe data follows.

Some example (PBF with BINARY and SPARSEXY – test_49_ToA.pbf.dsc):

B000000001                                      B=binary / A=ASCII and file type
[F0]                                            Index of frame in the file = 0
Type=double [X,Y,C] width=256 height=256        Pixel pos. X, Y and data with type double
"Acq Serie Index" ("Acquisition serie index"):  Some metadata item name and (description)
u32[1]                                          Type of the item data [number of values]
49                                              The value

(more metadata items separated by blank lines …)

"Frame name" ("Frame name"):
char[3]
ToA                                             This is the ToA frame

(more metadata items separated by blank lines …)
(end of the file)

Other example (PMF with BINARY+SPARSEX+ONEFILE – test.pmf.dsc):

B000000010
[F0]                                            Start of the first subframe
Type=double [X,C] width=256 height=256          Pixel index and double type pixel data (ToA in ns)
"Acq Serie Index" ("Acquisition serie index"):
u32[1]
0 

(more metadata items separated by blank lines …)

"Frame name" ("Frame name"):
char[3]
ToA 
(more metadata items separated by blank lines …)

[F1]                                            Start of the second subframe
Type=i16 [X,C] width=256 height=256             Pixel index and int16 pixel data (ToT counter value)
"Acq Serie Index" ("Acquisition serie index"):
u32[1]
0

(and the ToT frame metadata, [F2] and ToA subframe, [F3] and ToT sfr, … [Fn] and ToT sfr of (n/2)th frame)

Complete one frame DSC example (BINARY+SPARSEX – test_15_ToA.pbf.dsc):

B000000001
[F0]
Type=double [X,C] width=256 height=256
"Acq Serie Index" ("Acquisition serie index"):
u32[1]
15

"Acq Serie Start time" ("Acquisition serie start time"):
double[1]
1639059034.903085 
"Acq time" ("Acquisition time [s]"):
double[1]
0.500000

"ChipboardID" ("Chipboard ID"):
char[9]
I08-W0060

"DACs" ("DACs"):
u16[19]
16 8 128 10 120 1301 501 5 16 8 16 8 40 128 128 128 256 128 128 

"Frame name" ("Frame name"):
char[3]
ToA

"HV" ("High voltage [V]"):
double[1]
-500 

"Interface" ("Readout interface"):
char[7]
MiniPIX

"Mpx type" ("Medipix type (1-MXR, 2-TPX, 3-MPX3, 4-TPX3, 5-TPX2)"):
i32[1]
4 

"Pixet version" ("Pixet version"):
char[5]
1.7.8

"Start time" ("Acquisition start time"):
double[1]
1639059042.934810 

"Start time (string)" ("Acquisition start time (string)"):
char[64]
Thu Dec 9 15:10:42.934809 2021

"Threshold" ("Threshold [keV]"):
double[1]
5.026744