pyTelops 0.2.3__tar.gz → 0.2.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. {pytelops-0.2.3 → pytelops-0.2.5}/AGENTS.md +1 -1
  2. {pytelops-0.2.3 → pytelops-0.2.5}/PKG-INFO +2 -2
  3. {pytelops-0.2.3 → pytelops-0.2.5}/README.rst +97 -3
  4. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/camera.rst +16 -0
  5. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/changelog.rst +101 -0
  6. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/conf.py +1 -1
  7. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/examples.rst +10 -1
  8. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/index.rst +5 -0
  9. pytelops-0.2.5/docs/source/streaming_and_buffer.rst +441 -0
  10. {pytelops-0.2.3 → pytelops-0.2.5}/examples/03_buffer_record.py +2 -0
  11. {pytelops-0.2.3 → pytelops-0.2.5}/examples/05_external_trigger.py +10 -0
  12. pytelops-0.2.5/examples/08_pretrigger_software_moi.py +127 -0
  13. {pytelops-0.2.3 → pytelops-0.2.5}/examples/README.rst +2 -0
  14. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/__init__.py +15 -1
  15. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/camera.py +828 -69
  16. pytelops-0.2.5/pyTelops/header.py +483 -0
  17. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/registers.py +0 -2
  18. {pytelops-0.2.3 → pytelops-0.2.5}/pyproject.toml +1 -1
  19. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_camera.py +770 -1
  20. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_hardware.py +66 -4
  21. pytelops-0.2.5/tests/test_header.py +352 -0
  22. pytelops-0.2.3/docs/source/streaming_and_buffer.rst +0 -237
  23. {pytelops-0.2.3 → pytelops-0.2.5}/.gitignore +0 -0
  24. {pytelops-0.2.3 → pytelops-0.2.5}/CONTRIBUTING.rst +0 -0
  25. {pytelops-0.2.3 → pytelops-0.2.5}/LICENSE +0 -0
  26. {pytelops-0.2.3 → pytelops-0.2.5}/PYPI_README.rst +0 -0
  27. {pytelops-0.2.3 → pytelops-0.2.5}/docs/requirements.txt +0 -0
  28. {pytelops-0.2.3 → pytelops-0.2.5}/docs/rtd_postbuild.py +0 -0
  29. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/_static/.gitkeep +0 -0
  30. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/_static/ai-buttons.css +0 -0
  31. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/_static/ai-buttons.js +0 -0
  32. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/_static/logo.png +0 -0
  33. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/calibration.rst +0 -0
  34. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/getting_started.rst +0 -0
  35. {pytelops-0.2.3 → pytelops-0.2.5}/docs/source/troubleshooting.rst +0 -0
  36. {pytelops-0.2.3 → pytelops-0.2.5}/examples/01_connect_and_grab.py +0 -0
  37. {pytelops-0.2.3 → pytelops-0.2.5}/examples/02_continuous_live.py +0 -0
  38. {pytelops-0.2.3 → pytelops-0.2.5}/examples/04_calibration_load.py +0 -0
  39. {pytelops-0.2.3 → pytelops-0.2.5}/examples/06_force_ip.py +0 -0
  40. {pytelops-0.2.3 → pytelops-0.2.5}/examples/07_robust_download.py +0 -0
  41. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/cli.py +0 -0
  42. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/connection.py +0 -0
  43. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/errors.py +0 -0
  44. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/gui.py +0 -0
  45. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/provisioning.py +0 -0
  46. {pytelops-0.2.3 → pytelops-0.2.5}/pyTelops/py.typed +0 -0
  47. {pytelops-0.2.3 → pytelops-0.2.5}/requirements.dev.txt +0 -0
  48. {pytelops-0.2.3 → pytelops-0.2.5}/requirements.txt +0 -0
  49. {pytelops-0.2.3 → pytelops-0.2.5}/sync_version.py +0 -0
  50. {pytelops-0.2.3 → pytelops-0.2.5}/tests/conftest.py +0 -0
  51. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_cli.py +0 -0
  52. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_connection.py +0 -0
  53. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_discovery_reachability.py +0 -0
  54. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_download_integrity.py +0 -0
  55. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_enum_resolution.py +0 -0
  56. {pytelops-0.2.3 → pytelops-0.2.5}/tests/test_registers.py +0 -0
