nexatom-downloads

Time Tag Binary Decoder

The Time Tag Binary Decoder allows developers to build offline processing tools in C/C++ that consume the massive .nxtt binary streams generated by the File Saving module (Section 7.17).

Instead of parsing raw bytes manually, this decoder provides an iterator-like interface (nexatom_tt_time_tag_reader_t) to stream batched nexatom_time_tag_t records into memory, completely abstracted from the underlying file compression or framing protocols.

Function Reference

Function	Parameters (In/Out)	Returns	Description
`nexatom_tt_open_time_tag_file_reader`	`[In] const char* path` `[Out] nexatom_tt_time_tag_reader_t** out_reader`	`nexatom_error_code_t`	Opens a single `.nxtt` file and allocates the iterator handle.
`nexatom_tt_open_time_tag_series_reader`	`[In] const char* directory` `[In] const char* series_key` `[In] uint32_t seq_start` `[In] uint32_t seq_end` `[Out] nexatom_tt_time_tag_reader_t** out_reader`	`nexatom_error_code_t`	Opens a sequence of rotated `.nxtt` files from `directory` matching `series_key` (the base filename pattern). The `seq_start` (1-based) and `seq_end` parameters define the inclusive sequence range to load. Pass `seq_end = 0` to load all remaining contiguous files.
`nexatom_tt_get_time_tag_header`	`[In] nexatom_tt_time_tag_reader_t* reader` `[Out] nexatom_time_tag_file_header_t* header`	`nexatom_error_code_t`	Extracts metadata (like creation date) embedded at the top of the `.nxtt` binary.
`nexatom_tt_read_time_tag_batch`	`[In] nexatom_tt_time_tag_reader_t* reader` `[Out] nexatom_time_tag_t* out_tags` `[In] size_t max_tags` `[Out] size_t* out_count`	`nexatom_error_code_t`	Fills the caller’s batch. EOF is `NEXATOM_SUCCESS` with zero count; a nonzero error must be preserved.
`nexatom_tt_close_time_tag_reader`	`[In] nexatom_tt_time_tag_reader_t* reader`	`void`	Closes the file handles and frees the iterator memory. Must be called to prevent memory leaks.

Data Structures

`nexatom_time_tag_t`

The 16-byte host representation of a decoded event. It is not the packed disk record or the USB wire format.

Field	Type	Description
`timestamp_ps`	`uint64_t`	Decoded timestamp in ps; raw rollover is extended within a runtime session. Do not assume each acquisition resets the hardware time origin.
`channel`	`uint8_t`	Decoded public channel index. Interpret it using the runtime’s channel mapping; it is not independently a physical connector identifier.
`_padding`	`uint8_t[7]`	Explicit host ABI padding; this makes a 16-byte record, not a universal 16-byte alignment requirement.

`nexatom_time_tag_file_header_t`

Parsed from the top of the binary file. Note the FFI alignment padding fields.

Field	Type	Description
`magic`	`char[5]`	File format identifier: `"NXTT\0"` (null-terminated).
`_padding0`	`uint8_t[3]`	FFI alignment padding after magic.
`created_timestamp_us`	`uint64_t`	POSIX Unix epoch timestamp (in microseconds) of when the file was created.
`output_data_type`	`uint32_t`	Echoes the active mode from `nexatom_output_data_type_t` when the file was recorded.
`_padding1`	`uint8_t[4]`	FFI alignment padding at end of header.

C Example: Decoding a Run Offline

nexatom_tt_time_tag_reader_t* reader = NULL;

// 1. Open the file
if (nexatom_tt_open_time_tag_file_reader("/data/run_1.nxtt", &reader) == 0) {
    
    // 2. Allocate our batch buffer
    size_t batch_size = 10000;
    nexatom_time_tag_t* batch = malloc(batch_size * sizeof(nexatom_time_tag_t));
    if (batch == NULL) {
        nexatom_tt_close_time_tag_reader(reader); // Reader ownership exists even on allocation failure.
        return -1;
    }
    size_t tags_read = 0;
    nexatom_error_code_t read_status;
    
    // 3. Iterate through the file until EOF
    while ((read_status = nexatom_tt_read_time_tag_batch(reader, batch, batch_size, &tags_read)) == NEXATOM_SUCCESS) {
        if (tags_read == 0) break; // End of file
        
        // Process this block (e.g., software cross-correlation)
        for (size_t i = 0; i < tags_read; i++) {
            if (batch[i].channel == 0) {
                // Photon detected on Channel 0 at batch[i].timestamp_ps!
            }
        }
    }
    
    // 4. An error is not EOF; report it before subsequent diagnostics change.
    if (read_status != NEXATOM_SUCCESS)
        fprintf(stderr, "Decode failed: %s\n", nexatom_tt_get_last_error_message());
    // The complete caller also propagates read_status as its failed run result.
    free(batch);
    nexatom_tt_close_time_tag_reader(reader);
}

Offline readers require no device handle but enforce safe output/saving conditions if a device is connected. Quiet and finalize acquisition first. Reader close releases resources; EOF also releases temporary output ownership. A mode-restore failure remains an error. See reader lifecycle and series keys.

C Example: Loading a Rotated Series

nexatom_tt_time_tag_reader_t* reader = NULL;

// Open files matching pattern "my_experiment_TAGS_*.nxtt" in /data/
// Loads sequence numbers 1 through 10
nexatom_error_code_t err = nexatom_tt_open_time_tag_series_reader(
    "/data/",                // directory
    "my_experiment_TAGS",    // series_key (base filename pattern)
    1,                       // seq_start (1-based)
    10,                      // seq_end (0 = all remaining)
    &reader
);

if (err == 0) {
    // Read batches across all 10 files seamlessly...
    nexatom_tt_close_time_tag_reader(reader);
}