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.
Binary file
@@ -0,0 +1,264 @@
1
+ Metadata-Version: 2.4
2
+ Name: webcam-micro
3
+ Version: 0.2.0
4
+ Summary: Cross-platform microscope camera application distributed as a Python package on PyPI.
5
+ License-Expression: MIT
6
+ Requires-Python: <3.15,>=3.11
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: PySide6<6.12,>=6.11
9
+ Requires-Dist: rubicon-objc<0.6,>=0.5; sys_platform == "darwin"
10
+
11
+ # webcam-micro
12
+ **Doc ID:** README
13
+ **Doc Type:** repo-readme
14
+ **Project Version:** 0.2.0
15
+ **Last Updated:** 2026-04-08
16
+ **DevCovenant Version:** 1.0.1b1
17
+
18
+ <!-- DEVCOV:BEGIN -->
19
+
20
+ <!-- DEVCOV:END -->
21
+
22
+ Cross-platform microscope camera application distributed as a Python package
23
+ on PyPI.
24
+
25
+ ![webcam-micro preview](https://raw.githubusercontent.com/apostolovbg/webcam-micro/main/webcam_micro/webcam-micro.png)
26
+
27
+ ## Table of Contents
28
+ 1. [Overview](#overview)
29
+ 2. [Alpha Status](#alpha-status)
30
+ 3. [What Works Today](#what-works-today)
31
+ 4. [Installation](#installation)
32
+ 5. [Launch](#launch)
33
+ 6. [Windowed Workspace](#windowed-workspace)
34
+ 7. [Fullscreen Workspace](#fullscreen-workspace)
35
+ 8. [Preview and Framing](#preview-and-framing)
36
+ 9. [Camera Controls](#camera-controls)
37
+ 10. [Capture and Recording](#capture-and-recording)
38
+ 11. [Preferences, Defaults, and Presets](#preferences-defaults-and-presets)
39
+ 12. [Diagnostics and Status](#diagnostics-and-status)
40
+ 13. [Platform Notes](#platform-notes)
41
+ 14. [Current Limitations](#current-limitations)
42
+ 15. [Packaging and Distribution](#packaging-and-distribution)
43
+ 16. [Security, Privacy, and Support](#security-privacy-and-support)
44
+ 17. [Repository Notes](#repository-notes)
45
+ 18. [License](#license)
46
+
47
+ ## Overview
48
+ `webcam-micro` is a preview-first microscope camera application for live
49
+ viewing, camera control, still capture, and recording.
50
+
51
+ The current alpha release runs on the Qt Widgets shell baseline. Today it
52
+ opens a native desktop workspace with a menu bar, toolbar, central preview
53
+ area, toggleable controls dock, quiet still-image save to the configured
54
+ folder, a tighter preview refresh cadence, native recording, session
55
+ preferences, diagnostics, and a compact fullscreen command surface with
56
+ expanded and collapsed states. Preview framing, capture framing, camera
57
+ selection, window layout, current preset name, and per-camera control
58
+ values persist across launches. Image and video output folders live in
59
+ Preferences, and the compact status bar stays structured. User-editable
60
+ defaults, keyboard shortcuts, and named presets are available, while
61
+ broader platform validation is covered by automated tests and Linux smoke
62
+ checks here.
63
+
64
+ ## Alpha Status
65
+ `webcam-micro` is now the official alpha release.
66
+ The release version is sourced from `webcam_micro/VERSION`, and the shell
67
+ chrome carries the full legal-owner notice.
68
+ The Qt Widgets baseline is usable for live preview, camera control, still
69
+ capture, recording, presets, and diagnostics. The remaining beta-prep work
70
+ is now deferred until after beta publication, so the beta plan is
71
+ complete for the current release path.
72
+
73
+ ## What Works Today
74
+ - Launch and entrypoint: the application starts from the `webcam-micro`
75
+ command, bootstraps a stable per-user runtime interpreter on every
76
+ supported OS, refreshes the private runtime bridge on each launch, and
77
+ can also run from source during development.
78
+ - Windowed workspace: the main shell keeps the preview central while the
79
+ menu bar, toolbar, and status bar expose the primary microscope
80
+ actions, and the controls dock can dock, float, hide, and restore
81
+ without taking the preview off center. A visible Restore Dock action
82
+ keeps detached controls easy to reattach.
83
+ - Fullscreen workspace: the preview expands to the full screen and the
84
+ command surface collapses into a compact overlay with safe exit paths.
85
+ - Preview and framing: live preview supports fit, fill, and centered crop
86
+ modes, and a tighter refresh cadence keeps the newest frame close to live
87
+ motion when the preview resizes.
88
+ - Camera controls: the dock splits native controls into Camera Controls
89
+ and User Controls. Resolution stays in the preview path as a dropdown.
90
+ The selected device-control owner exposes Exposure and Focus as
91
+ slider-plus-spinbox controls with exposure lock and Auto checkboxes
92
+ when the camera reports them, Light as an on/off checkbox plus a level
93
+ slider when exposed, and Zoom as a slider-plus-spinbox row when the
94
+ camera reports it. When Auto is enabled, the paired numeric control
95
+ stays visible, greys out, and tracks the live device value. User
96
+ Controls expose backend-owned Backlight compensation, Brightness,
97
+ Contrast, Hue, Saturation, Sharpness, Gamma, Gain, Power Line
98
+ Frequency, and White balance rows, Contrast and Hue keep Auto
99
+ checkboxes, White balance keeps its Auto checkbox, and a Reset to
100
+ Defaults button sits at the bottom. The app selects one control owner
101
+ per camera by canonical device identity and reads ranges, choices, and
102
+ writes from that backend only.
103
+ - The active backend still exposes numeric, boolean, enum, read-only,
104
+ and action controls when the selected owner supports them. The preview
105
+ path keeps source-format selection separate from camera-control
106
+ ownership. On Linux, V4L2 adds power line frequency, image-quality
107
+ controls, lamp, illumination, activity LED, and vendor-specific
108
+ extension controls when the camera reports them.
109
+ - Capture and recording: still images save quietly to the configured folder
110
+ with the current capture framing, and recordings use native controls with
111
+ platform-supported containers.
112
+ - Preferences, defaults, and presets: framing, keyboard shortcuts,
113
+ defaults, and named presets are stored with the workspace, while image
114
+ and video output folders live in Preferences.
115
+ - Diagnostics and status: the shell reports runtime state, recent failures,
116
+ and prototype exit checks in a visible diagnostics dialog and status bar.
117
+ - Platform notes: Qt Multimedia owns the camera and recording stack,
118
+ while platform and device differences still shape the available
119
+ controls. The app selects one device-control owner per camera by
120
+ canonical hardware identity so the UI reads one source of truth for
121
+ ranges, menus, and writes. On macOS and Windows, that owner is
122
+ platform-selected; on Linux, V4L2 contributes extra control discovery
123
+ for device-specific and vendor-specific settings when available. The
124
+ shared error-reporting layer keeps launcher, runtime bootstrap, and
125
+ camera failures as typed notices and diagnostics instead of raw
126
+ tracebacks.
127
+
128
+ ## Installation
129
+ The packaged app supports Python `3.11` through `3.14`.
130
+ Install it from PyPI or a built wheel, then launch it with:
131
+
132
+ ```bash
133
+ webcam-micro
134
+ ```
135
+
136
+ ## Launch
137
+ The application starts in a preview-first Qt Widgets window.
138
+ The `webcam_micro.launcher` module uses `webcam_micro.runtime_bootstrap` to
139
+ create or reuse a stable per-user runtime interpreter on Windows, macOS,
140
+ and Linux before the Qt shell starts, so the first launch sets up the
141
+ Python identity that will own later camera access on macOS. The launcher
142
+ refreshes the private runtime bridge on each launch so stale runtimes
143
+ self-heal, and the bridge keeps the package imports visible in that
144
+ interpreter so Qt still loads from the installed package set. On macOS,
145
+ the camera permission prompt runs through a repo-owned adapter so the same
146
+ code path stays import-safe on Windows and Linux.
147
+ The command bar and native menu bar provide access to the core camera,
148
+ capture, framing, preference, and diagnostics actions without requiring a
149
+ terminal once the app is running.
150
+ On macOS, the runtime interpreter requests camera permission the first time
151
+ a camera opens through that adapter; if it was denied before, reset the
152
+ Camera privacy setting and relaunch.
153
+
154
+ ## Windowed Workspace
155
+ The main window keeps the microscope preview central.
156
+ The native menu bar carries File for Exit, Edit for copy status, View for
157
+ controls and framing, Camera for camera refresh, open, and close, Capture
158
+ for still and recording actions, Tools for preferences and diagnostics, and
159
+ Help for About. The toolbar keeps the main working actions close to the live
160
+ image, including controls, camera refresh, camera open and close, framing,
161
+ still capture, recording, fullscreen, and preferences. The right edge of
162
+ the toolbar displays `© 2026 Black Epsilon Ltd. and Apostol Apostolov`.
163
+
164
+ The controls dock can be shown, hidden, floated, or restored so camera
165
+ controls do not consume preview space permanently. It keeps the preview
166
+ central even when detached, defaults to one vertical column, and widens to
167
+ two columns on roomier layouts while preserving the section order.
168
+ Numeric controls use guvcview-style affordances: a slider, min/mid/max
169
+ labels, and an adjacent field with step buttons. Boolean, enumerated,
170
+ read-only, and action controls appear when the backend exposes them.
171
+
172
+ ## Fullscreen Workspace
173
+ Fullscreen replaces the windowed chrome with a compact command surface.
174
+ Expanded fullscreen shows the core microscope actions plus collapse and safe
175
+ windowed exit. Collapsed fullscreen keeps only collapse/expand and the
176
+ fullscreen/windowed toggle visible. Escape returns to windowed mode.
177
+
178
+ ## Preview and Framing
179
+ Preview framing supports fit, fill, and centered crop modes.
180
+ The live preview rerenders from the newest cached frame when the window or
181
+ preview area changes size, and the tighter poll cadence keeps the visible
182
+ motion closer to the live feed. Capture framing is separate from preview
183
+ framing so stills and videos can follow their own output rules without
184
+ changing the live microscope view.
185
+
186
+ ## Camera Controls
187
+ The app exposes the real control surface reported by the active camera and
188
+ backend. The dock splits those controls into Camera Controls and User
189
+ Controls. Camera Controls expose Resolution as a dropdown, Exposure and
190
+ Focus as slider-plus-spinbox widgets with Auto checkboxes when the camera
191
+ reports them, Light as an on/off checkbox plus a level slider when
192
+ available, and Zoom when the backend reports it. When Auto is enabled,
193
+ the paired numeric control stays visible, greys out, and tracks the auto
194
+ value. User Controls expose backend-owned Backlight compensation,
195
+ Brightness, Contrast, Hue, Saturation, Sharpness, Gamma, Gain, Power Line
196
+ Frequency, and White balance rows, with Auto checkboxes on Contrast, Hue,
197
+ and White balance when the backend exposes them, and a Reset to Defaults
198
+ button at the bottom.
199
+ Native device-control backends cover the common exposure, focus, white
200
+ balance, flash, torch, zoom, and source-format controls across supported
201
+ platforms, while Linux V4L2 adds power line frequency, image-quality
202
+ controls, lamp, illumination, activity LED, and vendor-specific
203
+ extensions when the device reports them. Supported controls include
204
+ numeric, boolean, enumerated, read-only, and action widgets. The app
205
+ tolerates partial control sets and does not fail just because a camera
206
+ lacks an expected control.
207
+ On macOS, the native UVC-style control backend owns UVC controls first and
208
+ AVFoundation remains a fallback for native-only gaps. AVFoundation
209
+ exposure, focus, white balance, and backlight writes stay on the native
210
+ nil-completion path so slider commits avoid the callback crash. Automatic
211
+ Video HDR is only surfaced when the active format reports HDR support.
212
+
213
+ ## Capture and Recording
214
+ Still images save quietly to the configured image folder as PNG or JPEG
215
+ output. Recording starts and stops natively in the Qt shell, shows elapsed
216
+ status while it runs, and only offers containers that the current Qt
217
+ Multimedia runtime supports. The `webcam_micro.camera` recording helper
218
+ rejects unsupported suffixes before recording starts. Recorded video uses
219
+ the active capture-framing choice and remembers the output folder across
220
+ launches.
221
+
222
+ ## Preferences, Defaults, and Presets
223
+ Preferences store preview framing, capture framing, output folders, editable
224
+ defaults, keyboard shortcuts, and named presets.
225
+ The app remembers the current preset name, restores per-camera control
226
+ values when available, and keeps editable control defaults grouped by the
227
+ same section names inside Preferences. It also lets users save or apply
228
+ named presets from the same preferences dialog.
229
+
230
+ ## Diagnostics and Status
231
+ The diagnostics dialog shows a runtime report, a recent-failures log, and
232
+ prototype exit checks. The status bar summarizes backend, camera, source
233
+ mode, preview framing, capture framing, controls state, preset name,
234
+ recording state, and the current status notice.
235
+
236
+ ## Platform Notes
237
+ Qt Multimedia owns camera discovery, preview, recording, and the common
238
+ control surface. On Linux, V4L2 contributes extra control discovery for
239
+ device-specific and vendor-specific settings when available. Actual
240
+ controls and container support vary by camera, backend, and platform. The
241
+ app only surfaces controls the backend can actually use, and the recording
242
+ path filters the save dialog to supported containers.
243
+
244
+ ## Current Limitations
245
+ Some camera controls and output formats remain backend-dependent.
246
+
247
+ ## Packaging and Distribution
248
+ `webcam-micro` is shipped as a Python package on PyPI.
249
+ The package-facing README lives at `webcam_micro/README.md`, where the
250
+ repo-only notes are stripped out before packaging. The `webcam_micro.launcher`
251
+ entrypoint uses `webcam_micro.runtime_bootstrap` to create or reuse the
252
+ per-user runtime interpreter on every supported OS before handing off to
253
+ the GUI app. It also refreshes the private runtime bridge on each launch
254
+ so stale runtimes self-heal, and the source package remains runnable
255
+ during development.
256
+
257
+ ## Security, Privacy, and Support
258
+ `webcam-micro` is a local desktop utility by default.
259
+ The core camera workflow does not depend on cloud services, accounts, or
260
+ telemetry, and the app should stay usable without terminal interaction
261
+ during normal microscope work.
262
+
263
+ ## License
264
+ Document the repository licensing terms here.
@@ -0,0 +1,22 @@
1
+ webcam_micro/README.md,sha256=m-P3cICSnbc_Vv2A7B-jO3nUbCBxFYBI65iA6DNbAtM,13417
2
+ webcam_micro/VERSION,sha256=H5MN0fEzwfl6lP46y42zQ3LPTAH_2ys_9Mpy-UlBIek,6
3
+ webcam_micro/__init__.py,sha256=AgXitbO2Sfo4nd_-4w8St_AGjy7mZopw8TIatl19C-U,754
4
+ webcam_micro/__main__.py,sha256=LdQxENmb2V69qcVL0G2qE-4iF8l589z1di2qxWUETTk,149
5
+ webcam_micro/app.py,sha256=2mNkvvg3uNwqHeO6eqYo-ZdKUng1y-jucTZw4etan94,2692
6
+ webcam_micro/camera.py,sha256=V5FCn9laZVNxRywdQFl6Sm6Xcq-VcAkeVpdXKJ7upRM,240167
7
+ webcam_micro/error_reporting.py,sha256=HG-_m2cPWkwFEkiUV1QtUThMKlQB9om0IHgEuT-JZLc,859
8
+ webcam_micro/launcher.py,sha256=OMYC98YDX7YtQkWVbxK0iw3VgU4b2EnP26bd56Stkn8,862
9
+ webcam_micro/macos_permission.py,sha256=CNG_6RaW_zb0sc9gj0T3DTJH43bSnfjLa0foNh6RVYk,443
10
+ webcam_micro/runtime-requirements.lock,sha256=JbP0alxclqslpMsIM-E74UJzzEuOmdGXHE1hKT4QmyU,1656
11
+ webcam_micro/runtime_bootstrap.py,sha256=8dgINQKZkO8VRw1j3ay_P-ZpS1Mu1ncC5qgODZDl5j4,7844
12
+ webcam_micro/ui.py,sha256=rnRTzwP5ftAvI9BcfgC70cmtG7PH-m2XE5AxSRo3SHw,146730
13
+ webcam_micro/webcam-micro.png,sha256=65MzWrfXX8MTMdAJZ2k6KAA5GHrUMzOgFJw7--TUC7I,3641383
14
+ webcam_micro/licenses/PySide6-6.11.3.txt,sha256=Ni4lHgsdPzm1OuThZW6juShlGuq1_Y-BYvPGIaMtfz4,61585
15
+ webcam_micro/licenses/README.md,sha256=wtnCvfcosl5-HLFHpaETAKbMw91eWDzfNZ6N-dpeUps,957
16
+ webcam_micro/licenses/THIRD_PARTY_LICENSES.md,sha256=I3Fpcpcwursp7kATx_DpFVBKTHsqX0JLaCt4r5c3eqE,448
17
+ webcam_micro/licenses/rubicon-objc-0.5.7.txt,sha256=UdWfjwtQ1j27OStX1jlnHx0QOxTEOvlrIW5WJWxVVAs,3490
18
+ webcam_micro-0.2.0.dist-info/METADATA,sha256=WPm36rAtiltDzawkasVWxN2DlaOwr3uxcURGC8E-iM4,13762
19
+ webcam_micro-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
20
+ webcam_micro-0.2.0.dist-info/entry_points.txt,sha256=HGVjAppAIPdiILUcDJ632gyLIxT4EMV6r1FgJfpHDts,60
21
+ webcam_micro-0.2.0.dist-info/top_level.txt,sha256=hOI3ZeHBVQajBK_6_X08zh8og1OmA2gftXUM4cPpp14,13
22
+ webcam_micro-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ webcam-micro = webcam_micro.launcher:main
@@ -0,0 +1 @@
1
+ webcam_micro