@@ -71,7 +71,7 @@ hardware tests, or camera discovery fails. See troubleshooting.md.
71
71
  ```
72
72
  pyTelops/ driver package: camera.py, registers.py, cli.py, gui.py
73
73
  tests/ pytest suite (test_hardware.py is camera-gated)
74
- examples/ runnable scripts (01_connect_and_grab.py ... 07_robust_download.py)
74
+ examples/ runnable scripts (01_connect_and_grab.py ... 08_pretrigger_software_moi.py)
75
75
  docs/source/ Sphinx docs (RST source)
76
76
  ```
77
77
 
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: pyTelops
3
- Version: 0.2.3
3
+ Version: 0.2.5
4
4
  Summary: Pure-Python driver for Telops thermal cameras over GigE Vision
5
5
  Project-URL: Homepage, https://github.com/ladisk/pyTelops
6
6
  Project-URL: Documentation, https://pytelops.readthedocs.io
@@ -22,6 +22,11 @@ Pure-Python driver for `Telops <https://www.telops.com/>`_ thermal cameras
22
22
  over GigE Vision. No vendor SDK required; communicates directly via GVCP/GVSP
23
23
  protocols over UDP.
24
24
 
25
+ .. image:: hero.gif
26
+ :alt: pyTelops demo: discover and connect to the camera, open a live thermal
27
+ view with cam.live_view(), then record to the camera buffer and
28
+ download the frames
29
+
25
30
  pyTelops is built on `pyGigEVision <https://github.com/ladisk/pyGigEVision>`_,
26
31
  which provides the GigE Vision protocol layer (GVCP control and GVSP
27
32
  streaming). pyTelops adds the Telops-specific calibration, register map, and
@@ -272,7 +277,7 @@ slots before recording:
272
277
 
273
278
  ``buffer_record()`` prints progress::
274
279
 
275
- Arming (seq 1/3)... Recording... Done (10000 frames)
280
+ Arming (seq 1/3)... Waiting for ring buffer (2.0 s)... Recording... Done (10000 frames)
276
281
  Firing (seq 2/3)... Recording... Done (10000 frames)
277
282
  Firing (seq 3/3)... Recording... Done (10000 frames)
278
283
 
@@ -287,6 +292,88 @@ If a download finishes with missing frames, ``buffer_download()`` raises
287
292
  <https://pytelops.readthedocs.io/en/latest/streaming_and_buffer.html>`_ for
288
293
  tolerating drops and inspecting ``cam.last_download_stats``.
289
294
 
