@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 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
- format: "force the output format",
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
- return args === null || isIntIn(args, 0, 255) ? null : bad;
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
- return args === "auto" || (args !== null && isIntIn(args, 1, 100)) ? null : bad;
188
- case "format":
189
- return args !== null && FORMAT_NAMES.has(args) ? null : bad;
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, detected face boxes (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",
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
- if (!cropSize || !isExactBox(cropSize) || !ALIGN_NAMES.has(align)) {
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
- 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], pixels only, no flips)`,
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}` };
@@ -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
- format(format: ImageFormat): string;
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. */
@@ -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
- format(format) {
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
- return `format(${format})`;
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) {
package/package.json CHANGED
@@ -21,7 +21,7 @@
21
21
  "test": "node --test"
22
22
  },
23
23
  "type": "module",
24
- "version": "0.9.6",
24
+ "version": "0.9.8",
25
25
  "devDependencies": {
26
26
  "@types/node": "^26.6.5",
27
27
  "typescript": "^7.0.2"