pyterse

Pyterse python package

Next generation TERSE/PROLIX diffraction data compression algorithm

The pyterse python package provides Python bindings for the C++ TERSE/PROLIX(TRPX) compression algorithm scheme (https://github.com/senikm/trpx).

Prerequisites

Before using pyterse, ensure your data meets these requirements:

• Signed or unsigned integral type data
• Grayscale data
• Preferably has high dynamic range

Installation

Create a virtual environment:

conda create -n pyterse python pip numpy pillow

Install the package:

pip install pyterse

Usage guide

Basic operations

Creating a Terse object

There are multiple ways to create a Terse object:

import pyterse

# Empty constructor
terse = pyterse.Terse()

# From NumPy array
terse = pyterse.Terse(data)  # data can be nD NumPy array or slice

# With custom compression mode
terse = pyterse.Terse(data, pyterse.TerseMode.SIGNED)  # Available modes: SIGNED, UNSIGNED, SMALL_UNSIGNED, DEFAULT

Inserting and managing data

Add data to an existing Terse object:

# Append data at the end
terse.push_back(data)  # Data must match existing shape (terse.dim())

# Insert at specific position
terse.insert(pos, data)  # pos is the frame index

File operations

Save and load compressed data:

# Save to file
terse.save('filename.trpx')

# Load from file
loaded_terse = pyterse.Terse.load('filename.trpx')

Data Decompression

Decompress data:

# Decompress all data
decompressed_data = terse.prolix()

# Decompress specific frame
frame = terse.at(0)
decompressed_frame = frame.prolix()

Metadata Management

# Set metadata for a frame
terse.set_metadata(frame, "metadata string")

# Get metadata from a frame
metadata = terse.metadata(frame)

Utility Methods

# Data information
terse.size()              # Number of elements per frame
terse.dim()               # Dimensions of one frame
terse.number_of_frames()  # Number of frames
terse.number_of_bytes()   # Size in bytes of compressed data
terse.bits_per_val()      # Bits used per value
terse.is_signed()         # Whether data is signed

# Data management
terse.erase(pos)          # Remove frame at position
terse.shrink_to_fit()     # Optimize memory usage

# Compression settings
terse.set_block_size(size)  # Set compression block size (before adding frames)
terse.set_fast(bool)        # Toggle fast compression mode
terse.set_small(bool)       # Toggle small data optimization
terse.set_dop(value)        # Set degree of parallelism (0.0 to 1.0)