webcam-micro 0.2.0__py3-none-any.whl
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.
- webcam_micro/README.md +254 -0
- webcam_micro/VERSION +1 -0
- webcam_micro/__init__.py +16 -0
- webcam_micro/__main__.py +6 -0
- webcam_micro/app.py +77 -0
- webcam_micro/camera.py +6992 -0
- webcam_micro/error_reporting.py +31 -0
- webcam_micro/launcher.py +28 -0
- webcam_micro/licenses/PySide6-6.11.3.txt +1198 -0
- webcam_micro/licenses/README.md +28 -0
- webcam_micro/licenses/THIRD_PARTY_LICENSES.md +13 -0
- webcam_micro/licenses/rubicon-objc-0.5.7.txt +71 -0
- webcam_micro/macos_permission.py +18 -0
- webcam_micro/runtime-requirements.lock +29 -0
- webcam_micro/runtime_bootstrap.py +232 -0
- webcam_micro/ui.py +4052 -0
- webcam_micro/webcam-micro.png +0 -0
- webcam_micro-0.2.0.dist-info/METADATA +264 -0
- webcam_micro-0.2.0.dist-info/RECORD +22 -0
- webcam_micro-0.2.0.dist-info/WHEEL +5 -0
- webcam_micro-0.2.0.dist-info/entry_points.txt +2 -0
- webcam_micro-0.2.0.dist-info/top_level.txt +1 -0
webcam_micro/README.md
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
# webcam-micro
|
|
2
|
+
**Doc ID:** README
|
|
3
|
+
**Doc Type:** repo-readme
|
|
4
|
+
**Project Version:** 0.2.0
|
|
5
|
+
**Last Updated:** 2026-04-08
|
|
6
|
+
**DevCovenant Version:** 1.0.1b1
|
|
7
|
+
|
|
8
|
+
<!-- DEVCOV:BEGIN -->
|
|
9
|
+
|
|
10
|
+
<!-- DEVCOV:END -->
|
|
11
|
+
|
|
12
|
+
Cross-platform microscope camera application distributed as a Python package
|
|
13
|
+
on PyPI.
|
|
14
|
+
|
|
15
|
+

