hiktemp 0.1.0__tar.gz

hiktemp-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: hiktemp
+Version: 0.1.0
+Summary: Minimal radiometric temperature extraction from Hikvision thermal cameras
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# hiktemp
+
+Minimal radiometric temperature extraction from Hikvision thermal cameras via ISAPI.  
+No SDK required. Only depends on `requests` and `numpy`.
+
+## Install
+
+```bash
+pip install hiktemp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourname/hiktemp
+cd hiktemp
+pip install -e .
+```
+
+## Usage
+
+```python
+from hiktemp import hiktemp
+
+# pull one frame
+frame = hiktemp("http://192.168.1.1", "admin", "password")
+
+frame.matrix          # np.ndarray (H, W) float32 — per-pixel °C
+frame.jpeg            # bytes — raw JPEG from camera (AGC, display only)
+frame.meta            # dict  — camera descriptor
+frame.min             # float — global min °C
+frame.max             # float — global max °C
+frame.mean            # float — global mean °C
+frame.std             # float — global std °C
+frame.hotspot()       # (row, col) — global hotspot
+frame.coldspot()      # (row, col) — global coldspot
+frame.to_bgr()        # np.ndarray (H,W,3) uint8 — cv2.imshow() ready
+
+# band filter — lo/hi passed at call time
+frame.hotspot(lo=28, hi=29)       # hotspot within band
+frame.coldspot(lo=28, hi=29)      # coldspot within band
+frame.masked(lo=28, hi=29)        # matrix, out-of-band pixels = NaN
+frame.alpha(lo=28, hi=29)         # float32 (H,W) quintic smoothstep mask
+frame.to_rgba(lo=28, hi=29)       # (H,W,4) uint8 with alpha mask applied
+
+# reuse session for continuous polling
+import requests
+from requests.auth import HTTPDigestAuth
+
+session = requests.Session()
+session.auth = HTTPDigestAuth("admin", "password")
+
+while True:
+    frame = hiktemp("http://192.168.1.1", "admin", "password", session=session)
+    bgr   = frame.to_bgr()
+    # cv2.imshow("thermal", bgr)
+```
+
+## Requirements
+
+- Python >= 3.10
+- `requests >= 2.28`
+- `numpy >= 1.23`
+
+opencv-python is **optional** — `to_bgr()` and `to_rgba()` return plain numpy arrays.
+
+## Tested on
+
+- DS-2TD2138-10/QY (384×288, float32 °C, channel 1)

hiktemp-0.1.0/README.md

@@ -0,0 +1,69 @@
+# hiktemp
+
+Minimal radiometric temperature extraction from Hikvision thermal cameras via ISAPI.  
+No SDK required. Only depends on `requests` and `numpy`.
+
+## Install
+
+```bash
+pip install hiktemp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourname/hiktemp
+cd hiktemp
+pip install -e .
+```
+
+## Usage
+
+```python
+from hiktemp import hiktemp
+
+# pull one frame
+frame = hiktemp("http://192.168.1.1", "admin", "password")
+
+frame.matrix          # np.ndarray (H, W) float32 — per-pixel °C
+frame.jpeg            # bytes — raw JPEG from camera (AGC, display only)
+frame.meta            # dict  — camera descriptor
+frame.min             # float — global min °C
+frame.max             # float — global max °C
+frame.mean            # float — global mean °C
+frame.std             # float — global std °C
+frame.hotspot()       # (row, col) — global hotspot
+frame.coldspot()      # (row, col) — global coldspot
+frame.to_bgr()        # np.ndarray (H,W,3) uint8 — cv2.imshow() ready
+
+# band filter — lo/hi passed at call time
+frame.hotspot(lo=28, hi=29)       # hotspot within band
+frame.coldspot(lo=28, hi=29)      # coldspot within band
+frame.masked(lo=28, hi=29)        # matrix, out-of-band pixels = NaN
+frame.alpha(lo=28, hi=29)         # float32 (H,W) quintic smoothstep mask
+frame.to_rgba(lo=28, hi=29)       # (H,W,4) uint8 with alpha mask applied
+
+# reuse session for continuous polling
+import requests
+from requests.auth import HTTPDigestAuth
+
+session = requests.Session()
+session.auth = HTTPDigestAuth("admin", "password")
+
+while True:
+    frame = hiktemp("http://192.168.1.1", "admin", "password", session=session)
+    bgr   = frame.to_bgr()
+    # cv2.imshow("thermal", bgr)
+```
+
+## Requirements
+
+- Python >= 3.10
+- `requests >= 2.28`
+- `numpy >= 1.23`
+
+opencv-python is **optional** — `to_bgr()` and `to_rgba()` return plain numpy arrays.
+
+## Tested on
+
+- DS-2TD2138-10/QY (384×288, float32 °C, channel 1)

