switchbot-e6-optimizer 1.0.0__tar.gz → 1.1.1__tar.gz
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.
- {switchbot_e6_optimizer-1.0.0 → switchbot_e6_optimizer-1.1.1}/PKG-INFO +112 -19
- switchbot_e6_optimizer-1.1.1/README.md +271 -0
- switchbot_e6_optimizer-1.1.1/pyproject.toml +74 -0
- switchbot_e6_optimizer-1.0.0/pyproject.toml → switchbot_e6_optimizer-1.1.1/pyproject.toml.orig +3 -3
- switchbot_e6_optimizer-1.1.1/src/switchbot_e6_optimizer/optimizer.py +896 -0
- switchbot_e6_optimizer-1.0.0/README.md +0 -178
- switchbot_e6_optimizer-1.0.0/src/switchbot_e6_optimizer/optimizer.py +0 -519
- {switchbot_e6_optimizer-1.0.0 → switchbot_e6_optimizer-1.1.1}/LICENSE +0 -0
- {switchbot_e6_optimizer-1.0.0 → switchbot_e6_optimizer-1.1.1}/src/switchbot_e6_optimizer/__init__.py +0 -0
- {switchbot_e6_optimizer-1.0.0 → switchbot_e6_optimizer-1.1.1}/src/switchbot_e6_optimizer/__main__.py +0 -0
- {switchbot_e6_optimizer-1.0.0 → switchbot_e6_optimizer-1.1.1}/src/switchbot_e6_optimizer/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: switchbot-e6-optimizer
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.1.1
|
|
4
4
|
Summary: Optimise photos for the SwitchBot 13.3" AI Art Frame (E Ink Spectra 6).
|
|
5
5
|
Keywords: switchbot,e-ink,eink,spectra6,epaper,image,pillow
|
|
6
6
|
Author: switchbot-e6-optimizer contributors
|
|
@@ -12,7 +12,7 @@ Classifier: Intended Audience :: End Users/Desktop
|
|
|
12
12
|
Classifier: Operating System :: OS Independent
|
|
13
13
|
Classifier: Programming Language :: Python :: 3.14
|
|
14
14
|
Classifier: Topic :: Multimedia :: Graphics
|
|
15
|
-
Requires-Dist: pillow>=
|
|
15
|
+
Requires-Dist: pillow>=13
|
|
16
16
|
Requires-Dist: pillow-heif>=1
|
|
17
17
|
Requires-Python: >=3.14
|
|
18
18
|
Project-URL: Homepage, https://github.com/hamzic/switchbot-e6-optimizer
|
|
@@ -84,11 +84,17 @@ uv tool uninstall switchbot-e6-optimizer
|
|
|
84
84
|
## Usage
|
|
85
85
|
|
|
86
86
|
```bash
|
|
87
|
-
# one photo,
|
|
87
|
+
# one photo, fixed medium intensity -> photo_e6.png next to it
|
|
88
88
|
switchbot-e6 photo.jpg
|
|
89
89
|
|
|
90
|
-
#
|
|
91
|
-
switchbot-e6
|
|
90
|
+
# opt in to per-image auto intensity
|
|
91
|
+
switchbot-e6 photo.jpg --auto
|
|
92
|
+
|
|
93
|
+
# a whole folder into ./out; each image keeps its own orientation (auto)
|
|
94
|
+
switchbot-e6 ~/Pictures/art --out ./out
|
|
95
|
+
|
|
96
|
+
# force landscape mount even for portrait photos
|
|
97
|
+
switchbot-e6 ~/Pictures/art --orientation landscape --out ./out
|
|
92
98
|
|
|
93
99
|
# punchier preset for flat, boldly-coloured art
|
|
94
100
|
switchbot-e6 poster.png --intensity high
|
|
@@ -96,13 +102,37 @@ switchbot-e6 poster.png --intensity high
|
|
|
96
102
|
# ride the high preset but pin saturation to exactly +80%
|
|
97
103
|
switchbot-e6 poster.png --intensity high --saturation 80
|
|
98
104
|
|
|
99
|
-
#
|
|
105
|
+
# zeroed tonal base; explicit knob flags still apply
|
|
100
106
|
switchbot-e6 photo.jpg --raw
|
|
101
107
|
```
|
|
102
108
|
|
|
103
109
|
Inputs can be files or whole folders. Running with no arguments prints the full
|
|
104
110
|
help. You can also run it as a module: `python -m switchbot_e6_optimizer`.
|
|
105
111
|
|
|
112
|
+
A fixed-intensity run reports each file's canvas and the chosen fixed preset.
|
|
113
|
+
An explicit `--auto` run names every per-image preset; non-medium picks also
|
|
114
|
+
include why they moved off medium:
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
🎨 Optimising 3 image(s) for E6
|
|
118
|
+
auto orientation (portrait) (1200×1600) · intensity: auto (low: bright highlights)
|
|
119
|
+
✓ dawn.jpg → dawn_e6.png
|
|
120
|
+
auto orientation (landscape) (1600×1200) · intensity: auto (low: colours would clip)
|
|
121
|
+
✓ prize_bull.jpg → prize_bull_e6.png
|
|
122
|
+
auto orientation (landscape) (1600×1200) · intensity: auto (medium)
|
|
123
|
+
✓ holiday.jpg → holiday_e6.png
|
|
124
|
+
✅ Done: 3/3 succeeded.
|
|
125
|
+
ℹ intensities were auto-chosen; override with --intensity low|medium|high
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
A single image folds that header into the first line:
|
|
129
|
+
|
|
130
|
+
```text
|
|
131
|
+
🎨 Optimising 1 image(s) for E6 @ auto orientation (portrait) (1200×1600) · intensity: auto (low: bright highlights)
|
|
132
|
+
✓ dawn.jpg → dawn_e6.png
|
|
133
|
+
✅ Done: 1/1 succeeded.
|
|
134
|
+
```
|
|
135
|
+
|
|
106
136
|
### Supported formats
|
|
107
137
|
|
|
108
138
|
| Direction | Formats |
|
|
@@ -121,17 +151,71 @@ sliders once you see it on the panel.
|
|
|
121
151
|
|
|
122
152
|
### Intensity presets
|
|
123
153
|
|
|
124
|
-
Each preset sets every knob at once. `medium` is the default
|
|
125
|
-
|
|
154
|
+
Each preset sets every knob at once. `medium` is the default; use `--auto` (or
|
|
155
|
+
`--intensity auto`) to opt in to per-image selection. Any single tuning flag
|
|
156
|
+
overrides just that value on top of the chosen preset.
|
|
126
157
|
|
|
127
158
|
| Preset | Saturation | Contrast | Brightness | Shadow lift | Warmth | Sharpen |
|
|
128
159
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
160
|
+
| `auto` (`--auto`) | per image | per image | per image | per image | per image | per image |
|
|
129
161
|
| `none` / `--raw` | - | - | - | - | - | - |
|
|
130
162
|
| `low` | +40% | +18% | +5% | 10 | 3 | 60 |
|
|
131
|
-
| `medium` | +60% | +25% | +8% | 18 | 5 | 80 |
|
|
163
|
+
| `medium` (default) | +60% | +25% | +8% | 18 | 5 | 80 |
|
|
132
164
|
| `high` | +100% | +30% | +12% | 26 | 8 | 100 |
|
|
133
165
|
|
|
134
|
-
`none` (or `--raw`)
|
|
166
|
+
`none` (or `--raw`) starts with every tuning knob at zero, so it does crop +
|
|
167
|
+
resize only unless an explicit tuning flag is also supplied; explicit knobs
|
|
168
|
+
still apply.
|
|
169
|
+
|
|
170
|
+
#### What `auto` does
|
|
171
|
+
|
|
172
|
+
Opt in with `--auto` (or `--intensity auto`). `auto` first fits the image to the final panel frame, then reads the luma
|
|
173
|
+
histogram of only the source content that remains in that frame. In crop mode,
|
|
174
|
+
source edges discarded by the centred fit do not affect the pick. With
|
|
175
|
+
`--no-crop`, synthetic white letterbox bars are excluded, so `--size` changes
|
|
176
|
+
the real output resolution without turning canvas into image content. It then
|
|
177
|
+
picks one of the three tonal presets:
|
|
178
|
+
|
|
179
|
+
- **`low`** for non-dark images that are already bright or sitting on white: a
|
|
180
|
+
large share of near-white pixels, or a very high 99th-percentile luma. For
|
|
181
|
+
dark-key images (mean luma at or below 85), p99 ≥ 250 selects `low`; a
|
|
182
|
+
separated upper-tail highlight also selects `low` when p75 ≥ 100, p99 ≥ 220,
|
|
183
|
+
and p99 − p95 ≥ 30.
|
|
184
|
+
- **`high`** for dark-key images whose p99 is below 120, which need the extra
|
|
185
|
+
contrast and shadow lift most.
|
|
186
|
+
- **`medium`** for everything else, including dark-key images with ordinary
|
|
187
|
+
bright detail (p99 120–249) that does not meet the separated-upper-tail
|
|
188
|
+
rule, even when those pixels exceed the normal 4% near-white share.
|
|
189
|
+
|
|
190
|
+
A final blow-out guard runs the selected settings through the exact
|
|
191
|
+
final-resolution output chain, including the output sharpening, and measures
|
|
192
|
+
newly clipped pixels only within retained source content. A strong red or blue
|
|
193
|
+
can clip long before the image looks bright. A channel begins clipping at 251;
|
|
194
|
+
more than 20% newly clipped and
|
|
195
|
+
the preset steps down one rung (`high` → `medium`, `medium` → `low`), never
|
|
196
|
+
below `low`. Any knob you passed explicitly is folded in before that
|
|
197
|
+
measurement, so the guard judges the chain that will actually run:
|
|
198
|
+
`--saturation 0` prevents saturation-induced clipping, while `--saturation 200`
|
|
199
|
+
or `--sharpen 1000` can readily trigger a step down. Contrast, warmth, tonal
|
|
200
|
+
lift, and sharpening can still clip with saturation set to zero. The low floor
|
|
201
|
+
is intentional: an explicit override stays pinned even after auto reaches
|
|
202
|
+
`low`, so extreme settings can still clip.
|
|
203
|
+
|
|
204
|
+
Every `auto` header names the selected preset. Non-medium picks also say why:
|
|
205
|
+
`(low: bright highlights)`, `(high: low overall brightness)`, or `(low: colours
|
|
206
|
+
would clip)` when it was the blow-out guard that stepped the preset down. A hint
|
|
207
|
+
after the run reminds you that `--intensity low|medium|high` pins one preset for
|
|
208
|
+
every image.
|
|
209
|
+
|
|
210
|
+
Because the numbers differ per image, `auto` does not print the
|
|
211
|
+
`sat +60% · con +25% · …` tuning line at all - that line appears only when you
|
|
212
|
+
pin a fixed `--intensity` (or `--raw`, whose numbers are all zero unless you
|
|
213
|
+
override one). The header names the preset each file got; the table above says
|
|
214
|
+
what each preset contains.
|
|
215
|
+
|
|
216
|
+
`auto` is not idempotent: re-running the tool on its own output classifies the
|
|
217
|
+
already-boosted image and may pick a different preset. Folder runs are safe -
|
|
218
|
+
files ending in `_e6` are skipped - but naming an output file explicitly is not.
|
|
135
219
|
|
|
136
220
|
### Options
|
|
137
221
|
|
|
@@ -141,16 +225,24 @@ flag overrides just that value on top of the chosen preset.
|
|
|
141
225
|
| `--suffix S` | `_e6` | Output filename suffix |
|
|
142
226
|
| `--format {png,jpg}` | `png` | Output format |
|
|
143
227
|
| `--quality N` | `100` | JPEG quality (1-100), used with `--format jpg` |
|
|
144
|
-
| `--orientation {landscape,portrait}` | `
|
|
145
|
-
| `--intensity {none,low,medium,high}` | `medium` | Overall strength preset |
|
|
228
|
+
| `--orientation {auto,landscape,portrait}` | `auto` | Panel mount; `auto` follows each image's own orientation |
|
|
229
|
+
| `--intensity {auto,none,low,medium,high}` | `medium` | Overall strength preset |
|
|
230
|
+
| `--auto` | off | Shortcut for `--intensity auto`; opt in to per-image selection |
|
|
146
231
|
| `--raw` | off | Alias for `--intensity none` |
|
|
147
232
|
| `--saturation` … `--sharpen` | from preset | Override an individual knob (values must be ≥ 0) |
|
|
148
|
-
| `--no-crop` | off | Letterbox instead of crop-to-fill
|
|
149
|
-
| `--size WxH` |
|
|
150
|
-
|
|
151
|
-
The panel is 1600×1200 (4:3)
|
|
152
|
-
|
|
153
|
-
(
|
|
233
|
+
| `--no-crop` | off | Letterbox instead of crop-to-fill the panel |
|
|
234
|
+
| `--size WxH` | auto (1600×1200 or 1200×1600) | Override panel size |
|
|
235
|
+
|
|
236
|
+
The panel is 1600×1200 (4:3), mountable landscape or portrait. By default each
|
|
237
|
+
image keeps its own orientation: portrait photos become 1200×1600, landscape
|
|
238
|
+
(and square) 1600×1200; use `--orientation landscape|portrait` to force one
|
|
239
|
+
mount for every image. The tool crops-to-fill the panel (4:3 landscape / 3:4
|
|
240
|
+
portrait), centred, so the image fills the frame; use `--no-crop` to contain the
|
|
241
|
+
whole image with borders instead (white with `--raw`, tinted slightly warm once
|
|
242
|
+
a tonal preset is applied).
|
|
243
|
+
`--no-crop` still letterboxes any image that isn't exactly 4:3 (landscape) or
|
|
244
|
+
3:4 (portrait) — auto orientation only makes the borders smaller than forcing
|
|
245
|
+
the wrong mount would.
|
|
154
246
|
|
|
155
247
|
## Development
|
|
156
248
|
|
|
@@ -170,7 +262,6 @@ uv build # build sdist + wheel into dist/
|
|
|
170
262
|
switchbot-e6-optimizer/
|
|
171
263
|
├── .github/
|
|
172
264
|
│ ├── dependabot.yml # weekly action-SHA + uv dep updates
|
|
173
|
-
│ ├── ruleset-main-protection.json # branch protection, applied via API
|
|
174
265
|
│ └── workflows/
|
|
175
266
|
│ ├── ci.yml # lint + tests on Linux/macOS/Windows
|
|
176
267
|
│ └── release.yml # gated build/publish (OIDC)
|
|
@@ -181,6 +272,8 @@ switchbot-e6-optimizer/
|
|
|
181
272
|
│ └── py.typed
|
|
182
273
|
├── tests/
|
|
183
274
|
│ └── test_optimizer.py
|
|
275
|
+
├── .gitignore
|
|
276
|
+
├── .python-version # pins the Python uv provisions (3.14)
|
|
184
277
|
├── AGENTS.md # guidance for AI coding agents
|
|
185
278
|
├── CHANGELOG.md
|
|
186
279
|
├── LICENSE
|
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
# switchbot-e6-optimizer
|
|
2
|
+
|
|
3
|
+
[](https://github.com/hamzic/switchbot-e6-optimizer/actions/workflows/ci.yml)
|
|
4
|
+
|
|
5
|
+
Make photos look better on the **SwitchBot 13.3" AI Art Frame** and other
|
|
6
|
+
**E Ink Spectra 6 ("E6")** panels.
|
|
7
|
+
|
|
8
|
+
E6 panels show only six muted inks and render dark, flat, and low-contrast to
|
|
9
|
+
mimic paper. Uploaded straight from your phone, most photos come out dull and
|
|
10
|
+
muddy. This tool applies the continuous-tone preparation the panel needs -
|
|
11
|
+
boosted saturation and contrast, opened shadows, a warm nudge, and sharpening -
|
|
12
|
+
then leaves the dithering to the SwitchBot app.
|
|
13
|
+
|
|
14
|
+
> **Do not pre-dither for the SwitchBot app.** The app does its own colour
|
|
15
|
+
> mapping and dithering on upload. If you dither first you get double-dithering:
|
|
16
|
+
> visible noise, muddy colour.
|
|
17
|
+
|
|
18
|
+
## Why the panel needs this
|
|
19
|
+
|
|
20
|
+
| Adjustment | Compensates for |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| Saturation (biggest lever) | Muted six-ink gamut |
|
|
23
|
+
| Contrast | Compressed (~26:1) dynamic range |
|
|
24
|
+
| Brightness + shadow lift | Panel renders dark and crushes shadows |
|
|
25
|
+
| Warmth | Paper-grey white, weak blues |
|
|
26
|
+
| Sharpen | Detail lost to dithering and sub-native resolution |
|
|
27
|
+
| **No dithering** | The app dithers; doing it twice = mud |
|
|
28
|
+
|
|
29
|
+
## Requirements
|
|
30
|
+
|
|
31
|
+
- Python **3.14+**
|
|
32
|
+
- [uv](https://docs.astral.sh/uv/) (manages the environment, tests, and linting)
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
git clone https://github.com/hamzic/switchbot-e6-optimizer
|
|
38
|
+
cd switchbot-e6-optimizer
|
|
39
|
+
uv sync # create the venv and install everything
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Run it with `uv run`:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
uv run switchbot-e6 photo.jpg
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Or install the CLI as a standalone tool:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
uv tool install .
|
|
52
|
+
switchbot-e6 photo.jpg
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
To uninstall the tool later:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
uv tool uninstall switchbot-e6-optimizer
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Usage
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# one photo, fixed medium intensity -> photo_e6.png next to it
|
|
65
|
+
switchbot-e6 photo.jpg
|
|
66
|
+
|
|
67
|
+
# opt in to per-image auto intensity
|
|
68
|
+
switchbot-e6 photo.jpg --auto
|
|
69
|
+
|
|
70
|
+
# a whole folder into ./out; each image keeps its own orientation (auto)
|
|
71
|
+
switchbot-e6 ~/Pictures/art --out ./out
|
|
72
|
+
|
|
73
|
+
# force landscape mount even for portrait photos
|
|
74
|
+
switchbot-e6 ~/Pictures/art --orientation landscape --out ./out
|
|
75
|
+
|
|
76
|
+
# punchier preset for flat, boldly-coloured art
|
|
77
|
+
switchbot-e6 poster.png --intensity high
|
|
78
|
+
|
|
79
|
+
# ride the high preset but pin saturation to exactly +80%
|
|
80
|
+
switchbot-e6 poster.png --intensity high --saturation 80
|
|
81
|
+
|
|
82
|
+
# zeroed tonal base; explicit knob flags still apply
|
|
83
|
+
switchbot-e6 photo.jpg --raw
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Inputs can be files or whole folders. Running with no arguments prints the full
|
|
87
|
+
help. You can also run it as a module: `python -m switchbot_e6_optimizer`.
|
|
88
|
+
|
|
89
|
+
A fixed-intensity run reports each file's canvas and the chosen fixed preset.
|
|
90
|
+
An explicit `--auto` run names every per-image preset; non-medium picks also
|
|
91
|
+
include why they moved off medium:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
🎨 Optimising 3 image(s) for E6
|
|
95
|
+
auto orientation (portrait) (1200×1600) · intensity: auto (low: bright highlights)
|
|
96
|
+
✓ dawn.jpg → dawn_e6.png
|
|
97
|
+
auto orientation (landscape) (1600×1200) · intensity: auto (low: colours would clip)
|
|
98
|
+
✓ prize_bull.jpg → prize_bull_e6.png
|
|
99
|
+
auto orientation (landscape) (1600×1200) · intensity: auto (medium)
|
|
100
|
+
✓ holiday.jpg → holiday_e6.png
|
|
101
|
+
✅ Done: 3/3 succeeded.
|
|
102
|
+
ℹ intensities were auto-chosen; override with --intensity low|medium|high
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
A single image folds that header into the first line:
|
|
106
|
+
|
|
107
|
+
```text
|
|
108
|
+
🎨 Optimising 1 image(s) for E6 @ auto orientation (portrait) (1200×1600) · intensity: auto (low: bright highlights)
|
|
109
|
+
✓ dawn.jpg → dawn_e6.png
|
|
110
|
+
✅ Done: 1/1 succeeded.
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Supported formats
|
|
114
|
+
|
|
115
|
+
| Direction | Formats |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| Input | JPEG, PNG, WebP, BMP, TIFF, iPhone HEIC/HEIF |
|
|
118
|
+
| Output | PNG (default) or JPEG (`--format jpg`) |
|
|
119
|
+
|
|
120
|
+
When a folder is expanded, files already ending in the output suffix (`*_e6`)
|
|
121
|
+
are skipped with a notice so re-runs don't double-process previous output; pass
|
|
122
|
+
such a file explicitly to force it.
|
|
123
|
+
|
|
124
|
+
The exported file looks a little too vivid and too bright on your monitor;
|
|
125
|
+
**that is correct for E6.** After exporting, upload the `*_e6` file to the
|
|
126
|
+
SwitchBot app **as-is** and fine-tune with the app's own saturation/contrast
|
|
127
|
+
sliders once you see it on the panel.
|
|
128
|
+
|
|
129
|
+
### Intensity presets
|
|
130
|
+
|
|
131
|
+
Each preset sets every knob at once. `medium` is the default; use `--auto` (or
|
|
132
|
+
`--intensity auto`) to opt in to per-image selection. Any single tuning flag
|
|
133
|
+
overrides just that value on top of the chosen preset.
|
|
134
|
+
|
|
135
|
+
| Preset | Saturation | Contrast | Brightness | Shadow lift | Warmth | Sharpen |
|
|
136
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
137
|
+
| `auto` (`--auto`) | per image | per image | per image | per image | per image | per image |
|
|
138
|
+
| `none` / `--raw` | - | - | - | - | - | - |
|
|
139
|
+
| `low` | +40% | +18% | +5% | 10 | 3 | 60 |
|
|
140
|
+
| `medium` (default) | +60% | +25% | +8% | 18 | 5 | 80 |
|
|
141
|
+
| `high` | +100% | +30% | +12% | 26 | 8 | 100 |
|
|
142
|
+
|
|
143
|
+
`none` (or `--raw`) starts with every tuning knob at zero, so it does crop +
|
|
144
|
+
resize only unless an explicit tuning flag is also supplied; explicit knobs
|
|
145
|
+
still apply.
|
|
146
|
+
|
|
147
|
+
#### What `auto` does
|
|
148
|
+
|
|
149
|
+
Opt in with `--auto` (or `--intensity auto`). `auto` first fits the image to the final panel frame, then reads the luma
|
|
150
|
+
histogram of only the source content that remains in that frame. In crop mode,
|
|
151
|
+
source edges discarded by the centred fit do not affect the pick. With
|
|
152
|
+
`--no-crop`, synthetic white letterbox bars are excluded, so `--size` changes
|
|
153
|
+
the real output resolution without turning canvas into image content. It then
|
|
154
|
+
picks one of the three tonal presets:
|
|
155
|
+
|
|
156
|
+
- **`low`** for non-dark images that are already bright or sitting on white: a
|
|
157
|
+
large share of near-white pixels, or a very high 99th-percentile luma. For
|
|
158
|
+
dark-key images (mean luma at or below 85), p99 ≥ 250 selects `low`; a
|
|
159
|
+
separated upper-tail highlight also selects `low` when p75 ≥ 100, p99 ≥ 220,
|
|
160
|
+
and p99 − p95 ≥ 30.
|
|
161
|
+
- **`high`** for dark-key images whose p99 is below 120, which need the extra
|
|
162
|
+
contrast and shadow lift most.
|
|
163
|
+
- **`medium`** for everything else, including dark-key images with ordinary
|
|
164
|
+
bright detail (p99 120–249) that does not meet the separated-upper-tail
|
|
165
|
+
rule, even when those pixels exceed the normal 4% near-white share.
|
|
166
|
+
|
|
167
|
+
A final blow-out guard runs the selected settings through the exact
|
|
168
|
+
final-resolution output chain, including the output sharpening, and measures
|
|
169
|
+
newly clipped pixels only within retained source content. A strong red or blue
|
|
170
|
+
can clip long before the image looks bright. A channel begins clipping at 251;
|
|
171
|
+
more than 20% newly clipped and
|
|
172
|
+
the preset steps down one rung (`high` → `medium`, `medium` → `low`), never
|
|
173
|
+
below `low`. Any knob you passed explicitly is folded in before that
|
|
174
|
+
measurement, so the guard judges the chain that will actually run:
|
|
175
|
+
`--saturation 0` prevents saturation-induced clipping, while `--saturation 200`
|
|
176
|
+
or `--sharpen 1000` can readily trigger a step down. Contrast, warmth, tonal
|
|
177
|
+
lift, and sharpening can still clip with saturation set to zero. The low floor
|
|
178
|
+
is intentional: an explicit override stays pinned even after auto reaches
|
|
179
|
+
`low`, so extreme settings can still clip.
|
|
180
|
+
|
|
181
|
+
Every `auto` header names the selected preset. Non-medium picks also say why:
|
|
182
|
+
`(low: bright highlights)`, `(high: low overall brightness)`, or `(low: colours
|
|
183
|
+
would clip)` when it was the blow-out guard that stepped the preset down. A hint
|
|
184
|
+
after the run reminds you that `--intensity low|medium|high` pins one preset for
|
|
185
|
+
every image.
|
|
186
|
+
|
|
187
|
+
Because the numbers differ per image, `auto` does not print the
|
|
188
|
+
`sat +60% · con +25% · …` tuning line at all - that line appears only when you
|
|
189
|
+
pin a fixed `--intensity` (or `--raw`, whose numbers are all zero unless you
|
|
190
|
+
override one). The header names the preset each file got; the table above says
|
|
191
|
+
what each preset contains.
|
|
192
|
+
|
|
193
|
+
`auto` is not idempotent: re-running the tool on its own output classifies the
|
|
194
|
+
already-boosted image and may pick a different preset. Folder runs are safe -
|
|
195
|
+
files ending in `_e6` are skipped - but naming an output file explicitly is not.
|
|
196
|
+
|
|
197
|
+
### Options
|
|
198
|
+
|
|
199
|
+
| Option | Default | Description |
|
|
200
|
+
| --- | --- | --- |
|
|
201
|
+
| `-o, --output DIR` (or `--out`) | next to source | Output directory, created if missing |
|
|
202
|
+
| `--suffix S` | `_e6` | Output filename suffix |
|
|
203
|
+
| `--format {png,jpg}` | `png` | Output format |
|
|
204
|
+
| `--quality N` | `100` | JPEG quality (1-100), used with `--format jpg` |
|
|
205
|
+
| `--orientation {auto,landscape,portrait}` | `auto` | Panel mount; `auto` follows each image's own orientation |
|
|
206
|
+
| `--intensity {auto,none,low,medium,high}` | `medium` | Overall strength preset |
|
|
207
|
+
| `--auto` | off | Shortcut for `--intensity auto`; opt in to per-image selection |
|
|
208
|
+
| `--raw` | off | Alias for `--intensity none` |
|
|
209
|
+
| `--saturation` … `--sharpen` | from preset | Override an individual knob (values must be ≥ 0) |
|
|
210
|
+
| `--no-crop` | off | Letterbox instead of crop-to-fill the panel |
|
|
211
|
+
| `--size WxH` | auto (1600×1200 or 1200×1600) | Override panel size |
|
|
212
|
+
|
|
213
|
+
The panel is 1600×1200 (4:3), mountable landscape or portrait. By default each
|
|
214
|
+
image keeps its own orientation: portrait photos become 1200×1600, landscape
|
|
215
|
+
(and square) 1600×1200; use `--orientation landscape|portrait` to force one
|
|
216
|
+
mount for every image. The tool crops-to-fill the panel (4:3 landscape / 3:4
|
|
217
|
+
portrait), centred, so the image fills the frame; use `--no-crop` to contain the
|
|
218
|
+
whole image with borders instead (white with `--raw`, tinted slightly warm once
|
|
219
|
+
a tonal preset is applied).
|
|
220
|
+
`--no-crop` still letterboxes any image that isn't exactly 4:3 (landscape) or
|
|
221
|
+
3:4 (portrait) — auto orientation only makes the borders smaller than forcing
|
|
222
|
+
the wrong mount would.
|
|
223
|
+
|
|
224
|
+
## Development
|
|
225
|
+
|
|
226
|
+
Everything runs through uv:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
uv sync # install deps + dev tools (pytest, ruff)
|
|
230
|
+
uv run pytest # run the test suite
|
|
231
|
+
uv run ruff check . # lint (PEP 8 + import sort + pyupgrade + bugbear)
|
|
232
|
+
uv run ruff format . # format
|
|
233
|
+
uv build # build sdist + wheel into dist/
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Project structure
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
switchbot-e6-optimizer/
|
|
240
|
+
├── .github/
|
|
241
|
+
│ ├── dependabot.yml # weekly action-SHA + uv dep updates
|
|
242
|
+
│ └── workflows/
|
|
243
|
+
│ ├── ci.yml # lint + tests on Linux/macOS/Windows
|
|
244
|
+
│ └── release.yml # gated build/publish (OIDC)
|
|
245
|
+
├── src/switchbot_e6_optimizer/
|
|
246
|
+
│ ├── __init__.py # version + public re-exports
|
|
247
|
+
│ ├── __main__.py # python -m switchbot_e6_optimizer
|
|
248
|
+
│ ├── optimizer.py # the pipeline + CLI
|
|
249
|
+
│ └── py.typed
|
|
250
|
+
├── tests/
|
|
251
|
+
│ └── test_optimizer.py
|
|
252
|
+
├── .gitignore
|
|
253
|
+
├── .python-version # pins the Python uv provisions (3.14)
|
|
254
|
+
├── AGENTS.md # guidance for AI coding agents
|
|
255
|
+
├── CHANGELOG.md
|
|
256
|
+
├── LICENSE
|
|
257
|
+
├── README.md
|
|
258
|
+
├── pyproject.toml
|
|
259
|
+
└── uv.lock
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
## Trademarks
|
|
263
|
+
|
|
264
|
+
"SwitchBot" and "E Ink" / "Spectra" are trademarks of their respective owners.
|
|
265
|
+
This is an independent, unofficial tool - not affiliated with, endorsed by, or
|
|
266
|
+
sponsored by SwitchBot or E Ink.
|
|
267
|
+
|
|
268
|
+
## License
|
|
269
|
+
|
|
270
|
+
[MIT](LICENSE) - free to use, modify, and distribute; just keep the license
|
|
271
|
+
notice so use traces back to this project.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "switchbot-e6-optimizer"
|
|
3
|
+
version = "1.1.1"
|
|
4
|
+
description = 'Optimise photos for the SwitchBot 13.3" AI Art Frame (E Ink Spectra 6).'
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.14"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
keywords = [
|
|
10
|
+
"switchbot",
|
|
11
|
+
"e-ink",
|
|
12
|
+
"eink",
|
|
13
|
+
"spectra6",
|
|
14
|
+
"epaper",
|
|
15
|
+
"image",
|
|
16
|
+
"pillow",
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Development Status :: 5 - Production/Stable",
|
|
20
|
+
"Environment :: Console",
|
|
21
|
+
"Intended Audience :: End Users/Desktop",
|
|
22
|
+
"Operating System :: OS Independent",
|
|
23
|
+
"Programming Language :: Python :: 3.14",
|
|
24
|
+
"Topic :: Multimedia :: Graphics",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"pillow>=13",
|
|
28
|
+
"pillow-heif>=1",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[[project.authors]]
|
|
32
|
+
name = "switchbot-e6-optimizer contributors"
|
|
33
|
+
|
|
34
|
+
[project.scripts]
|
|
35
|
+
switchbot-e6 = "switchbot_e6_optimizer.optimizer:main"
|
|
36
|
+
|
|
37
|
+
[project.urls]
|
|
38
|
+
Homepage = "https://github.com/hamzic/switchbot-e6-optimizer"
|
|
39
|
+
Repository = "https://github.com/hamzic/switchbot-e6-optimizer"
|
|
40
|
+
Issues = "https://github.com/hamzic/switchbot-e6-optimizer/issues"
|
|
41
|
+
Changelog = "https://github.com/hamzic/switchbot-e6-optimizer/blob/main/CHANGELOG.md"
|
|
42
|
+
|
|
43
|
+
[build-system]
|
|
44
|
+
requires = ["uv_build>=0.11.28,<0.14"]
|
|
45
|
+
build-backend = "uv_build"
|
|
46
|
+
|
|
47
|
+
[dependency-groups]
|
|
48
|
+
dev = [
|
|
49
|
+
"pytest>=8",
|
|
50
|
+
"ruff>=0.14",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[tool.ruff]
|
|
54
|
+
line-length = 88
|
|
55
|
+
target-version = "py314"
|
|
56
|
+
|
|
57
|
+
[tool.ruff.lint]
|
|
58
|
+
select = [
|
|
59
|
+
"E",
|
|
60
|
+
"F",
|
|
61
|
+
"I",
|
|
62
|
+
"UP",
|
|
63
|
+
"B",
|
|
64
|
+
"SIM",
|
|
65
|
+
"C4",
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
[tool.ruff.format]
|
|
69
|
+
docstring-code-format = true
|
|
70
|
+
|
|
71
|
+
[tool.pytest.ini_options]
|
|
72
|
+
testpaths = ["tests"]
|
|
73
|
+
addopts = "-q"
|
|
74
|
+
filterwarnings = ["error::DeprecationWarning"]
|
switchbot_e6_optimizer-1.0.0/pyproject.toml → switchbot_e6_optimizer-1.1.1/pyproject.toml.orig
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "switchbot-e6-optimizer"
|
|
3
|
-
version = "1.
|
|
3
|
+
version = "1.1.1"
|
|
4
4
|
description = "Optimise photos for the SwitchBot 13.3\" AI Art Frame (E Ink Spectra 6)."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.14"
|
|
@@ -16,7 +16,7 @@ classifiers = [
|
|
|
16
16
|
"Programming Language :: Python :: 3.14",
|
|
17
17
|
"Topic :: Multimedia :: Graphics",
|
|
18
18
|
]
|
|
19
|
-
dependencies = ["pillow>=
|
|
19
|
+
dependencies = ["pillow>=13", "pillow-heif>=1"]
|
|
20
20
|
|
|
21
21
|
[project.scripts]
|
|
22
22
|
switchbot-e6 = "switchbot_e6_optimizer.optimizer:main"
|
|
@@ -28,7 +28,7 @@ Issues = "https://github.com/hamzic/switchbot-e6-optimizer/issues"
|
|
|
28
28
|
Changelog = "https://github.com/hamzic/switchbot-e6-optimizer/blob/main/CHANGELOG.md"
|
|
29
29
|
|
|
30
30
|
[build-system]
|
|
31
|
-
requires = ["uv_build>=0.11.28,<0.
|
|
31
|
+
requires = ["uv_build>=0.11.28,<0.14"]
|
|
32
32
|
build-backend = "uv_build"
|
|
33
33
|
|
|
34
34
|
[dependency-groups]
|