295
+ Pre-trigger recording (pre-MOI)
296
+ -------------------------------
297
+
298
+ The armed camera fills the buffer as a ring. The MOI (moment of interest)
299
+ marks the split: the ``pre_moi`` frames before it and the rest of the sequence
300
+ after it are kept. Fire the MOI at the event, not right after arming, or the
301
+ pre-trigger window holds fewer frames than configured.
302
+
303
+ The ring keeps nothing for the first 2.02 s after acquisition starts. A MOI
304
+ fired inside that window is latched, but the sequence then starts at the first
305
+ frame the ring could keep, so the pre-trigger part is truncated.
306
+ ``buffer_arm()`` therefore blocks until the ring holds the configured
307
+ ``pre_moi`` frames, about 2 s plus ``pre_moi / frame_rate``. Pass
308
+ ``wait_ready=False`` to return at once, and use ``buffer_ready_in()`` or
309
+ ``buffer_wait_ready()`` if you schedule the event yourself. This is measured
310
+ with a software MOI; the same is expected for an external trigger, so send the
311
+ trigger after ``buffer_arm()`` returns.
312
+
313
+ ``pre_moi`` can be as large as ``frames_per_seq``. The whole slot is then
314
+ pre-trigger and the MOI lands on its last frame, at index
315
+ ``frames_per_seq - 1``.
316
+
317
+ ``buffer_record()`` is a shortcut over ``buffer_arm()``, ``buffer_fire_moi()``
318
+ and ``buffer_wait()``, and takes the waiting step as ``wait_for``: a delay in
319
+ seconds, or a callable that returns at the event. Every variant waits for the
320
+ ring buffer first.
321
+
322
+ .. code-block:: python
323
+
324
+ cam.buffer_configure(frames_per_seq=400, pre_moi=100) # frames, not seconds
325
+
326
+ cam.buffer_record(wait_for=0.5) # 0.5 s after the ring is ready
327
+ cam.buffer_record(wait_for=lambda: my_event.wait())
328
+
329
+ # or drive the same flow yourself
330
+ cam.buffer_arm() # blocks about 2.1 s at 2000 fps
331
+ wait_for_my_event()
332
+ cam.buffer_fire_moi()
333
+ cam.buffer_wait(timeout=30.0)
334
+ data = cam.buffer_download()
335
+
336
+ With ``pre_moi > 0`` and no ``wait_for``, ``buffer_record()`` warns and fires
337
+ the MOI as soon as the ring is ready, because the split point is then set by a
338
+ timer and not by an event. Pass ``wait_for=0`` to silence the warning. See
339
+ ``examples/08_pretrigger_software_moi.py``.
340
+
341
+ Frame headers and timestamps
342
+ ----------------------------
343
+
344
+ Every frame carries a Telops header written by the camera at exposure time, so
345
+ its timestamp has no host-side delay. Call ``cam.sync_time()`` before recording
346
+ to put the camera clock on host time, then ask the download for the headers:
347
+
348
+ .. code-block:: python
349
+
350
+ cam.sync_time()
351
+ data, headers = cam.buffer_download(sequence=0, return_headers=True)
352
+
353
+ print(headers[0].datetime) # exposure time of the first frame, UTC
354
+ moi = cam.buffer_moi_index(0) # index of the moment of interest
355
+ if 0 <= moi < len(headers):
356
+ print(headers[moi].timestamp - headers[0].timestamp)
357
+
358
+ Entry ``i`` belongs to frame ``i`` of the array. For very large downloads use
359
+ ``header_timestamps(raw)`` on a raw download (``strip_header=False,
360
+ convert=False``) instead; it reads the same bytes without building an object
361
+ per frame.
362
+
363
+ ``sync_time()`` writes whole seconds, so absolute timestamps are good to about
364
+ 1 s. Differences between frames are exact. Sub-second alignment to the host
365
+ clock is not available from the driver yet: the camera sub-second register is
366
+ read-only, and ``cam.posix_time = ...`` also writes whole seconds only.
367
+
368
+ ``buffer_moi_index()`` is verified on the TS-IR: with the MOI fired after the
369
+ ring warm-up it equals the configured ``pre_moi``. It is the authority for the
370
+ split index. In the header timestamps the event sits about 7 to 8 ms later than
371
+ the host-side ``buffer_fire_moi()`` call, which is the GVCP command latency, so
372
+ do not derive the split from a host clock reading. The camera's MOI frame id
373
+ maps directly onto ``FrameHeader.frame_id``: in every campaign recording,
374
+ ``REG_MEMORY_BUFFER_SEQ_FIRST_FRAME_ID`` equalled ``headers[0].frame_id``, so
375
+ ``headers[buffer_moi_index()].frame_id`` equals ``buffer_moi_frame_id()``.
376
+
290
377
  External trigger