|
|
16
|
+
|
|
17
|
+
## Table of Contents
|
|
18
|
+
1. [Overview](#overview)
|
|
19
|
+
2. [Alpha Status](#alpha-status)
|
|
20
|
+
3. [What Works Today](#what-works-today)
|
|
21
|
+
4. [Installation](#installation)
|
|
22
|
+
5. [Launch](#launch)
|
|
23
|
+
6. [Windowed Workspace](#windowed-workspace)
|
|
24
|
+
7. [Fullscreen Workspace](#fullscreen-workspace)
|
|
25
|
+
8. [Preview and Framing](#preview-and-framing)
|
|
26
|
+
9. [Camera Controls](#camera-controls)
|
|
27
|
+
10. [Capture and Recording](#capture-and-recording)
|
|
28
|
+
11. [Preferences, Defaults, and Presets](#preferences-defaults-and-presets)
|
|
29
|
+
12. [Diagnostics and Status](#diagnostics-and-status)
|
|
30
|
+
13. [Platform Notes](#platform-notes)
|
|
31
|
+
14. [Current Limitations](#current-limitations)
|
|
32
|
+
15. [Packaging and Distribution](#packaging-and-distribution)
|
|
33
|
+
16. [Security, Privacy, and Support](#security-privacy-and-support)
|
|
34
|
+
17. [Repository Notes](#repository-notes)
|
|
35
|
+
18. [License](#license)
|
|
36
|
+
|
|
37
|
+
## Overview
|
|
38
|
+
`webcam-micro` is a preview-first microscope camera application for live
|
|
39
|
+
viewing, camera control, still capture, and recording.
|
|
40
|
+
|
|
41
|
+
The current alpha release runs on the Qt Widgets shell baseline. Today it
|
|
42
|
+
opens a native desktop workspace with a menu bar, toolbar, central preview
|
|
43
|
+
area, toggleable controls dock, quiet still-image save to the configured
|
|
44
|
+
folder, a tighter preview refresh cadence, native recording, session
|
|
45
|
+
preferences, diagnostics, and a compact fullscreen command surface with
|
|
46
|
+
expanded and collapsed states. Preview framing, capture framing, camera
|
|
47
|
+
selection, window layout, current preset name, and per-camera control
|
|
48
|
+
values persist across launches. Image and video output folders live in
|
|
49
|
+
Preferences, and the compact status bar stays structured. User-editable
|
|
50
|
+
defaults, keyboard shortcuts, and named presets are available, while
|
|
51
|
+
broader platform validation is covered by automated tests and Linux smoke
|
|
52
|
+
checks here.
|
|
53
|
+
|
|
54
|
+
## Alpha Status
|
|
55
|
+
`webcam-micro` is now the official alpha release.
|
|
56
|
+
The release version is sourced from `webcam_micro/VERSION`, and the shell
|
|
57
|
+
chrome carries the full legal-owner notice.
|
|
58
|
+
The Qt Widgets baseline is usable for live preview, camera control, still
|
|
59
|
+
capture, recording, presets, and diagnostics. The remaining beta-prep work
|
|
60
|
+
is now deferred until after beta publication, so the beta plan is
|
|
61
|
+
complete for the current release path.
|
|
62
|
+
|
|
63
|
+
## What Works Today
|
|
64
|
+
- Launch and entrypoint: the application starts from the `webcam-micro`
|
|
65
|
+
command, bootstraps a stable per-user runtime interpreter on every
|
|
66
|
+
supported OS, refreshes the private runtime bridge on each launch, and
|
|
67
|
+
can also run from source during development.
|
|
68
|
+
- Windowed workspace: the main shell keeps the preview central while the
|
|
69
|
+
menu bar, toolbar, and status bar expose the primary microscope
|
|
70
|
+
actions, and the controls dock can dock, float, hide, and restore
|
|
71
|
+
without taking the preview off center. A visible Restore Dock action
|
|
72
|
+
keeps detached controls easy to reattach.
|
|
73
|
+
- Fullscreen workspace: the preview expands to the full screen and the
|
|
74
|
+
command surface collapses into a compact overlay with safe exit paths.
|
|
75
|
+
- Preview and framing: live preview supports fit, fill, and centered crop
|
|
76
|
+
modes, and a tighter refresh cadence keeps the newest frame close to live
|
|
77
|
+
motion when the preview resizes.
|
|
78
|
+
- Camera controls: the dock splits native controls into Camera Controls
|
|
79
|
+
and User Controls. Resolution stays in the preview path as a dropdown.
|
|
80
|
+
The selected device-control owner exposes Exposure and Focus as
|
|
81
|
+
slider-plus-spinbox controls with exposure lock and Auto checkboxes
|
|
82
|
+
when the camera reports them, Light as an on/off checkbox plus a level
|
|
83
|
+
slider when exposed, and Zoom as a slider-plus-spinbox row when the
|
|
84
|
+
camera reports it. When Auto is enabled, the paired numeric control
|
|
85
|
+
stays visible, greys out, and tracks the live device value. User
|
|
86
|
+
Controls expose backend-owned Backlight compensation, Brightness,
|
|
87
|
+
Contrast, Hue, Saturation, Sharpness, Gamma, Gain, Power Line
|
|
88
|
+
Frequency, and White balance rows, Contrast and Hue keep Auto
|
|
89
|
+
checkboxes, White balance keeps its Auto checkbox, and a Reset to
|
|
90
|
+
Defaults button sits at the bottom. The app selects one control owner
|
|
91
|
+
per camera by canonical device identity and reads ranges, choices, and
|
|
92
|
+
writes from that backend only.
|
|
93
|
+
- The active backend still exposes numeric, boolean, enum, read-only,
|
|
94
|
+
and action controls when the selected owner supports them. The preview
|
|
95
|
+
path keeps source-format selection separate from camera-control
|
|
96
|
+
ownership. On Linux, V4L2 adds power line frequency, image-quality
|
|
97
|
+
controls, lamp, illumination, activity LED, and vendor-specific
|
|
98
|
+
extension controls when the camera reports them.
|
|
99
|
+
- Capture and recording: still images save quietly to the configured folder
|
|
100
|
+
with the current capture framing, and recordings use native controls with
|
|
101
|
+
platform-supported containers.
|
|
102
|
+
- Preferences, defaults, and presets: framing, keyboard shortcuts,
|
|
103
|
+
defaults, and named presets are stored with the workspace, while image
|
|
104
|
+
and video output folders live in Preferences.
|
|
105
|
+
- Diagnostics and status: the shell reports runtime state, recent failures,
|
|
106
|
+
and prototype exit checks in a visible diagnostics dialog and status bar.
|
|
107
|
+
- Platform notes: Qt Multimedia owns the camera and recording stack,
|
|
108
|
+
while platform and device differences still shape the available
|
|
109
|
+
controls. The app selects one device-control owner per camera by
|
|
110
|
+
canonical hardware identity so the UI reads one source of truth for
|
|
111
|
+
ranges, menus, and writes. On macOS and Windows, that owner is
|
|
112
|
+
platform-selected; on Linux, V4L2 contributes extra control discovery
|
|
113
|
+
for device-specific and vendor-specific settings when available. The
|
|
114
|
+
shared error-reporting layer keeps launcher, runtime bootstrap, and
|
|
115
|
+
camera failures as typed notices and diagnostics instead of raw
|
|
116
|
+
tracebacks.
|
|
117
|
+
|
|
118
|
+
## Installation
|
|
119
|
+
The packaged app supports Python `3.11` through `3.14`.
|
|
120
|
+
Install it from PyPI or a built wheel, then launch it with:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
webcam-micro
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## Launch
|
|
127
|
+
The application starts in a preview-first Qt Widgets window.
|
|
128
|
+
The `webcam_micro.launcher` module uses `webcam_micro.runtime_bootstrap` to
|
|
129
|
+
create or reuse a stable per-user runtime interpreter on Windows, macOS,
|
|
130
|
+
and Linux before the Qt shell starts, so the first launch sets up the
|
|
131
|
+
Python identity that will own later camera access on macOS. The launcher
|
|
132
|
+
refreshes the private runtime bridge on each launch so stale runtimes
|
|
133
|
+
self-heal, and the bridge keeps the package imports visible in that
|
|
134
|
+
interpreter so Qt still loads from the installed package set. On macOS,
|
|
135
|
+
the camera permission prompt runs through a repo-owned adapter so the same
|
|
136
|
+
code path stays import-safe on Windows and Linux.
|
|
137
|
+
The command bar and native menu bar provide access to the core camera,
|
|
138
|
+
capture, framing, preference, and diagnostics actions without requiring a
|
|
139
|
+
terminal once the app is running.
|
|
140
|
+
On macOS, the runtime interpreter requests camera permission the first time
|
|
141
|
+
a camera opens through that adapter; if it was denied before, reset the
|
|
142
|
+
Camera privacy setting and relaunch.
|
|
143
|
+
|
|
144
|
+
## Windowed Workspace
|
|
145
|
+
The main window keeps the microscope preview central.
|
|
146
|
+
The native menu bar carries File for Exit, Edit for copy status, View for
|
|
147
|
+
controls and framing, Camera for camera refresh, open, and close, Capture
|
|
148
|
+
for still and recording actions, Tools for preferences and diagnostics, and
|
|
149
|
+
Help for About. The toolbar keeps the main working actions close to the live
|
|
150
|
+
image, including controls, camera refresh, camera open and close, framing,
|
|
151
|
+
still capture, recording, fullscreen, and preferences. The right edge of
|
|
152
|
+
the toolbar displays `© 2026 Black Epsilon Ltd. and Apostol Apostolov`.
|
|
153
|
+
|
|
154
|
+
The controls dock can be shown, hidden, floated, or restored so camera
|
|
155
|
+
controls do not consume preview space permanently. It keeps the preview
|
|
156
|
+
central even when detached, defaults to one vertical column, and widens to
|
|
157
|
+
two columns on roomier layouts while preserving the section order.
|
|
158
|
+
Numeric controls use guvcview-style affordances: a slider, min/mid/max
|
|
159
|
+
labels, and an adjacent field with step buttons. Boolean, enumerated,
|
|
160
|
+
read-only, and action controls appear when the backend exposes them.
|
|
161
|
+
|
|
162
|
+
## Fullscreen Workspace
|
|
163
|
+
Fullscreen replaces the windowed chrome with a compact command surface.
|
|
164
|
+
Expanded fullscreen shows the core microscope actions plus collapse and safe
|
|
165
|
+
windowed exit. Collapsed fullscreen keeps only collapse/expand and the
|
|
166
|
+
fullscreen/windowed toggle visible. Escape returns to windowed mode.
|
|
167
|
+
|
|
168
|
+
## Preview and Framing
|
|
169
|
+
Preview framing supports fit, fill, and centered crop modes.
|
|
170
|
+
The live preview rerenders from the newest cached frame when the window or
|
|
171
|
+
preview area changes size, and the tighter poll cadence keeps the visible
|
|
172
|
+
motion closer to the live feed. Capture framing is separate from preview
|
|
173
|
+
framing so stills and videos can follow their own output rules without
|
|
174
|
+
changing the live microscope view.
|
|
175
|
+
|
|
176
|
+
## Camera Controls
|
|
177
|
+
The app exposes the real control surface reported by the active camera and
|
|
178
|
+
backend. The dock splits those controls into Camera Controls and User
|
|
179
|
+
Controls. Camera Controls expose Resolution as a dropdown, Exposure and
|
|
180
|
+
Focus as slider-plus-spinbox widgets with Auto checkboxes when the camera
|
|
181
|
+
reports them, Light as an on/off checkbox plus a level slider when
|
|
182
|
+
available, and Zoom when the backend reports it. When Auto is enabled,
|
|
183
|
+
the paired numeric control stays visible, greys out, and tracks the auto
|
|
184
|
+
value. User Controls expose backend-owned Backlight compensation,
|
|
185
|
+
Brightness, Contrast, Hue, Saturation, Sharpness, Gamma, Gain, Power Line
|
|
186
|
+
Frequency, and White balance rows, with Auto checkboxes on Contrast, Hue,
|
|
187
|
+
and White balance when the backend exposes them, and a Reset to Defaults
|
|
188
|
+
button at the bottom.
|
|
189
|
+
Native device-control backends cover the common exposure, focus, white
|
|
190
|
+
balance, flash, torch, zoom, and source-format controls across supported
|
|
191
|
+
platforms, while Linux V4L2 adds power line frequency, image-quality
|
|
192
|
+
controls, lamp, illumination, activity LED, and vendor-specific
|
|
193
|
+
extensions when the device reports them. Supported controls include
|
|
194
|
+
numeric, boolean, enumerated, read-only, and action widgets. The app
|
|
195
|
+
tolerates partial control sets and does not fail just because a camera
|
|
196
|
+
lacks an expected control.
|
|
197
|
+
On macOS, the native UVC-style control backend owns UVC controls first and
|
|
198
|
+
AVFoundation remains a fallback for native-only gaps. AVFoundation
|
|
199
|
+
exposure, focus, white balance, and backlight writes stay on the native
|
|
200
|
+
nil-completion path so slider commits avoid the callback crash. Automatic
|
|
201
|
+
Video HDR is only surfaced when the active format reports HDR support.
|
|
202
|
+
|
|
203
|
+
## Capture and Recording
|
|
204
|
+
Still images save quietly to the configured image folder as PNG or JPEG
|
|
205
|
+
output. Recording starts and stops natively in the Qt shell, shows elapsed
|
|
206
|
+
status while it runs, and only offers containers that the current Qt
|
|
207
|
+
Multimedia runtime supports. The `webcam_micro.camera` recording helper
|
|
208
|
+
rejects unsupported suffixes before recording starts. Recorded video uses
|
|
209
|
+
the active capture-framing choice and remembers the output folder across
|
|
210
|
+
launches.
|
|
211
|
+
|
|
212
|
+
## Preferences, Defaults, and Presets
|
|
213
|
+
Preferences store preview framing, capture framing, output folders, editable
|
|
214
|
+
defaults, keyboard shortcuts, and named presets.
|
|
215
|
+
The app remembers the current preset name, restores per-camera control
|
|
216
|
+
values when available, and keeps editable control defaults grouped by the
|
|
217
|
+
same section names inside Preferences. It also lets users save or apply
|
|
218
|
+
named presets from the same preferences dialog.
|
|
219
|
+
|
|
220
|
+
## Diagnostics and Status
|
|
221
|
+
The diagnostics dialog shows a runtime report, a recent-failures log, and
|
|
222
|
+
prototype exit checks. The status bar summarizes backend, camera, source
|
|
223
|
+
mode, preview framing, capture framing, controls state, preset name,
|
|
224
|
+
recording state, and the current status notice.
|
|
225
|
+
|
|
226
|
+
## Platform Notes
|
|
227
|
+
Qt Multimedia owns camera discovery, preview, recording, and the common
|
|
228
|
+
control surface. On Linux, V4L2 contributes extra control discovery for
|
|
229
|
+
device-specific and vendor-specific settings when available. Actual
|
|
230
|
+
controls and container support vary by camera, backend, and platform. The
|
|
231
|
+
app only surfaces controls the backend can actually use, and the recording
|
|
232
|
+
path filters the save dialog to supported containers.
|
|
233
|
+
|
|
234
|
+
## Current Limitations
|
|
235
|
+
Some camera controls and output formats remain backend-dependent.
|
|
236
|
+
|
|
237
|
+
## Packaging and Distribution
|
|
238
|
+
`webcam-micro` is shipped as a Python package on PyPI.
|
|
239
|
+
The package-facing README lives at `webcam_micro/README.md`, where the
|
|
240
|
+
repo-only notes are stripped out before packaging. The `webcam_micro.launcher`
|
|
241
|
+
entrypoint uses `webcam_micro.runtime_bootstrap` to create or reuse the
|
|
242
|
+
per-user runtime interpreter on every supported OS before handing off to
|
|
243
|
+
the GUI app. It also refreshes the private runtime bridge on each launch
|
|
244
|
+
so stale runtimes self-heal, and the source package remains runnable
|
|
245
|
+
during development.
|
|
246
|
+
|
|
247
|
+
## Security, Privacy, and Support
|
|
248
|
+
`webcam-micro` is a local desktop utility by default.
|
|
249
|
+
The core camera workflow does not depend on cloud services, accounts, or
|
|
250
|
+
telemetry, and the app should stay usable without terminal interaction
|
|
251
|
+
during normal microscope work.
|
|
252
|
+
|
|
253
|
+
## License
|
|
254
|
+
Document the repository licensing terms here.
|
webcam_micro/VERSION
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
0.2.0
|
webcam_micro/__init__.py
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""Foundation constants for the `webcam_micro` prototype package."""
|
|
2
|
+
|
|
3
|
+
APP_NAME = "webcam-micro"
|
|
4
|
+
PACKAGE_NAME = "webcam_micro"
|
|
5
|
+
GUI_BASELINE = "PySide6 Qt Widgets"
|
|
6
|
+
BACKEND_STRATEGY = (
|
|
7
|
+
"Qt Widgets owns the native desktop shell while Qt Multimedia owns "
|
|
8
|
+
"camera discovery, preview, and recording; the repo layer keeps "
|
|
9
|
+
"microscope-specific framing, outputs, defaults, diagnostics, a "
|
|
10
|
+
"rubicon-backed AVFoundation permission bridge on macOS, and one "
|
|
11
|
+
"platform-selected device-control owner per camera. Canonical device "
|
|
12
|
+
"identity chooses that owner, preview-owned source-format selection "
|
|
13
|
+
"stays separate, and Linux V4L2 adds extra device-specific discovery "
|
|
14
|
+
"when available."
|
|
15
|
+
)
|
|
16
|
+
SHELL_TITLE = "webcam-micro workspace"
|
webcam_micro/__main__.py
ADDED
webcam_micro/app.py
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""Application entrypoints for the current Qt Widgets shell baseline."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from typing import Sequence
|
|
8
|
+
|
|
9
|
+
from webcam_micro import APP_NAME, BACKEND_STRATEGY, GUI_BASELINE, PACKAGE_NAME
|
|
10
|
+
from webcam_micro.camera import build_backend_plan
|
|
11
|
+
from webcam_micro.error_reporting import WebcamMicroError, build_error_report
|
|
12
|
+
from webcam_micro.ui import launch_main_window
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class LaunchPlan:
|
|
17
|
+
"""Describe the chosen launch baseline."""
|
|
18
|
+
|
|
19
|
+
app_name: str
|
|
20
|
+
package_name: str
|
|
21
|
+
entrypoint_name: str
|
|
22
|
+
gui_baseline: str
|
|
23
|
+
backend_strategy: str
|
|
24
|
+
first_device_backend_target: str
|
|
25
|
+
shell_contract: str
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def build_launch_plan() -> LaunchPlan:
|
|
29
|
+
"""Return the current application decision."""
|
|
30
|
+
|
|
31
|
+
backend_plan = build_backend_plan()
|
|
32
|
+
return LaunchPlan(
|
|
33
|
+
app_name=APP_NAME,
|
|
34
|
+
package_name=PACKAGE_NAME,
|
|
35
|
+
entrypoint_name="webcam-micro",
|
|
36
|
+
gui_baseline=GUI_BASELINE,
|
|
37
|
+
backend_strategy=BACKEND_STRATEGY,
|
|
38
|
+
first_device_backend_target=backend_plan.first_device_backend_target,
|
|
39
|
+
shell_contract=(
|
|
40
|
+
"Preview-first Qt Widgets main window with a native desktop menu "
|
|
41
|
+
"bar, toolbar, controls dock, live fit/fill/crop framing, "
|
|
42
|
+
"native still-save and recording actions, session preferences, "
|
|
43
|
+
"diagnostics with a failure log and exit checks, native "
|
|
44
|
+
"window fullscreen support, a dockable, detachable controls "
|
|
45
|
+
"pane that can hide, dock, float, and restore while keeping the "
|
|
46
|
+
"preview central, a one-column default layout with a wider "
|
|
47
|
+
"two-column variant on roomy layouts, image and video output "
|
|
48
|
+
"folders that live in Preferences, a compact structured status "
|
|
49
|
+
"bar, a stable per-user runtime interpreter bootstrap, and a "
|
|
50
|
+
"camera permission prompt on first open when the platform "
|
|
51
|
+
"requires it."
|
|
52
|
+
),
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _build_parser() -> argparse.ArgumentParser:
|
|
57
|
+
"""Build the current command-line parser."""
|
|
58
|
+
|
|
59
|
+
parser = argparse.ArgumentParser(prog="webcam-micro")
|
|
60
|
+
parser.add_argument(
|
|
61
|
+
"--smoke-test",
|
|
62
|
+
action="store_true",
|
|
63
|
+
help="exercise the entrypoint without launching the GUI",
|
|
64
|
+
)
|
|
65
|
+
return parser
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
69
|
+
"""Run the current application entrypoint."""
|
|
70
|
+
|
|
71
|
+
parsed = _build_parser().parse_args(argv)
|
|
72
|
+
if parsed.smoke_test:
|
|
73
|
+
return 0
|
|
74
|
+
try:
|
|
75
|
+
return launch_main_window()
|
|
76
|
+
except WebcamMicroError as exc:
|
|
77
|
+
raise SystemExit(build_error_report(exc).display_message) from exc
|