The API documentation¶
This part of the documentation covers all the interfaces of trsfile.
Overview¶
This section gives an overview of the main classes and their descriptions.
- trsfile.open(path, mode='r', **options)¶
Reads, modifies or creates a
TraceSet
with a specific storage engine (defaults toTrsEngine
).- Parameters:
path (str) – path to the file or directory
mode (str) – mode how to open the file or directory (same as the default Python
open
)options (dict(str, any)) – zero or more options that are passed down to the
TraceSet
and the storage engine. Available options can be found in the different storage engines. The storage engine can be selected withengine = 'TrsEngine'
(default value).
- Returns:
instance of a new or initialized
TraceSet
- Return type:
- trsfile.trs_open(path, mode='r', **options)[source]¶
Reads, modifies or creates a
TraceSet
with a specific storage engine (defaults toTrsEngine
).- Parameters:
path (str) – path to the file or directory
mode (str) – mode how to open the file or directory (same as the default Python
open
)options (dict(str, any)) – zero or more options that are passed down to the
TraceSet
and the storage engine. Available options can be found in the different storage engines. The storage engine can be selected withengine = 'TrsEngine'
(default value).
- Returns:
instance of a new or initialized
TraceSet
- Return type:
- class trsfile.trace.Trace(sample_coding, samples, parameters=None, title='trace', headers=None, raw_data: bytes = b'')[source]¶
The
Trace
class behaves like alist
object were each item in the list is a sample of the trace.When a
Trace
is initialized the samples are (optionally) converted to anumpy.array
depending on the current type of the samples and the providedsample_coding
.
- class trsfile.trace_set.TraceSet(path, mode='r', **options)[source]¶
The
TraceSet
class behaves like alist
object were each item in the list is aTrace
.Storing the
TraceSet
requires knowledge on the format which is resolved through the usage of storage engines (Engine
).
- class trsfile.engine.trs.TrsEngine(path, mode='x', **options)[source]¶
This engine supports .trs files from Riscure as specified in the “Trace set coding” document in Inspector.
This engine supports the following options:
Option
Description
headers
Dictionary containing zero or more headers, see
trsfile.common.Header
live_update
Performs live update of the TRS file every N traces. True for updating after every trace and False for never.
padding_mode
Padding mode to use. The supported values are:
trsfile.common.TracePadding.NONE
(default)trsfile.common.TracePadding.AUTO
- class trsfile.engine.file.FileEngine(path, mode='x', **options)[source]¶
This engine tries to save traces to disk in the most versatile and simple manner available. No known tools support this file format and serve only as an intermediate step to later convert it to a supported format.
This is can be useful when the trace length (number of samples) varies as this is often not supported in trace files.
After acquisition, the file can be converted to the proper format with the correct padding mode.
This engine supports the following options:
Option
Description
headers
Dictionary containing zero or more headers, see
trsfile.common.Header
- class trsfile.common.Header(value)[source]¶
All headers that are currently supported in the .trs file format as defined in the inspector manual (2018). The storage engine shall try to always store all headers regardless if they are used or not. However, some file formats will have no way of storing arbitrary headers. As such, optional headers can be dropped.
Some headers can be used by
trsfile.trace_set.TraceSet
ortrsfile.trace.Trace
to augment their functionality. An example of this is thetrsfile.trace.Trace.get_key()
method.
- class trsfile.common.SampleCoding(value)[source]¶
Defines the encoding of all the samples in the trace. Bit 4 specifies if it is a float (1) or an integer (0), bits 0 to 3 specifies the length of the value. Finally, bits 5-7 are currently reserved and set to 000.
This class is just a simple lookup table.
- class trsfile.common.TracePadding(value)[source]¶
Defines the padding mode of the samples in each trace. This can be helpful when not all traces will be the same length. This can be set in
trsfile.open()
,trsfile.trs_open()
Mode
Description
NONE
No padding will be used and an exception will be thrown when traces are not of the same length.
PAD
All traces will be padded with zeroes to the maximum trace length.
TRUNCATE
All traces will be truncated to the minimum trace length.
AUTO
Traces will be clipped or padded in the best possible way the storage engine supports. This could mean data is lost which because retroactive padding is not supported.
Common¶
- class trsfile.common.Header(value)[source]¶
Bases:
Enum
All headers that are currently supported in the .trs file format as defined in the inspector manual (2018). The storage engine shall try to always store all headers regardless if they are used or not. However, some file formats will have no way of storing arbitrary headers. As such, optional headers can be dropped.
Some headers can be used by
trsfile.trace_set.TraceSet
ortrsfile.trace.Trace
to augment their functionality. An example of this is thetrsfile.trace.Trace.get_key()
method.- ACQUISITION_COUPLING_OF_SCOPE = 86¶
- ACQUISITION_DEVICE_ID = 89¶
- ACQUISITION_FREQUENCY_FILTER = 91¶
- ACQUISITION_INPUT_IMPEDANCE = 88¶
- ACQUISITION_OFFSET_OF_SCOPE = 87¶
- ACQUISITION_RANGE_FILTER = 92¶
- ACQUISITION_RANGE_OF_SCOPE = 85¶
- ACQUISITION_TYPE_FILTER = 90¶
- DESCRIPTION = 71¶
- EXTERNAL_CLOCK_BASE = 103¶
- EXTERNAL_CLOCK_FREQUENCY = 102¶
- EXTERNAL_CLOCK_MULTIPLIER = 98¶
- EXTERNAL_CLOCK_PHASE_SHIFT = 99¶
- EXTERNAL_CLOCK_RESAMPLER_ENABLED = 101¶
- EXTERNAL_CLOCK_RESAMPLER_MASK = 100¶
- EXTERNAL_CLOCK_THRESHOLD = 97¶
- EXTERNAL_CLOCK_USED = 96¶
- GO_LAST_TRACE = 106¶
- INPUT_LENGTH = 110¶
- INPUT_OFFSET = 107¶
- KEY_LENGTH = 112¶
- KEY_OFFSET = 109¶
- LABEL_X = 73¶
- LABEL_Y = 74¶
- LENGTH_DATA = 68¶
- LOGARITHMIC_SCALE = 78¶
- NUMBER_OF_ENABLED_CHANNELS = 113¶
- NUMBER_OF_USED_OSCILLOSCOPES = 114¶
- NUMBER_SAMPLES = 66¶
- NUMBER_TRACES = 65¶
- NUMBER_VIEW = 104¶
- OFFSET_X = 72¶
- OUTPUT_LENGTH = 111¶
- OUTPUT_OFFSET = 108¶
- SAMPLE_CODING = 67¶
- SCALE_X = 75¶
- SCALE_Y = 76¶
- TITLE_SPACE = 69¶
- TRACE_BLOCK = 95¶
- TRACE_OFFSET = 77¶
- TRACE_OVERLAP = 105¶
- TRACE_PARAMETER_DEFINITIONS = 119¶
- TRACE_SET_PARAMETERS = 118¶
- TRACE_TITLE = 70¶
- TRS_VERSION = 79¶
- XY_MEASUREMENTS_PER_SPOT = 117¶
- XY_SCAN_HEIGHT = 116¶
- XY_SCAN_WIDTH = 115¶
- class trsfile.common.SampleCoding(value)[source]¶
Bases:
Enum
Defines the encoding of all the samples in the trace. Bit 4 specifies if it is a float (1) or an integer (0), bits 0 to 3 specifies the length of the value. Finally, bits 5-7 are currently reserved and set to 000.
This class is just a simple lookup table.
- BYTE = 1¶
- FLOAT = 20¶
- INT = 4¶
- SHORT = 2¶
- property is_float¶
- class trsfile.common.TracePadding(value)[source]¶
Bases:
Enum
Defines the padding mode of the samples in each trace. This can be helpful when not all traces will be the same length. This can be set in
trsfile.open()
,trsfile.trs_open()
Mode
Description
NONE
No padding will be used and an exception will be thrown when traces are not of the same length.
PAD
All traces will be padded with zeroes to the maximum trace length.
TRUNCATE
All traces will be truncated to the minimum trace length.
AUTO
Traces will be clipped or padded in the best possible way the storage engine supports. This could mean data is lost which because retroactive padding is not supported.
- AUTO = 3¶
- NONE = 0¶
- PAD = 1¶
- TRUNCATE = 2¶
Trace¶
- class trsfile.trace.Trace(sample_coding, samples, parameters=None, title='trace', headers=None, raw_data: bytes = b'')[source]¶
Bases:
object
The
Trace
class behaves like alist
object were each item in the list is a sample of the trace.When a
Trace
is initialized the samples are (optionally) converted to anumpy.array
depending on the current type of the samples and the providedsample_coding
.
TraceSet¶
Storage Engines¶
The TraceSet behaves like a list (it is a list of Traces). Each Trace also behaves like a list (it is a list of samples). This is all on a conceptual level and the storage engine specifies how this conceptual model is translated to a specific file format. This behavior also makes it easy to convert from any (supported) file format to another one.
TrsEngine¶
- class trsfile.engine.trs.TrsEngine(path, mode='x', **options)[source]¶
Bases:
Engine
This engine supports .trs files from Riscure as specified in the “Trace set coding” document in Inspector.
This engine supports the following options:
Option
Description
headers
Dictionary containing zero or more headers, see
trsfile.common.Header
live_update
Performs live update of the TRS file every N traces. True for updating after every trace and False for never.
padding_mode
Padding mode to use. The supported values are:
trsfile.common.TracePadding.NONE
(default)trsfile.common.TracePadding.AUTO
- get_traces(index: Union[slice, int]) List[Trace] [source]¶
Retrieves zero or more traces from the trace set
- is_closed()[source]¶
Returns if the file backing the trace set is closed
- Returns:
True if the file is closed, otherwise False
- Return type:
boolean
- length()[source]¶
Returns the total number of traces
- Returns:
total number of traces
- Return type:
int
- set_traces(index: Union[slice, int], traces: List[Trace]) None [source]¶
Inserts zero or more traces into the trace set
FileEngine¶
- class trsfile.engine.file.FileEngine(path, mode='x', **options)[source]¶
Bases:
Engine
This engine tries to save traces to disk in the most versatile and simple manner available. No known tools support this file format and serve only as an intermediate step to later convert it to a supported format.
This is can be useful when the trace length (number of samples) varies as this is often not supported in trace files.
After acquisition, the file can be converted to the proper format with the correct padding mode.
This engine supports the following options:
Option
Description
headers
Dictionary containing zero or more headers, see
trsfile.common.Header
- INFO_FILE = 'traceset.pickle'¶
- close()[source]¶
Closes the file backing the trace set. It also could perform the final writes to synchronize the file with the trace set.
- Returns:
None
- del_traces(index)[source]¶
Deletes zero or more traces from the trace set
- Parameters:
index (slice, int) – the slice or index that specifies which traces to delete
- Returns:
None
- is_closed()[source]¶
Returns if the file backing the trace set is closed
- Returns:
True if the file is closed, otherwise False
- Return type:
boolean
- length()[source]¶
Returns the total number of traces
- Returns:
total number of traces
- Return type:
int
Engine¶
- class trsfile.engine.engine.Engine(path, mode='x', **options)[source]¶
Bases:
object
- close()[source]¶
Closes the file backing the trace set. It also could perform the final writes to synchronize the file with the trace set.
- Returns:
None
- del_traces(index)[source]¶
Deletes zero or more traces from the trace set
- Parameters:
index (slice, int) – the slice or index that specifies which traces to delete
- Returns:
None
- is_closed()[source]¶
Returns if the file backing the trace set is closed
- Returns:
True if the file is closed, otherwise False
- Return type:
boolean
- is_read_only()[source]¶
Returns if the trace set is read-only
- Returns:
True if the file is read-only, otherwise False
- Return type:
boolean
- length()[source]¶
Returns the total number of traces
- Returns:
total number of traces
- Return type:
int
- read_only = False¶