# jacksonfcs/windows-hello-ir-camera-python architecture

> Architecture diagram of the GitHub repository jacksonfcs/windows-hello-ir-camera-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jacksonfcs/windows-hello-ir-camera-python
- Repository: https://github.com/jacksonfcs/windows-hello-ir-camera-python

## Overview

1. **Repository shape**
   - This is a **single-file Python library** centered on `whircam.py`, not a multi-package codebase.
   - The rest of the repo is mostly metadata, tests, and CI. That strongly suggests the architecture is intentionally flat: one public module exposes the full API and CLI.

2. **Primary purpose and boundary**
   - `whircam` is a **Windows-only raw camera access layer** for Windows Hello IR cameras.
   - Its main boundary is between:
     - **Windows WinRT camera APIs** on the native side, and
     - **Python callers** who want `find_groups()`, `IRCam()`, `read()`, and `imshow()`.

3. **External runtime dependencies**
   - Core functionality depends on the **WinRT Python projections** (`winrt-*` packages) and Windows 10 1809+.
   - `numpy` and `opencv-python` are **optional runtime dependencies** used only once a camera is opened, for array conversion and display.
   - That means discovery works without OpenCV, but frame reading and preview require it.

4. **Discovery subsystem**
   - The first subsystem is camera **enumeration** through `MediaFrameSourceGroup`.
   - `find_groups()` returns the IR-capable camera groups and their sources, which is the main discovery output consumed by the rest of the library.
   - This is the key architectural workaround for Windows Hello cameras, which are hidden from legacy camera APIs.

5. **Capture/open subsystem**
   - `IRCam()` is the main runtime object and the public entry point for actual capture.
   - It accepts multiple group selectors: by discovery index, display name, or a full group object.
   - The camera is opened in **SharedReadOnly** mode, which is an important architectural constraint: the library must coexist with Windows Hello authentication rather than taking exclusive control.

6. **Frame acquisition pipeline**
   - The capture path is built around a **pump loop** that continuously acquires the latest frame from the camera.
   - Frames are effectively buffered as “latest available” rather than queued exhaustively; older frames may be dropped if the consumer is slower than the camera.
   - The public read methods sit on top of this pump:
     - `read()` for image frames
     - `read_depth()` for depth frames
     - `read_both()` for paired delivery

7. **Frame transformation and output formats**
   - Raw WinRT frames are converted into Python-friendly arrays.
   - The output can be either **BGR** or **grayscale**, controlled by `format_output`.
   - Depth is delivered separately as **uint16 millimeter values**.
   - This conversion layer is where `numpy` and OpenCV become relevant; they are not needed for discovery alone.

8. **Preview/UI subsystem**
   - `imshow()` is a convenience layer on top of frame reading plus OpenCV window display.
   - It supports frame filtering modes like `illuminated`, `ambient`, and `both`, reflecting the IR camera’s alternating capture behavior.
   - This subsystem is optional and isolated from the core discovery API, which helps keep the minimal install usable without OpenCV.

9. **Lifecycle and cleanup**
   - `IRCam` is designed to work both as a normal object and as a **context manager**.
   - Cleanup is explicit via `release()`, with `destroy_all_windows()` for OpenCV UI resources.
   - The readme notes that WinRT calls can hang and that cleanup is best-effort, so the lifecycle boundary includes pragmatic shutdown handling rather than strict hard guarantees.

10. **CLI boundary**
   - The module also exposes a **command-line interface** for listing cameras, previewing video, and showing version information.
   - The CLI is a thin wrapper over the same discovery/capture core used by the Python API.
   - Architecturally, this means the same module serves both library and executable roles.

11. **Testing strategy**
   - The `test/` directory shows four main concerns:
     - API behavior
     - frame-store behavior
     - import stability
     - platform gating
   - That suggests the internal architecture includes a separable **frame store/buffering layer** and explicit checks for Windows-only execution.
   - Tests are intentionally designed around re-importing the module rather than mocking WinRT objects, which fits a native-binding-heavy architecture.

12. **CI and supported execution environment**
   - CI runs on **Windows Server 2022** across Python 3.10–3.13.
   - Hardware-dependent tests are excluded in CI, so the automated pipeline validates importability and core logic without requiring an actual IR camera.
   - This is a strong signal that the repo is meant to be robust in “no camera attached” environments, with the hardware path exercised separately.

