hiktemp 0.1.0__py3-none-any.whl

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/_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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+hiktemp/__init__.py,sha256=8K3loa7DGTDE1CbbpOWRQrQbNHvWuW4rmFsRZdgbnqA,2256
+hiktemp/_fetch.py,sha256=nsOg1pVnstzoDvL1_df4TTaTEgHalBLvwqn_ZxrY5-s,2032
+hiktemp/_frame.py,sha256=Itl1zPBkO5D126WJQ4AtdqpY27e8GWnWy7TzU2nNES8,3987
+hiktemp-0.1.0.dist-info/METADATA,sha256=my-9_-eNT9LwoKE7FrCnIfBeJbl2kFUYwBcMh7RFFw4,2309
+hiktemp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hiktemp-0.1.0.dist-info/top_level.txt,sha256=0qqqqDgHhms1RsQjvCHnsnU2pIoFuI9bDJYNHiOapu4,8
+hiktemp-0.1.0.dist-info/RECORD,,

hiktemp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hiktemp-0.1.0.dist-info/top_level.txt

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