@crabcrop/url 0.9.6 → 0.9.8
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.
- package/dist/explain.js +204 -12
- package/dist/operations.d.ts +58 -1
- package/dist/operations.js +160 -2
- package/package.json +1 -1
package/dist/explain.js
CHANGED
|
@@ -13,10 +13,15 @@ export const FILTER_DESCRIPTIONS = {
|
|
|
13
13
|
blurfaces: "blur detected faces (needs a face model on the server)",
|
|
14
14
|
brighten: "brighten by the given amount (-255..255)",
|
|
15
15
|
contrast: "contrast in percent, -100..100 (0 is unchanged, -100 is flat)",
|
|
16
|
+
gamma: "gamma correction with divisor g, 0 < g <= 10: each channel becomes 255 * (v / 255)^(1 / g) (1 is unchanged, above 1 brightens midtones)",
|
|
17
|
+
exposure: "exposure in stops, -10..10: multiply the linear light by 2^stops (0 is unchanged, positive brightens, negative darkens)",
|
|
18
|
+
highlights_shadows: "adjust the highlights and shadows ranges independently: two percents, each -100..100 (0 is unchanged)",
|
|
19
|
+
vibrance: "saturation weighted toward the muted colors: percent, -100..100 (0 is unchanged; vivid colors and skin tones are protected)",
|
|
16
20
|
huerotate: "rotate the hue by the given degrees",
|
|
17
21
|
rotate: "rotate by the given angle in degrees; the canvas expands to fit",
|
|
18
|
-
quality: "output quality 1..100, or `auto` for perceptual targeting",
|
|
19
|
-
|
|
22
|
+
quality: "output quality 1..100, or `auto` for perceptual targeting; or per-format values in one list (quality(80,jpeg:90,webp:75)), resolved after format negotiation",
|
|
23
|
+
palette: "write PNG output as an indexed (palette) image with at most this many colors, 2..256; ignored by the other formats",
|
|
24
|
+
format: "force the output format; a format also takes its encoder options (format(jpeg,progressive), format(png,interlace), format(webp,method:6,sns:50)); an option its encoder cannot honour is refused",
|
|
20
25
|
fill: "the background color other operations pad with",
|
|
21
26
|
facepad: "how much a face crop expands around the face",
|
|
22
27
|
pixelatefaces: "pixelate detected faces (needs a face model on the server)",
|
|
@@ -28,6 +33,7 @@ export const FILTER_DESCRIPTIONS = {
|
|
|
28
33
|
keep_profile: "keep the source color profile instead of converting to sRGB",
|
|
29
34
|
upscale: "AI upscale by the given factor (needs an AI model on the server)",
|
|
30
35
|
equalize: "histogram equalization",
|
|
36
|
+
enhance: "gentle per-channel auto-levels (0.5th percentile to 0, 99.5th to 255)",
|
|
31
37
|
saturation: "saturation factor, 0..255 (0 is grayscale, 1 is identity)",
|
|
32
38
|
sharpen: "sharpen by the given amount",
|
|
33
39
|
text: "draw a text overlay (needs a font on the server)",
|
|
@@ -35,7 +41,7 @@ export const FILTER_DESCRIPTIONS = {
|
|
|
35
41
|
curve: "tone curve: remap the named channel (rgb, r, g, or b) through 2 to 16 x,y control points, linearly interpolated, ends clamped",
|
|
36
42
|
convolution: "convolve with a 3x3 or 5x5 kernel: 9 or 25 row-major values (plain decimals, -1024..1024), then a normalize flag (0 or 1); edges replicate",
|
|
37
43
|
noise: "add monochrome film grain: one deterministic noise value per pixel on all channels, strength 0..100 percent of full scale (0 is a no-op)",
|
|
38
|
-
trim: "trim uniform borders",
|
|
44
|
+
trim: "trim uniform borders; the five-argument form (tolerance,left,top,right,bottom) also removes that many pixels per side after the tolerance pass",
|
|
39
45
|
dpr: "device pixel ratio the sizes are multiplied by",
|
|
40
46
|
watermark: "overlay a watermark image",
|
|
41
47
|
max_bytes: "cap the output size, lowering quality to fit",
|
|
@@ -104,6 +110,7 @@ const NO_ARG_FILTERS = new Set([
|
|
|
104
110
|
"invert",
|
|
105
111
|
"no_upscale",
|
|
106
112
|
"equalize",
|
|
113
|
+
"enhance",
|
|
107
114
|
"removebg",
|
|
108
115
|
"keep_profile",
|
|
109
116
|
"sepia",
|
|
@@ -166,8 +173,18 @@ function validateFilter(name, args) {
|
|
|
166
173
|
return args === null ? null : bad;
|
|
167
174
|
}
|
|
168
175
|
switch (name) {
|
|
169
|
-
case "trim":
|
|
170
|
-
|
|
176
|
+
case "trim": {
|
|
177
|
+
if (args === null)
|
|
178
|
+
return null;
|
|
179
|
+
const parts = args.split(",");
|
|
180
|
+
if (parts.length === 1)
|
|
181
|
+
return isIntIn(parts[0], 0, 255) ? null : bad;
|
|
182
|
+
return parts.length === 5 &&
|
|
183
|
+
isIntIn(parts[0], 0, 255) &&
|
|
184
|
+
parts.slice(1).every((p) => isIntIn(p, 0, 4294967295))
|
|
185
|
+
? null
|
|
186
|
+
: bad;
|
|
187
|
+
}
|
|
171
188
|
case "blur":
|
|
172
189
|
case "sharpen":
|
|
173
190
|
return args !== null && isFloat(args) && Number(args) > 0 ? null : bad;
|
|
@@ -179,14 +196,103 @@ function validateFilter(name, args) {
|
|
|
179
196
|
return args !== null && isFloat(args) && Number(args) >= -100 && Number(args) <= 100
|
|
180
197
|
? null
|
|
181
198
|
: bad;
|
|
199
|
+
case "gamma":
|
|
200
|
+
return args !== null && isFloat(args) && Number(args) > 0 && Number(args) <= 10
|
|
201
|
+
? null
|
|
202
|
+
: bad;
|
|
203
|
+
case "exposure":
|
|
204
|
+
return args !== null && isFloat(args) && Number(args) >= -10 && Number(args) <= 10
|
|
205
|
+
? null
|
|
206
|
+
: bad;
|
|
207
|
+
case "highlights_shadows": {
|
|
208
|
+
if (args === null)
|
|
209
|
+
return bad;
|
|
210
|
+
const parts = args.split(",");
|
|
211
|
+
return parts.length === 2 &&
|
|
212
|
+
parts.every((p) => isFloat(p) && Number(p) >= -100 && Number(p) <= 100)
|
|
213
|
+
? null
|
|
214
|
+
: bad;
|
|
215
|
+
}
|
|
216
|
+
case "vibrance":
|
|
217
|
+
return args !== null && isFloat(args) && Number(args) >= -100 && Number(args) <= 100
|
|
218
|
+
? null
|
|
219
|
+
: bad;
|
|
182
220
|
case "saturation":
|
|
183
221
|
return args !== null && isFloat(args) && Number(args) >= 0 && Number(args) <= 255
|
|
184
222
|
? null
|
|
185
223
|
: bad;
|
|
186
|
-
case "quality":
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
224
|
+
case "quality": {
|
|
225
|
+
if (args === null)
|
|
226
|
+
return bad;
|
|
227
|
+
if (args === "auto" || isIntIn(args, 1, 100))
|
|
228
|
+
return null;
|
|
229
|
+
// Per-format list (issue #319): at most one bare
|
|
230
|
+
// fallback, at most one entry per format, no video
|
|
231
|
+
// formats (their quality is not the server's to set).
|
|
232
|
+
const seen = new Set();
|
|
233
|
+
let fallbackSeen = false;
|
|
234
|
+
for (const part of args.split(",")) {
|
|
235
|
+
const colon = part.indexOf(":");
|
|
236
|
+
if (colon === -1) {
|
|
237
|
+
if (fallbackSeen || !(part === "auto" || isIntIn(part, 1, 100)))
|
|
238
|
+
return bad;
|
|
239
|
+
fallbackSeen = true;
|
|
240
|
+
}
|
|
241
|
+
else {
|
|
242
|
+
const name = part.slice(0, colon);
|
|
243
|
+
const value = part.slice(colon + 1);
|
|
244
|
+
if (!FORMAT_NAMES.has(name) || name === "mp4" || name === "webm")
|
|
245
|
+
return bad;
|
|
246
|
+
const canonical = name === "jpg" ? "jpeg" : name;
|
|
247
|
+
if (seen.has(canonical))
|
|
248
|
+
return bad;
|
|
249
|
+
seen.add(canonical);
|
|
250
|
+
if (!(value === "auto" || isIntIn(value, 1, 100)))
|
|
251
|
+
return bad;
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
return seen.size + (fallbackSeen ? 1 : 0) > 0 ? null : bad;
|
|
255
|
+
}
|
|
256
|
+
case "palette":
|
|
257
|
+
return args !== null && isIntIn(args, 2, 256) ? null : bad;
|
|
258
|
+
case "format": {
|
|
259
|
+
if (args === null)
|
|
260
|
+
return bad;
|
|
261
|
+
// A format name plus its encoder options (issue #319),
|
|
262
|
+
// each validated against the format it belongs to.
|
|
263
|
+
const parts = args.split(",");
|
|
264
|
+
const [name, ...options] = parts;
|
|
265
|
+
if (!FORMAT_NAMES.has(name))
|
|
266
|
+
return bad;
|
|
267
|
+
const seen = new Set();
|
|
268
|
+
for (const option of options) {
|
|
269
|
+
const key = option.includes(":") ? option.slice(0, option.indexOf(":")) : option;
|
|
270
|
+
if (seen.has(key))
|
|
271
|
+
return bad;
|
|
272
|
+
seen.add(key);
|
|
273
|
+
if (name === "jpeg" || name === "jpg") {
|
|
274
|
+
if (option === "progressive")
|
|
275
|
+
continue;
|
|
276
|
+
if (/^subsampling:(444|422|420)$/.test(option))
|
|
277
|
+
continue;
|
|
278
|
+
return bad;
|
|
279
|
+
}
|
|
280
|
+
if (name === "png") {
|
|
281
|
+
if (option === "interlace")
|
|
282
|
+
continue;
|
|
283
|
+
return bad;
|
|
284
|
+
}
|
|
285
|
+
if (name === "webp") {
|
|
286
|
+
if (/^method:[0-6]$/.test(option))
|
|
287
|
+
continue;
|
|
288
|
+
if (/^sns:\d+$/.test(option) && isIntIn(option.slice(4), 0, 100))
|
|
289
|
+
continue;
|
|
290
|
+
return bad;
|
|
291
|
+
}
|
|
292
|
+
return bad;
|
|
293
|
+
}
|
|
294
|
+
return null;
|
|
295
|
+
}
|
|
190
296
|
case "rgb": {
|
|
191
297
|
if (args === null)
|
|
192
298
|
return bad;
|
|
@@ -490,6 +596,56 @@ function explainFilters(rest) {
|
|
|
490
596
|
}
|
|
491
597
|
const ALIGN_NAMES = new Set(["center", "smart", "face", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"]);
|
|
492
598
|
const U64_MAX = 18446744073709551615n;
|
|
599
|
+
/**
|
|
600
|
+
* The objects crop alignment (url.rs parse_objects, ported):
|
|
601
|
+
* `objects(<class>[,<class>...])[:<scale>]`. Returns the
|
|
602
|
+
* decoded class names (duplicates folded, first spelling
|
|
603
|
+
* kept, as the server's canonical form folds them) and the
|
|
604
|
+
* scale, or null when the server would reject the form.
|
|
605
|
+
*/
|
|
606
|
+
function parseObjectsAlign(align) {
|
|
607
|
+
if (!align.startsWith("objects("))
|
|
608
|
+
return null;
|
|
609
|
+
const inner = align.slice("objects(".length);
|
|
610
|
+
const close = inner.indexOf(")");
|
|
611
|
+
if (close < 0)
|
|
612
|
+
return null;
|
|
613
|
+
const list = inner.slice(0, close);
|
|
614
|
+
const tail = inner.slice(close + 1);
|
|
615
|
+
let scale = 1;
|
|
616
|
+
if (tail !== "") {
|
|
617
|
+
if (!tail.startsWith(":"))
|
|
618
|
+
return null;
|
|
619
|
+
const text = tail.slice(1);
|
|
620
|
+
if (!isFloat(text))
|
|
621
|
+
return null;
|
|
622
|
+
scale = Number(text);
|
|
623
|
+
if (!(scale > 0) || scale > 100)
|
|
624
|
+
return null;
|
|
625
|
+
}
|
|
626
|
+
const parts = list.split(",");
|
|
627
|
+
if (parts.length > 32)
|
|
628
|
+
return null;
|
|
629
|
+
const classes = [];
|
|
630
|
+
const seen = new Set();
|
|
631
|
+
for (const part of parts) {
|
|
632
|
+
const decoded = percentDecodable(part);
|
|
633
|
+
if (decoded === null)
|
|
634
|
+
return null;
|
|
635
|
+
const name = decoded.trim();
|
|
636
|
+
if (name.length < 1 ||
|
|
637
|
+
new TextEncoder().encode(name).length > 64 ||
|
|
638
|
+
!/^[\p{L}\p{N} _.\-/]+$/u.test(name)) {
|
|
639
|
+
return null;
|
|
640
|
+
}
|
|
641
|
+
const key = name.toLowerCase();
|
|
642
|
+
if (!seen.has(key)) {
|
|
643
|
+
seen.add(key);
|
|
644
|
+
classes.push(name);
|
|
645
|
+
}
|
|
646
|
+
}
|
|
647
|
+
return classes.length > 0 ? { classes, scale } : null;
|
|
648
|
+
}
|
|
493
649
|
function explainSegment(seg, nowSeconds) {
|
|
494
650
|
if (seg.startsWith("exp:")) {
|
|
495
651
|
const value = seg.slice(4);
|
|
@@ -555,7 +711,7 @@ function explainSegment(seg, nowSeconds) {
|
|
|
555
711
|
return {
|
|
556
712
|
kind: "debug",
|
|
557
713
|
title: "Debug view",
|
|
558
|
-
detail: "the response is a diagnostic image instead of the transform result: the canvas the next crop operates on, with the chosen focal point (magenta crosshair), the focal rectangle when one is in play,
|
|
714
|
+
detail: "the response is a diagnostic image instead of the transform result: the canvas the next crop operates on, with the chosen focal point (magenta crosshair), the focal rectangle when one is in play, the detection boxes that fed the decision (amber), and the crop window outline (blue); with no crop it shows the focal analysis of the final image; debug responses are never cached and are served with Cache-Control: no-store; animated sources and video formats are refused with 400",
|
|
559
715
|
};
|
|
560
716
|
}
|
|
561
717
|
if (seg.startsWith("preset:")) {
|
|
@@ -599,17 +755,53 @@ function explainSegment(seg, nowSeconds) {
|
|
|
599
755
|
}
|
|
600
756
|
return { kind: "operation", title: "Focal rectangle", detail: `set the focal rectangle ${rest} for the next crop (left x top : right x bottom)` };
|
|
601
757
|
}
|
|
758
|
+
if (seg.startsWith("focalpoint:")) {
|
|
759
|
+
const rest = seg.slice(11);
|
|
760
|
+
const colon = rest.indexOf(":");
|
|
761
|
+
const point = colon === -1 ? rest : rest.slice(0, colon);
|
|
762
|
+
const zoomText = colon === -1 ? null : rest.slice(colon + 1);
|
|
763
|
+
const xy = point.split("x");
|
|
764
|
+
const ok = xy.length === 2 &&
|
|
765
|
+
isFloat(xy[0]) &&
|
|
766
|
+
isFloat(xy[1]) &&
|
|
767
|
+
Number(xy[0]) >= 0 &&
|
|
768
|
+
Number(xy[0]) <= 1 &&
|
|
769
|
+
Number(xy[1]) >= 0 &&
|
|
770
|
+
Number(xy[1]) <= 1 &&
|
|
771
|
+
(zoomText === null ||
|
|
772
|
+
(isFloat(zoomText) && Number(zoomText) > 0 && Number(zoomText) <= 100));
|
|
773
|
+
if (!ok) {
|
|
774
|
+
return {
|
|
775
|
+
kind: "operation",
|
|
776
|
+
title: "Focal point",
|
|
777
|
+
error: `malformed focalpoint segment: ${seg} (want focalpoint:<x>x<y>[:<zoom>] with x and y in 0..1 and zoom in (0, 100])`,
|
|
778
|
+
};
|
|
779
|
+
}
|
|
780
|
+
return {
|
|
781
|
+
kind: "operation",
|
|
782
|
+
title: "Focal point",
|
|
783
|
+
detail: `set the focal point ${point} at zoom ${zoomText ?? "1"} for the next crop (fractions of the image dimensions; zoom above 1 tightens the crop around the point)`,
|
|
784
|
+
};
|
|
785
|
+
}
|
|
602
786
|
if (seg.startsWith("crop:")) {
|
|
603
787
|
const rest = seg.slice(5);
|
|
604
788
|
const idx = rest.indexOf(":");
|
|
605
789
|
const dims = idx === -1 ? rest : rest.slice(0, idx);
|
|
606
790
|
const align = idx === -1 ? "center" : rest.slice(idx + 1);
|
|
607
791
|
const cropSize = parseSizeSegment(dims);
|
|
608
|
-
|
|
792
|
+
const objects = align.startsWith("objects") ? parseObjectsAlign(align) : null;
|
|
793
|
+
if (!cropSize || !isExactBox(cropSize) || (!ALIGN_NAMES.has(align) && objects === null)) {
|
|
794
|
+
return {
|
|
795
|
+
kind: "operation",
|
|
796
|
+
title: "Crop",
|
|
797
|
+
error: `malformed crop segment: ${seg} (want crop:<w>x<h>[:center|smart|face|top|bottom|left|right|top-left|top-right|bottom-left|bottom-right|objects(<class>[,<class>...])[:<scale>]], pixels only, no flips)`,
|
|
798
|
+
};
|
|
799
|
+
}
|
|
800
|
+
if (objects !== null) {
|
|
609
801
|
return {
|
|
610
802
|
kind: "operation",
|
|
611
803
|
title: "Crop",
|
|
612
|
-
|
|
804
|
+
detail: `crop to the aspect of ${dims} and resize to it; alignment: objects (${objects.classes.join(", ")}): frame the union of every detection of the named classes, the union box scaled by ${objects.scale} about its center and the crop centered on it; needs a detection model on the server, and falls back to the plain center crop of the same size when none of the classes is detected`,
|
|
613
805
|
};
|
|
614
806
|
}
|
|
615
807
|
return { kind: "operation", title: "Crop", detail: `crop to the aspect of ${dims} and resize to it; alignment: ${align === "center" ? "center (or the focal point for smart)" : align}` };
|
package/dist/operations.d.ts
CHANGED
|
@@ -13,6 +13,21 @@
|
|
|
13
13
|
*/
|
|
14
14
|
/** Output formats the `format(...)` filter accepts. */
|
|
15
15
|
export type ImageFormat = "jpeg" | "jpg" | "png" | "webp" | "jxl" | "avif" | "gif" | "mp4" | "webm";
|
|
16
|
+
/** Formats a per-format quality entry can name (the video formats take no quality). */
|
|
17
|
+
export type PerFormatQualityFormat = "jpeg" | "png" | "webp" | "jxl" | "avif" | "gif";
|
|
18
|
+
/** Per-format encoder options for the `format(...)` filter (issue #319). */
|
|
19
|
+
export interface FormatOptions {
|
|
20
|
+
/** JPEG: progressive (multi-scan) encoding. */
|
|
21
|
+
progressive?: boolean;
|
|
22
|
+
/** JPEG: chroma subsampling, 444, 422, or 420. */
|
|
23
|
+
subsampling?: 444 | 422 | 420;
|
|
24
|
+
/** PNG: Adam7 interlacing. */
|
|
25
|
+
interlace?: boolean;
|
|
26
|
+
/** WebP: libwebp compression method, 0..6. */
|
|
27
|
+
method?: number;
|
|
28
|
+
/** WebP: smart subsampling strength, 0..100. */
|
|
29
|
+
sns?: number;
|
|
30
|
+
}
|
|
16
31
|
/** Crop alignments; `center` is the bare `crop:WxH` spelling. */
|
|
17
32
|
export type CropAlign = "center" | "smart" | "face" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
|
|
18
33
|
/** Text-overlay anchor points. */
|
|
@@ -71,10 +86,24 @@ export declare const ops: {
|
|
|
71
86
|
fitIn(width: Dimension, height: Dimension, adaptive?: boolean): string;
|
|
72
87
|
/** `crop:300x200` or `crop:300x200:smart`; an exact pixel box. */
|
|
73
88
|
crop(width: number, height: number, align?: CropAlign): string;
|
|
89
|
+
/**
|
|
90
|
+
* `crop:300x200:objects(person,car):1.5`; crops to the
|
|
91
|
+
* union of every detection of the named classes, the
|
|
92
|
+
* union box scaled about its center by `scale` (1 is the
|
|
93
|
+
* tight box; the crop stays centered on the union).
|
|
94
|
+
* Needs a detection model configured on the server; when
|
|
95
|
+
* none of the classes is detected the render falls back
|
|
96
|
+
* to the plain center crop of the same size. Duplicate
|
|
97
|
+
* classes (case-insensitive) are spelled once, as the
|
|
98
|
+
* server's canonical form spells them.
|
|
99
|
+
*/
|
|
100
|
+
cropObjects(width: number, height: number, classes: string[], scale?: number): string;
|
|
74
101
|
/** `crop-rect:10x20:110x220` (left x top : right x bottom). */
|
|
75
102
|
cropRect(left: number, top: number, right: number, bottom: number): string;
|
|
76
103
|
/** `focal:10x20:110x220` (left x top : right x bottom); steers the next crop. */
|
|
77
104
|
focal(left: number, top: number, right: number, bottom: number): string;
|
|
105
|
+
/** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
|
|
106
|
+
focalPoint(x: number, y: number, zoom?: number): string;
|
|
78
107
|
/** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
|
|
79
108
|
pad(width: number, height: number, fill?: "blur" | string): string;
|
|
80
109
|
/** `preset:thumb`; expands server-side. */
|
|
@@ -107,6 +136,7 @@ export declare const filter: {
|
|
|
107
136
|
invert(): string;
|
|
108
137
|
noUpscale(): string;
|
|
109
138
|
equalize(): string;
|
|
139
|
+
enhance(): string;
|
|
110
140
|
removeBg(): string;
|
|
111
141
|
keepProfile(): string;
|
|
112
142
|
sepia(): string;
|
|
@@ -120,6 +150,14 @@ export declare const filter: {
|
|
|
120
150
|
brighten(amount: number): string;
|
|
121
151
|
/** Percent contrast: -100..100 (0 unchanged, -100 flat). */
|
|
122
152
|
contrast(percent: number): string;
|
|
153
|
+
/** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
|
|
154
|
+
gamma(value: number): string;
|
|
155
|
+
/** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
|
|
156
|
+
exposure(stops: number): string;
|
|
157
|
+
/** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
|
|
158
|
+
highlightsShadows(highlights: number, shadows: number): string;
|
|
159
|
+
/** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
|
|
160
|
+
vibrance(percent: number): string;
|
|
123
161
|
/** Rotate the hue by integer degrees. */
|
|
124
162
|
hueRotate(degrees: number): string;
|
|
125
163
|
/** Saturation factor: 0..255 (0 grayscale, 1 identity). */
|
|
@@ -161,9 +199,28 @@ export declare const filter: {
|
|
|
161
199
|
rotate(angle: number): string;
|
|
162
200
|
/** Trim uniform borders; tolerance 0..255, default 10. */
|
|
163
201
|
trim(tolerance?: number): string;
|
|
202
|
+
/** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
|
|
203
|
+
trimSides(tolerance: number, left: number, top: number, right: number, bottom: number): string;
|
|
164
204
|
/** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
|
|
165
205
|
quality(value: number | "auto"): string;
|
|
166
|
-
|
|
206
|
+
/**
|
|
207
|
+
* Per-format quality in one URL: a map of format to value
|
|
208
|
+
* (1..100 or "auto"), plus an optional fallback for
|
|
209
|
+
* formats with no entry. Resolved by the server after
|
|
210
|
+
* format negotiation; entries spell in canonical
|
|
211
|
+
* (format-name) order with the fallback first.
|
|
212
|
+
*/
|
|
213
|
+
qualityPerFormat(entries: Partial<Record<PerFormatQualityFormat, number | "auto">>, fallback?: number | "auto"): string;
|
|
214
|
+
/** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
|
|
215
|
+
palette(colors: number): string;
|
|
216
|
+
/**
|
|
217
|
+
* Output format, with its encoder options (issue #319):
|
|
218
|
+
* `progressive` and `subsampling` (444, 422, or 420) for
|
|
219
|
+
* JPEG, `interlace` for PNG, `method` (0..6) and `sns`
|
|
220
|
+
* (smart subsampling, 0..100) for WebP. An option its
|
|
221
|
+
* format cannot honour throws here, like the server's 400.
|
|
222
|
+
*/
|
|
223
|
+
format(format: ImageFormat, options?: FormatOptions): string;
|
|
167
224
|
/** The background color other operations pad with (RRGGBB). */
|
|
168
225
|
fill(color: string): string;
|
|
169
226
|
/** How much a face crop expands around the face: 0..3. */
|
package/dist/operations.js
CHANGED
|
@@ -11,6 +11,14 @@
|
|
|
11
11
|
* `buildSrcSet` does for widths: a value the server would 400
|
|
12
12
|
* never gets signed.
|
|
13
13
|
*/
|
|
14
|
+
const PER_FORMAT_QUALITY_FORMATS = [
|
|
15
|
+
"avif",
|
|
16
|
+
"gif",
|
|
17
|
+
"jpeg",
|
|
18
|
+
"jxl",
|
|
19
|
+
"png",
|
|
20
|
+
"webp",
|
|
21
|
+
];
|
|
14
22
|
const MAX_DIMENSION = 16383;
|
|
15
23
|
function fail(what, value, rule) {
|
|
16
24
|
throw new Error(`${what} must be ${rule}, got ${JSON.stringify(value)}`);
|
|
@@ -147,6 +155,37 @@ export const ops = {
|
|
|
147
155
|
const box = pixelBox("crop", width, height);
|
|
148
156
|
return align === "center" ? `crop:${box}` : `crop:${box}:${align}`;
|
|
149
157
|
},
|
|
158
|
+
/**
|
|
159
|
+
* `crop:300x200:objects(person,car):1.5`; crops to the
|
|
160
|
+
* union of every detection of the named classes, the
|
|
161
|
+
* union box scaled about its center by `scale` (1 is the
|
|
162
|
+
* tight box; the crop stays centered on the union).
|
|
163
|
+
* Needs a detection model configured on the server; when
|
|
164
|
+
* none of the classes is detected the render falls back
|
|
165
|
+
* to the plain center crop of the same size. Duplicate
|
|
166
|
+
* classes (case-insensitive) are spelled once, as the
|
|
167
|
+
* server's canonical form spells them.
|
|
168
|
+
*/
|
|
169
|
+
cropObjects(width, height, classes, scale = 1) {
|
|
170
|
+
if (!Array.isArray(classes) || classes.length < 1 || classes.length > 32) {
|
|
171
|
+
fail("crop objects classes", classes, "an array of 1 to 32 class names");
|
|
172
|
+
}
|
|
173
|
+
const seen = new Set();
|
|
174
|
+
const names = [];
|
|
175
|
+
for (const name of classes) {
|
|
176
|
+
const encoded = className("crop objects class", name);
|
|
177
|
+
const key = typeof name === "string" ? name.trim().toLowerCase() : "";
|
|
178
|
+
if (!seen.has(key)) {
|
|
179
|
+
seen.add(key);
|
|
180
|
+
names.push(encoded);
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
if (!Number.isFinite(scale) || scale <= 0 || scale > 100) {
|
|
184
|
+
fail("crop objects scale", scale, "a number above 0 and at most 100");
|
|
185
|
+
}
|
|
186
|
+
const box = pixelBox("crop", width, height);
|
|
187
|
+
return `crop:${box}:objects(${names.join(",")}):${num(scale)}`;
|
|
188
|
+
},
|
|
150
189
|
/** `crop-rect:10x20:110x220` (left x top : right x bottom). */
|
|
151
190
|
cropRect(left, top, right, bottom) {
|
|
152
191
|
intIn("crop-rect left", left, 0, 4294967295);
|
|
@@ -169,6 +208,19 @@ export const ops = {
|
|
|
169
208
|
}
|
|
170
209
|
return `focal:${left}x${top}:${right}x${bottom}`;
|
|
171
210
|
},
|
|
211
|
+
/** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
|
|
212
|
+
focalPoint(x, y, zoom = 1) {
|
|
213
|
+
const frac = (what, v) => {
|
|
214
|
+
if (!Number.isFinite(v) || v < 0 || v > 1) {
|
|
215
|
+
fail(what, v, "a fraction from 0 to 1");
|
|
216
|
+
}
|
|
217
|
+
return v;
|
|
218
|
+
};
|
|
219
|
+
if (!Number.isFinite(zoom) || zoom <= 0 || zoom > 100) {
|
|
220
|
+
fail("focalpoint zoom", zoom, "a number above 0 and at most 100");
|
|
221
|
+
}
|
|
222
|
+
return `focalpoint:${num(frac("focalpoint x", x))}x${num(frac("focalpoint y", y))}:${num(zoom)}`;
|
|
223
|
+
},
|
|
172
224
|
/** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
|
|
173
225
|
pad(width, height, fill) {
|
|
174
226
|
const box = pixelBox("pad", width, height);
|
|
@@ -236,6 +288,9 @@ export const filter = {
|
|
|
236
288
|
equalize() {
|
|
237
289
|
return "equalize";
|
|
238
290
|
},
|
|
291
|
+
enhance() {
|
|
292
|
+
return "enhance";
|
|
293
|
+
},
|
|
239
294
|
removeBg() {
|
|
240
295
|
return "removebg";
|
|
241
296
|
},
|
|
@@ -267,6 +322,28 @@ export const filter = {
|
|
|
267
322
|
contrast(percent) {
|
|
268
323
|
return `contrast(${num(floatIn("contrast", percent, -100, 100))})`;
|
|
269
324
|
},
|
|
325
|
+
/** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
|
|
326
|
+
gamma(value) {
|
|
327
|
+
if (!Number.isFinite(value) || value <= 0 || value > 10) {
|
|
328
|
+
fail("gamma", value, "a number above 0 and at most 10");
|
|
329
|
+
}
|
|
330
|
+
return `gamma(${num(value)})`;
|
|
331
|
+
},
|
|
332
|
+
/** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
|
|
333
|
+
exposure(stops) {
|
|
334
|
+
if (!Number.isFinite(stops) || stops < -10 || stops > 10) {
|
|
335
|
+
fail("exposure", stops, "a number between -10 and 10");
|
|
336
|
+
}
|
|
337
|
+
return `exposure(${num(stops)})`;
|
|
338
|
+
},
|
|
339
|
+
/** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
|
|
340
|
+
highlightsShadows(highlights, shadows) {
|
|
341
|
+
return `highlights_shadows(${num(floatIn("highlights_shadows highlights", highlights, -100, 100))},${num(floatIn("highlights_shadows shadows", shadows, -100, 100))})`;
|
|
342
|
+
},
|
|
343
|
+
/** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
|
|
344
|
+
vibrance(percent) {
|
|
345
|
+
return `vibrance(${num(floatIn("vibrance", percent, -100, 100))})`;
|
|
346
|
+
},
|
|
270
347
|
/** Rotate the hue by integer degrees. */
|
|
271
348
|
hueRotate(degrees) {
|
|
272
349
|
return `huerotate(${intIn("huerotate degrees", degrees, -2147483648, 2147483647)})`;
|
|
@@ -361,17 +438,98 @@ export const filter = {
|
|
|
361
438
|
trim(tolerance = 10) {
|
|
362
439
|
return `trim(${intIn("trim tolerance", tolerance, 0, 255)})`;
|
|
363
440
|
},
|
|
441
|
+
/** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
|
|
442
|
+
trimSides(tolerance, left, top, right, bottom) {
|
|
443
|
+
const side = (what, v) => intIn(what, v, 0, 4294967295);
|
|
444
|
+
return `trim(${intIn("trim tolerance", tolerance, 0, 255)},${side("trim left", left)},${side("trim top", top)},${side("trim right", right)},${side("trim bottom", bottom)})`;
|
|
445
|
+
},
|
|
364
446
|
/** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
|
|
365
447
|
quality(value) {
|
|
366
448
|
if (value === "auto")
|
|
367
449
|
return "quality(auto)";
|
|
368
450
|
return `quality(${intIn("quality", value, 1, 100)})`;
|
|
369
451
|
},
|
|
370
|
-
|
|
452
|
+
/**
|
|
453
|
+
* Per-format quality in one URL: a map of format to value
|
|
454
|
+
* (1..100 or "auto"), plus an optional fallback for
|
|
455
|
+
* formats with no entry. Resolved by the server after
|
|
456
|
+
* format negotiation; entries spell in canonical
|
|
457
|
+
* (format-name) order with the fallback first.
|
|
458
|
+
*/
|
|
459
|
+
qualityPerFormat(entries, fallback) {
|
|
460
|
+
const names = Object.keys(entries);
|
|
461
|
+
if (names.length === 0 && fallback === undefined) {
|
|
462
|
+
fail("quality", "{}", "at least one entry or a fallback");
|
|
463
|
+
}
|
|
464
|
+
const parts = [];
|
|
465
|
+
if (fallback !== undefined) {
|
|
466
|
+
parts.push(fallback === "auto" ? "auto" : String(intIn("quality", fallback, 1, 100)));
|
|
467
|
+
}
|
|
468
|
+
for (const name of names.sort()) {
|
|
469
|
+
if (!PER_FORMAT_QUALITY_FORMATS.includes(name)) {
|
|
470
|
+
fail("quality", name, `one of ${PER_FORMAT_QUALITY_FORMATS.join(", ")}`);
|
|
471
|
+
}
|
|
472
|
+
const value = entries[name];
|
|
473
|
+
parts.push(`${name}:${value === "auto" ? "auto" : intIn("quality", value, 1, 100)}`);
|
|
474
|
+
}
|
|
475
|
+
return `quality(${parts.join(",")})`;
|
|
476
|
+
},
|
|
477
|
+
/** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
|
|
478
|
+
palette(colors) {
|
|
479
|
+
return `palette(${intIn("palette colors", colors, 2, 256)})`;
|
|
480
|
+
},
|
|
481
|
+
/**
|
|
482
|
+
* Output format, with its encoder options (issue #319):
|
|
483
|
+
* `progressive` and `subsampling` (444, 422, or 420) for
|
|
484
|
+
* JPEG, `interlace` for PNG, `method` (0..6) and `sns`
|
|
485
|
+
* (smart subsampling, 0..100) for WebP. An option its
|
|
486
|
+
* format cannot honour throws here, like the server's 400.
|
|
487
|
+
*/
|
|
488
|
+
format(format, options = {}) {
|
|
371
489
|
if (!IMAGE_FORMATS.includes(format)) {
|
|
372
490
|
fail("format", format, `one of ${IMAGE_FORMATS.join(", ")}`);
|
|
373
491
|
}
|
|
374
|
-
|
|
492
|
+
const args = [format];
|
|
493
|
+
const used = (key) => options[key] !== undefined;
|
|
494
|
+
if (format === "jpeg" || format === "jpg") {
|
|
495
|
+
if (used("interlace") || used("method") || used("sns")) {
|
|
496
|
+
fail("format", JSON.stringify(options), "jpeg takes progressive and subsampling only");
|
|
497
|
+
}
|
|
498
|
+
if (options.progressive)
|
|
499
|
+
args.push("progressive");
|
|
500
|
+
if (options.subsampling !== undefined) {
|
|
501
|
+
if (![444, 422, 420].includes(options.subsampling)) {
|
|
502
|
+
fail("subsampling", options.subsampling, "one of 444, 422, 420");
|
|
503
|
+
}
|
|
504
|
+
args.push(`subsampling:${options.subsampling}`);
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
else if (format === "png") {
|
|
508
|
+
if (used("progressive") || used("subsampling") || used("method") || used("sns")) {
|
|
509
|
+
fail("format", JSON.stringify(options), "png takes interlace only");
|
|
510
|
+
}
|
|
511
|
+
if (options.interlace)
|
|
512
|
+
args.push("interlace");
|
|
513
|
+
}
|
|
514
|
+
else if (format === "webp") {
|
|
515
|
+
if (used("progressive") || used("subsampling") || used("interlace")) {
|
|
516
|
+
fail("format", JSON.stringify(options), "webp takes method and sns only");
|
|
517
|
+
}
|
|
518
|
+
if (options.method !== undefined) {
|
|
519
|
+
args.push(`method:${intIn("method", options.method, 0, 6)}`);
|
|
520
|
+
}
|
|
521
|
+
if (options.sns !== undefined) {
|
|
522
|
+
args.push(`sns:${intIn("sns", options.sns, 0, 100)}`);
|
|
523
|
+
}
|
|
524
|
+
}
|
|
525
|
+
else if (used("progressive") ||
|
|
526
|
+
used("subsampling") ||
|
|
527
|
+
used("interlace") ||
|
|
528
|
+
used("method") ||
|
|
529
|
+
used("sns")) {
|
|
530
|
+
fail("format", JSON.stringify(options), `${format} takes no encoder options`);
|
|
531
|
+
}
|
|
532
|
+
return `format(${args.join(",")})`;
|
|
375
533
|
},
|
|
376
534
|
/** The background color other operations pad with (RRGGBB). */
|
|
377
535
|
fill(color) {
|