hiktemp-0.1.0/hiktemp/__init__.py

@@ -0,0 +1,76 @@
+"""
+hiktemp
+~~~~~~~
+Minimal radiometric temperature extraction from Hikvision thermal cameras.
+
+    >>> from hiktemp import hiktemp
+    >>> from hiktemp import hiktemp
+    >>> frame = hiktemp("http://192.168.1.1", "admin", "password")
+    >>> frame.matrix              # np.ndarray (H,W) float32 °C
+    >>> frame.hotspot()           # (row, col) global
+    >>> frame.hotspot(lo=28, hi=29)  # (row, col) within band
+    >>> frame.masked(lo=28, hi=29)   # NaN outside band
+
+Only requires: requests, numpy.
+Visualization (colormap, bgr, rgba) is left to the caller via matplotlib/cv2.
+"""
+
+from __future__ import annotations
+
+import requests
+
+from ._fetch import fetch
+from ._frame import ThermalFrame
+
+__version__ = "0.1.0"
+__all__ = ["hiktemp", "ThermalFrame"]
+
+
+def hiktemp(
+    url: str,
+    username: str,
+    password: str,
+    *,
+    channel: int = 1,
+    timeout: float = 10.0,
+    session: requests.Session | None = None,
+) -> ThermalFrame:
+    """
+    Pull one radiometric frame from a Hikvision thermal camera.
+
+    Parameters
+    ----------
+    url : str
+        Base URL of the camera, e.g. ``"http://192.168.1.1"``.
+    username : str
+        Digest-auth username.
+    password : str
+        Digest-auth password.
+    channel : int
+        ISAPI thermal channel, default 1.
+    timeout : float
+        HTTP request timeout in seconds.
+    session : requests.Session, optional
+        Reuse an existing session (avoids repeated digest handshakes).
+
+    Returns
+    -------
+    ThermalFrame
+        ``.matrix``           — raw float32 °C array (H, W)
+        ``.jpeg``             — raw JPEG bytes (AGC, display only)
+        ``.meta``             — camera descriptor dict
+        ``.min/max/mean/std`` — scalar stats over full matrix
+        ``.hotspot(lo, hi)``  — (row, col) of peak temp, optional band
+        ``.coldspot(lo, hi)`` — (row, col) of min temp, optional band
+        ``.masked(lo, hi)``   — matrix with out-of-band pixels = NaN
+        ``.alpha(lo, hi)``    — float32 (H,W) quintic smoothstep mask
+    """
+    meta, jpeg, matrix = fetch(
+        url,
+        username,
+        password,
+        channel=channel,
+        timeout=timeout,
+        session=session,
+    )
+    return ThermalFrame(matrix, jpeg, meta)

hiktemp-0.1.0/hiktemp/_fetch.py