13. **Packaging model**
   - The project is published as a pip/uv installable library, but the readme emphasizes that `whircam.py` can also be copied directly into another project.
   - That copy-friendly requirement explains the single-file design and the avoidance of package-level subdivision.
   - In an architecture diagram, treat the module as both the implementation container and the public surface.

14. **What to draw as the main data flow**
   - A useful diagram would show:
     - **Python caller / CLI**
     - into **whircam.py public API**
     - into **WinRT discovery and capture APIs**
     - returning **camera groups, frames, and depth data**
     - optionally flowing through **NumPy/OpenCV conversion and display**
   - The key boundary is that the library does not process biometrics; it only exposes raw IR image/depth data from Windows Hello camera hardware.

Main entry points: [`whircam.py`](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py) (Public API), [`.github/workflows/ci.yml`](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/.github/workflows/ci.yml) (CI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_public["Public surface"]
  node_n_caller(("Python caller<br/>consumer"))
  node_n_cli["CLI<br/>entrypoint<br/>[whircam.py]"]
end

subgraph group_g_core["whircam.py"]
  node_n_api["Public API<br/>module api<br/>[whircam.py]"]
  node_n_discovery["Discovery<br/>enumeration<br/>[whircam.py]"]
  node_n_selector["Group select<br/>input resolution<br/>[whircam.py]"]
  node_n_cam["IRCam<br/>capture object<br/>[whircam.py]"]
  node_n_open[("Shared open<br/>camera session<br/>[whircam.py]")]
  node_n_pump{{"Pump loop<br/>acquisition loop<br/>[whircam.py]"}}
  node_n_store[("Frame store<br/>buffer<br/>[whircam.py]")]
  node_n_read["Read APIs<br/>frame access<br/>[whircam.py]"]
  node_n_convert["Convert<br/>transform<br/>[whircam.py]"]
  node_n_preview["imshow()<br/>preview<br/>[whircam.py]"]
  node_n_cleanup["Cleanup<br/>lifecycle<br/>[whircam.py]"]
end

subgraph group_g_external["External runtime"]
  node_n_winrt["WinRT APIs<br/>platform binding"]
  node_n_windows(("Windows 10+<br/>platform"))
  node_n_numpy["NumPy<br/>optional dependency"]
  node_n_opencv["OpenCV<br/>optional dependency"]
end

subgraph group_g_quality["Tests and CI"]
  node_n_tests["Tests<br/>validation suite"]
  node_n_ci["CI<br/>workflow<br/>[ci.yml]"]
end

node_n_caller -->|"imports/calls"| node_n_api
node_n_caller -->|"invokes"| node_n_cli
node_n_cli -->|"lists cameras"| node_n_discovery
node_n_api -->|"find_groups()"| node_n_discovery
node_n_api -->|"selects target"| node_n_selector
node_n_selector -->|"creates"| node_n_cam
node_n_cam -->|"opens"| node_n_open
node_n_open -->|"binds to"| node_n_winrt
node_n_winrt -->|"requires"| node_n_windows
node_n_cam -->|"starts"| node_n_pump
node_n_pump -->|"updates latest"| node_n_store
node_n_store -->|"serves"| node_n_read
node_n_read -->|"transforms"| node_n_convert
node_n_convert -->|"uses"| node_n_numpy
node_n_preview -->|"uses"| node_n_opencv
node_n_api -->|"imshow()"| node_n_preview
node_n_cam -->|"releases"| node_n_cleanup
node_n_cleanup -->|"closes windows"| node_n_opencv
node_n_tests -->|"covers"| node_n_api
node_n_tests -->|"covers"| node_n_store
node_n_tests -->|"gated by"| node_n_windows
node_n_ci -->|"runs"| node_n_tests

click node_n_cli "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_api "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_discovery "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_selector "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_cam "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_open "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_pump "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_store "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_read "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_convert "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_preview "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_cleanup "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py"
click node_n_ci "https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_caller,node_n_cli toneBlue
class node_n_api,node_n_discovery,node_n_selector,node_n_cam,node_n_open,node_n_pump,node_n_store,node_n_read,node_n_convert,node_n_preview,node_n_cleanup toneAmber
class node_n_winrt,node_n_windows,node_n_numpy,node_n_opencv toneMint
class node_n_tests,node_n_ci toneRose
```

## Components

### Public surface

How users enter the library

- **Python caller**: consumer · Library user code importing and calling the API
- [CLI](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): entrypoint · Command-line wrapper for listing and previewing cameras · `whircam.py`

### whircam.py

Single-file implementation and runtime pipeline

- [Public API](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): module api · Main module surface exposing discovery, capture, and preview helpers · `whircam.py`
- [Discovery](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): enumeration · Finds Windows Hello IR-capable camera groups and sources · `whircam.py`
- [Group select](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): input resolution · Resolves camera selection by index, display name, or group object · `whircam.py`
- [IRCam](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): capture object · Runtime camera handle and context-manager boundary · `whircam.py`
- [Shared open](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): camera session · Opens the camera in SharedReadOnly mode so Windows Hello can coexist · `whircam.py`
- [Pump loop](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): acquisition loop · Continuously acquires the latest available frame · `whircam.py`
- [Frame store](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): buffer · Holds latest image and depth frames, dropping stale ones when needed · `whircam.py`
- [Read APIs](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): frame access · read(), read_depth(), and read_both() output methods · `whircam.py`
- [Convert](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): transform · Turns WinRT frames into NumPy-friendly arrays and output formats · `whircam.py`
- [imshow()](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): preview · OpenCV-based display helper with IR frame mode filtering · `whircam.py`
- [Cleanup](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/whircam.py): lifecycle · release() and window teardown for best-effort shutdown · `whircam.py`

### External runtime

Platform and third-party dependencies

- **WinRT APIs**: platform binding · Windows MediaFrameSourceGroup and camera capture projections
- **Windows 10+**: platform · Windows-only execution environment for IR camera access
- **NumPy**: optional dependency · Used for array conversion after capture starts
- **OpenCV**: optional dependency · Used for preview windows and image display

### Tests and CI

Validation and supported execution environment

- **Tests**: validation suite · Behavior, frame-store, import, and platform-gating checks
- [CI](https://github.com/jacksonfcs/windows-hello-ir-camera-python/blob/main/.github/workflows/ci.yml): workflow · Windows Server 2022 matrix across Python 3.10-3.13 · `.github/workflows/ci.yml`

## Connections

- Python caller → Public API: imports/calls · Python code uses the library surface
- Python caller → CLI: invokes · The same module can run as a command-line tool
- CLI → Discovery: lists cameras · CLI discovery output is built from the same enumeration path
- Public API → Discovery: find_groups() · Enumerates IR-capable source groups
- Public API → Group select: selects target · Resolves user input into a camera group
- Group select → IRCam: creates · Selection feeds the main capture object
- IRCam → Shared open: opens · Establishes a shared camera session
- Shared open → WinRT APIs: binds to · Capture and discovery use WinRT camera projections
- WinRT APIs → Windows 10+: requires · Native camera access is Windows-only
- IRCam → Pump loop: starts · Runtime object drives the acquisition loop
- Pump loop → Frame store: updates latest · Pump writes newest image/depth frames into the buffer
- Frame store → Read APIs: serves · Public read methods pull from the buffered latest frame
- Read APIs → Convert: transforms · Frames are converted into Python-friendly outputs
- Convert → NumPy: uses · Array conversion depends on NumPy when capture is active
- imshow() → OpenCV: uses · Preview windows depend on OpenCV
- Public API → imshow(): imshow() · Convenience preview sits on top of frame reading
- IRCam → Cleanup: releases · Object lifecycle ends through explicit cleanup or context manager exit
- Cleanup → OpenCV: closes windows · Window teardown is part of UI cleanup
- Tests → Public API: covers · Tests focus on import stability and API behavior
- Tests → Frame store: covers · Frame-store behavior is tested as a separable concern
- Tests → Windows 10+: gated by · Platform checks keep non-Windows runs from executing hardware paths
- CI → Tests: runs · CI validates the repo in a Windows matrix without real hardware
