Template Class TrxFile

• Defined in File trx.h

Nested Relationships

Nested Types

• Struct TrxFile::GroupBackingInfo

Class Documentation

template<typename DT>
class TrxFile

Public Functions

TrxFile(int nb_vertices = 0, int nb_streamlines = 0, const TrxFile<DT> *init_as = nullptr, std::string reference = "")

~TrxFile()

std::unique_ptr<TrxFile<DT>> deepcopy()

Create a deepcopy of the TrxFile.

* A deepcopied TrxFile of the current object

Returns:

TrxFile

void resize(int nb_streamlines = -1, int nb_vertices = -1, bool delete_dpg = false)

Remove the ununsed portion of preallocated memmaps.

Parameters:

• nb_streamlines – The number of streamlines to keep

• nb_vertices – The number of vertices to keep

• delete_dpg – Remove data_per_group when resizing

void save(const std::string &filename, TrxCompression compression = TrxCompression::None)

Save a TrxFile.

Parameters:

• filename – The path to save the TrxFile to

• compression – Compression method (default: no compression).

void save(const std::string &filename, const TrxSaveOptions &options)

void normalize_for_save()

Normalize in-memory arrays for deterministic save semantics.

This trims trailing preallocated rows when detected, rewrites lengths from offsets, and synchronizes header counts with the actual payload.

void add_dps_from_text(const std::string &name, const std::string &dtype, const std::string &path)

template<typename T>
void add_dps_from_vector(const std::string &name, const std::string &dtype, const std::vector<T> &values)

template<typename T>
void add_dpv_from_vector(const std::string &name, const std::string &dtype, const std::vector<T> &values)

Add per-vertex values as DPV from an in-memory vector.

Parameters:

• name – DPV name (used as filename in dpv/).

• dtype – Output dtype (float16/float32/float64).

• values – Per-vertex values; size must match NB_VERTICES.

void add_group_from_indices(const std::string &name, const std::vector<uint32_t> &indices)

Add a group from a list of streamline indices.

Parameters:

• name – Group name (used as filename in groups/).

• indices – Streamline indices (uint32) belonging to the group.

void set_voxel_to_rasmm(const Eigen::Matrix4f &affine)

Set the VOXEL_TO_RASMM affine matrix in the TRX header.

This updates header[“VOXEL_TO_RASMM”] with the provided 4x4 matrix.

void add_dpv_from_tsf(const std::string &name, const std::string &dtype, const std::string &path)

void export_dpv_to_tsf(const std::string &name, const std::string &path, const std::string &timestamp, const std::string &dtype = "float32") const

void close()

Cleanup on-disk temporary folder and initialize an empty TrxFile.

void _cleanup_temporary_directory()

inline size_t num_vertices() const

inline size_t num_streamlines() const

std::unique_ptr<TrxFile<DT>> make_empty_like() const

Returns an empty TrxFile that inherits this file’s header metadata but has NB_VERTICES and NB_STREAMLINES reset to zero.

std::vector<std::array<Eigen::half, 6>> build_streamline_aabbs() const

Build per-streamline axis-aligned bounding boxes (AABB).

Each entry is {min_x, min_y, min_z, max_x, max_y, max_z} in TRX coordinates.

const std::vector<std::array<Eigen::half, 6>> &get_or_build_streamline_aabbs() const

void invalidate_aabb_cache() const

std::unique_ptr<TrxFile<DT>> query_aabb(const std::array<float, 3> &min_corner, const std::array<float, 3> &max_corner, const std::vector<std::array<Eigen::half, 6>> *precomputed_aabbs = nullptr, bool build_cache_for_result = false, size_t max_streamlines = 0, uint32_t rng_seed = 42) const

Extract a subset of streamlines intersecting an axis-aligned box.

The box is defined by min/max corners in TRX coordinates. Returns a new TrxFile with positions, DPV/DPS, and groups remapped. Optionally builds the AABB cache for the returned TrxFile.

If max_streamlines > 0 and more streamlines intersect the box than that limit, a random sample of exactly max_streamlines is returned instead of the full intersection. rng_seed controls the random draw so results are reproducible. The returned indices are sorted for efficient I/O.

std::unique_ptr<TrxFile<DT>> subset_streamlines(const std::vector<uint32_t> &streamline_ids, bool build_cache_for_result = false) const

Extract a subset of streamlines by index.

The returned TrxFile remaps positions, DPV/DPS, and groups. Optionally builds the AABB cache for the returned TrxFile.

const MMappedMatrix<DT> *get_dps(const std::string &name) const

const ArraySequence<DT> *get_dpv(const std::string &name) const

