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 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
+ ![webcam-micro preview](https://raw.githubusercontent.com/apostolovbg/webcam-micro/main/webcam_micro/webcam-micro.png)
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
@@ -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"
@@ -0,0 +1,6 @@
1
+ """Module launcher for `python -m webcam_micro`."""
2
+
3
+ from webcam_micro.launcher import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())
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