pyTelops 0.2.4__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 (55) hide show
  1. {pytelops-0.2.4 → pytelops-0.2.5}/PKG-INFO +1 -1
  2. {pytelops-0.2.4 → pytelops-0.2.5}/README.rst +5 -0
  3. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/changelog.rst +20 -0
  4. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/conf.py +1 -1
  5. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/index.rst +5 -0
  6. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/__init__.py +1 -1
  7. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/camera.py +63 -6
  8. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/registers.py +0 -2
  9. {pytelops-0.2.4 → pytelops-0.2.5}/pyproject.toml +1 -1
  10. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_camera.py +61 -0
  11. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_hardware.py +2 -0
  12. {pytelops-0.2.4 → pytelops-0.2.5}/.gitignore +0 -0
  13. {pytelops-0.2.4 → pytelops-0.2.5}/AGENTS.md +0 -0
  14. {pytelops-0.2.4 → pytelops-0.2.5}/CONTRIBUTING.rst +0 -0
  15. {pytelops-0.2.4 → pytelops-0.2.5}/LICENSE +0 -0
  16. {pytelops-0.2.4 → pytelops-0.2.5}/PYPI_README.rst +0 -0
  17. {pytelops-0.2.4 → pytelops-0.2.5}/docs/requirements.txt +0 -0
  18. {pytelops-0.2.4 → pytelops-0.2.5}/docs/rtd_postbuild.py +0 -0
  19. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/_static/.gitkeep +0 -0
  20. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/_static/ai-buttons.css +0 -0
  21. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/_static/ai-buttons.js +0 -0
  22. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/_static/logo.png +0 -0
  23. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/calibration.rst +0 -0
  24. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/camera.rst +0 -0
  25. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/examples.rst +0 -0
  26. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/getting_started.rst +0 -0
  27. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/streaming_and_buffer.rst +0 -0
  28. {pytelops-0.2.4 → pytelops-0.2.5}/docs/source/troubleshooting.rst +0 -0
  29. {pytelops-0.2.4 → pytelops-0.2.5}/examples/01_connect_and_grab.py +0 -0
  30. {pytelops-0.2.4 → pytelops-0.2.5}/examples/02_continuous_live.py +0 -0
  31. {pytelops-0.2.4 → pytelops-0.2.5}/examples/03_buffer_record.py +0 -0
  32. {pytelops-0.2.4 → pytelops-0.2.5}/examples/04_calibration_load.py +0 -0
  33. {pytelops-0.2.4 → pytelops-0.2.5}/examples/05_external_trigger.py +0 -0
  34. {pytelops-0.2.4 → pytelops-0.2.5}/examples/06_force_ip.py +0 -0
  35. {pytelops-0.2.4 → pytelops-0.2.5}/examples/07_robust_download.py +0 -0
  36. {pytelops-0.2.4 → pytelops-0.2.5}/examples/08_pretrigger_software_moi.py +0 -0
  37. {pytelops-0.2.4 → pytelops-0.2.5}/examples/README.rst +0 -0
  38. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/cli.py +0 -0
  39. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/connection.py +0 -0
  40. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/errors.py +0 -0
  41. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/gui.py +0 -0
  42. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/header.py +0 -0
  43. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/provisioning.py +0 -0
  44. {pytelops-0.2.4 → pytelops-0.2.5}/pyTelops/py.typed +0 -0
  45. {pytelops-0.2.4 → pytelops-0.2.5}/requirements.dev.txt +0 -0
  46. {pytelops-0.2.4 → pytelops-0.2.5}/requirements.txt +0 -0
  47. {pytelops-0.2.4 → pytelops-0.2.5}/sync_version.py +0 -0
  48. {pytelops-0.2.4 → pytelops-0.2.5}/tests/conftest.py +0 -0
  49. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_cli.py +0 -0
  50. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_connection.py +0 -0
  51. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_discovery_reachability.py +0 -0
  52. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_download_integrity.py +0 -0
  53. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_enum_resolution.py +0 -0
  54. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_header.py +0 -0
  55. {pytelops-0.2.4 → pytelops-0.2.5}/tests/test_registers.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pyTelops
3
- Version: 0.2.4
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
@@ -1,6 +1,26 @@
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
+
4
24
  Version 0.2.4
5
25
  -------------
6
26
 
@@ -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.4"
13
+ release = "0.2.5"
14
14
  # -- General configuration ---------------------------------------------------