const MMappedMatrix<uint32_t> *get_group_members(const std::string &name) const

std::vector<std::array<DT, 3>> get_streamline(size_t streamline_index) const

template<typename Fn>
void for_each_streamline(Fn &&fn) const

inline ConnectivityMatrixResult compute_group_connectivity(ConnectivityMeasure measure = ConnectivityMeasure::StreamlineCount, const std::string &dps_field_name = "") const

Compute symmetric group-by-group connectivity in packed upper-triangle form.

Connectivity can be computed either as raw streamline counts or as a weighted sum using a named 1D DPS field.

Parameters:

• measure – ConnectivityMeasure::StreamlineCount or ConnectivityMeasure::DpsSum.

• dps_field_name – Required when measure is DpsSum.

Returns:

ConnectivityMatrixResult packed as upper triangle (i<=j).

template<typename T>
void add_dpg_from_vector(const std::string &group, const std::string &name, const std::string &dtype, const std::vector<T> &values, int rows = 1, int cols = -1)

Add a data-per-group (DPG) field from a flat vector.

Values are stored as a matrix of shape (rows, cols). If cols is -1, it is inferred from values.size() / rows.

template<typename Derived>
void add_dpg_from_matrix(const std::string &group, const std::string &name, const std::string &dtype, const Eigen::MatrixBase<Derived> &matrix)

Add a data-per-group (DPG) field from an Eigen matrix.

const MMappedMatrix<DT> *get_dpg(const std::string &group, const std::string &name) const

Get a DPG field or nullptr if missing.

std::vector<std::string> list_dpg_groups() const

List DPG groups present in this TrxFile.

std::vector<std::string> list_dpg_fields(const std::string &group) const

List DPG fields for a given group.

void remove_dpg(const std::string &group, const std::string &name)

Remove a DPG field from a group.

void remove_dpg_group(const std::string &group)

Remove all DPG fields for a group.

inline const std::string &uncompressed_folder_handle() const

Access the backing directory path.

inline std::string &uncompressed_folder_handle()

std::tuple<int, int> _copy_fixed_arrays_from(TrxFile<DT> *trx, int strs_start = 0, int pts_start = 0, int nb_strs_to_copy = -1)

Fill a TrxFile using another and start indexes (preallocation)

Parameters:

• trx – TrxFile to copy data from

• strs_start – The start index of the streamline

• pts_start – The start index of the point

• nb_strs_to_copy – The number of streamlines to copy. If not set will copy all

Returns:

std::tuple<int, int> A tuple representing the end of the copied streamlines and end of copied points

int len()

Public Members

json header

std::unique_ptr<ArraySequence<DT>> streamlines

mutable std::map<std::string, std::unique_ptr<MMappedMatrix<uint32_t>>> groups

std::map<std::string, std::unique_ptr<MMappedMatrix<DT>>> data_per_streamline

std::map<std::string, std::unique_ptr<ArraySequence<DT>>> data_per_vertex

std::map<std::string, std::map<std::string, std::unique_ptr<MMappedMatrix<DT>>>> data_per_group

std::string _uncompressed_folder_handle

bool _copy_safe

bool _owns_uncompressed_folder = false

Public Static Functions

static std::unique_ptr<TrxFile<DT>> _create_trx_from_pointer(json header, std::map<std::string, std::tuple<long long, long long>> dict_pointer_size, std::string root_zip = "", std::string root = "")

After reading the structure of a zip/folder, create a TrxFile.

Parameters:

• header – A TrxFile header dictionary which will be used for the new TrxFile

• dict_pointer_size – A dictionary containing the filenames of all the files within the TrxFile disk file/folder

• root_zip – The path of the ZipFile pointer

• root – The dirname of the ZipFile pointer

Returns:

TrxFile*

static std::unique_ptr<TrxFile<DT>> load_from_zip(const std::string &path)

Load a TrxFile from a zip archive.

static std::unique_ptr<TrxFile<DT>> load_from_directory(const std::string &path)

Load a TrxFile from an on-disk directory.

static std::unique_ptr<TrxFile<DT>> load(const std::string &path)

Load a TrxFile from either a zip archive or directory.

Friends

friend class TrxReader

template<typename U>
friend std::unique_ptr<TrxFile<U>> load(const std::string &path)

Load a TRX file from either a zip archive or directory.

* TrxFile representing the read data

Template Parameters:

DT –

Parameters:

path – Path to TRX archive or directory

Returns:

TrxFile

struct GroupBackingInfo

Public Members

std::string filename

int rows = 0

int cols = 0

std::string dtype

long long mem_offset = 0