291
378
  ----------------
292
379
 
@@ -301,15 +388,22 @@ For triggered recording from an external BNC signal:
301
388
  pre_moi=1000,
302
389
  moi_source="external")
303
390
 
304
- cam.buffer_arm() # arm and wait for trigger
391
+ cam.buffer_arm() # blocks until the ring is ready
305
392
  cam.buffer_wait(timeout=60.0) # blocks until recording completes
306
393
  data = cam.buffer_download()
307
394
 
395
+ Send the trigger after ``buffer_arm()`` returns. An edge that arrives during
396
+ the ring warm-up is expected to behave like an early software MOI, that is
397
+ latched with a truncated pre-trigger part, but only the software MOI has been
398
+ measured. Check ``cam.buffer_moi_index(0)`` against the configured ``pre_moi``
399
+ afterwards.
400
+
308
401
  For manual control with software MOI (instead of ``buffer_record()``):
309
402
 
310
403
  .. code-block:: python
311
404
 
312
- cam.buffer_arm() # arm the buffer
405
+ cam.buffer_arm() # arm the buffer, wait for the ring
406
+ wait_for_my_event() # returns at the moment of interest
313
407
  cam.buffer_fire_moi() # software MOI trigger
314
408
  cam.buffer_wait(timeout=30.0) # wait for recording to finish
315
409
  data = cam.buffer_download()
@@ -32,6 +32,22 @@ Errors and results
32
32
  .. autoexception:: FrameIntegrityError
33
33
  :members:
34
34
 
35
+ Frame headers
36
+ -------------
37
+
38
+ .. autoclass:: FrameHeader
39
+ :members:
40
+
41
+ .. autoclass:: BufferingFlag
42
+
43
+ .. autofunction:: parse_header
44
+
45
+ .. autofunction:: parse_headers
46
+
47
+ .. autofunction:: header_timestamps
48
+
49
+ .. autofunction:: header_frame_ids
50
+
35
51
  Enumerations
36
52
  ------------
37
53
 
@@ -1,6 +1,107 @@
1
1
  Changelog
2
2
  =========
3
3
 
