pyTelops 0.2.2__tar.gz → 0.2.4__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.
- {pytelops-0.2.2 → pytelops-0.2.4}/AGENTS.md +1 -1
- {pytelops-0.2.2 → pytelops-0.2.4}/PKG-INFO +3 -3
- {pytelops-0.2.2 → pytelops-0.2.4}/README.rst +93 -4
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/camera.rst +16 -0
- pytelops-0.2.4/docs/source/changelog.rst +250 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/conf.py +1 -1
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/examples.rst +10 -1
- pytelops-0.2.4/docs/source/streaming_and_buffer.rst +441 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/03_buffer_record.py +2 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/05_external_trigger.py +10 -0
- pytelops-0.2.4/examples/08_pretrigger_software_moi.py +127 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/README.rst +2 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/__init__.py +15 -1
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/camera.py +1147 -145
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/errors.py +6 -0
- pytelops-0.2.4/pyTelops/header.py +483 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyproject.toml +2 -2
- {pytelops-0.2.2 → pytelops-0.2.4}/tests/conftest.py +18 -0
- pytelops-0.2.4/tests/test_camera.py +1635 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/tests/test_download_integrity.py +303 -14
- {pytelops-0.2.2 → pytelops-0.2.4}/tests/test_hardware.py +120 -4
- pytelops-0.2.4/tests/test_header.py +352 -0
- pytelops-0.2.2/docs/source/changelog.rst +0 -87
- pytelops-0.2.2/docs/source/streaming_and_buffer.rst +0 -237
- pytelops-0.2.2/tests/test_camera.py +0 -749
- {pytelops-0.2.2 → pytelops-0.2.4}/.gitignore +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/CONTRIBUTING.rst +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/LICENSE +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/PYPI_README.rst +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/requirements.txt +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/rtd_postbuild.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/_static/.gitkeep +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/_static/ai-buttons.css +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/_static/ai-buttons.js +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/_static/logo.png +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/calibration.rst +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/getting_started.rst +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/index.rst +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/docs/source/troubleshooting.rst +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/01_connect_and_grab.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/02_continuous_live.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/04_calibration_load.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/06_force_ip.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/examples/07_robust_download.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/cli.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/connection.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/gui.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/provisioning.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/py.typed +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/pyTelops/registers.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/requirements.dev.txt +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/requirements.txt +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/sync_version.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/tests/test_cli.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/tests/test_connection.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/tests/test_discovery_reachability.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/tests/test_enum_resolution.py +0 -0
- {pytelops-0.2.2 → pytelops-0.2.4}/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 ...
|
|
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.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: pyTelops
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.4
|
|
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
|
|
@@ -25,7 +25,7 @@ Classifier: Topic :: Scientific/Engineering :: Image Processing
|
|
|
25
25
|
Classifier: Topic :: System :: Hardware :: Hardware Drivers
|
|
26
26
|
Requires-Python: >=3.10
|
|
27
27
|
Requires-Dist: numpy>=1.20
|
|
28
|
-
Requires-Dist: pygigevision>=0.2.
|
|
28
|
+
Requires-Dist: pygigevision>=0.2.2
|
|
29
29
|
Requires-Dist: tqdm
|
|
30
30
|
Provides-Extra: dev
|
|
31
31
|
Requires-Dist: build; extra == 'dev'
|
|
@@ -76,7 +76,7 @@ Frames are returned as numpy arrays with Telops header rows already stripped.
|
|
|
76
76
|
Documentation
|
|
77
77
|
-------------
|
|
78
78
|
|
|
79
|
-
Full documentation at https://pytelops.readthedocs.io
|
|
79
|
+
Full documentation at https://pytelops.readthedocs.io/en/latest/
|
|
80
80
|
|
|
81
81
|
The sections below walk through the camera the way you use it: find it,
|
|
82
82
|
connect, configure, capture, and disconnect.
|
|
@@ -272,7 +272,7 @@ slots before recording:
|
|
|
272
272
|
|
|
273
273
|
``buffer_record()`` prints progress::
|
|
274
274
|
|
|
275
|
-
Arming (seq 1/3)... Recording... Done (10000 frames)
|
|
275
|
+
Arming (seq 1/3)... Waiting for ring buffer (2.0 s)... Recording... Done (10000 frames)
|
|
276
276
|
Firing (seq 2/3)... Recording... Done (10000 frames)
|
|
277
277
|
Firing (seq 3/3)... Recording... Done (10000 frames)
|
|
278
278
|
|
|
@@ -287,6 +287,88 @@ If a download finishes with missing frames, ``buffer_download()`` raises
|
|
|
287
287
|
<https://pytelops.readthedocs.io/en/latest/streaming_and_buffer.html>`_ for
|
|
288
288
|
tolerating drops and inspecting ``cam.last_download_stats``.
|
|
289
289
|
|
|
290
|
+
Pre-trigger recording (pre-MOI)
|
|
291
|
+
-------------------------------
|
|
292
|
+
|
|
293
|
+
The armed camera fills the buffer as a ring. The MOI (moment of interest)
|
|
294
|
+
marks the split: the ``pre_moi`` frames before it and the rest of the sequence
|
|
295
|
+
after it are kept. Fire the MOI at the event, not right after arming, or the
|
|
296
|
+
pre-trigger window holds fewer frames than configured.
|
|
297
|
+
|
|
298
|
+
The ring keeps nothing for the first 2.02 s after acquisition starts. A MOI
|
|
299
|
+
fired inside that window is latched, but the sequence then starts at the first
|
|
300
|
+
frame the ring could keep, so the pre-trigger part is truncated.
|
|
301
|
+
``buffer_arm()`` therefore blocks until the ring holds the configured
|
|
302
|
+
``pre_moi`` frames, about 2 s plus ``pre_moi / frame_rate``. Pass
|
|
303
|
+
``wait_ready=False`` to return at once, and use ``buffer_ready_in()`` or
|
|
304
|
+
``buffer_wait_ready()`` if you schedule the event yourself. This is measured
|
|
305
|
+
with a software MOI; the same is expected for an external trigger, so send the
|
|
306
|
+
trigger after ``buffer_arm()`` returns.
|
|
307
|
+
|
|
308
|
+
``pre_moi`` can be as large as ``frames_per_seq``. The whole slot is then
|
|
309
|
+
pre-trigger and the MOI lands on its last frame, at index
|
|
310
|
+
``frames_per_seq - 1``.
|
|
311
|
+
|
|
312
|
+
``buffer_record()`` is a shortcut over ``buffer_arm()``, ``buffer_fire_moi()``
|
|
313
|
+
and ``buffer_wait()``, and takes the waiting step as ``wait_for``: a delay in
|
|
314
|
+
seconds, or a callable that returns at the event. Every variant waits for the
|
|
315
|
+
ring buffer first.
|
|
316
|
+
|
|
317
|
+
.. code-block:: python
|
|
318
|
+
|
|
319
|
+
cam.buffer_configure(frames_per_seq=400, pre_moi=100) # frames, not seconds
|
|
320
|
+
|
|
321
|
+
cam.buffer_record(wait_for=0.5) # 0.5 s after the ring is ready
|
|
322
|
+
cam.buffer_record(wait_for=lambda: my_event.wait())
|
|
323
|
+
|
|
324
|
+
# or drive the same flow yourself
|
|
325
|
+
cam.buffer_arm() # blocks about 2.1 s at 2000 fps
|
|
326
|
+
wait_for_my_event()
|
|
327
|
+
cam.buffer_fire_moi()
|
|
328
|
+
cam.buffer_wait(timeout=30.0)
|
|
329
|
+
data = cam.buffer_download()
|
|
330
|
+
|
|
331
|
+
With ``pre_moi > 0`` and no ``wait_for``, ``buffer_record()`` warns and fires
|
|
332
|
+
the MOI as soon as the ring is ready, because the split point is then set by a
|
|
333
|
+
timer and not by an event. Pass ``wait_for=0`` to silence the warning. See
|
|
334
|
+
``examples/08_pretrigger_software_moi.py``.
|
|
335
|
+
|
|
336
|
+
Frame headers and timestamps
|
|
337
|
+
----------------------------
|
|
338
|
+
|
|
339
|
+
Every frame carries a Telops header written by the camera at exposure time, so
|
|
340
|
+
its timestamp has no host-side delay. Call ``cam.sync_time()`` before recording
|
|
341
|
+
to put the camera clock on host time, then ask the download for the headers:
|
|
342
|
+
|
|
343
|
+
.. code-block:: python
|
|
344
|
+
|
|
345
|
+
cam.sync_time()
|
|
346
|
+
data, headers = cam.buffer_download(sequence=0, return_headers=True)
|
|
347
|
+
|
|
348
|
+
print(headers[0].datetime) # exposure time of the first frame, UTC
|
|
349
|
+
moi = cam.buffer_moi_index(0) # index of the moment of interest
|
|
350
|
+
if 0 <= moi < len(headers):
|
|
351
|
+
print(headers[moi].timestamp - headers[0].timestamp)
|
|
352
|
+
|
|
353
|
+
Entry ``i`` belongs to frame ``i`` of the array. For very large downloads use
|
|
354
|
+
``header_timestamps(raw)`` on a raw download (``strip_header=False,
|
|
355
|
+
convert=False``) instead; it reads the same bytes without building an object
|
|
356
|
+
per frame.
|
|
357
|
+
|
|
358
|
+
``sync_time()`` writes whole seconds, so absolute timestamps are good to about
|
|
359
|
+
1 s. Differences between frames are exact. Sub-second alignment to the host
|
|
360
|
+
clock is not available from the driver yet: the camera sub-second register is
|
|
361
|
+
read-only, and ``cam.posix_time = ...`` also writes whole seconds only.
|
|
362
|
+
|
|
363
|
+
``buffer_moi_index()`` is verified on the TS-IR: with the MOI fired after the
|
|
364
|
+
ring warm-up it equals the configured ``pre_moi``. It is the authority for the
|
|
365
|
+
split index. In the header timestamps the event sits about 7 to 8 ms later than
|
|
366
|
+
the host-side ``buffer_fire_moi()`` call, which is the GVCP command latency, so
|
|
367
|
+
do not derive the split from a host clock reading. The camera's MOI frame id
|
|
368
|
+
maps directly onto ``FrameHeader.frame_id``: in every campaign recording,
|
|
369
|
+
``REG_MEMORY_BUFFER_SEQ_FIRST_FRAME_ID`` equalled ``headers[0].frame_id``, so
|
|
370
|
+
``headers[buffer_moi_index()].frame_id`` equals ``buffer_moi_frame_id()``.
|
|
371
|
+
|
|
290
372
|
External trigger
|
|
291
373
|
----------------
|
|
292
374
|
|
|
@@ -301,15 +383,22 @@ For triggered recording from an external BNC signal:
|
|
|
301
383
|
pre_moi=1000,
|
|
302
384
|
moi_source="external")
|
|
303
385
|
|
|
304
|
-
cam.buffer_arm() #
|
|
386
|
+
cam.buffer_arm() # blocks until the ring is ready
|
|
305
387
|
cam.buffer_wait(timeout=60.0) # blocks until recording completes
|
|
306
388
|
data = cam.buffer_download()
|
|
307
389
|
|
|
390
|
+
Send the trigger after ``buffer_arm()`` returns. An edge that arrives during
|
|
391
|
+
the ring warm-up is expected to behave like an early software MOI, that is
|
|
392
|
+
latched with a truncated pre-trigger part, but only the software MOI has been
|
|
393
|
+
measured. Check ``cam.buffer_moi_index(0)`` against the configured ``pre_moi``
|
|
394
|
+
afterwards.
|
|
395
|
+
|
|
308
396
|
For manual control with software MOI (instead of ``buffer_record()``):
|
|
309
397
|
|
|
310
398
|
.. code-block:: python
|
|
311
399
|
|
|
312
|
-
cam.buffer_arm() # arm the buffer
|
|
400
|
+
cam.buffer_arm() # arm the buffer, wait for the ring
|
|
401
|
+
wait_for_my_event() # returns at the moment of interest
|
|
313
402
|
cam.buffer_fire_moi() # software MOI trigger
|
|
314
403
|
cam.buffer_wait(timeout=30.0) # wait for recording to finish
|
|
315
404
|
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
|
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
Changelog
|
|
2
|
+
=========
|
|
3
|
+
|
|
4
|
+
Version 0.2.4
|
|
5
|
+
-------------
|
|
6
|
+
|
|
7
|
+
- **Pre-trigger recordings now keep the frames they were asked for.** The
|
|
8
|
+
camera's ring buffer keeps nothing for the first 2.02 s after acquisition
|
|
9
|
+
starts (measured on a TS-IR, the same at 250 and 1000 fps). A MOI fired
|
|
10
|
+
inside that window is latched, and the sequence then starts at the first
|
|
11
|
+
frame the ring could keep, so the pre-trigger part came out truncated or
|
|
12
|
+
empty. The driver now holds the MOI back until the ring can hold the
|
|
13
|
+
configured ``pre_moi`` frames: ``Camera.BUFFER_RING_WARMUP_S`` (2.05 s)
|
|
14
|
+
plus ``pre_moi / frame_rate`` after arming.
|
|
15
|
+
- ``buffer_arm()`` blocks until the ring buffer is ready, so about 2 s plus
|
|
16
|
+
``pre_moi / frame_rate``. Pass ``wait_ready=False`` for the old immediate
|
|
17
|
+
return.
|
|
18
|
+
- ``buffer_record()`` and ``buffer_arm()`` now take about 1.5 s longer than in
|
|
19
|
+
0.2.3 even with ``pre_moi=0``, because the ring dead time applies to the
|
|
20
|
+
sequence start as well.
|
|
21
|
+
- New ``buffer_ready_in()`` (seconds left of the ring warm-up, 0 when ready)
|
|
22
|
+
and ``buffer_wait_ready()`` (sleep that long), for callers that schedule the
|
|
23
|
+
event themselves.
|
|
24
|
+
- ``buffer_fire_moi()`` warns when it is called before the ring is ready, and
|
|
25
|
+
says how many pre-trigger frames the camera will actually keep. It reads no
|
|
26
|
+
registers, so the event path is a single register write.
|
|
27
|
+
- ``buffer_fire_moi()`` raises ``RuntimeError`` when ``buffer_arm()`` was not
|
|
28
|
+
called first. The camera rejects the write while it is not acquiring, so the
|
|
29
|
+
old silent write did nothing.
|
|
30
|
+
- ``buffer_arm()`` and ``buffer_record()`` write ``ACQUISITION_STOP`` before
|
|
31
|
+
``ACQUISITION_ARM``, and raise ``RuntimeError`` if the buffer still reads
|
|
32
|
+
RECORDING 5 s later. The stop write is unconditional, so an unreadable status
|
|
33
|
+
register no longer lets the guard pass. Arming during a recording aborts it:
|
|
34
|
+
the status drops to IDLE, the recorded count stays 0 and the sequence counter
|
|
35
|
+
sticks at 0 until ``buffer_clear()``.
|
|
36
|
+
- ``buffer_configure()`` warns when ``moi_source="acquisition_started"`` is
|
|
37
|
+
combined with ``pre_moi > 0``. That MOI fires inside the ring dead time, so
|
|
38
|
+
the pre-trigger window is always empty.
|
|
39
|
+
- Verified on hardware (TS-IR, header 12.7): with the MOI fired after the ring
|
|
40
|
+
warm-up, ``buffer_moi_index()`` equals the configured ``pre_moi``, for every
|
|
41
|
+
sequence of a three-sequence recording at 1000 and 2000 fps. Frame ids are
|
|
42
|
+
contiguous and ``buffering_flag`` is ``None``, as expected below header 12.9.
|
|
43
|
+
In the header timestamps the event sits about 7 to 8 ms after the host-side
|
|
44
|
+
``buffer_fire_moi()`` call, which is the GVCP command latency, so the MOI
|
|
45
|
+
register is the authority for the split index.
|
|
46
|
+
- ``buffer_record()`` takes a keyword-only ``wait_for``: a delay in seconds or
|
|
47
|
+
a zero-argument callable that returns at the moment of interest. It runs once
|
|
48
|
+
per sequence, after the ring buffer is ready and before the software MOI is
|
|
49
|
+
fired, so a ``pre_moi`` window can be placed around a real event instead of
|
|
50
|
+
around the arming call. Previously the MOI fired about 0.5 s after arming for
|
|
51
|
+
the first sequence and immediately for the following ones.
|
|
52
|
+
- ``buffer_record()`` warns when ``pre_moi > 0`` and no ``wait_for`` is given,
|
|
53
|
+
since the split point is then set by a timer and not by an event. It fires
|
|
54
|
+
the MOI as soon as the ring is ready. Pass ``wait_for=0`` to fire there
|
|
55
|
+
without the warning.
|
|
56
|
+
- ``buffer_record()`` raises ``ValueError`` when the configured ``moi_source``
|
|
57
|
+
is not ``"software"``, pointing at ``buffer_arm()`` and ``buffer_wait()``,
|
|
58
|
+
and it now stops acquisition on any exception, so Ctrl-C during a wait no
|
|
59
|
+
longer leaves the camera armed.
|
|
60
|
+
- ``buffer_configure()`` rejects a negative ``pre_moi`` or one larger than the
|
|
61
|
+
frames per sequence.
|
|
62
|
+
- New example ``examples/08_pretrigger_software_moi.py``: pre-trigger recording
|
|
63
|
+
with a software MOI, through the manual flow and through
|
|
64
|
+
``buffer_record(wait_for=...)``.
|
|
65
|
+
|
|
66
|
+
- New module ``pyTelops.header`` parses the 256-byte Telops header every frame
|
|
67
|
+
carries in its two metadata rows: ``FrameHeader``, ``parse_header()``,
|
|
68
|
+
``parse_headers()`` and the ``BufferingFlag`` enum. The camera writes the
|
|
69
|
+
header at exposure time, so the timestamp in it has no host-side delay. The
|
|
70
|
+
buffering flag exists only from header version 12.9 on and reads as ``None``
|
|
71
|
+
below that.
|
|
72
|
+
- ``header_timestamps()`` and ``header_frame_ids()`` read the same fields off a
|
|
73
|
+
raw frame stack with numpy views, for downloads too large to build one object
|
|
74
|
+
per frame.
|
|
75
|
+
- ``buffer_download()`` takes ``return_headers=True`` and then returns
|
|
76
|
+
``(data, headers)``, one header per frame of the array. The headers are parsed
|
|
77
|
+
before calibration and header stripping. A frame whose header does not parse
|
|
78
|
+
gives ``None``, and a single warning reports how many. The paths that return
|
|
79
|
+
no data return ``(None, [])``.
|
|
80
|
+
- New ``buffer_moi_frame_id()`` and ``buffer_moi_index()`` report where the
|
|
81
|
+
moment of interest sits in a recorded sequence. ``buffer_moi_index()`` is the
|
|
82
|
+
index of the MOI frame in a full download and equals the configured
|
|
83
|
+
``pre_moi``.
|
|
84
|
+
|
|
85
|
+
Version 0.2.3
|
|
86
|
+
-------------
|
|
87
|
+
|
|
88
|
+
- **Fixed silent frame decimation of buffer downloads when a non-zero**
|
|
89
|
+
``packet_delay`` **is set.** A live-streaming ``packet_delay`` (GVSP
|
|
90
|
+
inter-packet delay / SCPD) was being applied to memory-buffer downloads too,
|
|
91
|
+
where it makes the camera silently return **every other frame** (a 2x, or with
|
|
92
|
+
heavy throttling higher, decimation): the throttled transmit desyncs from the
|
|
93
|
+
camera's buffer-read clock, so it skips frames -- with contiguous block-ids and
|
|
94
|
+
no error, so the data looked valid but was time-aliased (a signal at frequency
|
|
95
|
+
``f`` appeared at ``2f``). ``buffer_download`` now forces SCPD to 0 for the
|
|
96
|
+
transfer and restores the user's value afterwards, so downloads are correct
|
|
97
|
+
regardless of the live ``packet_delay``. For host-side packet loss during
|
|
98
|
+
download use jumbo packets and/or a lower ``bitrate_mbps`` (both proven), NOT
|
|
99
|
+
``packet_delay``. Confirmed on hardware (FAST-M3k, firmware 3.1.13.2): with
|
|
100
|
+
``packet_delay=1000`` the same recording strided before the fix and downloads
|
|
101
|
+
cleanly after.
|
|
102
|
+
- **Large buffer downloads are now streamed in chunks (default 1000 frames per
|
|
103
|
+
session).** A single large acquisition session overruns the host receive path
|
|
104
|
+
and the camera's paced readout: an 8000-frame session lost most of its frames
|
|
105
|
+
(thousands incomplete at idle on a USB-GigE host) and returned them
|
|
106
|
+
mis-ordered, whereas sessions of at most a thousand frames come back complete.
|
|
107
|
+
``buffer_download`` now splits the range into ``chunk_size`` pieces, so large
|
|
108
|
+
downloads are **100% complete** at idle and under CPU load (validated on
|
|
109
|
+
hardware). The recovery loop also no longer paces the bitrate *down* between
|
|
110
|
+
rounds -- a low download bitrate is what makes the camera stride (skip frames),
|
|
111
|
+
so lowering it to fight packet loss was counter-productive; it stays at the
|
|
112
|
+
base rate. Use jumbo packets and/or a lower base ``bitrate_mbps`` for loss.
|
|
113
|
+
- ``buffer_download`` now verifies frame **ordering** using the per-frame camera
|
|
114
|
+
leader timestamps and raises ``FrameIntegrityError`` when more than
|
|
115
|
+
``order_tolerance`` (default 5%) of the frames are mis-ordered, duplicated, or
|
|
116
|
+
strided (new ``verify_order`` parameter, default ``True``). This backstop
|
|
117
|
+
catches gross corruption such as the decimation above (which mis-orders ~half
|
|
118
|
+
the frames) even though every packet arrives complete. A small (~1%)
|
|
119
|
+
irreducible residual of cross-session mis-ordering remains on large downloads
|
|
120
|
+
-- the camera does not halt a download session promptly, so a session's tail
|
|
121
|
+
can leak into the next -- and is recorded and logged but tolerated rather than
|
|
122
|
+
failing every download. The anomaly counts are on ``cam.last_download_stats``
|
|
123
|
+
(``n_out_of_order``, ``n_stride_gaps``); the check is skipped when the camera
|
|
124
|
+
does not populate timestamps. Pass ``order_tolerance=0`` for strict behaviour
|
|
125
|
+
or ``verify_order=False`` to accept frames as delivered.
|
|
126
|
+
- **Fixed stale frames leaking between recovery rounds of a buffer download on a
|
|
127
|
+
heavily loaded host.** Each paced recovery round re-streams the still-missing
|
|
128
|
+
frames in a fresh GVSP session, and the session's block id (which restarts at 1)
|
|
129
|
+
is used to place each frame at ``offset = block_id - 1``. Under host CPU
|
|
130
|
+
saturation the GVSP receiver could fall behind and leave a frame from the
|
|
131
|
+
previous session queued -- or unread in the OS socket buffer -- so the next
|
|
132
|
+
session read it first and mapped it to the **wrong position** (packet-complete
|
|
133
|
+
but out-of-order / strided frames, which ``verify_order`` above then reported).
|
|
134
|
+
The receiver now exposes ``flush()`` and ``buffer_download`` drains the frame
|
|
135
|
+
queue, partial frame buffers, and the socket receive buffer at each session
|
|
136
|
+
boundary, so recovery is correct under load. Requires
|
|
137
|
+
``pyGigEVision>=0.2.2`` (``GVSPReceiver.flush``).
|
|
138
|
+
- Added software **power-state control**. ``Camera.standby()`` spins the
|
|
139
|
+
Stirling cooler down while keeping the GVCP connection open;
|
|
140
|
+
``Camera.power_on(wait=True)`` brings it back and waits for the detector to
|
|
141
|
+
re-cool; and the read-only ``Camera.power_state`` property reports the current
|
|
142
|
+
``DevicePowerState``. Standby is the way to quiet the camera and cut power
|
|
143
|
+
during genuine idle periods without unplugging it -- coolers have a finite
|
|
144
|
+
cycle life (the camera counts them, see ``diagnostics()``
|
|
145
|
+
``cooler_power_on_cycles``), so use it for real idle time, not rapid cycling.
|
|
146
|
+
- Added ``Camera.reset()`` to issue a firmware reset via ``REG_DEVICE_RESET``
|
|
147
|
+
(0xD340). The camera reboots and the control channel is dropped, so the call
|
|
148
|
+
marks the camera disconnected; reconnect after it reboots. The reboot can bring
|
|
149
|
+
the camera up on a new link-local IP, so ``reset()`` clears the cached address
|
|
150
|
+
and the next ``connect()`` re-discovers it. Prefer ``standby()``/``power_on()``
|
|
151
|
+
for routine idling.
|
|
152
|
+
- ``connect()`` / ``wait_until_ready()`` no longer time out while the camera is
|
|
153
|
+
cooling. The old fixed 120 s wait failed on a freshly powered camera (an
|
|
154
|
+
from-ambient cooldown takes minutes) yet made you wait a full two minutes on a
|
|
155
|
+
genuinely absent one. There are now two budgets: a short ``timeout``
|
|
156
|
+
(default 10 s) that applies while the camera is unresponsive or stuck -- so a
|
|
157
|
+
missing camera fails fast -- and a long ``cooling_timeout`` (default 600 s)
|
|
158
|
+
that applies while the camera reports it is actively cooling or initialising
|
|
159
|
+
(from its TDC status). Both are keyword arguments on ``connect()`` and
|
|
160
|
+
``wait_until_ready()`` (issue #15).
|
|
161
|
+
- ``diagnostics()`` now returns ``None`` for temperature locations the camera
|
|
162
|
+
model does not support, as its docstring already promised. On the TS-IR the
|
|
163
|
+
unsupported thermistor locations reported the raw ADC-floor sentinel
|
|
164
|
+
(``-138.3`` C) instead of rejecting the read, leaking through as a bogus
|
|
165
|
+
temperature; it is now detected and mapped to ``None`` (issue #16).
|
|
166
|
+
|
|
167
|
+
Version 0.2.2
|
|
168
|
+
-------------
|
|
169
|
+
|
|
170
|
+
- First release published to PyPI.
|
|
171
|
+
- The pyGigEVision dependency now installs from PyPI (``pyGigEVision>=0.2.1``)
|
|
172
|
+
instead of a git URL; automated CI runs on push and pull request again.
|
|
173
|
+
- ``Camera(ip=...).connect()`` now runs a discovery sweep to bind the host
|
|
174
|
+
interface that actually reaches the camera, instead of trusting OS routing.
|
|
175
|
+
On hosts with several link-local interfaces (VPN, Bluetooth, virtual
|
|
176
|
+
adapters) the route by metric could pick a dead interface and the connect
|
|
177
|
+
timed out. Cameras the sweep cannot see fall back to OS routing as before.
|
|
178
|
+
- ``discover()`` now finds cameras on every host network interface (USB-to-GigE
|
|
179
|
+
adapters, secondary NICs), via the reworked multi-interface discovery in
|
|
180
|
+
pyGigEVision. Each result carries a ``reachable`` flag and an ``interface_ip``
|
|
181
|
+
recording the host NIC the camera replied on.
|
|
182
|
+
- ``Camera()`` now connects through the interface the camera replied on during
|
|
183
|
+
discovery, so a host with multiple link-local NICs no longer needs manual
|
|
184
|
+
interface selection. It also raises an actionable error when the selected
|
|
185
|
+
camera is on no host NIC subnet, instead of failing later with a confusing
|
|
186
|
+
OS error.
|
|
187
|
+
- Added ``pyTelops.force_ip(camera, ip, mask, gateway=None)`` to re-home a
|
|
188
|
+
wrong-subnet camera by MAC (GVCP FORCEIP).
|
|
189
|
+
- Removed the host-side link-local probe that the multi-interface discovery
|
|
190
|
+
makes redundant. Thanks to Lorenzo Capponi (LolloCappo) for the
|
|
191
|
+
connected-socket interface-detection approach (PR #13) that informed this work.
|
|
192
|
+
- Requires the updated pyGigEVision (multi-interface discovery, ``force_ip``).
|
|
193
|
+
- ``buffer_download`` now detects dropped and corrupted frames and raises
|
|
194
|
+
``FrameIntegrityError`` by default when any frame is incomplete. This is a
|
|
195
|
+
behavior change: pass ``max_dropped_frames=N`` to tolerate up to ``N``
|
|
196
|
+
incomplete frames, as older code relied on the method always returning an
|
|
197
|
+
array.
|
|
198
|
+
- ``buffer_download`` attaches a ``DownloadStats`` integrity report to
|
|
199
|
+
``cam.last_download_stats`` (per-frame missing packets, resend counts,
|
|
200
|
+
throughput) so callers can inspect data quality without pixel inspection.
|
|
201
|
+
- ``buffer_download`` enables GVSP packet resends during the stream and
|
|
202
|
+
re-downloads incomplete frames from the camera buffer, controlled by the new
|
|
203
|
+
``resend`` and ``retries`` parameters. It no longer suppresses the
|
|
204
|
+
``pyGigEVision.gvsp`` packet-loss warnings.
|
|
205
|
+
- Corrected the misleading ``packet_size=9000`` guidance. Oversized requests on
|
|
206
|
+
a non-jumbo path are now detected with a FireTestPacket path probe, and the
|
|
207
|
+
download warns and falls back to ``packet_size=1500`` instead of silently
|
|
208
|
+
emitting mostly-zero frames.
|
|
209
|
+
- ``buffer_download`` now auto-tunes by default: it probes once per connection
|
|
210
|
+
whether the path carries jumbo frames and learns a download bitrate from
|
|
211
|
+
each transfer's completeness. Pass ``packet_size`` or ``bitrate_mbps`` to
|
|
212
|
+
override, or set ``cam.auto_tune = False`` to disable.
|
|
213
|
+
- Added ``tune_connection()`` to probe the link and sweep download settings,
|
|
214
|
+
recommending a stable and fast configuration for the current adapter and
|
|
215
|
+
cable. Includes an opt-in read-only NIC diagnostics pass.
|
|
216
|
+
- New public names: ``FrameIntegrityError``, ``DownloadStats``,
|
|
217
|
+
``ConnectionReport``, ``tune_connection``.
|
|
218
|
+
|
|
219
|
+
Version 0.2.1
|
|
220
|
+
-------------
|
|
221
|
+
|
|
222
|
+
- Adopt sdypy package template conventions: hatchling build, sphinx-book-theme
|
|
223
|
+
docs on ReadTheDocs, manual changelog, version-sync release script.
|
|
224
|
+
- Add full Sphinx documentation: getting started, Camera API reference,
|
|
225
|
+
calibration, streaming and buffer, troubleshooting.
|
|
226
|
+
- Add five runnable examples in ``examples/``: connect and grab, continuous
|
|
227
|
+
live view, buffer recording, calibration loading, external trigger.
|
|
228
|
+
- Add ``CONTRIBUTING.rst`` and this changelog. Fold the standalone
|
|
229
|
+
troubleshooting guide into the documentation.
|
|
230
|
+
- Switch lint from flake8 to ruff (strict superset, includes formatter).
|
|
231
|
+
- Polish: NumPy-style docstrings and complete type hints across the Camera
|
|
232
|
+
class and the registers, CLI, and GUI modules.
|
|
233
|
+
- No public API changes; the LDAQ Telops plugin and existing user code
|
|
234
|
+
continue to work unchanged.
|
|
235
|
+
|
|
236
|
+
Version 0.2.0
|
|
237
|
+
-------------
|
|
238
|
+
|
|
239
|
+
- Split the GigE Vision protocol layer into the standalone `pyGigEVision
|
|
240
|
+
<https://github.com/ladisk/pyGigEVision>`_ package. pyTelops becomes the
|
|
241
|
+
Telops vendor layer on top of it.
|
|
242
|
+
- ``Camera`` re-exports ``GVCPClient`` and ``GVCPError`` from pyGigEVision for
|
|
243
|
+
back-compatibility.
|
|
244
|
+
- 127 unit tests plus 57 hardware tests.
|
|
245
|
+
|
|
246
|
+
Version 0.1.0
|
|
247
|
+
-------------
|
|
248
|
+
|
|
249
|
+
- Initial Telops camera driver: discovery, control, live streaming, onboard
|
|
250
|
+
buffer recording and download, calibration loading, NUC, diagnostics.
|
|
@@ -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.
|
|
13
|
+
release = "0.2.4"
|
|
14
14
|
# -- General configuration ---------------------------------------------------
|
|
15
15
|
extensions = [
|
|
16
16
|
"sphinx.ext.autodoc",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
Examples
|
|
2
2
|
========
|
|
3
3
|
|
|
4
|
-
|
|
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`.
|