@@ -0,0 +1,81 @@
+"""
+hiktemp._fetch
+~~~~~~~~~~~~~~
+HTTP layer: digest auth, multipart parse, float32 blob decode.
+Only depends on `requests` and `numpy`.
+"""
+
+from __future__ import annotations
+
+import json
+import requests
+from requests.auth import HTTPDigestAuth
+
+import numpy as np
+
+_ENDPOINT = "/ISAPI/Thermal/channels/{ch}/thermometry/jpegPicWithAppendData?format=json"
+_BOUNDARY = b"--boundary"
+
+
+def _body(part: bytes) -> bytes:
+    """Strip multipart headers, return body bytes."""
+    i = part.find(b"\r\n\r\n")
+    return part[i + 4 :]
+
+
+def fetch(
+    url: str,
+    username: str,
+    password: str,
+    channel: int = 1,
+    timeout: float = 10.0,
+    session: requests.Session | None = None,
+) -> tuple[dict, bytes, np.ndarray]:
+    """
+    Pull one thermal frame from a Hikvision ISAPI endpoint.
+
+    Returns
+    -------
+    meta : dict
+        Parsed JSON descriptor from Part 1.
+    jpeg : bytes
+        Raw JPEG bytes from Part 2.
+    matrix : np.ndarray  shape (H, W)  dtype float32
+        Per-pixel temperature in °C from Part 3.
+    """
+    own_session = session is None
+    if own_session:
+        session = requests.Session()
+        session.auth = HTTPDigestAuth(username, password)
+
+    try:
+        resp = session.get(
+            url.rstrip("/") + _ENDPOINT.format(ch=channel),
+            stream=True,
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+    finally:
+        if own_session:
+            session.close()
+
+    raw = resp.content
+    parts = raw.split(_BOUNDARY)
+
+    # Part 1 — JSON metadata
+    meta_body = _body(parts[1])
+    meta_body = meta_body[: meta_body.find(b"--")]
+    meta = json.loads(meta_body)["JpegPictureWithAppendData"]
+
+    W: int = meta["jpegPicWidth"]
+    H: int = meta["jpegPicHeight"]
+
+    # Part 2 — thermal JPEG
+    jpeg = _body(parts[2])
+    jpeg = jpeg[: jpeg.find(_BOUNDARY)]
+
+    # Part 3 — float32 temperature blob
+    blob = _body(parts[3])[: W * H * 4]
+    matrix = np.frombuffer(blob, dtype="<f4").reshape(H, W).copy()
+
+    return meta, jpeg, matrix

hiktemp-0.1.0/hiktemp/_frame.py

@@ -0,0 +1,120 @@
+"""
+hiktemp._frame
+~~~~~~~~~~~~~~
+ThermalFrame — thin wrapper around the float32 temperature matrix.
+No dependencies beyond numpy.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def _band_alpha(matrix: np.ndarray, lo: float, hi: float) -> np.ndarray:
+    """
+    Quintic smoothstep alpha mask for band [lo, hi].
+    1.0 inside band, fades to 0.0 outside over a 5% margin.
+    Pure polynomial — no exp, no overflow.
+    """
+    fade = max((hi - lo) * 0.05, 0.1)
+
+    def _quintic(t: np.ndarray) -> np.ndarray:
+        t = np.clip(t, 0.0, 1.0)
+        return t * t * t * (t * (t * 6.0 - 15.0) + 10.0)
+
+    rise = _quintic((matrix - (lo - fade)) / fade)
+    fall = _quintic(((hi + fade) - matrix) / fade)
+    return (rise * fall).astype(np.float32)
+
+
+class ThermalFrame:
+    """
+    A single radiometric thermal frame.  Stores only raw sensor data.
+    Band filtering is applied at query time via method arguments.
+
+    Parameters
+    ----------
+    matrix : np.ndarray (H, W) float32
+        Per-pixel temperature in °C.
+    jpeg : bytes
+        Raw JPEG from the camera (AGC, display only).
+    meta : dict
+        JSON descriptor returned by the camera.
+    """
+
+    __slots__ = ("matrix", "jpeg", "meta")
+
+    def __init__(self, matrix: np.ndarray, jpeg: bytes, meta: dict) -> None:
+        self.matrix = matrix
+        self.jpeg = jpeg
+        self.meta = meta
+
+    # ── stats ──────────────────────────────────────────────────────────────────
+
+    @property
+    def min(self) -> float:
+        return float(self.matrix.min())
+
+    @property
+    def max(self) -> float:
+        return float(self.matrix.max())
+
+    @property
+    def mean(self) -> float:
+        return float(self.matrix.mean())
+
+    @property
+    def std(self) -> float:
+        return float(self.matrix.std())
+
+    def hotspot(
+        self,
+        lo: float | None = None,
+        hi: float | None = None,
+    ) -> tuple[int, int]:
+        """
+        (row, col) of maximum temperature pixel.
+        With lo/hi → restricted to pixels inside band.
+        """
+        if lo is not None and hi is not None:
+            m = self.matrix.copy()
+            m[self.alpha(lo, hi) < 0.01] = -np.inf
+        else:
+            m = self.matrix
+        r, c = np.unravel_index(int(np.argmax(m)), m.shape)
+        return int(r), int(c)
+
+    def coldspot(
+        self,
+        lo: float | None = None,
+        hi: float | None = None,
+    ) -> tuple[int, int]:
+        """
+        (row, col) of minimum temperature pixel.
+        With lo/hi → restricted to pixels inside band.
+        """
+        if lo is not None and hi is not None:
+            m = self.matrix.copy()
+            m[self.alpha(lo, hi) < 0.01] = np.inf
+        else:
+            m = self.matrix
+        r, c = np.unravel_index(int(np.argmin(m)), m.shape)
+        return int(r), int(c)
+
+    # ── band ───────────────────────────────────────────────────────────────────
+
+    def alpha(self, lo: float, hi: float) -> np.ndarray:
+        """Float32 (H, W) quintic smoothstep mask — 1.0 inside [lo, hi], 0.0 outside."""
+        return _band_alpha(self.matrix, lo, hi)
+
+    def masked(self, lo: float, hi: float) -> np.ndarray:
+        """Float32 (H, W) matrix with out-of-band pixels set to NaN."""
+        out = self.matrix.copy()
+        out[self.alpha(lo, hi) < 0.01] = np.nan
+        return out
+
+    # ── dunder ─────────────────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        H, W = self.matrix.shape
+        return f"<ThermalFrame {W}×{H} min={self.min:.2f} max={self.max:.2f} °C>"

hiktemp-0.1.0/hiktemp.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: hiktemp
+Version: 0.1.0
+Summary: Minimal radiometric temperature extraction from Hikvision thermal cameras
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: numpy>=1.23
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# hiktemp
+
+Minimal radiometric temperature extraction from Hikvision thermal cameras via ISAPI.  
+No SDK required. Only depends on `requests` and `numpy`.
+
+## Install
+
+```bash
+pip install hiktemp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourname/hiktemp
+cd hiktemp
+pip install -e .
+```
+
+## Usage
+
+```python
+from hiktemp import hiktemp
+
+# pull one frame
+frame = hiktemp("http://192.168.1.1", "admin", "password")
+
+frame.matrix          # np.ndarray (H, W) float32 — per-pixel °C
+frame.jpeg            # bytes — raw JPEG from camera (AGC, display only)
+frame.meta            # dict  — camera descriptor
+frame.min             # float — global min °C
+frame.max             # float — global max °C
+frame.mean            # float — global mean °C
+frame.std             # float — global std °C
+frame.hotspot()       # (row, col) — global hotspot
+frame.coldspot()      # (row, col) — global coldspot
+frame.to_bgr()        # np.ndarray (H,W,3) uint8 — cv2.imshow() ready
+
+# band filter — lo/hi passed at call time
+frame.hotspot(lo=28, hi=29)       # hotspot within band
+frame.coldspot(lo=28, hi=29)      # coldspot within band
+frame.masked(lo=28, hi=29)        # matrix, out-of-band pixels = NaN
+frame.alpha(lo=28, hi=29)         # float32 (H,W) quintic smoothstep mask
+frame.to_rgba(lo=28, hi=29)       # (H,W,4) uint8 with alpha mask applied
+
+# reuse session for continuous polling
+import requests
+from requests.auth import HTTPDigestAuth
+
+session = requests.Session()
+session.auth = HTTPDigestAuth("admin", "password")
+
+while True:
+    frame = hiktemp("http://192.168.1.1", "admin", "password", session=session)
+    bgr   = frame.to_bgr()
+    # cv2.imshow("thermal", bgr)
+```
+
+## Requirements
+
+- Python >= 3.10
+- `requests >= 2.28`
+- `numpy >= 1.23`
+
+opencv-python is **optional** — `to_bgr()` and `to_rgba()` return plain numpy arrays.
+
+## Tested on
+
+- DS-2TD2138-10/QY (384×288, float32 °C, channel 1)

hiktemp-0.1.0/hiktemp.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+hiktemp/__init__.py
+hiktemp/_fetch.py
+hiktemp/_frame.py
+hiktemp.egg-info/PKG-INFO
+hiktemp.egg-info/SOURCES.txt
+hiktemp.egg-info/dependency_links.txt
+hiktemp.egg-info/requires.txt
+hiktemp.egg-info/top_level.txt
+tests/test_hiktemp.py

hiktemp-0.1.0/hiktemp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hiktemp-0.1.0/hiktemp.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.28
+numpy>=1.23
+
+[dev]
+pytest
+ruff

hiktemp-0.1.0/hiktemp.egg-info/top_level.txt

@@ -0,0 +1 @@
+hiktemp

hiktemp-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hiktemp"
+version = "0.1.0"
+description = "Minimal radiometric temperature extraction from Hikvision thermal cameras"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = ["requests>=2.28", "numpy>=1.23"]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["hiktemp*"]

hiktemp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hiktemp-0.1.0/tests/test_hiktemp.py

@@ -0,0 +1,156 @@
+"""
+Smoke tests for hiktemp.
+Uses debug_multipart.raw so no live camera needed.
+"""
+
+import sys
+import os
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import json
+import numpy as np
+import pytest
+from unittest.mock import MagicMock, patch
+
+from hiktemp._fetch import _body
+from hiktemp._frame import ThermalFrame
+
+
+# ── fixtures ──────────────────────────────────────────────────────────────────
+
+RAW = os.path.join(os.path.dirname(__file__), "sample_frame.raw")
+assert os.path.exists(RAW), f"test fixture missing: {RAW}"
+
+
+@pytest.fixture
+def raw_data():
+    with open(RAW, "rb") as f:
+        return f.read()
+
+
+@pytest.fixture
+def frame(raw_data):
+    """Build a ThermalFrame directly from cached raw file."""
+    parts = raw_data.split(b"--boundary")
+    meta_body = _body(parts[1])
+    meta = json.loads(meta_body.split(b"--")[0])["JpegPictureWithAppendData"]
+    W, H = meta["jpegPicWidth"], meta["jpegPicHeight"]
+    jpeg = _body(parts[2])
+    jpeg = jpeg[: jpeg.find(b"--boundary")]
+    blob = _body(parts[3])[: W * H * 4]
+    matrix = np.frombuffer(blob, dtype="<f4").reshape(H, W).copy()
+    return ThermalFrame(matrix, jpeg, meta)
+
+
+@pytest.fixture
+def frame_banded(raw_data):
+    parts = raw_data.split(b"--boundary")
+    meta = json.loads(_body(parts[1]).split(b"--")[0])["JpegPictureWithAppendData"]
+    W, H = meta["jpegPicWidth"], meta["jpegPicHeight"]
+    jpeg = _body(parts[2])
+    jpeg = jpeg[: jpeg.find(b"--boundary")]
+    blob = _body(parts[3])[: W * H * 4]
+    matrix = np.frombuffer(blob, dtype="<f4").reshape(H, W).copy()
+    return ThermalFrame(matrix, jpeg, meta)
+
+
+# ── ThermalFrame basic ────────────────────────────────────────────────────────
+
+
+def test_matrix_shape(frame):
+    assert frame.matrix.shape == (288, 384)
+    assert frame.matrix.dtype == np.float32
+
+
+def test_stats(frame):
+    assert frame.min <= frame.mean <= frame.max
+    assert frame.std >= 0
+
+
+def test_hotspot_in_bounds(frame):
+    r, c = frame.hotspot()
+    H, W = frame.matrix.shape
+    assert 0 <= r < H and 0 <= c < W
+    assert frame.matrix[r, c] == pytest.approx(frame.matrix.max())
+
+
+def test_coldspot_in_bounds(frame):
+    r, c = frame.coldspot()
+    assert frame.matrix[r, c] == pytest.approx(frame.matrix.min())
+
+
+def test_repr(frame):
+    assert "ThermalFrame" in repr(frame)
+    assert "384" in repr(frame)
+
+
+# ── band masking ──────────────────────────────────────────────────────────────
+
+
+def test_alpha_shape(frame_banded):
+    a = frame_banded.alpha(lo=28.0, hi=29.0)
+    assert a.shape == frame_banded.matrix.shape
+    assert a.dtype == np.float32
+
+
+def test_alpha_range(frame_banded):
+    a = frame_banded.alpha(lo=28.0, hi=29.0)
+    assert a.min() >= 0.0
+    assert a.max() <= 1.0
+
+
+def test_masked_outside_is_nan(frame_banded):
+    m = frame_banded.masked(lo=28.0, hi=29.0)
+    far_outside = frame_banded.matrix < 27.5
+    if far_outside.any():
+        assert np.all(np.isnan(m[far_outside]))
+
+
+def test_masked_inside_not_nan(frame_banded):
+    m = frame_banded.masked(lo=28.0, hi=29.0)
+    mid = (frame_banded.matrix >= 28.2) & (frame_banded.matrix <= 28.8)
+    if mid.any():
+        assert not np.any(np.isnan(m[mid]))
+
+
+def test_no_band_full_matrix(frame):
+    # no band — hotspot/coldspot use full matrix
+    r, c = frame.hotspot()
+    assert frame.matrix[r, c] == pytest.approx(frame.matrix.max())
+
+
+def test_hotspot_in_band(frame_banded):
+    r, c = frame_banded.hotspot(lo=28.0, hi=29.0)
+    assert 28.0 - 0.1 <= frame_banded.matrix[r, c] <= 29.0 + 0.1
+
+
+def test_coldspot_in_band(frame_banded):
+    r, c = frame_banded.coldspot(lo=28.0, hi=29.0)
+    assert 28.0 - 0.1 <= frame_banded.matrix[r, c] <= 29.0 + 0.1
+
+
+
+# ── hiktemp() integration (mocked HTTP) ──────────────────────────────────────
+
+
+def test_hiktemp_integration(raw_data):
+    mock_resp = MagicMock()
+    mock_resp.content = raw_data
+    mock_resp.raise_for_status = MagicMock()
+
+    with patch("hiktemp._fetch.requests.Session") as MockSession:
+        MockSession.return_value.__enter__ = MagicMock()
+        instance = MockSession.return_value
+        instance.get.return_value = mock_resp
+
+        # call fetch directly with the mock session
+        from hiktemp._fetch import fetch
+
+        with patch("hiktemp._fetch.requests.Session", return_value=instance):
+            meta, jpeg, matrix = fetch("http://fake", "admin", "pass", session=instance)
+
+    assert matrix.shape == (288, 384)
+    assert matrix.dtype == np.float32
+    assert matrix.min() > -21
+    assert matrix.max() < 151