4
+ Version 0.2.5
5
+ -------------
6
+
7
+ - **Fixed:** ``grab()`` and ``acquire()`` could return a frame left over from a
8
+ previous session, still sitting in the GVSP receiver's queue. Right after a
9
+ setting change, such as switching ``calibration_mode``, the first grab or two
10
+ came back captured under the old setting (issue #21). Both methods now
11
+ discard queued and buffered residue before waiting for a frame: a full
12
+ receiver flush when the stream was not already running, or a non-blocking
13
+ drain of the output queue when it was.
14
+ - **Fixed:** ``Camera.temperature`` and ``info["temperature_c"]`` always read
15
+ 0.0 (issue #20). They read address 0xE970, which the camera's GenICam XML
16
+ defines as the external fan speed mode, not a temperature. Both now return
17
+ the detector temperature, the same as ``sensor_temperature("sensor")``. The
18
+ wrong ``registers.REG_DEVICE_TEMPERATURE`` constant is removed; use
19
+ ``REG_DEVICE_TEMPERATURE_SELECTOR`` and ``REG_DEVICE_TEMPERATURE_READOUT``.
20
+ - **Fixed:** ``diagnostics()`` reported the mainboard temperature as 0.0 on the
21
+ TS-IR, which has no mainboard sensor. A readout of exactly 0.0 now maps to
22
+ ``None``, like other unsupported locations.
23
+
24
+ Version 0.2.4
25
+ -------------
26
+
27
+ - **Pre-trigger recordings now keep the frames they were asked for.** The
28
+ camera's ring buffer keeps nothing for the first 2.02 s after acquisition
29
+ starts (measured on a TS-IR, the same at 250 and 1000 fps). A MOI fired
30
+ inside that window is latched, and the sequence then starts at the first
31
+ frame the ring could keep, so the pre-trigger part came out truncated or
32
+ empty. The driver now holds the MOI back until the ring can hold the
33
+ configured ``pre_moi`` frames: ``Camera.BUFFER_RING_WARMUP_S`` (2.05 s)
34
+ plus ``pre_moi / frame_rate`` after arming.
35
+ - ``buffer_arm()`` blocks until the ring buffer is ready, so about 2 s plus
36
+ ``pre_moi / frame_rate``. Pass ``wait_ready=False`` for the old immediate
37
+ return.
38
+ - ``buffer_record()`` and ``buffer_arm()`` now take about 1.5 s longer than in
39
+ 0.2.3 even with ``pre_moi=0``, because the ring dead time applies to the
40
+ sequence start as well.
41
+ - New ``buffer_ready_in()`` (seconds left of the ring warm-up, 0 when ready)
42
+ and ``buffer_wait_ready()`` (sleep that long), for callers that schedule the
43
+ event themselves.
44
+ - ``buffer_fire_moi()`` warns when it is called before the ring is ready, and
45
+ says how many pre-trigger frames the camera will actually keep. It reads no
46
+ registers, so the event path is a single register write.
47
+ - ``buffer_fire_moi()`` raises ``RuntimeError`` when ``buffer_arm()`` was not
48
+ called first. The camera rejects the write while it is not acquiring, so the
49
+ old silent write did nothing.
50
+ - ``buffer_arm()`` and ``buffer_record()`` write ``ACQUISITION_STOP`` before
51
+ ``ACQUISITION_ARM``, and raise ``RuntimeError`` if the buffer still reads
52
+ RECORDING 5 s later. The stop write is unconditional, so an unreadable status
53
+ register no longer lets the guard pass. Arming during a recording aborts it:
54
+ the status drops to IDLE, the recorded count stays 0 and the sequence counter
55
+ sticks at 0 until ``buffer_clear()``.
56
+ - ``buffer_configure()`` warns when ``moi_source="acquisition_started"`` is
57
+ combined with ``pre_moi > 0``. That MOI fires inside the ring dead time, so
58
+ the pre-trigger window is always empty.
59
+ - Verified on hardware (TS-IR, header 12.7): with the MOI fired after the ring
60
+ warm-up, ``buffer_moi_index()`` equals the configured ``pre_moi``, for every
61
+ sequence of a three-sequence recording at 1000 and 2000 fps. Frame ids are
62
+ contiguous and ``buffering_flag`` is ``None``, as expected below header 12.9.
63
+ In the header timestamps the event sits about 7 to 8 ms after the host-side
64
+ ``buffer_fire_moi()`` call, which is the GVCP command latency, so the MOI
65
+ register is the authority for the split index.
66
+ - ``buffer_record()`` takes a keyword-only ``wait_for``: a delay in seconds or
67
+ a zero-argument callable that returns at the moment of interest. It runs once
68
+ per sequence, after the ring buffer is ready and before the software MOI is
69
+ fired, so a ``pre_moi`` window can be placed around a real event instead of
70
+ around the arming call. Previously the MOI fired about 0.5 s after arming for
71
+ the first sequence and immediately for the following ones.
72
+ - ``buffer_record()`` warns when ``pre_moi > 0`` and no ``wait_for`` is given,
73
+ since the split point is then set by a timer and not by an event. It fires
74
+ the MOI as soon as the ring is ready. Pass ``wait_for=0`` to fire there
75
+ without the warning.
76
+ - ``buffer_record()`` raises ``ValueError`` when the configured ``moi_source``
77
+ is not ``"software"``, pointing at ``buffer_arm()`` and ``buffer_wait()``,
78
+ and it now stops acquisition on any exception, so Ctrl-C during a wait no
79
+ longer leaves the camera armed.
80
+ - ``buffer_configure()`` rejects a negative ``pre_moi`` or one larger than the
81
+ frames per sequence.
82
+ - New example ``examples/08_pretrigger_software_moi.py``: pre-trigger recording
83
+ with a software MOI, through the manual flow and through
84
+ ``buffer_record(wait_for=...)``.
85
+
86
+ - New module ``pyTelops.header`` parses the 256-byte Telops header every frame
87
+ carries in its two metadata rows: ``FrameHeader``, ``parse_header()``,
88
+ ``parse_headers()`` and the ``BufferingFlag`` enum. The camera writes the
89
+ header at exposure time, so the timestamp in it has no host-side delay. The
90
+ buffering flag exists only from header version 12.9 on and reads as ``None``
91
+ below that.
92
+ - ``header_timestamps()`` and ``header_frame_ids()`` read the same fields off a
93
+ raw frame stack with numpy views, for downloads too large to build one object
94
+ per frame.
95
+ - ``buffer_download()`` takes ``return_headers=True`` and then returns
96
+ ``(data, headers)``, one header per frame of the array. The headers are parsed
97
+ before calibration and header stripping. A frame whose header does not parse
98
+ gives ``None``, and a single warning reports how many. The paths that return
99
+ no data return ``(None, [])``.
100
+ - New ``buffer_moi_frame_id()`` and ``buffer_moi_index()`` report where the
101
+ moment of interest sits in a recorded sequence. ``buffer_moi_index()`` is the
102
+ index of the MOI frame in a full download and equals the configured
103
+ ``pre_moi``.
104
+
4
105
  Version 0.2.3
5
106
  -------------
6
107
 
@@ -10,7 +10,7 @@ sys.path.insert(0, os.path.abspath("../.."))
10
10
  project = "pyTelops"
11
11
  author = "Jaša Šonc, Janko Slavič"
12
12
  copyright = "2026, Jaša Šonc and Ladisk group, University of Ljubljana"
13
- release = "0.2.3"
13
+ release = "0.2.5"
14
14
  # -- General configuration ---------------------------------------------------
15
15
  extensions = [
16
16
  "sphinx.ext.autodoc",
@@ -1,7 +1,7 @@
1
1
  Examples
2
2
  ========
3
3
 
4
- Seven runnable scripts ship in the ``examples/`` directory. Each needs a
4
+ Eight runnable scripts ship in the ``examples/`` directory. Each needs a
5
5
  connected Telops camera.
6
6
 
7
7
  01_connect_and_grab.py
@@ -47,3 +47,12 @@ See :doc:`troubleshooting`.
47
47
  Record a sequence, tune the link with :func:`~pyTelops.tune_connection`, then
48
48
  download with integrity checking and inspect
49
49
  :attr:`~pyTelops.Camera.last_download_stats`. See :doc:`streaming_and_buffer`.
50
+
51
+ 08_pretrigger_software_moi.py
52
+ -----------------------------
53
+
54
+ Keep frames from before an event with a software MOI. Shows the manual flow
55
+ (:meth:`~pyTelops.Camera.buffer_arm`, wait for the event,
56
+ :meth:`~pyTelops.Camera.buffer_fire_moi`, :meth:`~pyTelops.Camera.buffer_wait`)
57
+ and the same recording through ``buffer_record(wait_for=...)``. See
58
+ :doc:`streaming_and_buffer`.
@@ -6,6 +6,11 @@ over GigE Vision. No vendor SDK required: pyTelops speaks the GVCP and GVSP
6
6
  protocols directly over UDP, on top of `pyGigEVision
7
7
  <https://github.com/ladisk/pyGigEVision>`_.
8
8
 
9
+ .. image:: ../../hero.gif
10
+ :alt: pyTelops demo: discover and connect to the camera, open a live thermal
11
+ view with cam.live_view(), then record to the camera buffer and
12
+ download the frames
13
+
9
14
  Quickstart
10
15
  ----------
11
16