# Inspector Trace Set `.trs` file support in Python
[](https://app.travis-ci.com/Riscure/python-trsfile)
[](https://trsfile.readthedocs.io/)
Riscure Inspector uses the `.trs` file format to save and read traces from disk. To better assist reading and writing trace set files from third parties, Riscure published this Python library.
## Quick start
This library supports reading and writing of `.trs` files, but it does not (*yet*) support modifying existing `.trs` files. Both the `TraceSet` and the `Trace` class emulate all the functionality of a `list`, so slice to your heart's content!
### Installation
This library is available on [PyPi](https://www.pypi.org/project/trsfile/) for Python 3 and up. Just add `trsfile` to your `requirements.txt` or install it via the command line:
```shell
pip install trsfile
```
### TRS version 2: Trace (Set) Parameters
As of release 2.0, two additional provisions were added to the .trs format: Trace Set Parameters and Trace Parameters. These can be used to add supplementary (meta)data to your trace set in a structured, yet flexible way. Note that TRS V2 is backwards compatible with TRS V1. However, as can be expected, the additional information will not be available when using a pre-V2 reader.
### Trace Set Parameters
Trace Set Parameters are user-defined key value pairs that can be used to save global information about the trace set. The following types of data can be used (also see trsfile.traceparameter):
BYTE: 1 byte integer
SHORT: 2 byte integer
INT: 4 byte integer
FLOAT: 4 byte floating point
LONG: 8 byte integer
DOUBLE: 8 byte floating point
STRING: UTF-8 encoded string value
Each type is handled as a list (array) of values, including single values, so please make sure to supply these as such. Also note that all numeric values except for bytes are encoded and decoded as a _signed_ value.
#### Using Trace Set Parameters
Global parameters can be added by creating a `TraceSetParameterMap` object when creating a trace set. This object behaves like a dictionary, although the trs format dictates that keys must always be strings and values any of the supported parameter types. The following python code shows an example:
```python
from trsfile.parametermap import TraceSetParameterMap
import trsfile.traceparameter as tp
parameters = TraceSetParameterMap()
parameters['BYTES'] = tp.ByteArrayParameter([0, 1, 255])
parameters['SHORTS'] = tp.ShortArrayParameter([1, 1337, -32768, 32767])
parameters['INTS'] = tp.IntegerArrayParameter([42, int(1e6)])
parameters['FLOATS'] = tp.FloatArrayParameter([0.1, 0.2, 0.3])
parameters['LONGS'] = tp.LongArrayParameter([0x7fffffffffffffff])
parameters['DOUBLES'] = tp.DoubleArrayParameter([3.1415926535, 2.718281828])
parameters['STRINGS'] = tp.StringParameter('Lorem ipsum dolor')
```
### Trace Parameters
Trace Parameters behave very similar to Trace Set Parameters from a user perspective. They are values that can be added to _every_ trace, describing specific values that can vary between traces. The data types that can be used are the same as for Trace Set Parameters. However, there are several details that are different:
1. The length of the added information *must* be the same for every trace, due to the way in which trs files are stored. This means that the first trace added to the trace set dictates the length of both arrays _and_ strings. If a longer string is added later, it will result in a corrupted trace set.
2. The length of every parameter is saved in the header at creation time, in a structure called `TraceParameterDefinitionMap`. This structure is used when reading out the traces to determine the structure of the included data, and must therefore be consistent with the actual trace parameters to create a valid trace set. This information is _not_ added to the individual traces themselves.
3. Going forward, there will be pre-defined tags used to mark important information:
- SAMPLES: An alternative for saving the samples of a trace. This may in the future replace the predefined trace structure of title-data-samples.
- TITLE: An alternative for saving the title of a trace. This may in the future replace the predefined trace structure of title-data-samples.
#### Using Trace Parameters
Local parameters can be added by creating a `TraceParameters` object when creating a trace. The following java code shows an example:
```python
from trsfile import Trace, SampleCoding
from trsfile.parametermap import TraceParameterMap
import trsfile.traceparameter as tp
parameters = TraceParameterMap()
parameters["BYTE"] = tp.ByteArrayParameter([1, 2, 4, 8])
parameters["INT"] = tp.IntegerArrayParameter([42])
parameters["DOUBLE"] = tp.DoubleArrayParameter([3.14, 1.618])
parameters["STRING"] = tp.StringParameter("A string")
Trace(SampleCoding.FLOAT, list(range(100)), parameters, "trace title")
```
Note that the previously mentioned `TraceParameterDefinitionMap` must created consistent with the above parameters and added to the headers:
```python
from trsfile import Header, trs_open
from trsfile.parametermap import TraceParameterDefinitionMap
from trsfile.traceparameter import ParameterType, TraceParameterDefinition
definitions = TraceParameterDefinitionMap()
definitions["BYTE"] = TraceParameterDefinition(ParameterType.BYTE, 4, 0)
definitions["INT"] = TraceParameterDefinition(ParameterType.INT, 1, 4)
definitions["DOUBLE"] = TraceParameterDefinition(ParameterType.DOUBLE, 1, 8)
definitions["STRING"] = TraceParameterDefinition(ParameterType.STRING, 8, 16)
with trs_open('trace-set.trs', 'w',
headers = {Header.TRACE_PARAMETER_DEFINITIONS: definitions}):
pass
```
See below for a more elaborate example on creating trace sets with parameters.
### Reading `.trs` files
```python
import trsfile
with trsfile.open('trace-set.trs', 'r') as traces:
# Show all headers
for header, value in traces.get_headers().items():
print(header, '=', value)
print()
# Iterate over the first 25 traces
for i, trace in enumerate(traces[0:25]):
print('Trace {0:d} contains {1:d} samples'.format(i, len(trace)))
print(' - minimum value in trace: {0:f}'.format(min(trace)))
print(' - maximum value in trace: {0:f}'.format(max(trace)))
```
### Creating `.trs` files
```python
import random, os
from trsfile import trs_open, Trace, SampleCoding, TracePadding, Header
from trsfile.parametermap import TraceParameterMap, TraceParameterDefinitionMap
from trsfile.traceparameter import ByteArrayParameter, ParameterType, TraceParameterDefinition
with trs_open(
'trace-set.trs', # File name of the trace set
'w', # Mode: r, w, x, a (default to x)
# Zero or more options can be passed (supported options depend on the storage engine)
engine = 'TrsEngine', # Optional: how the trace set is stored (defaults to TrsEngine)
headers = { # Optional: headers (see Header class)
Header.TRS_VERSION: 2,
Header.SCALE_X: 1e-6,
Header.SCALE_Y: 0.1,
Header.DESCRIPTION: 'Testing trace creation',
Header.TRACE_PARAMETER_DEFINITIONS: TraceParameterDefinitionMap(
{'parameter': TraceParameterDefinition(ParameterType.BYTE, 16, 0)})
},
padding_mode = TracePadding.AUTO,# Optional: padding mode (defaults to TracePadding.AUTO)
live_update = True # Optional: updates the TRS file for live preview (small performance hit)
# 0 (False): Disabled (default)
# 1 (True) : TRS file updated after every trace
# N : TRS file is updated after N traces
) as traces:
# Extend the trace file with 100 traces with each 1000 samples
traces.extend([
Trace(
SampleCoding.FLOAT,
[random.uniform(-255, 255) for _ in range(0, 1000)],
TraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))})
)
for _ in range(0, 100)]
)
# Replace 5 traces (the slice [0:10:2]) with random length traces.
# Because we are creating using the TracePadding.PAD mode, all traces
# will be clipped or padded on the first trace length
traces[0:10:2] = [
Trace(
SampleCoding.FLOAT,
[random.uniform(0, 255) for _ in range(0, random.randrange(1000))],
TraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))}),
title = 'Clipped trace'
)
for _ in range(0, 5)
]
# Adding one Trace
traces.append(
Trace(
SampleCoding.FLOAT,
[random.uniform(-255, 255) for _ in range(0, 1000)],
TraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))})
)
)
# We cannot delete traces with the TrsEngine, other engines do support this feature
#del traces[40:50]
# We can only change headers with a value that has the same length as the previous value
# with the TrsEngine, other engines can support dynamically adding, deleting or changing
# headers.
#traces.update_header(Header.LABEL_X, 'Time')
#traces.update_header(Header.LABEL_Y, 'Voltage')
#traces.update_header(Header.DESCRIPTION, 'Traces created for some purpose!')
print('Total length of new trace set: {0:d}'.format(len(traces)))
```
### Converting `TraceSet` from one type to another
```python
import trsfile
with \
trsfile.open(
'trace-set', # Previously create trace set
'r', # Read only mode
engine='FileEngine' # Using the FileEngine
) as traces, \
trsfile.open( # Note: TrsEngine is the default
'trace-set.trs', # Name of the new trace set
'w', # Write mode
headers=traces.get_headers() # Copy the headers
) as new_traces:
new_traces.extend(traces) # Extend the new trace set with the
# traces from the old trace set
```
## Documentation
The full documentation is available in the `docs` folder with a readable version on [Read the Docs](https://trsfile.readthedocs.io/).
## Contributing
### Testing
The library supports Python `unittest` module and the tests can be executed with the following command:
```
python -m unittest
```
### Creating Releases
We use Github Actions to publish packages to PYPy. Read the [Github docs on how to create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) and trigger the publishing workflow:
## License
[BSD 3-Clause Clear License](https://choosealicense.com/licenses/bsd-3-clause-clear/)
Raw data
{
"_id": null,
"home_page": "https://github.com/riscure/python-trsfile",
"name": "trsfile",
"maintainer": "Riscure",
"docs_url": null,
"requires_python": "",
"maintainer_email": "inforequest@riscure.com",
"keywords": "trs,trace,inspector,riscure",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/e4/bc/990cd61d4396dee1826526099ffce7eb8d0e9ba0a75cbb836dd937b90cdd/trsfile-2.2.1.tar.gz",
"platform": null,
"description": "# Inspector Trace Set `.trs` file support in Python\n[](https://app.travis-ci.com/Riscure/python-trsfile)\n[](https://trsfile.readthedocs.io/)\n\nRiscure Inspector uses the `.trs` file format to save and read traces from disk. To better assist reading and writing trace set files from third parties, Riscure published this Python library.\n\n## Quick start\nThis library supports reading and writing of `.trs` files, but it does not (*yet*) support modifying existing `.trs` files. Both the `TraceSet` and the `Trace` class emulate all the functionality of a `list`, so slice to your heart's content!\n\n### Installation\nThis library is available on [PyPi](https://www.pypi.org/project/trsfile/) for Python 3 and up. Just add `trsfile` to your `requirements.txt` or install it via the command line:\n```shell\npip install trsfile\n```\n\n### TRS version 2: Trace (Set) Parameters\nAs of release 2.0, two additional provisions were added to the .trs format: Trace Set Parameters and Trace Parameters. These can be used to add supplementary (meta)data to your trace set in a structured, yet flexible way. Note that TRS V2 is backwards compatible with TRS V1. However, as can be expected, the additional information will not be available when using a pre-V2 reader.\n\n### Trace Set Parameters\nTrace Set Parameters are user-defined key value pairs that can be used to save global information about the trace set. The following types of data can be used (also see trsfile.traceparameter):\n\n BYTE: 1 byte integer\n SHORT: 2 byte integer\n INT: 4 byte integer\n FLOAT: 4 byte floating point\n LONG: 8 byte integer\n DOUBLE: 8 byte floating point\n STRING: UTF-8 encoded string value\n\nEach type is handled as a list (array) of values, including single values, so please make sure to supply these as such. Also note that all numeric values except for bytes are encoded and decoded as a _signed_ value.\n\n#### Using Trace Set Parameters\nGlobal parameters can be added by creating a `TraceSetParameterMap` object when creating a trace set. This object behaves like a dictionary, although the trs format dictates that keys must always be strings and values any of the supported parameter types. The following python code shows an example:\n```python\nfrom trsfile.parametermap import TraceSetParameterMap\nimport trsfile.traceparameter as tp\n\nparameters = TraceSetParameterMap()\nparameters['BYTES'] = tp.ByteArrayParameter([0, 1, 255])\nparameters['SHORTS'] = tp.ShortArrayParameter([1, 1337, -32768, 32767]) \nparameters['INTS'] = tp.IntegerArrayParameter([42, int(1e6)]) \nparameters['FLOATS'] = tp.FloatArrayParameter([0.1, 0.2, 0.3]) \nparameters['LONGS'] = tp.LongArrayParameter([0x7fffffffffffffff])\nparameters['DOUBLES'] = tp.DoubleArrayParameter([3.1415926535, 2.718281828])\nparameters['STRINGS'] = tp.StringParameter('Lorem ipsum dolor')\n``` \n\n### Trace Parameters\nTrace Parameters behave very similar to Trace Set Parameters from a user perspective. They are values that can be added to _every_ trace, describing specific values that can vary between traces. The data types that can be used are the same as for Trace Set Parameters. However, there are several details that are different:\n\n1. The length of the added information *must* be the same for every trace, due to the way in which trs files are stored. This means that the first trace added to the trace set dictates the length of both arrays _and_ strings. If a longer string is added later, it will result in a corrupted trace set.\n2. The length of every parameter is saved in the header at creation time, in a structure called `TraceParameterDefinitionMap`. This structure is used when reading out the traces to determine the structure of the included data, and must therefore be consistent with the actual trace parameters to create a valid trace set. This information is _not_ added to the individual traces themselves.\n3. Going forward, there will be pre-defined tags used to mark important information:\n - SAMPLES: An alternative for saving the samples of a trace. This may in the future replace the predefined trace structure of title-data-samples.\n - TITLE: An alternative for saving the title of a trace. This may in the future replace the predefined trace structure of title-data-samples.\n\n#### Using Trace Parameters\nLocal parameters can be added by creating a `TraceParameters` object when creating a trace. The following java code shows an example:\n```python\nfrom trsfile import Trace, SampleCoding\nfrom trsfile.parametermap import TraceParameterMap\nimport trsfile.traceparameter as tp\n\nparameters = TraceParameterMap()\nparameters[\"BYTE\"] = tp.ByteArrayParameter([1, 2, 4, 8])\nparameters[\"INT\"] = tp.IntegerArrayParameter([42])\nparameters[\"DOUBLE\"] = tp.DoubleArrayParameter([3.14, 1.618])\nparameters[\"STRING\"] = tp.StringParameter(\"A string\")\nTrace(SampleCoding.FLOAT, list(range(100)), parameters, \"trace title\")\n```\n\nNote that the previously mentioned `TraceParameterDefinitionMap` must created consistent with the above parameters and added to the headers:\n```python\nfrom trsfile import Header, trs_open\nfrom trsfile.parametermap import TraceParameterDefinitionMap\nfrom trsfile.traceparameter import ParameterType, TraceParameterDefinition\n\ndefinitions = TraceParameterDefinitionMap()\ndefinitions[\"BYTE\"] = TraceParameterDefinition(ParameterType.BYTE, 4, 0)\ndefinitions[\"INT\"] = TraceParameterDefinition(ParameterType.INT, 1, 4)\ndefinitions[\"DOUBLE\"] = TraceParameterDefinition(ParameterType.DOUBLE, 1, 8)\ndefinitions[\"STRING\"] = TraceParameterDefinition(ParameterType.STRING, 8, 16)\n\nwith trs_open('trace-set.trs', 'w',\n headers = {Header.TRACE_PARAMETER_DEFINITIONS: definitions}):\n pass\n```\nSee below for a more elaborate example on creating trace sets with parameters.\n\n### Reading `.trs` files\n```python\nimport trsfile\n\nwith trsfile.open('trace-set.trs', 'r') as traces:\n\t# Show all headers\n\tfor header, value in traces.get_headers().items():\n\t\tprint(header, '=', value)\n\tprint()\n\n\t# Iterate over the first 25 traces\n\tfor i, trace in enumerate(traces[0:25]):\n\t\tprint('Trace {0:d} contains {1:d} samples'.format(i, len(trace)))\n\t\tprint(' - minimum value in trace: {0:f}'.format(min(trace)))\n\t\tprint(' - maximum value in trace: {0:f}'.format(max(trace)))\n```\n\n### Creating `.trs` files\n```python\nimport random, os\nfrom trsfile import trs_open, Trace, SampleCoding, TracePadding, Header\nfrom trsfile.parametermap import TraceParameterMap, TraceParameterDefinitionMap\nfrom trsfile.traceparameter import ByteArrayParameter, ParameterType, TraceParameterDefinition\n\nwith trs_open(\n\t\t'trace-set.trs', # File name of the trace set\n\t\t'w', # Mode: r, w, x, a (default to x)\n\t\t# Zero or more options can be passed (supported options depend on the storage engine)\n\t\tengine = 'TrsEngine', # Optional: how the trace set is stored (defaults to TrsEngine)\n\t\theaders = { # Optional: headers (see Header class)\n\t\t\tHeader.TRS_VERSION: 2,\n\t\t\tHeader.SCALE_X: 1e-6,\n\t\t\tHeader.SCALE_Y: 0.1,\n\t\t\tHeader.DESCRIPTION: 'Testing trace creation',\n\t\t\tHeader.TRACE_PARAMETER_DEFINITIONS: TraceParameterDefinitionMap(\n\t\t\t\t{'parameter': TraceParameterDefinition(ParameterType.BYTE, 16, 0)})\n\t\t},\n\t\tpadding_mode = TracePadding.AUTO,# Optional: padding mode (defaults to TracePadding.AUTO)\n\t\tlive_update = True # Optional: updates the TRS file for live preview (small performance hit)\n\t\t # 0 (False): Disabled (default)\n\t\t # 1 (True) : TRS file updated after every trace\n\t\t # N : TRS file is updated after N traces\n\t) as traces:\n\t# Extend the trace file with 100 traces with each 1000 samples\n\ttraces.extend([\n\t\tTrace(\n\t\t\tSampleCoding.FLOAT,\n\t\t\t[random.uniform(-255, 255) for _ in range(0, 1000)],\n\t\t\tTraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))})\n\t\t)\n\t\tfor _ in range(0, 100)]\n\t)\n\n\t# Replace 5 traces (the slice [0:10:2]) with random length traces.\n\t# Because we are creating using the TracePadding.PAD mode, all traces\n\t# will be clipped or padded on the first trace length\n\ttraces[0:10:2] = [\n\t\tTrace(\n\t\t\tSampleCoding.FLOAT,\n\t\t\t[random.uniform(0, 255) for _ in range(0, random.randrange(1000))],\n\t\t\tTraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))}),\n\t\t\ttitle = 'Clipped trace'\n\t\t)\n\t\tfor _ in range(0, 5)\n\t]\n\n\t# Adding one Trace\n\ttraces.append(\n\t\tTrace(\n\t\t\tSampleCoding.FLOAT,\n\t\t\t[random.uniform(-255, 255) for _ in range(0, 1000)],\n\t\t\tTraceParameterMap({'parameter': ByteArrayParameter(os.urandom(16))})\n\t\t)\n\t)\n\n\t# We cannot delete traces with the TrsEngine, other engines do support this feature\n\t#del traces[40:50]\n\n\t# We can only change headers with a value that has the same length as the previous value\n\t# with the TrsEngine, other engines can support dynamically adding, deleting or changing\n\t# headers.\n\t#traces.update_header(Header.LABEL_X, 'Time')\n\t#traces.update_header(Header.LABEL_Y, 'Voltage')\n\t#traces.update_header(Header.DESCRIPTION, 'Traces created for some purpose!')\n\n\tprint('Total length of new trace set: {0:d}'.format(len(traces)))\n```\n\n### Converting `TraceSet` from one type to another\n```python\nimport trsfile\n\nwith \\\n\ttrsfile.open(\n\t\t'trace-set', # Previously create trace set\n\t\t'r', # Read only mode\n\t\tengine='FileEngine' # Using the FileEngine\n\t) as traces, \\\n\ttrsfile.open( # Note: TrsEngine is the default\n\t\t'trace-set.trs', # Name of the new trace set\n\t\t'w', # Write mode\n\t\theaders=traces.get_headers() # Copy the headers\n\t) as new_traces:\n\tnew_traces.extend(traces) # Extend the new trace set with the\n\t # traces from the old trace set\n```\n\n## Documentation\nThe full documentation is available in the `docs` folder with a readable version on [Read the Docs](https://trsfile.readthedocs.io/).\n\n## Contributing\n\n### Testing\nThe library supports Python `unittest` module and the tests can be executed with the following command:\n```\npython -m unittest\n```\n\n### Creating Releases\nWe use Github Actions to publish packages to PYPy. Read the [Github docs on how to create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) and trigger the publishing workflow:\n\n## License\n[BSD 3-Clause Clear License](https://choosealicense.com/licenses/bsd-3-clause-clear/)\n",
"bugtrack_url": null,
"license": "BSD 3-Clause Clear License",
"summary": "Library to read and create Riscure Inspector trace set files (.trs)",
"version": "2.2.1",
"project_urls": {
"Bug Reports": "https://github.com/riscure/python-trsfile/issues",
"Documentation": "https://trsfile.readthedocs.io/en/latest",
"Homepage": "https://github.com/riscure/python-trsfile",
"Riscure": "https://www.riscure.com"
},
"split_keywords": [
"trs",
"trace",
"inspector",
"riscure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "474a69fc3841d08ff2fca58025636632c390ddb20f8baa1bba8ad46f842b1ca9",
"md5": "82539c141619f5265efb2468ecb85d41",
"sha256": "c3b1453cf656ccbea2d511106732a040220fbad08d6072720b776a1082e41a11"
},
"downloads": -1,
"filename": "trsfile-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "82539c141619f5265efb2468ecb85d41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 37281,
"upload_time": "2024-02-06T08:28:23",
"upload_time_iso_8601": "2024-02-06T08:28:23.373053Z",
"url": "https://files.pythonhosted.org/packages/47/4a/69fc3841d08ff2fca58025636632c390ddb20f8baa1bba8ad46f842b1ca9/trsfile-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e4bc990cd61d4396dee1826526099ffce7eb8d0e9ba0a75cbb836dd937b90cdd",
"md5": "f946c514f2f6e018f31324a154faaf81",
"sha256": "2020ba461048653fcf0adff6e922aa0a27404cade6bab8758814a701ba6efa4a"
},
"downloads": -1,
"filename": "trsfile-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "f946c514f2f6e018f31324a154faaf81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 225788,
"upload_time": "2024-02-06T08:28:24",
"upload_time_iso_8601": "2024-02-06T08:28:24.862728Z",
"url": "https://files.pythonhosted.org/packages/e4/bc/990cd61d4396dee1826526099ffce7eb8d0e9ba0a75cbb836dd937b90cdd/trsfile-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-06 08:28:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "riscure",
"github_project": "python-trsfile",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "trsfile"
}
JSON
