framewise-cull 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.
framewise/CHANGELOG.md ADDED
@@ -0,0 +1,25 @@
1
+ # Changelog
2
+
3
+ What changed in framewise, written for photographers. The Review UI shows this list under **What's new**.
4
+
5
+ ## Unreleased
6
+
7
+ ## 0.2.0 — 2026-11-19
8
+
9
+ - framewise runs on Windows x64 as a preview, with the same portable Providers as on Linux. Set it up with `scripts\setup.ps1`. **Rating write-back** uses the color label names from Lightroom Classic's preferences there too.
10
+ - On Windows and Linux, key hints say `Alt+` and `Delete` instead of the Mac symbols.
11
+ - framewise can be installed as one package with the Review UI built in. A machine that runs it from that package with `uvx` needs only ExifTool, with no git clone, Node.js or setup script.
12
+ - Each Release is published on PyPI as `framewise-cull` and attached to its GitHub Release. Run it with `uvx --python 3.13 --from framewise-cull framewise review`, on Linux and Windows with `framewise-cull[portable]` instead. To update, add `@latest` at the end, such as `framewise-cull[portable]@latest`.
13
+ - Without ExifTool, framewise stops at start-up with one message that says how to install it, instead of failing later at **Rating write-back**.
14
+ - A Frame without faces is judged on the sharpness of its subject rather than the whole Frame: the area the camera focused on where it recorded one (Fujifilm for now), else the main subject Apple Vision finds (macOS 14 or later). A sharp subject in front of a blurred background is no longer marked soft, and within a Burst the Frame with the sharper subject wins. The score breakdown says what sharpness was measured on.
15
+
16
+ ## 0.1.0 — 2026-11-18
17
+
18
+ - Open a Session folder and framewise groups its Frames into Bursts and Near-duplicates. Everything is analyzed on your own machine; no Frame leaves it.
19
+ - Each Frame gets a proposed Verdict (Winner, Keeper, Reject or Unsure) with Reasons such as "eyes closed" or "motion blur". The Keeper budget slider sets roughly what share of the Session to keep.
20
+ - Faces are checked for closed eyes and sharpness, and a Frame with faces is judged by its faces rather than the whole image.
21
+ - Review with Lightroom Classic's shortcuts. Change any Verdict with an Override, and fix wrong grouping by splitting, moving or merging Groups. Overrides survive re-analysis.
22
+ - Trash junk Frames or whole Groups. Their files go to the OS Trash and are never deleted outright.
23
+ - **Rating write-back** writes your Verdicts as stars and color labels that Lightroom Classic reads, after showing a dry run, and can be undone.
24
+ - Runs on macOS with Apple Vision, and on Linux with the portable Providers.
25
+ - The Review UI shows which version of framewise is running, next to its name. Click it, or choose **What's new** in the command palette, to read this list. After an update, a dot on the version marks what changed until you open it.
framewise/__init__.py ADDED
File without changes
framewise/analyzer.py ADDED
@@ -0,0 +1,122 @@
1
+ from collections.abc import Mapping
2
+ from dataclasses import dataclass
3
+ from pathlib import Path
4
+ from typing import Literal, Protocol
5
+
6
+ # Bump whenever the built-in image maths or the shape of FrameSignals changes, so a re-run
7
+ # re-analyzes Frames whose saved analysis predates it. A Provider's own changes are covered by
8
+ # its version, in the ProviderSignature.
9
+ ANALYSIS_VERSION = 7
10
+
11
+ ProviderSignature = Mapping[str, str]
12
+ """The Provider that served each Capability of an analysis, as "<id>@<version>" by Capability."""
13
+
14
+ ProviderSource = Literal["automatic", "config"]
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class ActiveProvider:
19
+ id: str
20
+ version: int
21
+ source: ProviderSource
22
+ """Whether it was picked as the highest-priority available Provider or chosen in the config."""
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class AlternativeProvider:
27
+ id: str
28
+ version: int
29
+ available: bool
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class CapabilityLineup:
34
+ active: ActiveProvider | None
35
+ """None where no Provider serves the Capability."""
36
+ alternatives: tuple[AlternativeProvider, ...] = ()
37
+ """The other installed Providers of the Capability, in descending priority."""
38
+
39
+
40
+ ProviderLineup = Mapping[str, CapabilityLineup]
41
+ """What serves each Capability in new analyses, keyed by Capability in the order to show them."""
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class SimilarityThresholds:
46
+ """The fingerprint similarity from which two Frames belong in one Group. Each fingerprint
47
+ Provider declares its own, because similarities from different Providers aren't comparable."""
48
+
49
+ burst: float
50
+ """For Frames captured within moments of each other."""
51
+ near_duplicate: float
52
+ """For Frames captured minutes apart, or without a capture time."""
53
+
54
+
55
+ @dataclass(frozen=True)
56
+ class Face:
57
+ """One face the face detection Provider found in a Frame. Its box is a fraction of the
58
+ Frame's width and height, measured from the top left."""
59
+
60
+ x: float
61
+ y: float
62
+ width: float
63
+ height: float
64
+ eyes_open: bool | None
65
+ """None where the eye state Provider could not tell, or there is none."""
66
+ sharpness: float
67
+ """Like the Frame's sharpness, measured on the face alone."""
68
+ quality: float | None
69
+ """The face quality Provider's score from 0 to 1, or None where it is unavailable."""
70
+
71
+
72
+ SubjectSource = Literal["focus-point", "subject-mask"]
73
+
74
+
75
+ @dataclass(frozen=True)
76
+ class Subject:
77
+ """The part of a Frame that matters most, as a box measured like a face's. Frames without
78
+ faces are judged on it rather than on the whole Frame."""
79
+
80
+ x: float
81
+ y: float
82
+ width: float
83
+ height: float
84
+ sharpness: float
85
+ """Like the Frame's sharpness, measured on the subject alone."""
86
+ found_by: SubjectSource
87
+ """"focus-point" where the camera recorded the area it focused on, else "subject-mask" where
88
+ the subject Provider found the Frame's main subject. A subject mask's box is the box around
89
+ it, but its sharpness is measured on the mask alone."""
90
+
91
+
92
+ @dataclass(frozen=True)
93
+ class FrameSignals:
94
+ fingerprint: list[float]
95
+ sharpness: float
96
+ """0 for a completely blurred Frame, 1 for crisp edges."""
97
+ motion_blur: float
98
+ """0 when the Frame is equally sharp in every direction, towards 1 when it is smeared along
99
+ one direction."""
100
+ exposure_stops: float
101
+ """How far the Frame is over (positive) or under (negative) a mid-gray exposure."""
102
+ low_key: bool
103
+ """Dark overall but with bright highlights, so deliberately dark rather than underexposed."""
104
+ high_key: bool
105
+ """Bright overall but with its highlights intact, so deliberately bright rather than
106
+ overexposed. With faces, only the faces' highlights count, so a person against a blown-out
107
+ white wall is high key."""
108
+ aesthetics: float | None
109
+ """The aesthetics Provider's score from 0 to 1, or None where it is unavailable."""
110
+ faces: list[Face]
111
+ subject: Subject | None = None
112
+ """None where framewise can't tell where the subject is."""
113
+
114
+
115
+ class FrameAnalyzer(Protocol):
116
+ signature: ProviderSignature
117
+ """Saved with each analysis, so a re-run re-analyzes the Frames whose Providers changed."""
118
+ similarity: SimilarityThresholds
119
+ provider_lineup: ProviderLineup
120
+ """Shown in the Review UI, so the photographer can see how new analyses are made."""
121
+
122
+ def analyze(self, jpg_path: Path) -> FrameSignals: ...
@@ -0,0 +1,251 @@
1
+ """framewise's own Providers, built on Apple Vision on macOS. Elsewhere they report themselves
2
+ unavailable."""
3
+
4
+ import threading
5
+ from array import array
6
+ from dataclasses import dataclass, field
7
+ from pathlib import Path
8
+
9
+ from PIL import Image
10
+
11
+ from framewise.analyzer import SimilarityThresholds
12
+ from framewise.image_measures import Region
13
+ from framewise.providers import (
14
+ AESTHETICS,
15
+ EYE_STATE,
16
+ FACE_DETECTION,
17
+ FACE_QUALITY,
18
+ FINGERPRINT,
19
+ SUBJECT,
20
+ )
21
+
22
+ try:
23
+ import Foundation
24
+ import Quartz
25
+ import Vision
26
+ except ImportError:
27
+ Foundation = Quartz = Vision = None
28
+
29
+ PRIORITY = 100
30
+ FLOAT_ELEMENT_TYPE = 1
31
+ FEATURE_PRINT_REVISION = 2
32
+ # An eye's landmarks outline its opening, so a closed eye's outline is a flat line: open eyes
33
+ # measure about 0.3 high for each unit wide, closed ones under 0.1. On the reference benchmark,
34
+ # blinks and half-closed eyes measure up to 0.158, laughing squints from 0.17 and the
35
+ # photographer's rated faces from 0.205 (#30).
36
+ EYES_CLOSED_BELOW = 0.16
37
+
38
+
39
+ class _AppleVisionProvider:
40
+ version = 1
41
+ priority = PRIORITY
42
+
43
+ def is_available(self) -> bool:
44
+ return Vision is not None
45
+
46
+
47
+ class AppleFingerprint(_AppleVisionProvider):
48
+ capability = FINGERPRINT
49
+ id = "apple-vision-fingerprint"
50
+ similarity = SimilarityThresholds(burst=0.8, near_duplicate=0.9)
51
+
52
+ def fingerprint(self, jpg_path: Path) -> list[float]:
53
+ request = Vision.VNGenerateImageFeaturePrintRequest.alloc().init()
54
+ request.setRevision_(FEATURE_PRINT_REVISION)
55
+ _perform(_vision_image(jpg_path), [request])
56
+ observation = request.results()[0]
57
+ type_code = "f" if observation.elementType() == FLOAT_ELEMENT_TYPE else "d"
58
+ return array(type_code, bytes(observation.data())).tolist()
59
+
60
+
61
+ class AppleFaceDetection(_AppleVisionProvider):
62
+ capability = FACE_DETECTION
63
+ id = "apple-vision-face-detection"
64
+
65
+ def detect_faces(self, jpg_path: Path) -> list[Region]:
66
+ image = _vision_image(jpg_path)
67
+ request = Vision.VNDetectFaceLandmarksRequest.alloc().init()
68
+ _perform(image, [request])
69
+ observations = list(request.results() or [])
70
+ regions = [_region(observation) for observation in observations]
71
+ image.faces = dict(zip(regions, observations, strict=True))
72
+ return regions
73
+
74
+
75
+ class AppleEyeState(_AppleVisionProvider):
76
+ capability = EYE_STATE
77
+ id = "apple-vision-eye-state"
78
+
79
+ def eyes_open(self, jpg_path: Path, faces: list[Region]) -> list[bool | None]:
80
+ image = _vision_image(jpg_path)
81
+ if all(face in image.faces for face in faces):
82
+ observations = [image.faces[face] for face in faces]
83
+ else:
84
+ observations = _perform_on_faces(
85
+ image,
86
+ Vision.VNDetectFaceLandmarksRequest.alloc().init(),
87
+ [_observation(face) for face in faces],
88
+ )
89
+ return [_eyes_open(observation) for observation in observations]
90
+
91
+
92
+ class AppleFaceQuality(_AppleVisionProvider):
93
+ capability = FACE_QUALITY
94
+ id = "apple-vision-face-quality"
95
+
96
+ def face_quality(self, jpg_path: Path, faces: list[Region]) -> list[float | None]:
97
+ image = _vision_image(jpg_path)
98
+ observations = _perform_on_faces(
99
+ image,
100
+ Vision.VNDetectFaceCaptureQualityRequest.alloc().init(),
101
+ [image.faces.get(face) or _observation(face) for face in faces],
102
+ )
103
+ return [_quality(observation) for observation in observations]
104
+
105
+
106
+ class AppleAesthetics(_AppleVisionProvider):
107
+ capability = AESTHETICS
108
+ id = "apple-vision-aesthetics"
109
+ version = 2
110
+
111
+ def is_available(self) -> bool:
112
+ """Apple Vision's aesthetics request exists from macOS 15 on."""
113
+ return Vision is not None and hasattr(Vision, "VNCalculateImageAestheticsScoresRequest")
114
+
115
+ def aesthetics(self, jpg_path: Path) -> float | None:
116
+ """Apple Vision scores from -1 to 1."""
117
+ request = Vision.VNCalculateImageAestheticsScoresRequest.alloc().init()
118
+ _perform(_vision_image(jpg_path), [request])
119
+ return _clamp((float(request.results()[0].overallScore()) + 1) / 2)
120
+
121
+
122
+ class AppleSubject(_AppleVisionProvider):
123
+ capability = SUBJECT
124
+ id = "apple-vision-subject"
125
+
126
+ def is_available(self) -> bool:
127
+ """Apple Vision's foreground mask request exists from macOS 14 on."""
128
+ return Vision is not None and hasattr(Vision, "VNGenerateForegroundInstanceMaskRequest")
129
+
130
+ def subject_mask(self, jpg_path: Path) -> Image.Image | None:
131
+ """Joins every foreground instance Vision finds into one subject. Vision's own
132
+ low-resolution mask spans the whole Frame as displayed, stretched to a square, so it
133
+ costs far less than one scaled to the Frame's full size."""
134
+ request = Vision.VNGenerateForegroundInstanceMaskRequest.alloc().init()
135
+ _perform(_vision_image(jpg_path), [request])
136
+ if not request.results():
137
+ return None
138
+ observation = request.results()[0]
139
+ buffer, error = observation.generateMaskForInstances_error_(
140
+ observation.allInstances(), None
141
+ )
142
+ if buffer is None:
143
+ raise RuntimeError(f"Apple Vision could not mask the subject of {jpg_path}: {error}")
144
+ return _greyscale(buffer)
145
+
146
+
147
+ @dataclass
148
+ class _VisionImage:
149
+ key: tuple[Path, int]
150
+ handler: object
151
+ faces: dict[Region, object] = field(default_factory=dict)
152
+ """The face observations the face detection Provider found, by their box."""
153
+
154
+
155
+ _this_thread = threading.local()
156
+
157
+
158
+ def _vision_image(jpg_path: Path) -> _VisionImage:
159
+ """The Vision handler of the Analysis source this thread analyzes. The Providers share it,
160
+ so Vision reads the image once, and the eye state and face quality Providers reuse the face
161
+ detection Provider's own observations, landmarks and all, for the boxes it found."""
162
+ key = (jpg_path, jpg_path.stat().st_mtime_ns)
163
+ image = getattr(_this_thread, "image", None)
164
+ if image is None or image.key != key:
165
+ url = Foundation.NSURL.fileURLWithPath_(str(jpg_path))
166
+ handler = Vision.VNImageRequestHandler.alloc().initWithURL_options_(
167
+ url, Foundation.NSDictionary.dictionary()
168
+ )
169
+ image = _VisionImage(key, handler)
170
+ _this_thread.image = image
171
+ return image
172
+
173
+
174
+ def _perform(image: _VisionImage, requests: list) -> None:
175
+ succeeded, error = image.handler.performRequests_error_(requests, None)
176
+ if not succeeded:
177
+ raise RuntimeError(f"Apple Vision could not analyze {image.key[0]}: {error}")
178
+
179
+
180
+ def _perform_on_faces(image: _VisionImage, request, faces: list) -> list:
181
+ """Runs a request on the given face observations and returns its results in their order,
182
+ None for a face Vision returned nothing for. Vision returns them in any order, each with the
183
+ uuid of the face it belongs to."""
184
+ request.setInputFaceObservations_(faces)
185
+ _perform(image, [request])
186
+ by_face = {observation.uuid(): observation for observation in request.results() or []}
187
+ return [by_face.get(face.uuid()) for face in faces]
188
+
189
+
190
+ def _region(face) -> Region:
191
+ """Converts Apple Vision's box, measured from the bottom left, to one from the top left."""
192
+ box = face.boundingBox()
193
+ x = _clamp(box.origin.x)
194
+ y = _clamp(1 - box.origin.y - box.size.height)
195
+ width = _clamp(box.origin.x + box.size.width) - x
196
+ height = _clamp(1 - box.origin.y) - y
197
+ return x, y, width, height
198
+
199
+
200
+ def _observation(region: Region):
201
+ """A face observation for a box another detector found, measured from the bottom left."""
202
+ x, y, width, height = region
203
+ return Vision.VNFaceObservation.faceObservationWithRequestRevision_boundingBox_roll_yaw_(
204
+ Vision.VNDetectFaceRectanglesRequestRevision3,
205
+ ((x, 1 - y - height), (width, height)),
206
+ None,
207
+ None,
208
+ )
209
+
210
+
211
+ def _eyes_open(face) -> bool | None:
212
+ landmarks = None if face is None else face.landmarks()
213
+ if landmarks is None:
214
+ return None
215
+ eyes = [landmarks.leftEye(), landmarks.rightEye()]
216
+ if any(eye is None for eye in eyes):
217
+ return None
218
+ openness = sum(_openness(eye) for eye in eyes) / len(eyes)
219
+ return openness >= EYES_CLOSED_BELOW
220
+
221
+
222
+ def _openness(eye) -> float:
223
+ points = eye.normalizedPoints()
224
+ xs = [points[index].x for index in range(eye.pointCount())]
225
+ ys = [points[index].y for index in range(eye.pointCount())]
226
+ width = max(xs) - min(xs)
227
+ return 0.0 if width == 0 else (max(ys) - min(ys)) / width
228
+
229
+
230
+ def _quality(observation) -> float | None:
231
+ quality = None if observation is None else observation.faceCaptureQuality()
232
+ return None if quality is None else float(quality)
233
+
234
+
235
+ def _greyscale(mask_buffer) -> Image.Image:
236
+ """Vision's mask holds one float per pixel, from 0 outside the subject to 1 inside it."""
237
+ Quartz.CVPixelBufferLockBaseAddress(mask_buffer, Quartz.kCVPixelBufferLock_ReadOnly)
238
+ try:
239
+ width = Quartz.CVPixelBufferGetWidth(mask_buffer)
240
+ height = Quartz.CVPixelBufferGetHeight(mask_buffer)
241
+ row_bytes = Quartz.CVPixelBufferGetBytesPerRow(mask_buffer)
242
+ address = Quartz.CVPixelBufferGetBaseAddress(mask_buffer)
243
+ pixels = bytes(address.as_buffer(row_bytes * height))
244
+ finally:
245
+ Quartz.CVPixelBufferUnlockBaseAddress(mask_buffer, Quartz.kCVPixelBufferLock_ReadOnly)
246
+ floats = Image.frombuffer("F", (width, height), pixels, "raw", "F", row_bytes, 1)
247
+ return floats.point(lambda value: value * 255).convert("L")
248
+
249
+
250
+ def _clamp(value: float) -> float:
251
+ return min(1.0, max(0.0, value))