@crabcrop/mcp 0.0.0-stage → 0.9.11
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/README.md +62 -2
- package/dist/index.js +424 -0
- package/node_modules/@crabcrop/url/README.md +97 -0
- package/node_modules/@crabcrop/url/dist/explain.d.ts +42 -0
- package/node_modules/@crabcrop/url/dist/explain.js +1050 -0
- package/node_modules/@crabcrop/url/dist/index.d.ts +161 -0
- package/node_modules/@crabcrop/url/dist/index.js +347 -0
- package/node_modules/@crabcrop/url/dist/operations.d.ts +285 -0
- package/node_modules/@crabcrop/url/dist/operations.js +722 -0
- package/node_modules/@crabcrop/url/package.json +31 -0
- package/package.json +48 -4
- package/server.json +1 -0
|
@@ -0,0 +1,722 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed builders for crabcrop operation strings (AP-24).
|
|
3
|
+
*
|
|
4
|
+
* `buildURL` takes operations verbatim, by design: the string
|
|
5
|
+
* is the spec. This module is the optional typed surface over
|
|
6
|
+
* it: each call validates its arguments against the server's
|
|
7
|
+
* grammar (the same bounds the explainer enforces) and returns
|
|
8
|
+
* the operation segment in its canonical spelling, so a typed
|
|
9
|
+
* pipeline and the equivalent hand-written string produce
|
|
10
|
+
* byte-identical URLs. Validation throws at build time, like
|
|
11
|
+
* `buildSrcSet` does for widths: a value the server would 400
|
|
12
|
+
* never gets signed.
|
|
13
|
+
*/
|
|
14
|
+
const PER_FORMAT_QUALITY_FORMATS = [
|
|
15
|
+
"avif",
|
|
16
|
+
"gif",
|
|
17
|
+
"jpeg",
|
|
18
|
+
"jxl",
|
|
19
|
+
"png",
|
|
20
|
+
"webp",
|
|
21
|
+
];
|
|
22
|
+
const MAX_DIMENSION = 16383;
|
|
23
|
+
function fail(what, value, rule) {
|
|
24
|
+
throw new Error(`${what} must be ${rule}, got ${JSON.stringify(value)}`);
|
|
25
|
+
}
|
|
26
|
+
function intIn(what, value, min, max) {
|
|
27
|
+
if (!Number.isSafeInteger(value) || value < min || value > max) {
|
|
28
|
+
fail(what, value, `an integer from ${min} to ${max}`);
|
|
29
|
+
}
|
|
30
|
+
return value;
|
|
31
|
+
}
|
|
32
|
+
function floatIn(what, value, min, max) {
|
|
33
|
+
if (!Number.isFinite(value) || value < min || value > max) {
|
|
34
|
+
fail(what, value, `a number from ${min} to ${max}`);
|
|
35
|
+
}
|
|
36
|
+
return value;
|
|
37
|
+
}
|
|
38
|
+
function positiveFloat(what, value) {
|
|
39
|
+
if (!Number.isFinite(value) || value <= 0) {
|
|
40
|
+
fail(what, value, "a positive number");
|
|
41
|
+
}
|
|
42
|
+
return value;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* The canonical number spelling: integers without a fraction,
|
|
46
|
+
* other values in plain decimal (the grammar takes no
|
|
47
|
+
* exponent forms). JavaScript's shortest round-trip spelling
|
|
48
|
+
* agrees with the server's for the magnitudes the grammar
|
|
49
|
+
* allows; exponent spellings are expanded to plain decimal.
|
|
50
|
+
*/
|
|
51
|
+
function num(value) {
|
|
52
|
+
if (Number.isSafeInteger(value))
|
|
53
|
+
return String(value);
|
|
54
|
+
const s = String(value);
|
|
55
|
+
if (!s.includes("e"))
|
|
56
|
+
return s;
|
|
57
|
+
return value
|
|
58
|
+
.toFixed(12)
|
|
59
|
+
.replace(/0+$/, "")
|
|
60
|
+
.replace(/\.$/, "");
|
|
61
|
+
}
|
|
62
|
+
function dimension(what, value) {
|
|
63
|
+
if (value === "orig")
|
|
64
|
+
return "orig";
|
|
65
|
+
if (!Number.isSafeInteger(value) || Math.abs(value) > MAX_DIMENSION) {
|
|
66
|
+
fail(what, value, `a pixel count up to ${MAX_DIMENSION}, 0, or "orig"`);
|
|
67
|
+
}
|
|
68
|
+
return String(value);
|
|
69
|
+
}
|
|
70
|
+
function pixelBox(what, width, height) {
|
|
71
|
+
intIn(`${what} width`, width, 1, MAX_DIMENSION);
|
|
72
|
+
intIn(`${what} height`, height, 1, MAX_DIMENSION);
|
|
73
|
+
return `${width}x${height}`;
|
|
74
|
+
}
|
|
75
|
+
function hex6(what, value) {
|
|
76
|
+
if (!/^[0-9a-fA-F]{6}$/.test(value)) {
|
|
77
|
+
fail(what, value, "six hex digits (RRGGBB)");
|
|
78
|
+
}
|
|
79
|
+
return value.toLowerCase();
|
|
80
|
+
}
|
|
81
|
+
function hex6or8(what, value) {
|
|
82
|
+
if (/^[0-9a-fA-F]{6}$/.test(value))
|
|
83
|
+
return `${value.toLowerCase()}ff`;
|
|
84
|
+
if (/^[0-9a-fA-F]{8}$/.test(value))
|
|
85
|
+
return value.toLowerCase();
|
|
86
|
+
return fail(what, value, "six or eight hex digits (RRGGBB or RRGGBBAA)");
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* The canonical percent-encoding for filter arguments that
|
|
90
|
+
* carry text (watermark and overlay URLs, class names, text
|
|
91
|
+
* labels): everything outside the RFC 3986 unreserved set is
|
|
92
|
+
* encoded, byte-wise, exactly as the server's canonical form
|
|
93
|
+
* spells it.
|
|
94
|
+
*/
|
|
95
|
+
function encodeArg(text) {
|
|
96
|
+
return encodeURIComponent(text).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
|
|
97
|
+
}
|
|
98
|
+
function className(what, name) {
|
|
99
|
+
const trimmed = name.trim();
|
|
100
|
+
// The server's bound is on UTF-8 bytes, not UTF-16 code
|
|
101
|
+
// units: a name of multibyte characters can pass a
|
|
102
|
+
// length check here and still be rejected there, so
|
|
103
|
+
// measure the encoded form, as the explainer does.
|
|
104
|
+
const bytes = new TextEncoder().encode(trimmed).length;
|
|
105
|
+
if (bytes < 1 || bytes > 64 || !/^[\p{L}\p{N} _.\-/]+$/u.test(trimmed)) {
|
|
106
|
+
fail(what, name, "1 to 64 UTF-8 bytes of letters, digits, space, `_`, `.`, `-`, `/`");
|
|
107
|
+
}
|
|
108
|
+
return encodeArg(name);
|
|
109
|
+
}
|
|
110
|
+
const CROP_ALIGNS = ["center", "smart", "face", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"];
|
|
111
|
+
const ANCHORS = [
|
|
112
|
+
"top-left",
|
|
113
|
+
"top-center",
|
|
114
|
+
"top-right",
|
|
115
|
+
"center-left",
|
|
116
|
+
"center",
|
|
117
|
+
"center-right",
|
|
118
|
+
"bottom-left",
|
|
119
|
+
"bottom-center",
|
|
120
|
+
"bottom-right",
|
|
121
|
+
];
|
|
122
|
+
const BLEND_MODES = ["normal", "multiply", "screen", "overlay"];
|
|
123
|
+
const CURVE_CHANNELS = ["rgb", "r", "g", "b"];
|
|
124
|
+
const STUDIO_MODES = ["product", "scene"];
|
|
125
|
+
const STUDIO_SHADOWS = ["soft", "strong", "none"];
|
|
126
|
+
const IMAGE_FORMATS = ["jpeg", "jpg", "png", "webp", "jxl", "avif", "gif", "mp4", "webm"];
|
|
127
|
+
/** Operation segments, one typed call per segment kind. */
|
|
128
|
+
export const ops = {
|
|
129
|
+
/** `300x200`; each side a Dimension (0 proportional, negative flips). */
|
|
130
|
+
size(width, height) {
|
|
131
|
+
return `${dimension("width", width)}x${dimension("height", height)}`;
|
|
132
|
+
},
|
|
133
|
+
/**
|
|
134
|
+
* `fit-in:300x200`; no flips (the server rejects them here).
|
|
135
|
+
* With `adaptive`, `fit-in:300x200:adaptive`: the box axes
|
|
136
|
+
* swap when the source orientation disagrees with the box's.
|
|
137
|
+
*/
|
|
138
|
+
fitIn(width, height, adaptive = false) {
|
|
139
|
+
for (const [what, v] of [
|
|
140
|
+
["width", width],
|
|
141
|
+
["height", height],
|
|
142
|
+
]) {
|
|
143
|
+
if (typeof v === "number" && v < 0) {
|
|
144
|
+
fail(`fit-in ${what}`, v, "not a flip: fit-in takes no negative sizes");
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
const base = `fit-in:${dimension("width", width)}x${dimension("height", height)}`;
|
|
148
|
+
return adaptive ? `${base}:adaptive` : base;
|
|
149
|
+
},
|
|
150
|
+
/** `crop:300x200` or `crop:300x200:smart`; an exact pixel box. */
|
|
151
|
+
crop(width, height, align = "center") {
|
|
152
|
+
if (!CROP_ALIGNS.includes(align)) {
|
|
153
|
+
fail("crop align", align, `one of ${CROP_ALIGNS.join(", ")}`);
|
|
154
|
+
}
|
|
155
|
+
const box = pixelBox("crop", width, height);
|
|
156
|
+
return align === "center" ? `crop:${box}` : `crop:${box}:${align}`;
|
|
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; at most 32
|
|
168
|
+
* distinct classes, and a 33rd throws, since the server
|
|
169
|
+
* rejects it with `invalid_crop`.
|
|
170
|
+
*/
|
|
171
|
+
cropObjects(width, height, classes, scale = 1) {
|
|
172
|
+
if (!Array.isArray(classes) || classes.length < 1) {
|
|
173
|
+
fail("crop objects classes", classes, "an array of 1 to 32 distinct class names");
|
|
174
|
+
}
|
|
175
|
+
// The cap counts distinct names, as the server's parser
|
|
176
|
+
// does (issue #408): repeats fold first and cost nothing.
|
|
177
|
+
const seen = new Set();
|
|
178
|
+
const names = [];
|
|
179
|
+
for (const name of classes) {
|
|
180
|
+
const encoded = className("crop objects class", name);
|
|
181
|
+
const key = typeof name === "string" ? name.trim().toLowerCase() : "";
|
|
182
|
+
if (!seen.has(key)) {
|
|
183
|
+
if (names.length === 32) {
|
|
184
|
+
fail("crop objects classes", classes, "an array of 1 to 32 distinct class names");
|
|
185
|
+
}
|
|
186
|
+
seen.add(key);
|
|
187
|
+
names.push(encoded);
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
if (!Number.isFinite(scale) || scale <= 0 || scale > 100) {
|
|
191
|
+
fail("crop objects scale", scale, "a number above 0 and at most 100");
|
|
192
|
+
}
|
|
193
|
+
const box = pixelBox("crop", width, height);
|
|
194
|
+
return `crop:${box}:objects(${names.join(",")}):${num(scale)}`;
|
|
195
|
+
},
|
|
196
|
+
/** `crop-rect:10x20:110x220` (left x top : right x bottom). */
|
|
197
|
+
cropRect(left, top, right, bottom) {
|
|
198
|
+
intIn("crop-rect left", left, 0, 4294967295);
|
|
199
|
+
intIn("crop-rect top", top, 0, 4294967295);
|
|
200
|
+
intIn("crop-rect right", right, 0, 4294967295);
|
|
201
|
+
intIn("crop-rect bottom", bottom, 0, 4294967295);
|
|
202
|
+
if (right <= left || bottom <= top) {
|
|
203
|
+
fail("crop-rect", `${left}x${top}:${right}x${bottom}`, "right > left and bottom > top");
|
|
204
|
+
}
|
|
205
|
+
return `crop-rect:${left}x${top}:${right}x${bottom}`;
|
|
206
|
+
},
|
|
207
|
+
/** `focal:10x20:110x220` (left x top : right x bottom); steers the next crop. */
|
|
208
|
+
focal(left, top, right, bottom) {
|
|
209
|
+
intIn("focal left", left, 0, 4294967295);
|
|
210
|
+
intIn("focal top", top, 0, 4294967295);
|
|
211
|
+
intIn("focal right", right, 0, 4294967295);
|
|
212
|
+
intIn("focal bottom", bottom, 0, 4294967295);
|
|
213
|
+
if (right <= left || bottom <= top) {
|
|
214
|
+
fail("focal", `${left}x${top}:${right}x${bottom}`, "right > left and bottom > top");
|
|
215
|
+
}
|
|
216
|
+
return `focal:${left}x${top}:${right}x${bottom}`;
|
|
217
|
+
},
|
|
218
|
+
/** `focalpoint:0.75x0.4:2` (fractions of the image dimensions, zoom optional); steers the next crop. */
|
|
219
|
+
focalPoint(x, y, zoom = 1) {
|
|
220
|
+
const frac = (what, v) => {
|
|
221
|
+
if (!Number.isFinite(v) || v < 0 || v > 1) {
|
|
222
|
+
fail(what, v, "a fraction from 0 to 1");
|
|
223
|
+
}
|
|
224
|
+
return v;
|
|
225
|
+
};
|
|
226
|
+
if (!Number.isFinite(zoom) || zoom <= 0 || zoom > 100) {
|
|
227
|
+
fail("focalpoint zoom", zoom, "a number above 0 and at most 100");
|
|
228
|
+
}
|
|
229
|
+
return `focalpoint:${num(frac("focalpoint x", x))}x${num(frac("focalpoint y", y))}:${num(zoom)}`;
|
|
230
|
+
},
|
|
231
|
+
/** `pad:300x200`, optionally `:blur` or a RRGGBB fill color. */
|
|
232
|
+
pad(width, height, fill) {
|
|
233
|
+
const box = pixelBox("pad", width, height);
|
|
234
|
+
if (fill === undefined)
|
|
235
|
+
return `pad:${box}`;
|
|
236
|
+
if (fill === "blur")
|
|
237
|
+
return `pad:${box}:blur`;
|
|
238
|
+
return `pad:${box}:${hex6("pad fill", fill)}`;
|
|
239
|
+
},
|
|
240
|
+
/** `preset:thumb`; expands server-side. */
|
|
241
|
+
preset(name) {
|
|
242
|
+
// The server can only configure names from this
|
|
243
|
+
// charset (its preset file validation), so anything
|
|
244
|
+
// outside it is a reference that can only ever answer
|
|
245
|
+
// unknown_preset; refuse it here instead.
|
|
246
|
+
if (!/^[A-Za-z0-9_-]+$/.test(name)) {
|
|
247
|
+
fail("preset name", name, "letters, digits, `_`, `-` (the server's preset name charset)");
|
|
248
|
+
}
|
|
249
|
+
return `preset:${name}`;
|
|
250
|
+
},
|
|
251
|
+
/**
|
|
252
|
+
* `maxage:60`; this response's Cache-Control lifetime in
|
|
253
|
+
* seconds (0 to 31536000), overriding the default year for
|
|
254
|
+
* this request only. Header-only: it never enters the
|
|
255
|
+
* cache key, so spellings that differ only here share one
|
|
256
|
+
* stored image.
|
|
257
|
+
*/
|
|
258
|
+
maxage(seconds) {
|
|
259
|
+
return `maxage:${intIn("maxage seconds", seconds, 0, 31536000)}`;
|
|
260
|
+
},
|
|
261
|
+
/**
|
|
262
|
+
* `debug:focal`; the smart-crop debug view. Place it
|
|
263
|
+
* before the crop it annotates: the response is a
|
|
264
|
+
* diagnostic image of the focal decision (focal point,
|
|
265
|
+
* focal rectangle, crop window drawn on the crop's
|
|
266
|
+
* canvas), never the transform result, and it is never
|
|
267
|
+
* cached (served with Cache-Control: no-store).
|
|
268
|
+
*/
|
|
269
|
+
debugFocal() {
|
|
270
|
+
return "debug:focal";
|
|
271
|
+
},
|
|
272
|
+
/** Join filter calls into one `filters:` segment. */
|
|
273
|
+
filters(...calls) {
|
|
274
|
+
if (calls.length === 0) {
|
|
275
|
+
fail("filters", calls, "at least one filter call");
|
|
276
|
+
}
|
|
277
|
+
return `filters:${calls.join(":")}`;
|
|
278
|
+
},
|
|
279
|
+
};
|
|
280
|
+
/** Join operation segments into the operations string `buildURL` takes. */
|
|
281
|
+
export function joinOps(...segments) {
|
|
282
|
+
return segments.join("/");
|
|
283
|
+
}
|
|
284
|
+
/** Filter calls for `ops.filters(...)`; each returns its canonical spelling. */
|
|
285
|
+
export const filter = {
|
|
286
|
+
grayscale() {
|
|
287
|
+
return "grayscale";
|
|
288
|
+
},
|
|
289
|
+
invert() {
|
|
290
|
+
return "invert";
|
|
291
|
+
},
|
|
292
|
+
noUpscale() {
|
|
293
|
+
return "no_upscale";
|
|
294
|
+
},
|
|
295
|
+
equalize() {
|
|
296
|
+
return "equalize";
|
|
297
|
+
},
|
|
298
|
+
enhance() {
|
|
299
|
+
return "enhance";
|
|
300
|
+
},
|
|
301
|
+
removeBg() {
|
|
302
|
+
return "removebg";
|
|
303
|
+
},
|
|
304
|
+
keepProfile() {
|
|
305
|
+
return "keep_profile";
|
|
306
|
+
},
|
|
307
|
+
sepia() {
|
|
308
|
+
return "sepia";
|
|
309
|
+
},
|
|
310
|
+
blurFaces() {
|
|
311
|
+
return "blurfaces";
|
|
312
|
+
},
|
|
313
|
+
pixelateFaces() {
|
|
314
|
+
return "pixelatefaces";
|
|
315
|
+
},
|
|
316
|
+
/** Gaussian blur by sigma: positive, at most the server's 512 cap. */
|
|
317
|
+
blur(sigma) {
|
|
318
|
+
if (!Number.isFinite(sigma) || sigma <= 0 || sigma > 512) {
|
|
319
|
+
fail("blur sigma", sigma, "a positive number up to 512");
|
|
320
|
+
}
|
|
321
|
+
return `blur(${num(sigma)})`;
|
|
322
|
+
},
|
|
323
|
+
/** Unsharp-mask strength (positive). */
|
|
324
|
+
sharpen(amount) {
|
|
325
|
+
return `sharpen(${num(positiveFloat("sharpen amount", amount))})`;
|
|
326
|
+
},
|
|
327
|
+
/** Add to every channel: -255..255. */
|
|
328
|
+
brighten(amount) {
|
|
329
|
+
return `brighten(${intIn("brighten amount", amount, -255, 255)})`;
|
|
330
|
+
},
|
|
331
|
+
/** Percent contrast: -100..100 (0 unchanged, -100 flat). */
|
|
332
|
+
contrast(percent) {
|
|
333
|
+
return `contrast(${num(floatIn("contrast", percent, -100, 100))})`;
|
|
334
|
+
},
|
|
335
|
+
/** Gamma correction divisor: 0 < g <= 10 (1 unchanged; above 1 brightens midtones). */
|
|
336
|
+
gamma(value) {
|
|
337
|
+
if (!Number.isFinite(value) || value <= 0 || value > 10) {
|
|
338
|
+
fail("gamma", value, "a number above 0 and at most 10");
|
|
339
|
+
}
|
|
340
|
+
return `gamma(${num(value)})`;
|
|
341
|
+
},
|
|
342
|
+
/** Exposure in stops: -10..10 (0 unchanged; +1 doubles the light, -1 halves it). */
|
|
343
|
+
exposure(stops) {
|
|
344
|
+
if (!Number.isFinite(stops) || stops < -10 || stops > 10) {
|
|
345
|
+
fail("exposure", stops, "a number between -10 and 10");
|
|
346
|
+
}
|
|
347
|
+
return `exposure(${num(stops)})`;
|
|
348
|
+
},
|
|
349
|
+
/** Highlights and shadows: two percents, each -100..100 (0 unchanged). */
|
|
350
|
+
highlightsShadows(highlights, shadows) {
|
|
351
|
+
return `highlights_shadows(${num(floatIn("highlights_shadows highlights", highlights, -100, 100))},${num(floatIn("highlights_shadows shadows", shadows, -100, 100))})`;
|
|
352
|
+
},
|
|
353
|
+
/** Vibrance percent: -100..100 (0 unchanged; muted colors move most, vivid colors are protected). */
|
|
354
|
+
vibrance(percent) {
|
|
355
|
+
return `vibrance(${num(floatIn("vibrance", percent, -100, 100))})`;
|
|
356
|
+
},
|
|
357
|
+
/** Rotate the hue by integer degrees. */
|
|
358
|
+
hueRotate(degrees) {
|
|
359
|
+
return `huerotate(${intIn("huerotate degrees", degrees, -2147483648, 2147483647)})`;
|
|
360
|
+
},
|
|
361
|
+
/** Saturation factor: 0..255 (0 grayscale, 1 identity). */
|
|
362
|
+
saturation(factor) {
|
|
363
|
+
return `saturation(${num(floatIn("saturation", factor, 0, 255))})`;
|
|
364
|
+
},
|
|
365
|
+
/** Per-channel offsets, each -255..255. */
|
|
366
|
+
rgb(r, g, b) {
|
|
367
|
+
return `rgb(${intIn("rgb red", r, -255, 255)},${intIn("rgb green", g, -255, 255)},${intIn("rgb blue", b, -255, 255)})`;
|
|
368
|
+
},
|
|
369
|
+
/**
|
|
370
|
+
* Tone curve: remap the channel through 2 to 16 [x, y]
|
|
371
|
+
* control points, each coordinate 0..255 with x strictly
|
|
372
|
+
* increasing. Between points the server interpolates
|
|
373
|
+
* linearly; inputs outside the point range clamp to the
|
|
374
|
+
* nearest end value.
|
|
375
|
+
*/
|
|
376
|
+
curve(channel, points) {
|
|
377
|
+
if (!CURVE_CHANNELS.includes(channel)) {
|
|
378
|
+
fail("curve channel", channel, `one of ${CURVE_CHANNELS.join(", ")}`);
|
|
379
|
+
}
|
|
380
|
+
if (points.length < 2 || points.length > 16) {
|
|
381
|
+
fail("curve points", points, "2 to 16 control points");
|
|
382
|
+
}
|
|
383
|
+
const flat = [];
|
|
384
|
+
let prevX = -1;
|
|
385
|
+
for (const [x, y] of points) {
|
|
386
|
+
intIn("curve point x", x, 0, 255);
|
|
387
|
+
intIn("curve point y", y, 0, 255);
|
|
388
|
+
if (x <= prevX) {
|
|
389
|
+
fail("curve points", points, "control points with strictly increasing x");
|
|
390
|
+
}
|
|
391
|
+
prevX = x;
|
|
392
|
+
flat.push(x, y);
|
|
393
|
+
}
|
|
394
|
+
return `curve(${channel},${flat.join(",")})`;
|
|
395
|
+
},
|
|
396
|
+
/**
|
|
397
|
+
* Convolution: apply a caller-supplied kernel, 9 values
|
|
398
|
+
* (3x3) or 25 (5x5) in row-major order, each a plain
|
|
399
|
+
* decimal from -1024 to 1024. With normalize set the
|
|
400
|
+
* server scales the kernel by the sum of its entries
|
|
401
|
+
* first (a zero sum applies the kernel as written). The
|
|
402
|
+
* edges replicate. `normalize` is a boolean or the 0/1
|
|
403
|
+
* flag itself.
|
|
404
|
+
*/
|
|
405
|
+
convolution(values, normalize = false) {
|
|
406
|
+
if (values.length !== 9 && values.length !== 25) {
|
|
407
|
+
fail("convolution kernel", values, "9 (3x3) or 25 (5x5) values");
|
|
408
|
+
}
|
|
409
|
+
for (const v of values) {
|
|
410
|
+
floatIn("convolution kernel value", v, -1024, 1024);
|
|
411
|
+
if (!/^-?\d+(\.\d+)?$/.test(num(v))) {
|
|
412
|
+
fail("convolution kernel value", v, "a plain decimal (the grammar takes no exponent forms)");
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
if (normalize !== true &&
|
|
416
|
+
normalize !== false &&
|
|
417
|
+
normalize !== 0 &&
|
|
418
|
+
normalize !== 1) {
|
|
419
|
+
fail("convolution normalize", normalize, "a boolean or 0/1");
|
|
420
|
+
}
|
|
421
|
+
const flag = normalize === true || normalize === 1 ? 1 : 0;
|
|
422
|
+
return `convolution(${values.map(num).join(",")},${flag})`;
|
|
423
|
+
},
|
|
424
|
+
/**
|
|
425
|
+
* Film grain: one noise value per pixel, added equally
|
|
426
|
+
* to all three channels (alpha untouched), the value
|
|
427
|
+
* uniform in plus or minus the given percent of full
|
|
428
|
+
* scale. The field is deterministic, seeded from the
|
|
429
|
+
* image content and the amount, so the same request
|
|
430
|
+
* always renders the same bytes; 0 is a no-op.
|
|
431
|
+
*/
|
|
432
|
+
noise(amount) {
|
|
433
|
+
return `noise(${intIn("noise amount", amount, 0, 100)})`;
|
|
434
|
+
},
|
|
435
|
+
/**
|
|
436
|
+
* Rotate by an angle in degrees (decimals allowed, no
|
|
437
|
+
* exponent spelling); multiples of 90 are exact quarter
|
|
438
|
+
* turns on the server.
|
|
439
|
+
*/
|
|
440
|
+
rotate(angle) {
|
|
441
|
+
floatIn("rotate angle", angle, -36000, 36000);
|
|
442
|
+
if (!/^-?\d+(\.\d+)?$/.test(num(angle))) {
|
|
443
|
+
fail("rotate angle", angle, "a plain decimal angle (the grammar takes no exponent forms)");
|
|
444
|
+
}
|
|
445
|
+
return `rotate(${num(angle)})`;
|
|
446
|
+
},
|
|
447
|
+
/** Trim uniform borders; tolerance 0..255, default 10. */
|
|
448
|
+
trim(tolerance = 10) {
|
|
449
|
+
return `trim(${intIn("trim tolerance", tolerance, 0, 255)})`;
|
|
450
|
+
},
|
|
451
|
+
/** Trim uniform borders, then remove pixels per side (left, top, right, bottom). */
|
|
452
|
+
trimSides(tolerance, left, top, right, bottom) {
|
|
453
|
+
const side = (what, v) => intIn(what, v, 0, 4294967295);
|
|
454
|
+
return `trim(${intIn("trim tolerance", tolerance, 0, 255)},${side("trim left", left)},${side("trim top", top)},${side("trim right", right)},${side("trim bottom", bottom)})`;
|
|
455
|
+
},
|
|
456
|
+
/** Encoding quality 1..100, or `"auto"` for perceptual targeting. */
|
|
457
|
+
quality(value) {
|
|
458
|
+
if (value === "auto")
|
|
459
|
+
return "quality(auto)";
|
|
460
|
+
return `quality(${intIn("quality", value, 1, 100)})`;
|
|
461
|
+
},
|
|
462
|
+
/**
|
|
463
|
+
* Per-format quality in one URL: a map of format to value
|
|
464
|
+
* (1..100 or "auto"), plus an optional fallback for
|
|
465
|
+
* formats with no entry. Resolved by the server after
|
|
466
|
+
* format negotiation; entries spell in canonical
|
|
467
|
+
* (format-name) order with the fallback first.
|
|
468
|
+
*/
|
|
469
|
+
qualityPerFormat(entries, fallback) {
|
|
470
|
+
const names = Object.keys(entries);
|
|
471
|
+
if (names.length === 0 && fallback === undefined) {
|
|
472
|
+
fail("quality", "{}", "at least one entry or a fallback");
|
|
473
|
+
}
|
|
474
|
+
const parts = [];
|
|
475
|
+
if (fallback !== undefined) {
|
|
476
|
+
parts.push(fallback === "auto" ? "auto" : String(intIn("quality", fallback, 1, 100)));
|
|
477
|
+
}
|
|
478
|
+
for (const name of names.sort()) {
|
|
479
|
+
if (!PER_FORMAT_QUALITY_FORMATS.includes(name)) {
|
|
480
|
+
fail("quality", name, `one of ${PER_FORMAT_QUALITY_FORMATS.join(", ")}`);
|
|
481
|
+
}
|
|
482
|
+
const value = entries[name];
|
|
483
|
+
parts.push(`${name}:${value === "auto" ? "auto" : intIn("quality", value, 1, 100)}`);
|
|
484
|
+
}
|
|
485
|
+
return `quality(${parts.join(",")})`;
|
|
486
|
+
},
|
|
487
|
+
/** Indexed PNG output with at most this many colors, 2..256; other formats ignore it. */
|
|
488
|
+
palette(colors) {
|
|
489
|
+
return `palette(${intIn("palette colors", colors, 2, 256)})`;
|
|
490
|
+
},
|
|
491
|
+
/**
|
|
492
|
+
* Output format, with its encoder options (issue #319):
|
|
493
|
+
* `progressive` and `subsampling` (444, 422, or 420) for
|
|
494
|
+
* JPEG, `interlace` for PNG, `method` (0..6) and `sns`
|
|
495
|
+
* (smart subsampling, 0..100) for WebP. An option its
|
|
496
|
+
* format cannot honour throws here, like the server's 400.
|
|
497
|
+
*/
|
|
498
|
+
format(format, options = {}) {
|
|
499
|
+
if (!IMAGE_FORMATS.includes(format)) {
|
|
500
|
+
fail("format", format, `one of ${IMAGE_FORMATS.join(", ")}`);
|
|
501
|
+
}
|
|
502
|
+
// The output segment is the canonical spelling: the
|
|
503
|
+
// `jpg` input alias spells as `jpeg`, like the server's
|
|
504
|
+
// canonical form.
|
|
505
|
+
const canonical = format === "jpg" ? "jpeg" : format;
|
|
506
|
+
const args = [canonical];
|
|
507
|
+
const used = (key) => options[key] !== undefined;
|
|
508
|
+
if (format === "jpeg" || format === "jpg") {
|
|
509
|
+
if (used("interlace") || used("method") || used("sns")) {
|
|
510
|
+
fail("format", JSON.stringify(options), "jpeg takes progressive and subsampling only");
|
|
511
|
+
}
|
|
512
|
+
if (options.progressive)
|
|
513
|
+
args.push("progressive");
|
|
514
|
+
if (options.subsampling !== undefined) {
|
|
515
|
+
if (![444, 422, 420].includes(options.subsampling)) {
|
|
516
|
+
fail("subsampling", options.subsampling, "one of 444, 422, 420");
|
|
517
|
+
}
|
|
518
|
+
args.push(`subsampling:${options.subsampling}`);
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
else if (format === "png") {
|
|
522
|
+
if (used("progressive") || used("subsampling") || used("method") || used("sns")) {
|
|
523
|
+
fail("format", JSON.stringify(options), "png takes interlace only");
|
|
524
|
+
}
|
|
525
|
+
if (options.interlace)
|
|
526
|
+
args.push("interlace");
|
|
527
|
+
}
|
|
528
|
+
else if (format === "webp") {
|
|
529
|
+
if (used("progressive") || used("subsampling") || used("interlace")) {
|
|
530
|
+
fail("format", JSON.stringify(options), "webp takes method and sns only");
|
|
531
|
+
}
|
|
532
|
+
if (options.method !== undefined) {
|
|
533
|
+
args.push(`method:${intIn("method", options.method, 0, 6)}`);
|
|
534
|
+
}
|
|
535
|
+
if (options.sns !== undefined) {
|
|
536
|
+
args.push(`sns:${intIn("sns", options.sns, 0, 100)}`);
|
|
537
|
+
}
|
|
538
|
+
}
|
|
539
|
+
else if (used("progressive") ||
|
|
540
|
+
used("subsampling") ||
|
|
541
|
+
used("interlace") ||
|
|
542
|
+
used("method") ||
|
|
543
|
+
used("sns")) {
|
|
544
|
+
fail("format", JSON.stringify(options), `${format} takes no encoder options`);
|
|
545
|
+
}
|
|
546
|
+
return `format(${args.join(",")})`;
|
|
547
|
+
},
|
|
548
|
+
/** The background color other operations pad with (RRGGBB). */
|
|
549
|
+
fill(color) {
|
|
550
|
+
return `fill(${hex6("fill color", color)})`;
|
|
551
|
+
},
|
|
552
|
+
/** How much a face crop expands around the face: 0..3. */
|
|
553
|
+
facePad(amount) {
|
|
554
|
+
return `facepad(${num(floatIn("facepad", amount, 0, 3))})`;
|
|
555
|
+
},
|
|
556
|
+
/**
|
|
557
|
+
* Studio mode: `studio(product)` composites the subject
|
|
558
|
+
* the server's segmentation model finds onto a backdrop
|
|
559
|
+
* with a synthesized contact shadow, scaled and centered
|
|
560
|
+
* to the pad margin; `studio(scene)` keeps the
|
|
561
|
+
* photograph's scene, reframing it on the detected
|
|
562
|
+
* subject and correcting light and color. See
|
|
563
|
+
* {@link StudioOptions} for the named arguments.
|
|
564
|
+
* Arguments spelled at their defaults (shadow `soft`,
|
|
565
|
+
* pad 10) are omitted, matching the server's canonical
|
|
566
|
+
* spelling, so `studio("product", { pad: 10 })` and
|
|
567
|
+
* `studio("product")` are the same string.
|
|
568
|
+
*/
|
|
569
|
+
studio(mode, options = {}) {
|
|
570
|
+
if (!STUDIO_MODES.includes(mode)) {
|
|
571
|
+
fail("studio mode", mode, `one of ${STUDIO_MODES.join(", ")}`);
|
|
572
|
+
}
|
|
573
|
+
const { bg, shadow, pad } = options;
|
|
574
|
+
if (mode === "scene" && (bg !== undefined || shadow !== undefined)) {
|
|
575
|
+
fail("studio scene options", options, "pad only: bg and shadow are product arguments");
|
|
576
|
+
}
|
|
577
|
+
const parts = [mode];
|
|
578
|
+
if (mode === "product") {
|
|
579
|
+
if (bg !== undefined) {
|
|
580
|
+
const value = bg === "white" || bg === "brand" || bg === "none" ? bg : hex6("studio bg", bg);
|
|
581
|
+
parts.push(`bg:${value}`);
|
|
582
|
+
}
|
|
583
|
+
if (shadow !== undefined) {
|
|
584
|
+
if (!STUDIO_SHADOWS.includes(shadow)) {
|
|
585
|
+
fail("studio shadow", shadow, `one of ${STUDIO_SHADOWS.join(", ")}`);
|
|
586
|
+
}
|
|
587
|
+
if (shadow !== "soft")
|
|
588
|
+
parts.push(`shadow:${shadow}`);
|
|
589
|
+
}
|
|
590
|
+
}
|
|
591
|
+
if (pad !== undefined) {
|
|
592
|
+
intIn("studio pad", pad, 0, 40);
|
|
593
|
+
if (pad !== 10)
|
|
594
|
+
parts.push(`pad:${pad}`);
|
|
595
|
+
}
|
|
596
|
+
return `studio(${parts.join(",")})`;
|
|
597
|
+
},
|
|
598
|
+
/** AI upscale by the given factor. */
|
|
599
|
+
upscale(factor) {
|
|
600
|
+
if (factor !== 2 && factor !== 4) {
|
|
601
|
+
fail("upscale factor", factor, "2 or 4");
|
|
602
|
+
}
|
|
603
|
+
return `upscale(${factor})`;
|
|
604
|
+
},
|
|
605
|
+
/** Device pixel ratio the sizes are multiplied by. */
|
|
606
|
+
dpr(factor) {
|
|
607
|
+
if (![1, 1.5, 2, 3].includes(factor)) {
|
|
608
|
+
fail("dpr", factor, "1, 1.5, 2, or 3");
|
|
609
|
+
}
|
|
610
|
+
return `dpr(${num(factor)})`;
|
|
611
|
+
},
|
|
612
|
+
/** Cap the output bytes, lowering quality to fit: at least 1. */
|
|
613
|
+
maxBytes(bytes) {
|
|
614
|
+
if (!Number.isSafeInteger(bytes) || bytes < 1) {
|
|
615
|
+
fail("max_bytes", bytes, "a positive integer byte budget");
|
|
616
|
+
}
|
|
617
|
+
return `max_bytes(${bytes})`;
|
|
618
|
+
},
|
|
619
|
+
/** Round the corners: one radius for all, or [tl, tr, br, bl]. */
|
|
620
|
+
radius(value) {
|
|
621
|
+
const corners = Array.isArray(value) ? value : [value, value, value, value];
|
|
622
|
+
for (const c of corners)
|
|
623
|
+
intIn("radius", c, 0, MAX_DIMENSION);
|
|
624
|
+
return `radius(${corners.join(",")})`;
|
|
625
|
+
},
|
|
626
|
+
/** Paint an opaque border inside the frame (RRGGBB); a width of 0 is a no-op. */
|
|
627
|
+
border(width, color) {
|
|
628
|
+
return `border(${intIn("border width", width, 0, MAX_DIMENSION)},${hex6("border color", color)})`;
|
|
629
|
+
},
|
|
630
|
+
mask(shape) {
|
|
631
|
+
if (shape !== "circle" && shape !== "ellipse") {
|
|
632
|
+
fail("mask shape", shape, '"circle" or "ellipse"');
|
|
633
|
+
}
|
|
634
|
+
return `mask(${shape})`;
|
|
635
|
+
},
|
|
636
|
+
duotone(shadow, highlight) {
|
|
637
|
+
return `duotone(${hex6("duotone shadow", shadow)},${hex6("duotone highlight", highlight)})`;
|
|
638
|
+
},
|
|
639
|
+
monochrome(color) {
|
|
640
|
+
return `monochrome(${hex6("monochrome color", color)})`;
|
|
641
|
+
},
|
|
642
|
+
/** Mosaic block size in pixels: 1..16383. */
|
|
643
|
+
pixelate(blockSize) {
|
|
644
|
+
return `pixelate(${intIn("pixelate size", blockSize, 1, MAX_DIMENSION)})`;
|
|
645
|
+
},
|
|
646
|
+
flip(axis) {
|
|
647
|
+
if (axis !== "h" && axis !== "v") {
|
|
648
|
+
fail("flip axis", axis, '"h" or "v"');
|
|
649
|
+
}
|
|
650
|
+
return `flip(${axis})`;
|
|
651
|
+
},
|
|
652
|
+
/** Overlay a watermark image at (x, y), opacity 0..100. */
|
|
653
|
+
watermark(url, x, y, alpha) {
|
|
654
|
+
intIn("watermark x", x, -2147483648, 2147483647);
|
|
655
|
+
intIn("watermark y", y, -2147483648, 2147483647);
|
|
656
|
+
intIn("watermark alpha", alpha, 0, 100);
|
|
657
|
+
if (url === "")
|
|
658
|
+
fail("watermark url", url, "a non-empty URL");
|
|
659
|
+
return `watermark(${encodeArg(url)},${x},${y},${alpha})`;
|
|
660
|
+
},
|
|
661
|
+
/**
|
|
662
|
+
* Composite another image over the result at (x, y) with
|
|
663
|
+
* opacity 0..100 and a blend mode; `widthPct` optionally
|
|
664
|
+
* scales it to that percent of the base width (1..400).
|
|
665
|
+
*/
|
|
666
|
+
overlay(url, x, y, alpha, blend, widthPct) {
|
|
667
|
+
intIn("overlay x", x, -2147483648, 2147483647);
|
|
668
|
+
intIn("overlay y", y, -2147483648, 2147483647);
|
|
669
|
+
intIn("overlay alpha", alpha, 0, 100);
|
|
670
|
+
if (!BLEND_MODES.includes(blend)) {
|
|
671
|
+
fail("overlay blend", blend, `one of ${BLEND_MODES.join(", ")}`);
|
|
672
|
+
}
|
|
673
|
+
if (url === "")
|
|
674
|
+
fail("overlay url", url, "a non-empty URL");
|
|
675
|
+
const width = widthPct === undefined ? "" : `,${intIn("overlay width", widthPct, 1, 400)}`;
|
|
676
|
+
return `overlay(${encodeArg(url)},${x},${y},${alpha},${blend}${width})`;
|
|
677
|
+
},
|
|
678
|
+
/**
|
|
679
|
+
* Draw a text overlay. Color is RRGGBB or RRGGBBAA; the
|
|
680
|
+
* canonical spelling is always eight lowercase hex digits.
|
|
681
|
+
*/
|
|
682
|
+
text(content, size, color, anchor) {
|
|
683
|
+
if (!ANCHORS.includes(anchor)) {
|
|
684
|
+
fail("text anchor", anchor, `one of ${ANCHORS.join(", ")}`);
|
|
685
|
+
}
|
|
686
|
+
if (content === "")
|
|
687
|
+
fail("text", content, "a non-empty label");
|
|
688
|
+
intIn("text size", size, 1, 1000);
|
|
689
|
+
return `text(${encodeArg(content)},${size},${hex6or8("text color", color)},${anchor})`;
|
|
690
|
+
},
|
|
691
|
+
/** Blur every detected object of the named class. */
|
|
692
|
+
blurClass(name) {
|
|
693
|
+
return `blurclass(${className("blurclass name", name)})`;
|
|
694
|
+
},
|
|
695
|
+
/** Pixelate every detected object of the named class. */
|
|
696
|
+
pixelateClass(name) {
|
|
697
|
+
return `pixelateclass(${className("pixelateclass name", name)})`;
|
|
698
|
+
},
|
|
699
|
+
/** Recolor every detected object of the named class to the given RRGGBB color. */
|
|
700
|
+
recolorClass(name, color) {
|
|
701
|
+
return `recolorclass(${className("recolorclass name", name)},${hex6("recolorclass color", color)})`;
|
|
702
|
+
},
|
|
703
|
+
/** Blur the rectangle (x, y, w, h) in pixels. */
|
|
704
|
+
blurRegion(x, y, w, h) {
|
|
705
|
+
return `blur_region(${region(x, y, w, h)})`;
|
|
706
|
+
},
|
|
707
|
+
/** Pixelate the rectangle (x, y, w, h) in pixels. */
|
|
708
|
+
pixelateRegion(x, y, w, h) {
|
|
709
|
+
return `pixelate_region(${region(x, y, w, h)})`;
|
|
710
|
+
},
|
|
711
|
+
/** Erase the rectangle (x, y, w, h) in pixels and inpaint it (AI). */
|
|
712
|
+
removeRegion(x, y, w, h) {
|
|
713
|
+
return `remove_region(${region(x, y, w, h)})`;
|
|
714
|
+
},
|
|
715
|
+
};
|
|
716
|
+
function region(x, y, w, h) {
|
|
717
|
+
intIn("region x", x, 0, MAX_DIMENSION);
|
|
718
|
+
intIn("region y", y, 0, MAX_DIMENSION);
|
|
719
|
+
intIn("region width", w, 1, MAX_DIMENSION);
|
|
720
|
+
intIn("region height", h, 1, MAX_DIMENSION);
|
|
721
|
+
return `${x},${y},${w},${h}`;
|
|
722
|
+
}
|