@hussmartinez/image-sdk 0.0.0-stage → 0.2.0
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/LICENSE +202 -0
- package/README.md +68 -2
- package/dist/assets/image/render.worker.js +1 -0
- package/dist/element.d.ts +1152 -0
- package/dist/element.js +129 -0
- package/dist/element.js.map +1 -0
- package/dist/index.d.ts +1729 -0
- package/dist/index.js +157 -0
- package/dist/index.js.map +1 -0
- package/dist/lazy/inline-worker-Cvw0Gpxf.js +30 -0
- package/dist/lazy/inline-worker-Cvw0Gpxf.js.map +1 -0
- package/dist/react.d.ts +1530 -0
- package/dist/react.js +2 -0
- package/dist/shared/core-CAX3GOaj.js +1444 -0
- package/dist/shared/core-CAX3GOaj.js.map +1 -0
- package/dist/shared/editor-DziYqEP3.js +1748 -0
- package/dist/shared/editor-DziYqEP3.js.map +1 -0
- package/dist/styles.css +399 -0
- package/formats/hm-image-command/v1.schema.json +102 -0
- package/formats/hm-image-plan/v1.schema.json +328 -0
- package/package.json +117 -3
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,1729 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Headless core of the image SDK: contracts, errors, the document session,
|
|
3
|
+
* operations and the image engine, whose worker loads only on its first call.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* This entry is server-safe: it has no React and touches no DOM on import, so
|
|
7
|
+
* Server Components and Node can import it (ADR 0004, ADR 0007).
|
|
8
|
+
*
|
|
9
|
+
* @packageDocumentation
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { FilePolicy } from '@hussmartinez/sdk-core';
|
|
13
|
+
import { FilePolicyOverrides } from '@hussmartinez/sdk-core';
|
|
14
|
+
import { Limits } from '@hussmartinez/sdk-core';
|
|
15
|
+
import type { Reducer } from '@hussmartinez/sdk-core';
|
|
16
|
+
import { SdkCoreErrorCode } from '@hussmartinez/sdk-core';
|
|
17
|
+
import { SdkError } from '@hussmartinez/sdk-core';
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* The crop panel's presets, landscape then portrait (docs/adr/0007).
|
|
21
|
+
*
|
|
22
|
+
* @public
|
|
23
|
+
*/
|
|
24
|
+
export declare const ASPECT_PRESETS: readonly ImageAspect[];
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The ratio of an aspect, width over height, or `undefined` for free.
|
|
28
|
+
*
|
|
29
|
+
* @public
|
|
30
|
+
*/
|
|
31
|
+
export declare function aspectRatio(aspect: ImageAspect, source: ImageSize): number | undefined;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The size of the preview canvas's backing store for a view: its size times
|
|
35
|
+
* its pixel ratio, at most {@link MAX_PIXEL_RATIO}, in whole pixels.
|
|
36
|
+
*
|
|
37
|
+
* @public
|
|
38
|
+
*/
|
|
39
|
+
export declare function backingSize(view: ImageView): {
|
|
40
|
+
readonly width: number;
|
|
41
|
+
readonly height: number;
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Checks one probed file against a policy's per-file limits, in the order
|
|
46
|
+
* of {@link PER_FILE_LIMITS}, and throws the first violation as an
|
|
47
|
+
* `ImageError` with the limit's code (ADR 0004). Returns the limits whose
|
|
48
|
+
* warning threshold the file reaches.
|
|
49
|
+
*
|
|
50
|
+
* @public
|
|
51
|
+
*/
|
|
52
|
+
export declare function checkFileLimits(policy: ImageFilePolicy, fileSize: number, probe: ImageProbe): ImageLimitName[];
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Checks an export's output size against a policy before its canvas is
|
|
56
|
+
* allocated, and throws the first violation as an `ImageError` with the
|
|
57
|
+
* limit's code (ADR 0004).
|
|
58
|
+
*
|
|
59
|
+
* @public
|
|
60
|
+
*/
|
|
61
|
+
export declare function checkOutputLimits(policy: ImageFilePolicy, size: {
|
|
62
|
+
readonly width: number;
|
|
63
|
+
readonly height: number;
|
|
64
|
+
}): void;
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* A distance in the composition of the whole source, as a distance in the
|
|
68
|
+
* oriented source: what a pointer drag on the stage moves the crop by.
|
|
69
|
+
*
|
|
70
|
+
* @public
|
|
71
|
+
*/
|
|
72
|
+
export declare function compositionDeltaToSource(dx: number, dy: number, orientation: ImageOrientation_2, source: ImageSize): {
|
|
73
|
+
readonly dx: number;
|
|
74
|
+
readonly dy: number;
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* The size of the composition: the cropped source, turned by the plan's own
|
|
79
|
+
* rotation (ADR 0003).
|
|
80
|
+
*
|
|
81
|
+
* @public
|
|
82
|
+
*/
|
|
83
|
+
export declare function compositionSize(plan: ImagePlan, source: ImageSize): ImageSize;
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* The inverse of {@link sourceToComposition}: maps a point in the
|
|
87
|
+
* composition, such as the pointer, back to the source.
|
|
88
|
+
*
|
|
89
|
+
* @public
|
|
90
|
+
*/
|
|
91
|
+
export declare function compositionToSource(point: ImagePoint, crop: ImageCrop, orientation: ImageOrientation_2): ImagePoint;
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Creates the SDK's image engine (docs/adr/0001, docs/adr/0002,
|
|
95
|
+
* docs/adr/0005). It probes files in its render worker with the SDK's own
|
|
96
|
+
* readers, and decodes them there with `createImageBitmap`, upright: where
|
|
97
|
+
* the browser doesn't apply a format's orientation, as its one-time
|
|
98
|
+
* calibration shows, the worker applies it itself. Every decode must have
|
|
99
|
+
* the probe's oriented size exactly. The worker holds the sources until
|
|
100
|
+
* they're released or the engine is destroyed.
|
|
101
|
+
*
|
|
102
|
+
* Nothing starts until the first call. By default the worker is inlined,
|
|
103
|
+
* which needs `worker-src blob:` in a Content Security Policy; with
|
|
104
|
+
* `assetsUrl` it loads from your own origin, which needs `worker-src 'self'`
|
|
105
|
+
* instead. Either way it makes no requests of its own.
|
|
106
|
+
*
|
|
107
|
+
* @example
|
|
108
|
+
* ```ts
|
|
109
|
+
* const engine = createImageEngine();
|
|
110
|
+
* const probe = await engine.probe(file);
|
|
111
|
+
* policy.check("maxImagePixels", probe.oriented.width * probe.oriented.height);
|
|
112
|
+
* const source = await engine.register("photo", file, probe);
|
|
113
|
+
* ```
|
|
114
|
+
*
|
|
115
|
+
* @public
|
|
116
|
+
*/
|
|
117
|
+
export declare function createImageEngine(options?: ImageEngineOptions): ImageEngine;
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Creates the SDK's image processor over an engine from
|
|
121
|
+
* {@link createImageEngine}, sharing its render worker, where the sources
|
|
122
|
+
* are (docs/adr/0002). An export renders the plan at its output size in an
|
|
123
|
+
* sRGB canvas, after checking that size against the file policy, encodes
|
|
124
|
+
* it with the browser's encoder, and keeps nothing of the result but the
|
|
125
|
+
* image data and the fields the user kept: title, description, artist and
|
|
126
|
+
* copyright, as EXIF in JPEG and `iTXt` in PNG. WebP exports carry no
|
|
127
|
+
* metadata. The encoded type is checked: a browser that can't encode the
|
|
128
|
+
* requested format fails with `UNSUPPORTED_FORMAT` (docs/adr/0001,
|
|
129
|
+
* docs/adr/0005).
|
|
130
|
+
*
|
|
131
|
+
* @example
|
|
132
|
+
* ```ts
|
|
133
|
+
* const engine = createImageEngine();
|
|
134
|
+
* const processor = createImageProcessor(engine);
|
|
135
|
+
* const blob = await processor.export({ plan, format: { type: "jpeg", quality: 0.9 } });
|
|
136
|
+
* ```
|
|
137
|
+
*
|
|
138
|
+
* @throws `TypeError` for an engine that `createImageEngine` didn't make.
|
|
139
|
+
* @public
|
|
140
|
+
*/
|
|
141
|
+
export declare function createImageProcessor(engine: ImageEngine): ImageProcessor;
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Creates the reducer for {@link ImageCommand}s: a pure function that
|
|
145
|
+
* applies one command and returns the command that undoes it (ADR 0003,
|
|
146
|
+
* ADR 0029). It needs the oriented size of each source, to check crops.
|
|
147
|
+
*
|
|
148
|
+
* Commands are strict, as the `hm-image-command` schema is (sdk-core ADR
|
|
149
|
+
* 0045): an invalid command, including one with a field its type doesn't
|
|
150
|
+
* have, throws `ImageError` with `INVALID_COMMAND` and an
|
|
151
|
+
* {@link ImageCommandRejection} as `details.reason`. The reducer never
|
|
152
|
+
* silently corrects one.
|
|
153
|
+
*
|
|
154
|
+
* @public
|
|
155
|
+
*/
|
|
156
|
+
export declare function createImageReducer(sourceSize: (id: string) => ImageSize | undefined): Reducer<ImagePlan, ImageCommand>;
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Creates the SDK's preview renderer over an engine from
|
|
160
|
+
* `createImageEngine`, sharing its render worker, where the sources are
|
|
161
|
+
* (docs/adr/0002). The canvas is transferred to the worker once, and every
|
|
162
|
+
* frame is drawn there by the same renderer as the export.
|
|
163
|
+
*
|
|
164
|
+
* Renders are coalesced, latest first: while one is being drawn, newer
|
|
165
|
+
* calls replace the waiting one, which resolves `superseded`, and the one
|
|
166
|
+
* being drawn is cancelled at its next strip. So a slider drag that sends
|
|
167
|
+
* many plans ends with one final render of the last.
|
|
168
|
+
*
|
|
169
|
+
* @example
|
|
170
|
+
* ```ts
|
|
171
|
+
* const renderer = createImageRenderer(engine);
|
|
172
|
+
* await renderer.attach(canvas);
|
|
173
|
+
* await renderer.render(plan, fittedView(stage.clientWidth, stage.clientHeight, devicePixelRatio));
|
|
174
|
+
* ```
|
|
175
|
+
*
|
|
176
|
+
* @throws `TypeError` for an engine that `createImageEngine` didn't make.
|
|
177
|
+
* @public
|
|
178
|
+
*/
|
|
179
|
+
export declare function createImageRenderer(engine: ImageEngine): ImageRenderer;
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* Creates an {@link ImageSession} (ADR 0003): its store and history are
|
|
183
|
+
* sdk-core's (ADR 0029), its reducer is {@link createImageReducer}, and it
|
|
184
|
+
* reaches files only through its engine and processor.
|
|
185
|
+
*
|
|
186
|
+
* @example
|
|
187
|
+
* ```ts
|
|
188
|
+
* const engine = createImageEngine();
|
|
189
|
+
* const session = createImageSession({ engine, processor: createImageProcessor(engine) });
|
|
190
|
+
* await session.open(file);
|
|
191
|
+
* session.execute({ type: "image.setDevelop", values: { exposure: 20 } });
|
|
192
|
+
* const { blob, removed } = await session.export({ type: "jpeg", quality: 0.9 });
|
|
193
|
+
* ```
|
|
194
|
+
*
|
|
195
|
+
* @public
|
|
196
|
+
*/
|
|
197
|
+
export declare function createImageSession(options: ImageSessionOptions): ImageSession;
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* The plan for a newly opened source: the whole image, upright, undeveloped
|
|
201
|
+
* and unfiltered, at full size, keeping no metadata.
|
|
202
|
+
*
|
|
203
|
+
* @public
|
|
204
|
+
*/
|
|
205
|
+
export declare function createPlan(source: string): ImagePlan;
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* The edges a handle moves: `n`, `s`, `e` and `w`, and the corners that
|
|
209
|
+
* combine two.
|
|
210
|
+
*
|
|
211
|
+
* @public
|
|
212
|
+
*/
|
|
213
|
+
export declare type CropHandle = "n" | "s" | "e" | "w" | "ne" | "nw" | "se" | "sw";
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Where a crop of the oriented source appears in the composition of the
|
|
217
|
+
* whole source under an orientation: an axis-aligned rectangle, since the
|
|
218
|
+
* plan turns in quarter turns.
|
|
219
|
+
*
|
|
220
|
+
* @public
|
|
221
|
+
*/
|
|
222
|
+
export declare function cropInComposition(crop: ImageCrop, orientation: ImageOrientation_2, source: ImageSize): ImageCrop;
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* The cropped area of a source, or the whole source when there's no crop.
|
|
226
|
+
*
|
|
227
|
+
* @public
|
|
228
|
+
*/
|
|
229
|
+
export declare function cropRect(crop: ImageCrop | null, source: ImageSize): ImageCrop;
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* The names of the develop adjustments, in the order they're applied.
|
|
233
|
+
*
|
|
234
|
+
* @public
|
|
235
|
+
*/
|
|
236
|
+
export declare const DEVELOP_ADJUSTMENTS: readonly ["temperature", "tint", "exposure", "highlights", "shadows", "contrast", "saturation", "vibrance"];
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* A crop with a handle dragged by a distance in source pixels, kept inside
|
|
240
|
+
* the source and at least 1 × 1, in whole pixels. With a ratio, the opposite
|
|
241
|
+
* edge or corner stays put and the other side follows the ratio.
|
|
242
|
+
*
|
|
243
|
+
* @public
|
|
244
|
+
*/
|
|
245
|
+
export declare function dragHandle(crop: ImageCrop, handle: CropHandle, dx: number, dy: number, source: ImageSize, ratio?: number): ImageCrop;
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* Keepable metadata with every field empty.
|
|
249
|
+
*
|
|
250
|
+
* @public
|
|
251
|
+
*/
|
|
252
|
+
export declare const EMPTY_KEEPABLE_METADATA: ImageKeepableMetadata;
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* An EXIF orientation, 1 to 8: how the stored pixels must be turned to be
|
|
256
|
+
* upright. 1 means they already are (ADR 0005).
|
|
257
|
+
*
|
|
258
|
+
* @public
|
|
259
|
+
*/
|
|
260
|
+
export declare type ExifOrientation = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* The filter presets (ADR 0006). Names are part of the document format:
|
|
264
|
+
* presets are only ever added.
|
|
265
|
+
*
|
|
266
|
+
* @public
|
|
267
|
+
*/
|
|
268
|
+
export declare const FILTER_PRESETS: readonly ["vivid", "warm", "cool", "fade", "mono", "noir", "sepia"];
|
|
269
|
+
|
|
270
|
+
/**
|
|
271
|
+
* The largest crop of a ratio inside `within`, centred in it, in whole
|
|
272
|
+
* pixels and at least 1 × 1. With no ratio, `within` as it is.
|
|
273
|
+
*
|
|
274
|
+
* @public
|
|
275
|
+
*/
|
|
276
|
+
export declare function fitAspect(within: ImageCrop, ratio: number | undefined): ImageCrop;
|
|
277
|
+
|
|
278
|
+
/**
|
|
279
|
+
* The view for a stage of this size: fitted, centred, at this ratio.
|
|
280
|
+
*
|
|
281
|
+
* @public
|
|
282
|
+
*/
|
|
283
|
+
export declare function fittedView(width: number, height: number, pixelRatio?: number): ImageView;
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* The export at full size.
|
|
287
|
+
*
|
|
288
|
+
* @public
|
|
289
|
+
*/
|
|
290
|
+
export declare const FULL_SIZE: ImageOutput;
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* Which source edges a handle on screen moves, under an orientation: the
|
|
294
|
+
* handle's compass point in the composition, mapped back to the source.
|
|
295
|
+
*
|
|
296
|
+
* @public
|
|
297
|
+
*/
|
|
298
|
+
export declare function handleInSource(handle: CropHandle, orientation: ImageOrientation_2): CropHandle;
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* The name of the plan's portable format (sdk-core ADR 0045).
|
|
302
|
+
*
|
|
303
|
+
* @public
|
|
304
|
+
*/
|
|
305
|
+
export declare const IMAGE_PLAN_FORMAT = "hm-image-plan";
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* The version of {@link IMAGE_PLAN_FORMAT} this release writes, and the
|
|
309
|
+
* latest it reads.
|
|
310
|
+
*
|
|
311
|
+
* @public
|
|
312
|
+
*/
|
|
313
|
+
export declare const IMAGE_PLAN_VERSION = 1;
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* The crop frame's geometry (docs/adr/0007): pure functions over crops in
|
|
317
|
+
* whole pixels of the oriented source, which the editor's frame, keys and
|
|
318
|
+
* fields share, so every way of cropping gives the same result.
|
|
319
|
+
*/
|
|
320
|
+
/**
|
|
321
|
+
* An aspect ratio the crop panel offers: free, the source's own, or width
|
|
322
|
+
* over height.
|
|
323
|
+
*
|
|
324
|
+
* @public
|
|
325
|
+
*/
|
|
326
|
+
export declare type ImageAspect = "free" | "original" | readonly [number, number];
|
|
327
|
+
|
|
328
|
+
/**
|
|
329
|
+
* A content-addressed reference to binary data, such as a source's file
|
|
330
|
+
* (sdk-core ADR 0045). Documents never inline bytes.
|
|
331
|
+
*
|
|
332
|
+
* @public
|
|
333
|
+
*/
|
|
334
|
+
export declare interface ImageAssetReference {
|
|
335
|
+
/** `sha256:` and the lowercase hex SHA-256 of the bytes. */
|
|
336
|
+
readonly asset: string;
|
|
337
|
+
/** The bytes' media type, such as `image/jpeg`, in lowercase. */
|
|
338
|
+
readonly mediaType: string;
|
|
339
|
+
/** The size of the bytes. */
|
|
340
|
+
readonly size: number;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* The image being edited: a source, its crop and orientation, and its
|
|
345
|
+
* develop adjustments and filter.
|
|
346
|
+
*
|
|
347
|
+
* @public
|
|
348
|
+
*/
|
|
349
|
+
export declare interface ImageBase {
|
|
350
|
+
/** The id of a registered source. */
|
|
351
|
+
readonly source: string;
|
|
352
|
+
/** The crop, or `null` for the whole image. */
|
|
353
|
+
readonly crop: ImageCrop | null;
|
|
354
|
+
readonly orientation: ImageOrientation_2;
|
|
355
|
+
readonly develop: ImageDevelop;
|
|
356
|
+
/** The filter, or `null` for none. */
|
|
357
|
+
readonly filter: ImageFilter | null;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* Options every port call accepts.
|
|
362
|
+
*
|
|
363
|
+
* @public
|
|
364
|
+
*/
|
|
365
|
+
export declare interface ImageCallOptions {
|
|
366
|
+
/**
|
|
367
|
+
* Cancels the call. It then rejects with an `ImageError` whose code is
|
|
368
|
+
* `ABORTED`, `TIMEOUT`, or the code of an `SdkError` given as the abort
|
|
369
|
+
* reason, such as `PROCESSING_TIME_EXCEEDED`.
|
|
370
|
+
*/
|
|
371
|
+
readonly signal?: AbortSignal;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* Every edit to an {@link ImagePlan}: plain, structured-cloneable data
|
|
376
|
+
* (ADR 0003). Feature pull requests add their own commands to this union.
|
|
377
|
+
*
|
|
378
|
+
* @public
|
|
379
|
+
*/
|
|
380
|
+
export declare type ImageCommand = SetCropCommand | SetOrientationCommand | SetOutputCommand | SetMetadataCommand | SetDevelopCommand | SetFilterCommand;
|
|
381
|
+
|
|
382
|
+
/**
|
|
383
|
+
* Why a command was refused, as a stable token: `details.reason` on the
|
|
384
|
+
* `INVALID_COMMAND` error (sdk-core ADR 0045).
|
|
385
|
+
*
|
|
386
|
+
* - `malformed-command`: not shaped as the `hm-image-command` schema says,
|
|
387
|
+
* such as a missing field, a field of the wrong type, an unknown field, or
|
|
388
|
+
* a crop that isn't whole pixels of at least 1 × 1.
|
|
389
|
+
* - `unknown-command`: a `type` the reducer doesn't know.
|
|
390
|
+
* - `unknown-source`: a crop for a plan whose source isn't registered.
|
|
391
|
+
* - `crop-outside-source`: a crop that doesn't fit inside its source.
|
|
392
|
+
* - `invalid-orientation`: a rotation other than 0, 90, 180 or 270.
|
|
393
|
+
* - `invalid-output`: a scale outside (0, 1], or a box under 1 pixel.
|
|
394
|
+
* - `unknown-metadata-field`: a field other than title, description, artist
|
|
395
|
+
* and copyright.
|
|
396
|
+
* - `metadata-too-long`: a value over `MAX_METADATA_LENGTH` code points.
|
|
397
|
+
* - `unknown-adjustment`: a develop value that isn't an adjustment.
|
|
398
|
+
* - `invalid-level`: a develop value that isn't a whole number from -100 to 100.
|
|
399
|
+
* - `unknown-preset`: a filter that isn't one of `FILTER_PRESETS`.
|
|
400
|
+
* - `invalid-strength`: a filter strength that isn't a whole number from 0 to 100.
|
|
401
|
+
*
|
|
402
|
+
* @public
|
|
403
|
+
*/
|
|
404
|
+
export declare type ImageCommandRejection = "malformed-command" | "unknown-command" | "unknown-source" | "crop-outside-source" | "invalid-orientation" | "invalid-output" | "unknown-metadata-field" | "metadata-too-long" | "unknown-adjustment" | "invalid-level" | "unknown-preset" | "invalid-strength";
|
|
405
|
+
|
|
406
|
+
/**
|
|
407
|
+
* A rectangle in whole pixels of the oriented source: `x` and `y` from its
|
|
408
|
+
* top left, `width` and `height` at least 1 (ADR 0003).
|
|
409
|
+
*
|
|
410
|
+
* @public
|
|
411
|
+
*/
|
|
412
|
+
export declare interface ImageCrop {
|
|
413
|
+
readonly x: number;
|
|
414
|
+
readonly y: number;
|
|
415
|
+
readonly width: number;
|
|
416
|
+
readonly height: number;
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* The base's tonal and colour adjustments (ADR 0006). Each is an integer
|
|
421
|
+
* from -100 to 100, where 0 is unchanged, applied in this order.
|
|
422
|
+
*
|
|
423
|
+
* @public
|
|
424
|
+
*/
|
|
425
|
+
export declare interface ImageDevelop {
|
|
426
|
+
/** Warmer (positive) or cooler (negative). */
|
|
427
|
+
readonly temperature: number;
|
|
428
|
+
/** Toward magenta (positive) or green (negative). */
|
|
429
|
+
readonly tint: number;
|
|
430
|
+
/** In fiftieths of a stop: 100 is two stops brighter. */
|
|
431
|
+
readonly exposure: number;
|
|
432
|
+
readonly highlights: number;
|
|
433
|
+
readonly shadows: number;
|
|
434
|
+
readonly contrast: number;
|
|
435
|
+
readonly saturation: number;
|
|
436
|
+
/** Saturation weighted toward the least saturated colours. */
|
|
437
|
+
readonly vibrance: number;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Why a plan document was refused, as a stable token: `details.reason` on
|
|
442
|
+
* the error (sdk-core ADR 0045).
|
|
443
|
+
*
|
|
444
|
+
* - With `UNSUPPORTED_FORMAT`: `unknown-format`, a document of another
|
|
445
|
+
* format, and `unknown-format-version`, a later version than this release
|
|
446
|
+
* reads.
|
|
447
|
+
* - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
|
|
448
|
+
* shaped as the schema says; `unknown-source`, a base whose source the
|
|
449
|
+
* document doesn't list; and, as for commands, `crop-outside-source`,
|
|
450
|
+
* `invalid-orientation`, `invalid-output`, `metadata-too-long`,
|
|
451
|
+
* `unknown-adjustment`, `invalid-level`, `unknown-preset` and
|
|
452
|
+
* `invalid-strength`.
|
|
453
|
+
*
|
|
454
|
+
* @public
|
|
455
|
+
*/
|
|
456
|
+
export declare type ImageDocumentRejection = "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "crop-outside-source" | "invalid-orientation" | "invalid-output" | "metadata-too-long" | "unknown-adjustment" | "invalid-level" | "unknown-preset" | "invalid-strength";
|
|
457
|
+
|
|
458
|
+
/**
|
|
459
|
+
* The port for reading images: probe a file's headers, decode it into a
|
|
460
|
+
* source the engine holds, make thumbnails and release sources (ADR 0001,
|
|
461
|
+
* ADR 0002, ADR 0003, ADR 0008). The SDK's own adapter probes with its own
|
|
462
|
+
* readers and decodes with `createImageBitmap`, both in its render worker;
|
|
463
|
+
* hosts can pass their own to the editor's `engine` prop, and every
|
|
464
|
+
* implementation must pass the engine's contract tests.
|
|
465
|
+
*
|
|
466
|
+
* `register` checks a file's own limits, from `filePolicy`, against the
|
|
467
|
+
* engine's own probe before decoding it, so a host can't decode past them by
|
|
468
|
+
* passing a probe of another file. Session-wide limits, such as
|
|
469
|
+
* `maxSessionSize`, are the session's (ADR 0004).
|
|
470
|
+
*
|
|
471
|
+
* Failures reject with `ImageError`: `INVALID_IMAGE` for a malformed file,
|
|
472
|
+
* one whose headers claim more than its data holds, or one whose decoded
|
|
473
|
+
* size differs from the probe's; `UNSUPPORTED_FORMAT` for one the probe
|
|
474
|
+
* can't bound; `DECODE_FAILED` when the browser can't decode it; and
|
|
475
|
+
* sdk-core's codes for cancellation and worker failures.
|
|
476
|
+
*
|
|
477
|
+
* @public
|
|
478
|
+
*/
|
|
479
|
+
export declare interface ImageEngine {
|
|
480
|
+
/** Reads a file's headers and metadata, without decoding it. */
|
|
481
|
+
probe(file: Blob, options?: ImageCallOptions): Promise<ImageProbe>;
|
|
482
|
+
/**
|
|
483
|
+
* Decodes a probed file into a source with the given id, upright. The
|
|
484
|
+
* decoded size must equal the probe's oriented size, or the call rejects
|
|
485
|
+
* with `INVALID_IMAGE` and keeps nothing. A file over one of
|
|
486
|
+
* `filePolicy`'s per-file limits rejects with that limit's code, before
|
|
487
|
+
* anything decodes it. An id already in use is a
|
|
488
|
+
* `TypeError`.
|
|
489
|
+
*/
|
|
490
|
+
register(id: string, file: Blob, probe: ImageProbe, options?: ImageRegisterOptions): Promise<ImageSourceInfo>;
|
|
491
|
+
/**
|
|
492
|
+
* A rendering of a source that fits inside `maxSize` × `maxSize`, keeping
|
|
493
|
+
* its aspect ratio and never enlarging it. An unknown id is a `TypeError`.
|
|
494
|
+
*/
|
|
495
|
+
thumbnail(id: string, maxSize: number, options?: ImageCallOptions): Promise<ImageThumbnail>;
|
|
496
|
+
/** Frees a source's pixels. Releasing an unknown id does nothing. */
|
|
497
|
+
release(id: string): Promise<void>;
|
|
498
|
+
/** Releases the engine, its sources and its worker. Pending calls reject, and later calls throw. */
|
|
499
|
+
destroy(): Promise<void>;
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
/**
|
|
503
|
+
* Options for {@link createImageEngine}.
|
|
504
|
+
*
|
|
505
|
+
* @public
|
|
506
|
+
*/
|
|
507
|
+
export declare interface ImageEngineOptions {
|
|
508
|
+
/**
|
|
509
|
+
* Where the application serves the package's `dist/assets/` directory, to
|
|
510
|
+
* load the render worker from its own origin instead of a `blob:` URL. The
|
|
511
|
+
* worker is then `image/render.worker.js` there, and a Content Security
|
|
512
|
+
* Policy needs `worker-src 'self'` and no `blob:` (docs/adr/0002). Copy
|
|
513
|
+
* `dist/assets` again after every upgrade: a worker from another version
|
|
514
|
+
* is refused with `WORKER_START_FAILED`. By default the worker is inlined.
|
|
515
|
+
*/
|
|
516
|
+
readonly assetsUrl?: string | URL;
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
/**
|
|
520
|
+
* The error `@hussmartinez/image-sdk` throws and rejects with, with a stable
|
|
521
|
+
* `code`, structured `details` and the underlying error as `cause`. Show
|
|
522
|
+
* users the text for its code from {@link imageMessages}, never its
|
|
523
|
+
* `message`, which is for developers and may contain text from the file.
|
|
524
|
+
*
|
|
525
|
+
* @example
|
|
526
|
+
* ```ts
|
|
527
|
+
* try {
|
|
528
|
+
* await session.open(file);
|
|
529
|
+
* } catch (error) {
|
|
530
|
+
* if (isImageError(error, "DECODE_FAILED")) {
|
|
531
|
+
* suggestConvertingToPng();
|
|
532
|
+
* } else {
|
|
533
|
+
* show(messages.error(error));
|
|
534
|
+
* }
|
|
535
|
+
* }
|
|
536
|
+
* ```
|
|
537
|
+
*
|
|
538
|
+
* @public
|
|
539
|
+
*/
|
|
540
|
+
export declare class ImageError extends SdkError<ImageErrorCode> {
|
|
541
|
+
/** Always `"ImageError"`, which survives minification and worker boundaries. */
|
|
542
|
+
readonly name = "ImageError";
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
/**
|
|
546
|
+
* Error codes of `@hussmartinez/image-sdk`: sdk-core's own codes, such as
|
|
547
|
+
* `ABORTED`, `WORKER_CRASHED` and `FILE_TOO_LARGE`, plus the image SDK's
|
|
548
|
+
* (ADR 0001, ADR 0004). They never change meaning once released.
|
|
549
|
+
*
|
|
550
|
+
* - `INVALID_IMAGE`: the file is malformed, its headers claim more than its
|
|
551
|
+
* data can carry or less than its decoder would produce, or its decoded
|
|
552
|
+
* size differs from what its headers declare.
|
|
553
|
+
* - `UNSUPPORTED_FORMAT`: the format isn't recognised, its bound can't be
|
|
554
|
+
* read, or the browser can't encode the requested export format.
|
|
555
|
+
* `details.format` names it.
|
|
556
|
+
* - `DECODE_FAILED`: the browser couldn't decode a file the SDK probed,
|
|
557
|
+
* usually because it lacks the format. `details.format` names it.
|
|
558
|
+
* - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as a
|
|
559
|
+
* crop outside its source. `details.reason` says why, as a stable token
|
|
560
|
+
* (`ImageCommandRejection`).
|
|
561
|
+
* - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
|
|
562
|
+
* valid in its format. `details.reason` says why (`ImageDocumentRejection`).
|
|
563
|
+
* A document of another format, or a later version, is `UNSUPPORTED_FORMAT`
|
|
564
|
+
* instead, with `details.reason` `unknown-format` or `unknown-format-version`.
|
|
565
|
+
* - `IMAGE_TOO_LARGE`: an image, a frame, the canvas or the export exceeds
|
|
566
|
+
* the `maxImagePixels` limit.
|
|
567
|
+
* - `IMAGE_DIMENSION_TOO_LARGE`: a width or height exceeds the
|
|
568
|
+
* `maxImageDimension` limit.
|
|
569
|
+
* - `TOO_MANY_FRAMES`: an animation exceeds the `maxFrames` limit.
|
|
570
|
+
* - `SESSION_TOO_LARGE`: the decoded images the session holds exceed the
|
|
571
|
+
* `maxSessionSize` limit.
|
|
572
|
+
* - `TOO_MANY_LAYERS`: the layer plan exceeds the `maxLayers` limit.
|
|
573
|
+
*
|
|
574
|
+
* Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
|
|
575
|
+
* value and the `unit`. Other codes' `details` name the format involved,
|
|
576
|
+
* and a `reason`, never data from the file.
|
|
577
|
+
*
|
|
578
|
+
* @public
|
|
579
|
+
*/
|
|
580
|
+
export declare type ImageErrorCode = SdkCoreErrorCode | "INVALID_IMAGE" | "UNSUPPORTED_FORMAT" | "DECODE_FAILED" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "IMAGE_TOO_LARGE" | "IMAGE_DIMENSION_TOO_LARGE" | "TOO_MANY_FRAMES" | "SESSION_TOO_LARGE" | "TOO_MANY_LAYERS";
|
|
581
|
+
|
|
582
|
+
/**
|
|
583
|
+
* The file an export produces (ADR 0001). `quality`, from 0 to 1, applies to
|
|
584
|
+
* the lossy formats; it defaults to 0.92. WebP is encoded only where the
|
|
585
|
+
* browser can, and otherwise rejects with `UNSUPPORTED_FORMAT`.
|
|
586
|
+
*
|
|
587
|
+
* @public
|
|
588
|
+
*/
|
|
589
|
+
export declare type ImageExportFormat = {
|
|
590
|
+
readonly type: "png";
|
|
591
|
+
} | {
|
|
592
|
+
readonly type: "jpeg";
|
|
593
|
+
readonly quality?: number;
|
|
594
|
+
} | {
|
|
595
|
+
readonly type: "webp";
|
|
596
|
+
readonly quality?: number;
|
|
597
|
+
};
|
|
598
|
+
|
|
599
|
+
/**
|
|
600
|
+
* One export: a plan over sources registered with the same engine, and the
|
|
601
|
+
* output format. The plan's kept metadata goes into the file, and nothing
|
|
602
|
+
* else does (ADR 0005).
|
|
603
|
+
*
|
|
604
|
+
* @public
|
|
605
|
+
*/
|
|
606
|
+
export declare interface ImageExportJob {
|
|
607
|
+
readonly plan: ImagePlan;
|
|
608
|
+
readonly format: ImageExportFormat;
|
|
609
|
+
}
|
|
610
|
+
|
|
611
|
+
/**
|
|
612
|
+
* Options for exporting.
|
|
613
|
+
*
|
|
614
|
+
* @public
|
|
615
|
+
*/
|
|
616
|
+
export declare interface ImageExportOptions extends ImageProgressOptions {
|
|
617
|
+
/**
|
|
618
|
+
* The limits the output canvas is checked against before it's allocated:
|
|
619
|
+
* `maxImageDimension` and `maxImagePixels` (ADR 0004). The defaults of
|
|
620
|
+
* `imageLimits` when omitted.
|
|
621
|
+
*/
|
|
622
|
+
readonly filePolicy?: ImageFilePolicy;
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
/**
|
|
626
|
+
* A resolved file policy for the image SDK. Violations throw
|
|
627
|
+
* {@link ImageError}.
|
|
628
|
+
*
|
|
629
|
+
* @public
|
|
630
|
+
*/
|
|
631
|
+
export declare type ImageFilePolicy = FilePolicy<ImageLimitDefinitions>;
|
|
632
|
+
|
|
633
|
+
/**
|
|
634
|
+
* A host's `filePolicy`: a new maximum, or `{ maximum, warning }`, for any of
|
|
635
|
+
* the image SDK's limits. `Infinity` disables a maximum, which removes a
|
|
636
|
+
* protection against hostile files, or disables a warning. Unknown limit
|
|
637
|
+
* names throw `TypeError` when the policy is resolved.
|
|
638
|
+
*
|
|
639
|
+
* @example
|
|
640
|
+
* ```ts
|
|
641
|
+
* // Large scans: raise the pixel and decoded sizes together.
|
|
642
|
+
* const filePolicy: ImageFilePolicyOverrides = {
|
|
643
|
+
* maxImagePixels: 100_000_000,
|
|
644
|
+
* maxDecodedSize: { maximum: 2e9, warning: 800e6 },
|
|
645
|
+
* };
|
|
646
|
+
* ```
|
|
647
|
+
*
|
|
648
|
+
* @public
|
|
649
|
+
*/
|
|
650
|
+
export declare type ImageFilePolicyOverrides = FilePolicyOverrides<ImageLimitDefinitions>;
|
|
651
|
+
|
|
652
|
+
/**
|
|
653
|
+
* A filter preset and its strength, an integer from 0 (no effect) to 100.
|
|
654
|
+
*
|
|
655
|
+
* @public
|
|
656
|
+
*/
|
|
657
|
+
export declare interface ImageFilter {
|
|
658
|
+
readonly preset: ImageFilterPreset;
|
|
659
|
+
readonly strength: number;
|
|
660
|
+
}
|
|
661
|
+
|
|
662
|
+
/**
|
|
663
|
+
* A filter preset's name.
|
|
664
|
+
*
|
|
665
|
+
* @public
|
|
666
|
+
*/
|
|
667
|
+
export declare type ImageFilterPreset = (typeof FILTER_PRESETS)[number];
|
|
668
|
+
|
|
669
|
+
/**
|
|
670
|
+
* The formats the probe recognises, by their signature bytes (ADR 0001).
|
|
671
|
+
*
|
|
672
|
+
* @public
|
|
673
|
+
*/
|
|
674
|
+
export declare type ImageFormat = "png" | "jpeg" | "webp" | "gif" | "avif" | "heif" | "bmp";
|
|
675
|
+
|
|
676
|
+
/**
|
|
677
|
+
* The metadata fields a user may keep on export (ADR 0005). Empty strings
|
|
678
|
+
* mean the field isn't written.
|
|
679
|
+
*
|
|
680
|
+
* @public
|
|
681
|
+
*/
|
|
682
|
+
export declare interface ImageKeepableMetadata {
|
|
683
|
+
readonly title: string;
|
|
684
|
+
readonly description: string;
|
|
685
|
+
readonly artist: string;
|
|
686
|
+
readonly copyright: string;
|
|
687
|
+
}
|
|
688
|
+
|
|
689
|
+
/**
|
|
690
|
+
* The type of {@link imageLimitDefinitions}.
|
|
691
|
+
*
|
|
692
|
+
* @public
|
|
693
|
+
*/
|
|
694
|
+
export declare type ImageLimitDefinitions = typeof imageLimitDefinitions;
|
|
695
|
+
|
|
696
|
+
/**
|
|
697
|
+
* The image SDK's limit definitions: sdk-core's core limits with image
|
|
698
|
+
* defaults, plus five for images (ADR 0004).
|
|
699
|
+
*
|
|
700
|
+
* | Limit | Code | Default maximum | Default warning |
|
|
701
|
+
* |---|---|---|---|
|
|
702
|
+
* | `maxFileSize` | `FILE_TOO_LARGE` | 100 MB | 50 MB |
|
|
703
|
+
* | `maxFiles` | `TOO_MANY_FILES` | 20 | none |
|
|
704
|
+
* | `maxDecodedSize` | `DECODED_SIZE_TOO_LARGE` | 1 GB | 400 MB |
|
|
705
|
+
* | `maxProcessingTime` | `PROCESSING_TIME_EXCEEDED` | 120 s | none |
|
|
706
|
+
* | `maxImagePixels` | `IMAGE_TOO_LARGE` | 50 megapixels | 24 megapixels |
|
|
707
|
+
* | `maxImageDimension` | `IMAGE_DIMENSION_TOO_LARGE` | 16,384 pixels | none |
|
|
708
|
+
* | `maxFrames` | `TOO_MANY_FRAMES` | 300 | 100 |
|
|
709
|
+
* | `maxSessionSize` | `SESSION_TOO_LARGE` | 1 GB | 500 MB |
|
|
710
|
+
* | `maxLayers` | `TOO_MANY_LAYERS` | 256 | none |
|
|
711
|
+
*
|
|
712
|
+
* Sizes are decimal: 1 MB is 1,000,000 bytes. Decoded sizes count 4 bytes
|
|
713
|
+
* per pixel. `maxImagePixels` is the same limit, with the same name, code
|
|
714
|
+
* and unit, as `pdf-sdk`'s. `maxImageDimension` is a side length, in pixels.
|
|
715
|
+
*
|
|
716
|
+
* @public
|
|
717
|
+
*/
|
|
718
|
+
export declare const imageLimitDefinitions: {
|
|
719
|
+
readonly maxDecodedSize: {
|
|
720
|
+
readonly default: 1000000000;
|
|
721
|
+
readonly warning: 400000000;
|
|
722
|
+
readonly code: "DECODED_SIZE_TOO_LARGE";
|
|
723
|
+
readonly unit: "bytes";
|
|
724
|
+
};
|
|
725
|
+
readonly maxImagePixels: {
|
|
726
|
+
readonly code: "IMAGE_TOO_LARGE";
|
|
727
|
+
readonly unit: "pixels";
|
|
728
|
+
readonly default: 50000000;
|
|
729
|
+
readonly warning: 24000000;
|
|
730
|
+
};
|
|
731
|
+
readonly maxImageDimension: {
|
|
732
|
+
readonly code: "IMAGE_DIMENSION_TOO_LARGE";
|
|
733
|
+
readonly unit: "pixels";
|
|
734
|
+
readonly default: 16384;
|
|
735
|
+
};
|
|
736
|
+
readonly maxFrames: {
|
|
737
|
+
readonly code: "TOO_MANY_FRAMES";
|
|
738
|
+
readonly unit: "count";
|
|
739
|
+
readonly default: 300;
|
|
740
|
+
readonly warning: 100;
|
|
741
|
+
};
|
|
742
|
+
readonly maxSessionSize: {
|
|
743
|
+
readonly code: "SESSION_TOO_LARGE";
|
|
744
|
+
readonly unit: "bytes";
|
|
745
|
+
readonly default: 1000000000;
|
|
746
|
+
readonly warning: 500000000;
|
|
747
|
+
};
|
|
748
|
+
readonly maxLayers: {
|
|
749
|
+
readonly code: "TOO_MANY_LAYERS";
|
|
750
|
+
readonly unit: "count";
|
|
751
|
+
readonly default: 256;
|
|
752
|
+
};
|
|
753
|
+
readonly maxFileSize: {
|
|
754
|
+
readonly code: "FILE_TOO_LARGE";
|
|
755
|
+
readonly unit: "bytes";
|
|
756
|
+
readonly default: 100000000;
|
|
757
|
+
readonly warning: 50000000;
|
|
758
|
+
};
|
|
759
|
+
readonly maxFiles: {
|
|
760
|
+
readonly code: "TOO_MANY_FILES";
|
|
761
|
+
readonly unit: "count";
|
|
762
|
+
readonly default: 20;
|
|
763
|
+
};
|
|
764
|
+
readonly maxProcessingTime: {
|
|
765
|
+
readonly code: "PROCESSING_TIME_EXCEEDED";
|
|
766
|
+
readonly unit: "milliseconds";
|
|
767
|
+
readonly default: 120000;
|
|
768
|
+
};
|
|
769
|
+
};
|
|
770
|
+
|
|
771
|
+
/**
|
|
772
|
+
* The names of the image SDK's limits.
|
|
773
|
+
*
|
|
774
|
+
* @public
|
|
775
|
+
*/
|
|
776
|
+
export declare type ImageLimitName = keyof ImageLimitDefinitions;
|
|
777
|
+
|
|
778
|
+
/**
|
|
779
|
+
* The image SDK's limits, ready to resolve a host's `filePolicy`. Violations
|
|
780
|
+
* are thrown as {@link ImageError}, with `details` naming the limit.
|
|
781
|
+
*
|
|
782
|
+
* @example
|
|
783
|
+
* ```ts
|
|
784
|
+
* const policy = imageLimits.resolve(props.filePolicy);
|
|
785
|
+
* policy.check("maxImagePixels", width * height); // throws ImageError("IMAGE_TOO_LARGE") above 50 megapixels
|
|
786
|
+
* ```
|
|
787
|
+
*
|
|
788
|
+
* @public
|
|
789
|
+
*/
|
|
790
|
+
export declare const imageLimits: Limits<ImageLimitDefinitions>;
|
|
791
|
+
|
|
792
|
+
/**
|
|
793
|
+
* The type of {@link imageMessages}, for typing a host's overrides with
|
|
794
|
+
* `MessageOverrides<ImageMessageCatalogue>`.
|
|
795
|
+
*
|
|
796
|
+
* @public
|
|
797
|
+
*/
|
|
798
|
+
export declare type ImageMessageCatalogue = typeof imageMessages;
|
|
799
|
+
|
|
800
|
+
/**
|
|
801
|
+
* The image SDK's English message catalogue: sdk-core's and ui's messages, and text
|
|
802
|
+
* for every {@link ImageErrorCode} and every limit's warning. Pass it to
|
|
803
|
+
* `createMessages` from `@hussmartinez/sdk-core`, with the host's locale and
|
|
804
|
+
* overrides. It also has the editor's text: its labels, states,
|
|
805
|
+
* announcements and tool names.
|
|
806
|
+
*
|
|
807
|
+
* Error text is looked up by code, with the error's `details` as
|
|
808
|
+
* parameters, and never taken from `error.message` (ADR 0019).
|
|
809
|
+
*
|
|
810
|
+
* @example
|
|
811
|
+
* ```ts
|
|
812
|
+
* const messages = createMessages(imageMessages, { locale: "en", overrides: props.messages });
|
|
813
|
+
* messages.error(error); // "This animation has 400 frames, which is over the 300-frame limit."
|
|
814
|
+
* messages.t("warnings.maxSessionSize", { actual: 600e6 });
|
|
815
|
+
* ```
|
|
816
|
+
*
|
|
817
|
+
* @public
|
|
818
|
+
*/
|
|
819
|
+
export declare const imageMessages: {
|
|
820
|
+
readonly "errors.INVALID_IMAGE": "This file isn't a valid image, or it's too damaged to open.";
|
|
821
|
+
readonly "errors.UNSUPPORTED_FORMAT": "This image format isn't supported. Try converting the file to PNG or JPEG, then open it again.";
|
|
822
|
+
readonly "errors.DECODE_FAILED": "This browser can't open this kind of image. Try another browser, or convert the file to PNG or JPEG.";
|
|
823
|
+
readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
|
|
824
|
+
readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't an image project.";
|
|
825
|
+
readonly "errors.IMAGE_TOO_LARGE": "This image has more pixels than the editor can handle. Try a smaller version of it.";
|
|
826
|
+
readonly "errors.IMAGE_DIMENSION_TOO_LARGE": "This image is {actual, number} pixels across, which is over the {maximum, number}-pixel limit.";
|
|
827
|
+
readonly "errors.TOO_MANY_FRAMES": {
|
|
828
|
+
readonly $plural: "maximum";
|
|
829
|
+
} & {
|
|
830
|
+
readonly one: "This animation has {actual, number} frames, which is over the {maximum}-frame limit.";
|
|
831
|
+
readonly other: "This animation has {actual, number} frames, which is over the {maximum, number}-frame limit.";
|
|
832
|
+
};
|
|
833
|
+
readonly "errors.SESSION_TOO_LARGE": "The open images would use {actual, fileSize} of memory, which is over the {maximum, fileSize} limit. Close an image, or clear the undo history, and try again.";
|
|
834
|
+
readonly "errors.TOO_MANY_LAYERS": {
|
|
835
|
+
readonly $plural: "maximum";
|
|
836
|
+
} & {
|
|
837
|
+
readonly one: "An image can have {maximum} layer. Merge or delete layers, and try again.";
|
|
838
|
+
readonly other: "An image can have up to {maximum, number} layers. Merge or delete layers, and try again.";
|
|
839
|
+
};
|
|
840
|
+
readonly "warnings.maxImagePixels": "This image is large, and may be slow to edit on some devices.";
|
|
841
|
+
readonly "warnings.maxImageDimension": "This image is very wide or tall, and may be slow to edit.";
|
|
842
|
+
readonly "warnings.maxFrames": {
|
|
843
|
+
readonly $plural: "actual";
|
|
844
|
+
} & {
|
|
845
|
+
readonly one: "This animation has {actual} frame.";
|
|
846
|
+
readonly other: "This animation has {actual, number} frames, and may be slow to edit and export.";
|
|
847
|
+
};
|
|
848
|
+
readonly "warnings.maxSessionSize": "The open images use {actual, fileSize} of memory. Clearing the undo history frees memory.";
|
|
849
|
+
readonly "warnings.maxLayers": {
|
|
850
|
+
readonly $plural: "actual";
|
|
851
|
+
} & {
|
|
852
|
+
readonly one: "This image has {actual} layer.";
|
|
853
|
+
readonly other: "This image has {actual, number} layers, and may be slow to edit and export.";
|
|
854
|
+
};
|
|
855
|
+
readonly "editor.label": "Image editor";
|
|
856
|
+
readonly "editor.preview": "Edited image preview, {width, number} × {height, number}";
|
|
857
|
+
readonly "editor.empty": "Open an image to start editing. It stays on this device.";
|
|
858
|
+
readonly "editor.choose": "Choose an image";
|
|
859
|
+
readonly "editor.dropHint": "or drop it here";
|
|
860
|
+
readonly "editor.opening": "Opening the image…";
|
|
861
|
+
readonly "editor.cancel": "Cancel";
|
|
862
|
+
readonly "editor.opened": "Image opened, {width, number} × {height, number}.";
|
|
863
|
+
readonly "editor.undid": "Undid {action}.";
|
|
864
|
+
readonly "editor.redid": "Redid {action}.";
|
|
865
|
+
readonly "actions.image.setCrop": "crop";
|
|
866
|
+
readonly "actions.image.setOrientation": "rotate or flip";
|
|
867
|
+
readonly "actions.image.setOutput": "size";
|
|
868
|
+
readonly "actions.image.setMetadata": "metadata";
|
|
869
|
+
readonly "actions.image.setDevelop": "adjustment";
|
|
870
|
+
readonly "actions.image.setFilter": "filter";
|
|
871
|
+
readonly "toolbar.label": "Image tools";
|
|
872
|
+
readonly "toolbar.groups.file": "File";
|
|
873
|
+
readonly "toolbar.groups.history": "History";
|
|
874
|
+
readonly "toolbar.groups.orientation": "Rotate";
|
|
875
|
+
readonly "toolbar.groups.zoom": "Zoom";
|
|
876
|
+
readonly "toolbar.groups.other": "More tools";
|
|
877
|
+
readonly "tools.open": "Open image";
|
|
878
|
+
readonly "tools.undo": "Undo";
|
|
879
|
+
readonly "tools.redo": "Redo";
|
|
880
|
+
readonly "tools.rotate-left": "Rotate left";
|
|
881
|
+
readonly "tools.rotate-right": "Rotate right";
|
|
882
|
+
readonly "tools.zoom-in": "Zoom in";
|
|
883
|
+
readonly "tools.zoom-out": "Zoom out";
|
|
884
|
+
readonly "tools.zoom-fit": "Fit to the stage";
|
|
885
|
+
readonly "tools.crop": "Crop";
|
|
886
|
+
readonly "tools.flip-horizontal": "Flip horizontally";
|
|
887
|
+
readonly "tools.flip-vertical": "Flip vertically";
|
|
888
|
+
readonly "toolbar.groups.crop": "Crop";
|
|
889
|
+
readonly "crop.frame": "Crop area";
|
|
890
|
+
readonly "crop.frameDescription": "{width, number} × {height, number} pixels, from {x, number}, {y, number}. Arrow keys move it; with Alt, they resize it; Enter applies and Escape cancels.";
|
|
891
|
+
readonly "crop.size": "{width, number} × {height, number}, from {x, number}, {y, number}";
|
|
892
|
+
readonly "crop.panel": "Crop";
|
|
893
|
+
readonly "crop.x": "Left";
|
|
894
|
+
readonly "crop.y": "Top";
|
|
895
|
+
readonly "crop.width": "Width";
|
|
896
|
+
readonly "crop.height": "Height";
|
|
897
|
+
readonly "crop.aspect": "Aspect ratio";
|
|
898
|
+
readonly "crop.aspects.free": "Free";
|
|
899
|
+
readonly "crop.aspects.original": "Original";
|
|
900
|
+
readonly "crop.aspects.ratio": "{width}:{height}";
|
|
901
|
+
readonly "crop.apply": "Apply crop";
|
|
902
|
+
readonly "crop.cancel": "Cancel";
|
|
903
|
+
readonly "crop.reset": "Whole image";
|
|
904
|
+
readonly "crop.applied": "Cropped to {width, number} × {height, number}.";
|
|
905
|
+
readonly "inspector.label": "Panels";
|
|
906
|
+
readonly "inspector.adjust": "Adjust";
|
|
907
|
+
readonly "inspector.filters": "Filters";
|
|
908
|
+
readonly "inspector.info": "Info";
|
|
909
|
+
readonly "notices.label": "Notices";
|
|
910
|
+
readonly "notices.dismiss": "Dismiss";
|
|
911
|
+
readonly "notices.colourProfile": "This image has a colour profile. Colours outside sRGB will be clipped in the exported file.";
|
|
912
|
+
readonly "info.panel": "Image info";
|
|
913
|
+
readonly "info.size": "Size";
|
|
914
|
+
readonly "info.sizeValue": "{width, number} × {height, number} pixels";
|
|
915
|
+
readonly "info.format": "Format";
|
|
916
|
+
readonly "info.formats.png": "PNG";
|
|
917
|
+
readonly "info.formats.jpeg": "JPEG";
|
|
918
|
+
readonly "info.formats.webp": "WebP";
|
|
919
|
+
readonly "info.formats.gif": "GIF";
|
|
920
|
+
readonly "info.formats.avif": "AVIF";
|
|
921
|
+
readonly "info.formats.heif": "HEIF";
|
|
922
|
+
readonly "info.formats.bmp": "BMP";
|
|
923
|
+
readonly "info.frames": "Frames";
|
|
924
|
+
readonly "info.fileSize": "File size";
|
|
925
|
+
readonly "info.fileSizeValue": "{size, fileSize}";
|
|
926
|
+
readonly "info.metadata": "Metadata in the file";
|
|
927
|
+
readonly "info.metadataNone": "None";
|
|
928
|
+
readonly "info.kept": "Kept on export";
|
|
929
|
+
readonly "info.keptNone": "Nothing";
|
|
930
|
+
readonly "develop.panel": "Adjust";
|
|
931
|
+
readonly "develop.temperature": "Temperature";
|
|
932
|
+
readonly "develop.tint": "Tint";
|
|
933
|
+
readonly "develop.exposure": "Exposure";
|
|
934
|
+
readonly "develop.highlights": "Highlights";
|
|
935
|
+
readonly "develop.shadows": "Shadows";
|
|
936
|
+
readonly "develop.contrast": "Contrast";
|
|
937
|
+
readonly "develop.saturation": "Saturation";
|
|
938
|
+
readonly "develop.vibrance": "Vibrance";
|
|
939
|
+
readonly "develop.reset": "Reset {name}";
|
|
940
|
+
readonly "develop.resetAll": "Reset all";
|
|
941
|
+
readonly "develop.wasReset": "All adjustments reset.";
|
|
942
|
+
readonly "filters.panel": "Filters";
|
|
943
|
+
readonly "filters.label": "Filter";
|
|
944
|
+
readonly "filters.none": "None";
|
|
945
|
+
readonly "filters.vivid": "Vivid";
|
|
946
|
+
readonly "filters.warm": "Warm";
|
|
947
|
+
readonly "filters.cool": "Cool";
|
|
948
|
+
readonly "filters.fade": "Fade";
|
|
949
|
+
readonly "filters.mono": "Mono";
|
|
950
|
+
readonly "filters.noir": "Noir";
|
|
951
|
+
readonly "filters.sepia": "Sepia";
|
|
952
|
+
readonly "filters.strength": "Strength";
|
|
953
|
+
readonly "toolbar.groups.export": "Export";
|
|
954
|
+
readonly "tools.export": "Export";
|
|
955
|
+
readonly "export.title": "Export image";
|
|
956
|
+
readonly "export.description": "The file is made on this device, and nothing is uploaded.";
|
|
957
|
+
readonly "export.format": "Format";
|
|
958
|
+
readonly "export.formats.png": "PNG";
|
|
959
|
+
readonly "export.formats.jpeg": "JPEG";
|
|
960
|
+
readonly "export.formats.webp": "WebP";
|
|
961
|
+
readonly "export.quality": "Quality";
|
|
962
|
+
readonly "export.qualityValue": "{quality, number}%";
|
|
963
|
+
readonly "export.size": "Size";
|
|
964
|
+
readonly "export.sizes.scale": "Scale";
|
|
965
|
+
readonly "export.sizes.fit": "Fit in a box";
|
|
966
|
+
readonly "export.scale": "Scale, in percent";
|
|
967
|
+
readonly "export.fitWidth": "Largest width";
|
|
968
|
+
readonly "export.fitHeight": "Largest height";
|
|
969
|
+
readonly "export.fields": "Details to include";
|
|
970
|
+
readonly "export.fieldsHint": "Only what you fill in is written to the file.";
|
|
971
|
+
readonly "export.field.title": "Title";
|
|
972
|
+
readonly "export.field.description": "Description";
|
|
973
|
+
readonly "export.field.artist": "Artist";
|
|
974
|
+
readonly "export.field.copyright": "Copyright";
|
|
975
|
+
readonly "export.summary": "Summary";
|
|
976
|
+
readonly "export.output": "{width, number} × {height, number} pixels, {format}";
|
|
977
|
+
readonly "export.removed": "Removed from the file";
|
|
978
|
+
readonly "export.removedNone": "The image had no other details to remove.";
|
|
979
|
+
readonly "export.kind.location": "Location";
|
|
980
|
+
readonly "export.kind.camera": "Camera details";
|
|
981
|
+
readonly "export.kind.timestamps": "Dates and times";
|
|
982
|
+
readonly "export.kind.thumbnail": "Embedded thumbnail";
|
|
983
|
+
readonly "export.kind.colourProfile": "Colour profile: colours outside sRGB are clipped";
|
|
984
|
+
readonly "export.kind.other": "Other metadata";
|
|
985
|
+
readonly "export.kept": "Kept in the file";
|
|
986
|
+
readonly "export.confirm": "Export";
|
|
987
|
+
readonly "export.cancel": "Cancel";
|
|
988
|
+
readonly "export.progress": "Exporting the image";
|
|
989
|
+
readonly "export.stop": "Stop exporting";
|
|
990
|
+
readonly "export.cancelled": "Export stopped.";
|
|
991
|
+
readonly "export.done": "Exported a {format} of {size, fileSize}.";
|
|
992
|
+
readonly "export.ready": "{width, number} × {height, number} pixels, {format}, {size, fileSize}";
|
|
993
|
+
readonly "export.download": "Download";
|
|
994
|
+
readonly "export.close": "Done";
|
|
995
|
+
readonly "dialog.close": "Close";
|
|
996
|
+
readonly "fileDropZone.choose": "Choose a file";
|
|
997
|
+
readonly "fileDropZone.chooseMultiple": "Choose files";
|
|
998
|
+
readonly "fileDropZone.hint": "or drop it here";
|
|
999
|
+
readonly "fileDropZone.hintMultiple": "or drop them here";
|
|
1000
|
+
readonly "progress.label": "Progress";
|
|
1001
|
+
readonly "spinner.label": "Loading";
|
|
1002
|
+
readonly "errors.INVALID_THEME_TOKEN": "The theme setting {token} has a value that can't be used.";
|
|
1003
|
+
readonly "errors.INVALID_THEME_SELECTOR": "The theme can't be applied to the selector {selector}.";
|
|
1004
|
+
readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
|
|
1005
|
+
readonly "errors.ABORTED": "The operation was cancelled.";
|
|
1006
|
+
readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
|
|
1007
|
+
readonly "errors.WORKER_START_FAILED": "The file processor couldn't start. Reload the page and try again.";
|
|
1008
|
+
readonly "errors.WORKER_PROTOCOL_MISMATCH": "The file processor is out of date. Reload the page to update it.";
|
|
1009
|
+
readonly "errors.WORKER_CRASHED": "The file processor stopped unexpectedly. Please try again.";
|
|
1010
|
+
readonly "errors.WORKER_TERMINATED": "The operation was stopped before it finished. Please try again.";
|
|
1011
|
+
readonly "errors.WORKER_METHOD_NOT_FOUND": "This operation isn't available. Reload the page and try again.";
|
|
1012
|
+
readonly "errors.WORKER_DATA_NOT_CLONEABLE": "Something went wrong while processing the file. Please try again.";
|
|
1013
|
+
readonly "errors.UNSUPPORTED_ENVIRONMENT": "This browser doesn't support a feature this tool needs. Update your browser, or try another one.";
|
|
1014
|
+
readonly "errors.FILE_TOO_LARGE": "This file is {actual, fileSize}, which is over the {maximum, fileSize} limit.";
|
|
1015
|
+
readonly "errors.TOO_MANY_FILES": {
|
|
1016
|
+
readonly $plural: "maximum";
|
|
1017
|
+
} & {
|
|
1018
|
+
readonly one: "You can add {maximum} file at a time.";
|
|
1019
|
+
readonly other: "You can add up to {maximum} files at a time.";
|
|
1020
|
+
};
|
|
1021
|
+
readonly "errors.DECODED_SIZE_TOO_LARGE": "This file expands to more than {maximum, fileSize} when opened, which is over the limit.";
|
|
1022
|
+
readonly "errors.PROCESSING_TIME_EXCEEDED": "Processing this file took too long and was stopped.";
|
|
1023
|
+
readonly "warnings.maxFileSize": "This file is {actual, fileSize}. Large files may be slow to process.";
|
|
1024
|
+
readonly "warnings.maxFiles": "Adding {actual} files at once may be slow.";
|
|
1025
|
+
readonly "warnings.maxDecodedSize": "This file is very large once opened and may be slow to process.";
|
|
1026
|
+
readonly "warnings.maxProcessingTime": "This is taking longer than usual.";
|
|
1027
|
+
readonly "keys.control": "Ctrl";
|
|
1028
|
+
readonly "keys.alt": "Alt";
|
|
1029
|
+
readonly "keys.shift": "Shift";
|
|
1030
|
+
readonly "keys.meta": "Meta";
|
|
1031
|
+
readonly "keys.apple.control": "\u2303";
|
|
1032
|
+
readonly "keys.apple.alt": "\u2325";
|
|
1033
|
+
readonly "keys.apple.shift": "\u21E7";
|
|
1034
|
+
readonly "keys.apple.meta": "\u2318";
|
|
1035
|
+
readonly "keys.space": "Space";
|
|
1036
|
+
readonly "keys.enter": "Enter";
|
|
1037
|
+
readonly "keys.escape": "Esc";
|
|
1038
|
+
readonly "keys.tab": "Tab";
|
|
1039
|
+
readonly "keys.delete": "Delete";
|
|
1040
|
+
readonly "keys.backspace": "Backspace";
|
|
1041
|
+
readonly "keys.arrowUp": "\u2191";
|
|
1042
|
+
readonly "keys.arrowDown": "\u2193";
|
|
1043
|
+
readonly "keys.arrowLeft": "\u2190";
|
|
1044
|
+
readonly "keys.arrowRight": "\u2192";
|
|
1045
|
+
readonly "keys.home": "Home";
|
|
1046
|
+
readonly "keys.end": "End";
|
|
1047
|
+
readonly "keys.pageUp": "Page Up";
|
|
1048
|
+
readonly "keys.pageDown": "Page Down";
|
|
1049
|
+
};
|
|
1050
|
+
|
|
1051
|
+
/**
|
|
1052
|
+
* Which kinds of metadata a file carries, as presence flags, never values,
|
|
1053
|
+
* so the editor can say what an export removes (ADR 0005).
|
|
1054
|
+
*
|
|
1055
|
+
* @public
|
|
1056
|
+
*/
|
|
1057
|
+
export declare interface ImageMetadataPresence {
|
|
1058
|
+
readonly location: boolean;
|
|
1059
|
+
readonly camera: boolean;
|
|
1060
|
+
readonly timestamps: boolean;
|
|
1061
|
+
readonly thumbnail: boolean;
|
|
1062
|
+
readonly colourProfile: boolean;
|
|
1063
|
+
/** Any other field, such as maker notes or unknown tags. */
|
|
1064
|
+
readonly other: boolean;
|
|
1065
|
+
}
|
|
1066
|
+
|
|
1067
|
+
/**
|
|
1068
|
+
* The plan's own rotation and flips, applied after the crop. They're user
|
|
1069
|
+
* edits, separate from the file's EXIF orientation, which decoding has
|
|
1070
|
+
* already applied (ADR 0005).
|
|
1071
|
+
*
|
|
1072
|
+
* @public
|
|
1073
|
+
*/
|
|
1074
|
+
declare interface ImageOrientation_2 {
|
|
1075
|
+
readonly rotate: ImageRotation;
|
|
1076
|
+
/** Mirrors left to right, after the rotation. */
|
|
1077
|
+
readonly flipX: boolean;
|
|
1078
|
+
/** Mirrors top to bottom, after the rotation. */
|
|
1079
|
+
readonly flipY: boolean;
|
|
1080
|
+
}
|
|
1081
|
+
export { ImageOrientation_2 as ImageOrientation }
|
|
1082
|
+
|
|
1083
|
+
/**
|
|
1084
|
+
* The export's size: the composition scaled by a factor up to 1, or fitted
|
|
1085
|
+
* inside a box without enlarging it.
|
|
1086
|
+
*
|
|
1087
|
+
* @public
|
|
1088
|
+
*/
|
|
1089
|
+
export declare type ImageOutput = {
|
|
1090
|
+
readonly kind: "scale";
|
|
1091
|
+
readonly scale: number;
|
|
1092
|
+
} | {
|
|
1093
|
+
readonly kind: "fit";
|
|
1094
|
+
readonly width: number;
|
|
1095
|
+
readonly height: number;
|
|
1096
|
+
};
|
|
1097
|
+
|
|
1098
|
+
/**
|
|
1099
|
+
* The session's document: a description of the edits over an immutable
|
|
1100
|
+
* source, rendered to pixels only for display and export (ADR 0003).
|
|
1101
|
+
*
|
|
1102
|
+
* @public
|
|
1103
|
+
*/
|
|
1104
|
+
export declare interface ImagePlan {
|
|
1105
|
+
readonly base: ImageBase;
|
|
1106
|
+
readonly output: ImageOutput;
|
|
1107
|
+
/** The fields the user chose to keep on export. Never a location (ADR 0005). */
|
|
1108
|
+
readonly metadata: ImageKeepableMetadata;
|
|
1109
|
+
}
|
|
1110
|
+
|
|
1111
|
+
/**
|
|
1112
|
+
* The plan as portable JSON: `hm-image-plan` version 1, which
|
|
1113
|
+
* `formats/hm-image-plan/v1.schema.json` describes
|
|
1114
|
+
* (docs/formats/hm-image-plan.md). Positions are whole pixels of the
|
|
1115
|
+
* oriented source, and the base names its source by an id the document
|
|
1116
|
+
* lists.
|
|
1117
|
+
*
|
|
1118
|
+
* @public
|
|
1119
|
+
*/
|
|
1120
|
+
export declare interface ImagePlanDocument extends ImagePlan {
|
|
1121
|
+
readonly format: typeof IMAGE_PLAN_FORMAT;
|
|
1122
|
+
readonly version: typeof IMAGE_PLAN_VERSION;
|
|
1123
|
+
readonly sources: Readonly<Record<string, ImagePlanDocumentSource>>;
|
|
1124
|
+
}
|
|
1125
|
+
|
|
1126
|
+
/**
|
|
1127
|
+
* A source, as a plan document records it: its oriented size in pixels,
|
|
1128
|
+
* which a crop must fit inside, and, once documents travel with their files,
|
|
1129
|
+
* its content.
|
|
1130
|
+
*
|
|
1131
|
+
* @public
|
|
1132
|
+
*/
|
|
1133
|
+
export declare interface ImagePlanDocumentSource extends ImageSize {
|
|
1134
|
+
readonly asset?: ImageAssetReference;
|
|
1135
|
+
}
|
|
1136
|
+
|
|
1137
|
+
/**
|
|
1138
|
+
* A point in pixels, which may be fractional.
|
|
1139
|
+
*
|
|
1140
|
+
* @public
|
|
1141
|
+
*/
|
|
1142
|
+
export declare interface ImagePoint {
|
|
1143
|
+
readonly x: number;
|
|
1144
|
+
readonly y: number;
|
|
1145
|
+
}
|
|
1146
|
+
|
|
1147
|
+
/**
|
|
1148
|
+
* What the probe learned about a file before anything decodes it (ADR 0001,
|
|
1149
|
+
* ADR 0004, ADR 0005). Limits are checked against it.
|
|
1150
|
+
*
|
|
1151
|
+
* @public
|
|
1152
|
+
*/
|
|
1153
|
+
export declare interface ImageProbe {
|
|
1154
|
+
readonly format: ImageFormat;
|
|
1155
|
+
/** The size of the stored pixels, before orientation. */
|
|
1156
|
+
readonly stored: ImageSize;
|
|
1157
|
+
/** The upright size, after orientation: the size the decoder must return. */
|
|
1158
|
+
readonly oriented: ImageSize;
|
|
1159
|
+
/** The EXIF or `irot`/`imir` orientation; 1 when there's none. */
|
|
1160
|
+
readonly orientation: ExifOrientation;
|
|
1161
|
+
/** 1 for a still image, otherwise the number of frames the probe walked. */
|
|
1162
|
+
readonly frames: number;
|
|
1163
|
+
readonly hasAlpha: boolean;
|
|
1164
|
+
/**
|
|
1165
|
+
* The most pixels the decoder can produce for the file: frames × the
|
|
1166
|
+
* oriented size for most formats, and for AVIF and HEIF the sum over every
|
|
1167
|
+
* item decoded with the primary, such as grid tiles and auxiliary planes.
|
|
1168
|
+
* A file with an orientation counts one more oriented frame, which the
|
|
1169
|
+
* worker needs when it applies the orientation itself (ADR 0005).
|
|
1170
|
+
* Never a count declared by one header (ADR 0001).
|
|
1171
|
+
*/
|
|
1172
|
+
readonly decodedPixelBound: number;
|
|
1173
|
+
readonly metadata: ImageMetadataPresence;
|
|
1174
|
+
/** The keepable fields the file carries, length-limited, shown only as text. */
|
|
1175
|
+
readonly keepable: ImageKeepableMetadata;
|
|
1176
|
+
}
|
|
1177
|
+
|
|
1178
|
+
/**
|
|
1179
|
+
* The port for exporting: render a plan at its output size and encode it
|
|
1180
|
+
* (ADR 0001, ADR 0003, ADR 0008). It renders sources registered with its
|
|
1181
|
+
* engine, so the SDK's own adapter shares the engine's render worker; hosts
|
|
1182
|
+
* can pass their own to the editor's `processor` prop, and every
|
|
1183
|
+
* implementation must pass the processor's contract tests.
|
|
1184
|
+
*
|
|
1185
|
+
* Failures reject with `ImageError` for cancellation, worker failures and
|
|
1186
|
+
* formats the browser can't encode, and `TypeError` for a plan whose source
|
|
1187
|
+
* isn't registered.
|
|
1188
|
+
*
|
|
1189
|
+
* @public
|
|
1190
|
+
*/
|
|
1191
|
+
export declare interface ImageProcessor {
|
|
1192
|
+
/**
|
|
1193
|
+
* Renders and encodes a plan, and returns the file. It writes only the
|
|
1194
|
+
* plan's kept metadata, and never a location, a camera's details,
|
|
1195
|
+
* timestamps, a thumbnail or an orientation. An output over `filePolicy`'s
|
|
1196
|
+
* `maxImageDimension` or `maxImagePixels` rejects with that limit's code
|
|
1197
|
+
* before anything is drawn.
|
|
1198
|
+
*/
|
|
1199
|
+
export(job: ImageExportJob, options?: ImageExportOptions): Promise<Blob>;
|
|
1200
|
+
/** Releases the processor. Pending calls reject, and later calls throw. */
|
|
1201
|
+
destroy(): Promise<void>;
|
|
1202
|
+
}
|
|
1203
|
+
|
|
1204
|
+
/**
|
|
1205
|
+
* Options for long calls, which report how far they've got.
|
|
1206
|
+
*
|
|
1207
|
+
* @public
|
|
1208
|
+
*/
|
|
1209
|
+
export declare interface ImageProgressOptions extends ImageCallOptions {
|
|
1210
|
+
/**
|
|
1211
|
+
* Called with the fraction done, from 0 to 1. It only moves forward, and
|
|
1212
|
+
* it's called with 1 before the call resolves.
|
|
1213
|
+
*/
|
|
1214
|
+
readonly onProgress?: (fraction: number) => void;
|
|
1215
|
+
}
|
|
1216
|
+
|
|
1217
|
+
/**
|
|
1218
|
+
* Options for registering a source.
|
|
1219
|
+
*
|
|
1220
|
+
* @public
|
|
1221
|
+
*/
|
|
1222
|
+
export declare interface ImageRegisterOptions extends ImageProgressOptions {
|
|
1223
|
+
/**
|
|
1224
|
+
* The limits checked against the engine's own probe of the file before
|
|
1225
|
+
* anything decodes it: `maxFileSize`, `maxImageDimension`,
|
|
1226
|
+
* `maxImagePixels`, `maxFrames` and `maxDecodedSize` (ADR 0004). The
|
|
1227
|
+
* defaults of `imageLimits` when omitted. The session checks the same
|
|
1228
|
+
* policy first, so this is defence in depth for hosts that use the engine
|
|
1229
|
+
* directly.
|
|
1230
|
+
*/
|
|
1231
|
+
readonly filePolicy?: ImageFilePolicy;
|
|
1232
|
+
}
|
|
1233
|
+
|
|
1234
|
+
/**
|
|
1235
|
+
* The port for the preview (ADR 0002): a canvas on the page, drawn by the
|
|
1236
|
+
* engine's render worker through the same renderer as every export, so what
|
|
1237
|
+
* the editor shows is what the file will contain. Renders are coalesced:
|
|
1238
|
+
* when plans arrive faster than they're drawn, only the latest is drawn, and
|
|
1239
|
+
* a render in progress stops at its next strip.
|
|
1240
|
+
*
|
|
1241
|
+
* @public
|
|
1242
|
+
*/
|
|
1243
|
+
export declare interface ImageRenderer {
|
|
1244
|
+
/**
|
|
1245
|
+
* Hands a canvas to the render worker, once per canvas. The page can't
|
|
1246
|
+
* draw into or read it afterwards. Without `transferControlToOffscreen`
|
|
1247
|
+
* it rejects with `UNSUPPORTED_ENVIRONMENT`.
|
|
1248
|
+
*/
|
|
1249
|
+
attach(canvas: HTMLCanvasElement): Promise<void>;
|
|
1250
|
+
/**
|
|
1251
|
+
* Draws a plan into the attached canvas for a view. It resolves `drawn`
|
|
1252
|
+
* when this plan is on screen, or `superseded` when a later call replaced
|
|
1253
|
+
* it. A plan whose source isn't registered is a `TypeError`. A view whose
|
|
1254
|
+
* backing size is over `filePolicy`'s limits rejects with the limit's code
|
|
1255
|
+
* before anything is drawn, and the canvas keeps its previous frame.
|
|
1256
|
+
*/
|
|
1257
|
+
render(plan: ImagePlan, view: ImageView, options?: ImageRenderOptions): Promise<ImageRenderOutcome>;
|
|
1258
|
+
/** Releases the canvas in the worker. Pending renders resolve `superseded`, and later calls throw. */
|
|
1259
|
+
destroy(): Promise<void>;
|
|
1260
|
+
}
|
|
1261
|
+
|
|
1262
|
+
/**
|
|
1263
|
+
* Options for a render.
|
|
1264
|
+
*
|
|
1265
|
+
* @public
|
|
1266
|
+
*/
|
|
1267
|
+
export declare interface ImageRenderOptions extends ImageCallOptions {
|
|
1268
|
+
/**
|
|
1269
|
+
* The limits the preview canvas's backing size, the view's size times its
|
|
1270
|
+
* pixel ratio, is checked against before the canvas is resized:
|
|
1271
|
+
* `maxImageDimension` and `maxImagePixels` (ADR 0004). The defaults of
|
|
1272
|
+
* `imageLimits` when omitted.
|
|
1273
|
+
*/
|
|
1274
|
+
readonly filePolicy?: ImageFilePolicy;
|
|
1275
|
+
}
|
|
1276
|
+
|
|
1277
|
+
/**
|
|
1278
|
+
* What became of one `render` call: `drawn`, or `superseded` when a later
|
|
1279
|
+
* call replaced it before it was drawn (ADR 0002).
|
|
1280
|
+
*
|
|
1281
|
+
* @public
|
|
1282
|
+
*/
|
|
1283
|
+
export declare type ImageRenderOutcome = "drawn" | "superseded";
|
|
1284
|
+
|
|
1285
|
+
/**
|
|
1286
|
+
* A quarter-turn rotation, clockwise, in degrees.
|
|
1287
|
+
*
|
|
1288
|
+
* @public
|
|
1289
|
+
*/
|
|
1290
|
+
export declare type ImageRotation = 0 | 90 | 180 | 270;
|
|
1291
|
+
|
|
1292
|
+
/**
|
|
1293
|
+
* An image editing session (ADR 0003, ADR 0008): one document, its plan
|
|
1294
|
+
* over the source it opened, edited by commands with undo and redo, and
|
|
1295
|
+
* exported through its processor.
|
|
1296
|
+
*
|
|
1297
|
+
* @public
|
|
1298
|
+
*/
|
|
1299
|
+
export declare interface ImageSession {
|
|
1300
|
+
getSnapshot(): ImageSessionSnapshot;
|
|
1301
|
+
/** Calls the listener after every change. Returns a function that unsubscribes. */
|
|
1302
|
+
subscribe(listener: () => void): () => void;
|
|
1303
|
+
/**
|
|
1304
|
+
* Probes, checks and decodes a file, and makes it the document, with a new
|
|
1305
|
+
* plan and an empty history; the previous source is released (ADR 0003,
|
|
1306
|
+
* ADR 0004). The newest open wins: an open that finishes after a later one
|
|
1307
|
+
* started applies nothing, releases its source and rejects with
|
|
1308
|
+
* `ABORTED`. A failed or cancelled open leaves the current document as it
|
|
1309
|
+
* was.
|
|
1310
|
+
*/
|
|
1311
|
+
open(file: Blob, options?: {
|
|
1312
|
+
readonly signal?: AbortSignal;
|
|
1313
|
+
}): Promise<ImageSessionSource>;
|
|
1314
|
+
/**
|
|
1315
|
+
* Applies commands as one undoable step. They're checked by the reducer,
|
|
1316
|
+
* then the output against `maxImageDimension` and `maxImagePixels`; a
|
|
1317
|
+
* failure throws `ImageError` and changes nothing.
|
|
1318
|
+
*/
|
|
1319
|
+
execute(commands: ImageCommand | readonly ImageCommand[]): void;
|
|
1320
|
+
/**
|
|
1321
|
+
* Makes the document's plan equal to `plan`, as one undoable step of the
|
|
1322
|
+
* commands that reach it, checked as `execute` checks them (ADR 0003). A
|
|
1323
|
+
* plan equal to the current one changes nothing. A plan over another
|
|
1324
|
+
* source is `INVALID_COMMAND`. For editors whose host holds the plan.
|
|
1325
|
+
*/
|
|
1326
|
+
applyPlan(plan: ImagePlan): void;
|
|
1327
|
+
/**
|
|
1328
|
+
* Runs `fn`, and records every step it executes as one undoable step, for
|
|
1329
|
+
* a gesture such as dragging a crop handle (ADR 0003). `fn` must be
|
|
1330
|
+
* synchronous.
|
|
1331
|
+
*/
|
|
1332
|
+
group<T>(fn: () => T): T;
|
|
1333
|
+
/** Undoes the last step. Returns whether there was one. */
|
|
1334
|
+
undo(): boolean;
|
|
1335
|
+
/** Redoes the last undone step. Returns whether there was one. */
|
|
1336
|
+
redo(): boolean;
|
|
1337
|
+
/**
|
|
1338
|
+
* Renders and encodes the document (ADR 0003). An export that finishes
|
|
1339
|
+
* after another file was opened rejects with `ABORTED`.
|
|
1340
|
+
*/
|
|
1341
|
+
export(format: ImageExportFormat, options?: {
|
|
1342
|
+
readonly signal?: AbortSignal;
|
|
1343
|
+
readonly onProgress?: (fraction: number) => void;
|
|
1344
|
+
}): Promise<ImageSessionExport>;
|
|
1345
|
+
/** Releases the source the session holds. Later calls throw. */
|
|
1346
|
+
destroy(): Promise<void>;
|
|
1347
|
+
}
|
|
1348
|
+
|
|
1349
|
+
/**
|
|
1350
|
+
* An anonymous usage event for the host's `onEvent` (ADR 0003). It never
|
|
1351
|
+
* carries file names, pixels, text the user typed or metadata values.
|
|
1352
|
+
*
|
|
1353
|
+
* @public
|
|
1354
|
+
*/
|
|
1355
|
+
export declare interface ImageSessionEvent {
|
|
1356
|
+
readonly type: "open" | "execute" | "undo" | "redo" | "export";
|
|
1357
|
+
readonly outcome: "done" | "failed" | "cancelled";
|
|
1358
|
+
/** The types of the commands applied or undone. */
|
|
1359
|
+
readonly commands: readonly ImageCommand["type"][];
|
|
1360
|
+
}
|
|
1361
|
+
|
|
1362
|
+
/**
|
|
1363
|
+
* What an export produced, and what the summary before a download shows
|
|
1364
|
+
* (ADR 0003, ADR 0005).
|
|
1365
|
+
*
|
|
1366
|
+
* @public
|
|
1367
|
+
*/
|
|
1368
|
+
export declare interface ImageSessionExport {
|
|
1369
|
+
readonly blob: Blob;
|
|
1370
|
+
readonly width: number;
|
|
1371
|
+
readonly height: number;
|
|
1372
|
+
/**
|
|
1373
|
+
* The kinds of metadata the source carried that the file doesn't: every
|
|
1374
|
+
* kind, since exports keep only the fields the user chose, which are
|
|
1375
|
+
* never these. Empty when the source carried none.
|
|
1376
|
+
*/
|
|
1377
|
+
readonly removed: readonly (keyof ImageMetadataPresence)[];
|
|
1378
|
+
/** The fields the user kept, which the file carries. */
|
|
1379
|
+
readonly kept: readonly (keyof ImageKeepableMetadata)[];
|
|
1380
|
+
}
|
|
1381
|
+
|
|
1382
|
+
/**
|
|
1383
|
+
* Options for {@link createImageSession}.
|
|
1384
|
+
*
|
|
1385
|
+
* @public
|
|
1386
|
+
*/
|
|
1387
|
+
export declare interface ImageSessionOptions {
|
|
1388
|
+
/** Probes, decodes and holds sources. The session releases the sources it registered, never the engine. */
|
|
1389
|
+
readonly engine: ImageEngine;
|
|
1390
|
+
/** Renders and encodes exports, over the same engine's sources. */
|
|
1391
|
+
readonly processor: ImageProcessor;
|
|
1392
|
+
/** The host's limits, over `imageLimits`' defaults (ADR 0004). */
|
|
1393
|
+
readonly filePolicy?: ImageFilePolicyOverrides;
|
|
1394
|
+
readonly onEvent?: (event: ImageSessionEvent) => void;
|
|
1395
|
+
}
|
|
1396
|
+
|
|
1397
|
+
/**
|
|
1398
|
+
* The session's state, for `useSyncExternalStore`: a new object on every
|
|
1399
|
+
* change (ADR 0003).
|
|
1400
|
+
*
|
|
1401
|
+
* @public
|
|
1402
|
+
*/
|
|
1403
|
+
export declare interface ImageSessionSnapshot {
|
|
1404
|
+
/** `empty` until a file opens; `opening` while the first one is; then `ready`. */
|
|
1405
|
+
readonly status: "empty" | "opening" | "ready";
|
|
1406
|
+
/** The document, or `null` before a file is open. */
|
|
1407
|
+
readonly plan: ImagePlan | null;
|
|
1408
|
+
/** The document's source, or `null` before a file is open. */
|
|
1409
|
+
readonly source: ImageSessionSource | null;
|
|
1410
|
+
readonly canUndo: boolean;
|
|
1411
|
+
readonly canRedo: boolean;
|
|
1412
|
+
/** Whether a file is being opened. The current document stays until it's ready. */
|
|
1413
|
+
readonly opening: boolean;
|
|
1414
|
+
/** Whether an export is in progress. */
|
|
1415
|
+
readonly exporting: boolean;
|
|
1416
|
+
/** The limits the last open, edit or export came near: at or above their warnings. */
|
|
1417
|
+
readonly warnings: readonly ImageLimitName[];
|
|
1418
|
+
/** The last failure, until the next successful open, edit or export. */
|
|
1419
|
+
readonly error: ImageError | null;
|
|
1420
|
+
}
|
|
1421
|
+
|
|
1422
|
+
/**
|
|
1423
|
+
* The document's source, as the editor shows it: its size and format, and
|
|
1424
|
+
* what metadata the file carried, which the export summary reports as
|
|
1425
|
+
* removed unless the user kept it (ADR 0005).
|
|
1426
|
+
*
|
|
1427
|
+
* @public
|
|
1428
|
+
*/
|
|
1429
|
+
export declare interface ImageSessionSource extends ImageSourceInfo {
|
|
1430
|
+
/** The file's size in bytes, as it was opened. Never its name. */
|
|
1431
|
+
readonly fileSize: number;
|
|
1432
|
+
/** Which kinds of metadata the file carried, never their values. */
|
|
1433
|
+
readonly metadata: ImageMetadataPresence;
|
|
1434
|
+
/** The fields the user may choose to keep, as the file had them. */
|
|
1435
|
+
readonly keepable: ImageKeepableMetadata;
|
|
1436
|
+
}
|
|
1437
|
+
|
|
1438
|
+
/**
|
|
1439
|
+
* A width and a height, in whole pixels.
|
|
1440
|
+
*
|
|
1441
|
+
* @public
|
|
1442
|
+
*/
|
|
1443
|
+
export declare interface ImageSize {
|
|
1444
|
+
readonly width: number;
|
|
1445
|
+
readonly height: number;
|
|
1446
|
+
}
|
|
1447
|
+
|
|
1448
|
+
/**
|
|
1449
|
+
* A source the session holds, without its pixels: what the snapshot shows
|
|
1450
|
+
* (ADR 0003). Its size is the oriented size.
|
|
1451
|
+
*
|
|
1452
|
+
* @public
|
|
1453
|
+
*/
|
|
1454
|
+
export declare interface ImageSourceInfo {
|
|
1455
|
+
readonly id: string;
|
|
1456
|
+
readonly format: ImageFormat;
|
|
1457
|
+
readonly width: number;
|
|
1458
|
+
readonly height: number;
|
|
1459
|
+
readonly frames: number;
|
|
1460
|
+
readonly hasAlpha: boolean;
|
|
1461
|
+
/** The bytes the decoded source takes in the worker: frames × width × height × 4. */
|
|
1462
|
+
readonly decodedBytes: number;
|
|
1463
|
+
}
|
|
1464
|
+
|
|
1465
|
+
/**
|
|
1466
|
+
* A small rendering of a source for lists and frame strips. An `ImageBitmap`
|
|
1467
|
+
* is one; tests can supply their own. Close it when it's no longer shown.
|
|
1468
|
+
*
|
|
1469
|
+
* @public
|
|
1470
|
+
*/
|
|
1471
|
+
export declare interface ImageThumbnail {
|
|
1472
|
+
readonly width: number;
|
|
1473
|
+
readonly height: number;
|
|
1474
|
+
close(): void;
|
|
1475
|
+
}
|
|
1476
|
+
|
|
1477
|
+
/**
|
|
1478
|
+
* Where and how the preview is shown: the stage's size in CSS pixels, the
|
|
1479
|
+
* device pixel ratio, and the zoom and pan. At zoom 1 the composition fits
|
|
1480
|
+
* the stage; the pan moves it, in CSS pixels. The view isn't part of the
|
|
1481
|
+
* document (ADR 0003).
|
|
1482
|
+
*
|
|
1483
|
+
* @public
|
|
1484
|
+
*/
|
|
1485
|
+
export declare interface ImageView {
|
|
1486
|
+
readonly width: number;
|
|
1487
|
+
readonly height: number;
|
|
1488
|
+
/**
|
|
1489
|
+
* Device pixels per CSS pixel, such as `devicePixelRatio`. Ratios above
|
|
1490
|
+
* {@link MAX_PIXEL_RATIO} are drawn at it.
|
|
1491
|
+
*/
|
|
1492
|
+
readonly pixelRatio: number;
|
|
1493
|
+
/** 1 fits the composition inside the stage; 2 is twice that. */
|
|
1494
|
+
readonly zoom: number;
|
|
1495
|
+
readonly pan: {
|
|
1496
|
+
readonly x: number;
|
|
1497
|
+
readonly y: number;
|
|
1498
|
+
};
|
|
1499
|
+
/**
|
|
1500
|
+
* CSS pixels the fitted composition keeps clear inside each edge of the
|
|
1501
|
+
* stage, such as room for the crop frame's handles, which would otherwise
|
|
1502
|
+
* be cut off where the image meets the stage's edge. 0 when omitted.
|
|
1503
|
+
*/
|
|
1504
|
+
readonly inset?: number;
|
|
1505
|
+
}
|
|
1506
|
+
|
|
1507
|
+
/**
|
|
1508
|
+
* Checks whether a value is an {@link ImageError}, optionally with a given
|
|
1509
|
+
* code.
|
|
1510
|
+
*
|
|
1511
|
+
* Unlike `instanceof`, it recognises errors from another copy of this
|
|
1512
|
+
* package or another realm, and errors rebuilt after crossing a worker
|
|
1513
|
+
* boundary.
|
|
1514
|
+
*
|
|
1515
|
+
* @param value - Any thrown value.
|
|
1516
|
+
* @param code - When given, the error must also have this code.
|
|
1517
|
+
* @public
|
|
1518
|
+
*/
|
|
1519
|
+
export declare function isImageError<Code extends ImageErrorCode = ImageErrorCode>(value: unknown, code?: Code): value is ImageError & {
|
|
1520
|
+
readonly code: Code;
|
|
1521
|
+
};
|
|
1522
|
+
|
|
1523
|
+
/**
|
|
1524
|
+
* The longest a kept metadata value may be, in Unicode code points, as JSON
|
|
1525
|
+
* Schema and every language count them (ADR 0005, sdk-core ADR 0045).
|
|
1526
|
+
*
|
|
1527
|
+
* @public
|
|
1528
|
+
*/
|
|
1529
|
+
export declare const MAX_METADATA_LENGTH = 2000;
|
|
1530
|
+
|
|
1531
|
+
/**
|
|
1532
|
+
* The highest device pixel ratio the preview draws at. A larger ratio is
|
|
1533
|
+
* drawn at this one: no display needs more, and it bounds the canvas a
|
|
1534
|
+
* runaway layout can ask for.
|
|
1535
|
+
*
|
|
1536
|
+
* @public
|
|
1537
|
+
*/
|
|
1538
|
+
export declare const MAX_PIXEL_RATIO = 4;
|
|
1539
|
+
|
|
1540
|
+
/**
|
|
1541
|
+
* A crop moved by whole pixels, kept inside the source.
|
|
1542
|
+
*
|
|
1543
|
+
* @public
|
|
1544
|
+
*/
|
|
1545
|
+
export declare function moveCrop(crop: ImageCrop, dx: number, dy: number, source: ImageSize): ImageCrop;
|
|
1546
|
+
|
|
1547
|
+
/**
|
|
1548
|
+
* Every adjustment at 0: the base as it was decoded.
|
|
1549
|
+
*
|
|
1550
|
+
* @public
|
|
1551
|
+
*/
|
|
1552
|
+
export declare const NEUTRAL_DEVELOP: ImageDevelop;
|
|
1553
|
+
|
|
1554
|
+
/**
|
|
1555
|
+
* Metadata presence with nothing present.
|
|
1556
|
+
*
|
|
1557
|
+
* @public
|
|
1558
|
+
*/
|
|
1559
|
+
export declare const NO_METADATA: ImageMetadataPresence;
|
|
1560
|
+
|
|
1561
|
+
/**
|
|
1562
|
+
* Moves or resizes a crop from the keyboard as it's seen on screen
|
|
1563
|
+
* (docs/adr/0007): an arrow moves it that way on screen, by `step` pixels of
|
|
1564
|
+
* the source; with `resize`, Left and Right move its right edge on screen,
|
|
1565
|
+
* and Up and Down its bottom edge, keeping a ratio if one is set.
|
|
1566
|
+
*
|
|
1567
|
+
* @public
|
|
1568
|
+
*/
|
|
1569
|
+
export declare function nudgeCropOnScreen(crop: ImageCrop, key: "ArrowLeft" | "ArrowRight" | "ArrowUp" | "ArrowDown", step: number, resize: boolean, orientation: ImageOrientation_2, source: ImageSize, ratio?: number): ImageCrop;
|
|
1570
|
+
|
|
1571
|
+
/**
|
|
1572
|
+
* The upright size of stored pixels with an EXIF orientation: orientations 5
|
|
1573
|
+
* to 8 swap width and height (ADR 0005).
|
|
1574
|
+
*
|
|
1575
|
+
* @public
|
|
1576
|
+
*/
|
|
1577
|
+
export declare function orientedSize(stored: ImageSize, orientation: ExifOrientation): ImageSize;
|
|
1578
|
+
|
|
1579
|
+
/**
|
|
1580
|
+
* The limits an export's output canvas is checked against before it's
|
|
1581
|
+
* allocated: its longest side and its pixels (ADR 0004).
|
|
1582
|
+
*
|
|
1583
|
+
* @public
|
|
1584
|
+
*/
|
|
1585
|
+
export declare const OUTPUT_LIMITS: readonly ["maxImageDimension", "maxImagePixels"];
|
|
1586
|
+
|
|
1587
|
+
/**
|
|
1588
|
+
* The size an export produces: the composition scaled down or fitted inside
|
|
1589
|
+
* a box, never enlarged, rounded to whole pixels and at least 1 × 1.
|
|
1590
|
+
*
|
|
1591
|
+
* @public
|
|
1592
|
+
*/
|
|
1593
|
+
export declare function outputSize(output: ImageOutput, composition: ImageSize): ImageSize;
|
|
1594
|
+
|
|
1595
|
+
/**
|
|
1596
|
+
* The limits that apply to one file on its own, which the engine checks
|
|
1597
|
+
* against its own probe before it decodes anything (ADR 0004).
|
|
1598
|
+
*
|
|
1599
|
+
* @public
|
|
1600
|
+
*/
|
|
1601
|
+
export declare const PER_FILE_LIMITS: readonly ["maxFileSize", "maxImageDimension", "maxImagePixels", "maxFrames", "maxDecodedSize"];
|
|
1602
|
+
|
|
1603
|
+
/**
|
|
1604
|
+
* Where a composition of this size is shown on the stage for a view, in the
|
|
1605
|
+
* stage's CSS pixels: fitted, zoomed, centred and panned. The renderer draws
|
|
1606
|
+
* there, and the editor's crop frame and handles are placed with it, so the
|
|
1607
|
+
* DOM over the canvas lines up with its pixels (ADR 0002).
|
|
1608
|
+
*
|
|
1609
|
+
* @public
|
|
1610
|
+
*/
|
|
1611
|
+
export declare function placement(composition: {
|
|
1612
|
+
readonly width: number;
|
|
1613
|
+
readonly height: number;
|
|
1614
|
+
}, view: ImageView): {
|
|
1615
|
+
readonly x: number;
|
|
1616
|
+
readonly y: number;
|
|
1617
|
+
readonly width: number;
|
|
1618
|
+
readonly height: number;
|
|
1619
|
+
readonly scale: number;
|
|
1620
|
+
};
|
|
1621
|
+
|
|
1622
|
+
/**
|
|
1623
|
+
* Reads a plan document, such as one parsed from JSON, checking it as
|
|
1624
|
+
* {@link ImagePlanDocument}'s schema does and more: the base's source must
|
|
1625
|
+
* be one the document lists, and its crop must fit inside it. Unknown fields
|
|
1626
|
+
* are refused, never dropped.
|
|
1627
|
+
*
|
|
1628
|
+
* @param value - The parsed JSON.
|
|
1629
|
+
* @returns The plan, and its sources by id.
|
|
1630
|
+
* @throws `ImageError` with `UNSUPPORTED_FORMAT` for another format or a
|
|
1631
|
+
* later version, and `INVALID_DOCUMENT` for anything else that's wrong,
|
|
1632
|
+
* with an {@link ImageDocumentRejection} as `details.reason`.
|
|
1633
|
+
* @public
|
|
1634
|
+
*/
|
|
1635
|
+
export declare function readImagePlanDocument(value: unknown): {
|
|
1636
|
+
readonly plan: ImagePlan;
|
|
1637
|
+
readonly sources: Readonly<Record<string, ImagePlanDocumentSource>>;
|
|
1638
|
+
};
|
|
1639
|
+
|
|
1640
|
+
/**
|
|
1641
|
+
* Sets or removes the base's crop, in whole pixels of the oriented source.
|
|
1642
|
+
*
|
|
1643
|
+
* @public
|
|
1644
|
+
*/
|
|
1645
|
+
export declare interface SetCropCommand {
|
|
1646
|
+
readonly type: "image.setCrop";
|
|
1647
|
+
readonly crop: ImageCrop | null;
|
|
1648
|
+
}
|
|
1649
|
+
|
|
1650
|
+
/**
|
|
1651
|
+
* Sets some of the base's develop adjustments; the others keep their values
|
|
1652
|
+
* (ADR 0006).
|
|
1653
|
+
*
|
|
1654
|
+
* @public
|
|
1655
|
+
*/
|
|
1656
|
+
export declare interface SetDevelopCommand {
|
|
1657
|
+
readonly type: "image.setDevelop";
|
|
1658
|
+
readonly values: Partial<ImageDevelop>;
|
|
1659
|
+
}
|
|
1660
|
+
|
|
1661
|
+
/**
|
|
1662
|
+
* Sets the base's filter preset and strength, or removes it with `null`.
|
|
1663
|
+
*
|
|
1664
|
+
* @public
|
|
1665
|
+
*/
|
|
1666
|
+
export declare interface SetFilterCommand {
|
|
1667
|
+
readonly type: "image.setFilter";
|
|
1668
|
+
readonly filter: ImageFilter | null;
|
|
1669
|
+
}
|
|
1670
|
+
|
|
1671
|
+
/**
|
|
1672
|
+
* Sets one metadata field to keep on export. An empty value keeps nothing.
|
|
1673
|
+
*
|
|
1674
|
+
* @public
|
|
1675
|
+
*/
|
|
1676
|
+
export declare interface SetMetadataCommand {
|
|
1677
|
+
readonly type: "image.setMetadata";
|
|
1678
|
+
readonly field: keyof ImageKeepableMetadata;
|
|
1679
|
+
readonly value: string;
|
|
1680
|
+
}
|
|
1681
|
+
|
|
1682
|
+
/**
|
|
1683
|
+
* Sets the base's rotation and flips.
|
|
1684
|
+
*
|
|
1685
|
+
* @public
|
|
1686
|
+
*/
|
|
1687
|
+
export declare interface SetOrientationCommand {
|
|
1688
|
+
readonly type: "image.setOrientation";
|
|
1689
|
+
readonly orientation: ImageOrientation_2;
|
|
1690
|
+
}
|
|
1691
|
+
|
|
1692
|
+
/**
|
|
1693
|
+
* Sets the export's size.
|
|
1694
|
+
*
|
|
1695
|
+
* @public
|
|
1696
|
+
*/
|
|
1697
|
+
export declare interface SetOutputCommand {
|
|
1698
|
+
readonly type: "image.setOutput";
|
|
1699
|
+
readonly output: ImageOutput;
|
|
1700
|
+
}
|
|
1701
|
+
|
|
1702
|
+
/**
|
|
1703
|
+
* Maps a point in the cropped source to the composition, through the plan's
|
|
1704
|
+
* rotation and then its flips. Points are continuous coordinates, so the
|
|
1705
|
+
* cropped rectangle's corners map to the composition's corners.
|
|
1706
|
+
*
|
|
1707
|
+
* @public
|
|
1708
|
+
*/
|
|
1709
|
+
export declare function sourceToComposition(point: ImagePoint, crop: ImageCrop, orientation: ImageOrientation_2): ImagePoint;
|
|
1710
|
+
|
|
1711
|
+
/**
|
|
1712
|
+
* Writes a plan as an {@link ImagePlanDocument}, plain JSON-ready data.
|
|
1713
|
+
*
|
|
1714
|
+
* @param plan - The plan.
|
|
1715
|
+
* @param sources - The sources by id, with at least the base's. They're
|
|
1716
|
+
* written as given.
|
|
1717
|
+
* @throws `TypeError` if the base's source is missing from `sources`.
|
|
1718
|
+
* @public
|
|
1719
|
+
*/
|
|
1720
|
+
export declare function toImagePlanDocument(plan: ImagePlan, sources: Readonly<Record<string, ImagePlanDocumentSource>>): ImagePlanDocument;
|
|
1721
|
+
|
|
1722
|
+
/**
|
|
1723
|
+
* No rotation and no flips.
|
|
1724
|
+
*
|
|
1725
|
+
* @public
|
|
1726
|
+
*/
|
|
1727
|
+
export declare const UPRIGHT: ImageOrientation_2;
|
|
1728
|
+
|
|
1729
|
+
export { }
|