15
15
  extensions = [
16
16
  "sphinx.ext.autodoc",
@@ -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
 
@@ -18,7 +18,7 @@ Usage::
18
18
 
19
19
  from __future__ import annotations
20
20
 
21
- __version__ = "0.2.4"
21
+ __version__ = "0.2.5"
22
22
  from pyGigEVision import GVCPClient, GVCPError
23
23
 
24
24
  from .camera import Camera, discover
@@ -1367,8 +1367,8 @@ class Camera:
1367
1367
  def temperature(self) -> float:
1368
1368
  """Main camera sensor temperature in degrees Celsius (read-only).
1369
1369
 
1370
- Reports the value from ``REG_DEVICE_TEMPERATURE``. For other
1371
- internal temperature sensors (compressor, FPGAs, etc.) use
1370
+ Same as ``sensor_temperature("sensor")``. For other internal
1371
+ temperature sensors (compressor, FPGAs, etc.) use
1372
1372
  :meth:`sensor_temperature`.
1373
1373
 
1374
1374
  Returns
@@ -1381,8 +1381,7 @@ class Camera:
1381
1381
  RuntimeError
1382
1382
  If the camera is not connected.
1383
1383
  """
1384
- self._check_connected()
1385
- return self._gvcp.read_float(reg.REG_DEVICE_TEMPERATURE)
1384
+ return self.sensor_temperature("sensor")
1386
1385
 
1387
1386
  @property
1388
1387
  def info(self) -> dict:
@@ -1429,7 +1428,7 @@ class Camera:
1429
1428
  "power_state": reg.DevicePowerState(
1430
1429
  self._gvcp.read_reg(reg.REG_DEVICE_POWER_STATE)
1431
1430
  ).name,
1432
- "temperature_c": self._gvcp.read_float(reg.REG_DEVICE_TEMPERATURE),
1431
+ "temperature_c": self.sensor_temperature("sensor"),
1433
1432
  "buffer_mode": reg.MemoryBufferMode(
1434
1433
  self._gvcp.read_reg(reg.REG_MEMORY_BUFFER_MODE)
1435
1434
  ).name,
@@ -2241,6 +2240,12 @@ class Camera:
2241
2240
  repeated access in a loop, prefer :meth:`acquisition` +
2242
2241
  :meth:`read_frame` -- this method carries per-call setup overhead.
2243
2242
 
2243
+ Before waiting for a frame, any frame already sitting in the
2244
+ receiver's queue is discarded, so a leftover frame from before a
2245
+ setting change (for example :attr:`calibration_mode`) is not
2246
+ returned. Inside an :meth:`acquisition` block, frames still in
2247
+ transit can arrive after the drain. See the Notes section.
2248
+
2244
2249
  Parameters
2245
2250
  ----------
2246
2251
  timeout : float, optional
@@ -2266,6 +2271,33 @@ class Camera:
2266
2271
  RuntimeError
2267
2272
  If the camera is not connected or not ready.
2268
2273
 
2274
+ Notes
2275
+ -----
2276
+ ``stop_stream`` (called after every self-contained ``grab()``) joins
2277
+ the receiver thread but does not clear its output queue, so an
2278
+ assembled-but-unconsumed frame can survive across sessions. Without
2279
+ draining it, the next ``grab()`` -- possibly issued after a setting
2280
+ change such as :attr:`calibration_mode` -- would return that stale
2281
+ frame instead of a fresh one (issue #21).
2282
+
2283
+ ``grab()`` drains that queue itself before capturing a new frame:
2284
+
2285
+ - If the stream is not currently running, the receiver thread is
2286
+ guaranteed stopped, so a full :meth:`~pyGigEVision.GVSPReceiver.flush`
2287
+ is used: it drops queued frames, in-progress frame buffers, and any
2288
+ stray datagrams left in the OS socket buffer.
2289
+ - If the stream is already running (the receiver thread is active,
2290
+ e.g. inside an :meth:`acquisition` block), only the thread-safe
2291
+ output queue is drained by popping it non-blocking until empty.
2292
+ The raw socket is left alone in this case, because
2293
+ :meth:`~pyGigEVision.GVSPReceiver.flush` requires the receiver
2294
+ thread to be stopped to drain it safely.
2295
+
2296
+ Settings setters (e.g. the :attr:`calibration_mode` setter) do not
2297
+ drain the queue themselves: they may run while the receiver thread
2298
+ is active and have no safe, cheap way to do a full flush, and
2299
+ ``grab()`` already handles the draining on the read side.
2300
+
2269
2301
  Examples
2270
2302
  --------
2271
2303
  >>> with Camera() as cam:
@@ -2277,6 +2309,17 @@ class Camera:
2277
2309
  was_acquiring = self._acquiring
2278
2310
 
2279
2311
  try:
2312
+ if not self._streaming:
2313
+ # Receiver thread is not running yet -- safe to fully flush
2314
+ # any residual frames (and stray socket data) from a
2315
+ # previous session before starting a clean one.
2316
+ self._gvsp.flush()
2317
+ else:
2318
+ # Receiver thread is already running: only pop frames
2319
+ # already sitting on the thread-safe output queue. Do not
2320
+ # touch the raw socket while the thread reads from it.
2321
+ while self._gvsp.get_frame(timeout=0.0) is not None:
2322
+ pass
2280
2323
  if not self._acquiring:
2281
2324
  self.acquisition_start()
2282
2325
  frame = self._gvsp.get_frame(timeout=timeout)
@@ -2330,6 +2373,13 @@ class Camera:
2330
2373
  ------
2331
2374
  RuntimeError
2332
2375
  If the camera is not connected or not ready.
2376
+
2377
+ Notes
2378
+ -----
2379
+ Like :meth:`grab`, this drains any residual frame left over from a
2380
+ previous session before collecting *n_frames*, so the first frame
2381
+ of the batch is not a stale one from before this call. See the
2382
+ Notes section of :meth:`grab` for the full rationale (issue #21).
2333
2383
  """
2334
2384
  self._check_ready()
2335
2385
  was_streaming = self._streaming
@@ -2337,6 +2387,11 @@ class Camera:
2337
2387
 
2338
2388
  frames = []
2339
2389
  try:
2390
+ if not self._streaming:
2391
+ self._gvsp.flush()
2392
+ else:
2393
+ while self._gvsp.get_frame(timeout=0.0) is not None:
2394
+ pass
2340
2395
  if not self._acquiring:
2341
2396
  self.acquisition_start()
2342
2397
  deadline = time.monotonic() + timeout
@@ -2590,7 +2645,9 @@ class Camera:
2590
2645
  value = self._gvcp.read_float(reg.REG_DEVICE_TEMPERATURE_READOUT)
2591
2646
  # An unsupported location is reported as the ADC-floor sentinel
2592
2647
  # rather than a GVCPError; map it to the documented None (#16).
2593
- if abs(value - _TEMPERATURE_UNSUPPORTED_SENTINEL) < 1e-4:
2648
+ # Mainboard, marked not implemented in the TS-IR GenICam XML,
2649
+ # reads exactly 0.0 instead (#20).
2650
+ if value == 0.0 or abs(value - _TEMPERATURE_UNSUPPORTED_SENTINEL) < 1e-4:
2594
2651
  value = None
2595
2652
  temps[loc.name.lower()] = value
2596
2653
  except GVCPError:
@@ -100,7 +100,6 @@ REG_DEVICE_POWER_STATE = 0xE94C
100
100
  REG_DEVICE_LED = 0xE950
101
101
  REG_DEVICE_NOT_READY = 0xEA84
102
102
  REG_TDC_STATUS = 0xEAAC # Int, bitmask (RO, NoCache)
103
- REG_DEVICE_TEMPERATURE = 0xE970 # Float, Celsius
104
103
 
105
104
  # TDC Status bit flags
106
105
  TDC_WAITING_FOR_COOLER = 0x0001
@@ -451,7 +450,6 @@ REGISTER_INFO = {
451
450
  REG_DEVICE_POWER_STATE: ("DevicePowerState", "enum", "RO"),
452
451
  REG_DEVICE_NOT_READY: ("DeviceNotReady", "bool", "RO"),
453
452
  REG_TDC_STATUS: ("TDCStatus", "int", "RO"),
454
- REG_DEVICE_TEMPERATURE: ("DeviceTemperature", "float", "RO"),
455
453
  REG_DEVICE_RESET: ("DeviceReset", "cmd", "WO"),
456
454
  # Image Processing
457
455
  REG_IMAGE_CORRECTION: ("ImageCorrection", "cmd", "WO"),
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pyTelops"
7
- version = "0.2.4"
7
+ version = "0.2.5"
8
8
  description = "Pure-Python driver for Telops thermal cameras over GigE Vision"
9
9
  readme = "PYPI_README.rst"
10
10
  license = "MIT"
@@ -296,6 +296,39 @@ class TestAcquisitionAPI:
296
296
  assert cam.is_acquiring is True
297
297
  assert cam.is_acquiring is False
298
298
 
299
+ def test_grab_flushes_receiver_when_not_streaming(self):
300
+ """When the stream is not already running, grab() must fully flush
301
+ the receiver before starting a new session (issue #21)."""
302
+ cam = _make_fake_connected_camera()
303
+ cam._gvsp.get_frame.return_value = None
304
+ with patch.object(cam, "start_stream"), patch.object(cam, "stop_stream"):
305
+ cam.grab(timeout=0.0)
306
+ cam._gvsp.flush.assert_called_once()
307
+
308
+ def test_grab_drains_stale_frame_before_returning_fresh_one(self):
309
+ """If the stream is already running, grab() must discard any frame
310
+ already queued from before this call and return the next fresh one.
311
+
312
+ Regression test for issue #21: right after a calibration_mode
313
+ change, grab() returned a frame left over in the receiver queue
314
+ from before the change instead of a frame reflecting the new mode.
315
+ """
316
+ cam = _make_fake_connected_camera()
317
+ cam._streaming = True # receiver thread already running
318
+ stale = np.full((6, 8), 111, dtype=np.uint16)
319
+ fresh = np.full((6, 8), 222, dtype=np.uint16)
320
+ # Non-blocking drain loop pops "stale" then finds the queue empty;
321
+ # the subsequent blocking call returns the fresh frame.
322
+ cam._gvsp.get_frame.side_effect = [stale, None, fresh]
323
+
324
+ result = cam.grab(timeout=0.0, convert=False, strip_header=False)
325
+
326
+ assert (result == 222).all()
327
+ assert cam._gvsp.get_frame.call_count == 3
328
+ # The receiver thread is alive here, so the raw socket must not be
329
+ # touched -- only flush() (which drains the socket) is unsafe then.
330
+ cam._gvsp.flush.assert_not_called()
331
+
299
332
  def test_acquire_uses_acquisition_lifecycle(self):
300
333
  cam = _make_fake_connected_camera()
301
334
  cam._gvsp.get_frame.return_value = None
@@ -925,6 +958,13 @@ class TestDiagnosticsSentinel:
925
958
  assert d["temperatures"]
926
959
  assert all(v is None for v in d["temperatures"].values())
927
960
 
961
+ def test_zero_temperature_maps_to_none(self):
962
+ # Unimplemented Mainboard location reads exactly 0.0 on the TS-IR (#20)
963
+ cam = _make_fake_connected_camera()
964
+ cam._gvcp.read_float.return_value = 0.0
965
+ d = cam.diagnostics()
966
+ assert all(v is None for v in d["temperatures"].values())
967
+
928
968
  def test_real_temperature_preserved(self):
929
969
  cam = _make_fake_connected_camera()
930
970
  cam._gvcp.read_float.return_value = -196.3
@@ -932,6 +972,27 @@ class TestDiagnosticsSentinel:
932
972
  assert all(v == -196.3 for v in d["temperatures"].values())
933
973
 
934
974
 
975
+ class TestTemperature:
976
+ """``temperature`` must read the selector-based DeviceTemperature register.
977
+ 0xE970, the address it used before, is the external fan speed mode (issue #20)."""
978
+
979
+ def test_temperature_reads_sensor_location(self):
980
+ cam = _make_fake_connected_camera()
981
+ cam._gvcp.read_float.return_value = -196.3
982
+ assert cam.temperature == -196.3
983
+ cam._gvcp.write_reg.assert_called_with(
984
+ reg.REG_DEVICE_TEMPERATURE_SELECTOR, int(reg.TemperatureLocation.SENSOR)
985
+ )
986
+ cam._gvcp.read_float.assert_called_with(reg.REG_DEVICE_TEMPERATURE_READOUT)
987
+
988
+ def test_info_temperature_matches_property(self):
989
+ cam = _make_fake_connected_camera()
990
+ cam._gvcp.read_float.side_effect = lambda a: (
991
+ -196.3 if a == reg.REG_DEVICE_TEMPERATURE_READOUT else 1.0
992
+ )
993
+ assert cam.info["temperature_c"] == -196.3
994
+
995
+
935
996
  def _make_buffer_camera(
936
997
  pre_moi: int = 100,
937
998
  frames_per_seq: int | None = None,
@@ -120,6 +120,8 @@ class TestProperties:
120
120
  def test_temperature(self, cam):
121
121
  temp = cam.temperature
122
122
  assert isinstance(temp, float)
123
+ assert temp == pytest.approx(cam.sensor_temperature("sensor"), abs=1.0)
124
+ assert temp != 0.0 # 0.0 was the fan-mode register (issue #20)
123
125
 
124
126
  def test_calibration_mode_string(self, cam):
125
127
  """String enum works for calibration mode."""
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes