dcmnorm 0.0.0 → 0.12.1

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.
Files changed (5) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +231 -2
  3. package/index.d.ts +785 -0
  4. package/index.js +866 -0
  5. package/package.json +57 -3
package/index.d.ts ADDED
@@ -0,0 +1,785 @@
1
+ /* auto-generated by NAPI-RS */
2
+ /* eslint-disable */
3
+
4
+ /**
5
+ * Which binding artifact the generated loader actually loaded: `'native'` for
6
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
7
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
8
+ * can point the loader at a WASI artifact this package does not build itself.
9
+ */
10
+ export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
11
+
12
+ export declare class DicomServerHandle {
13
+ get localPort(): number
14
+ /**
15
+ * Stops accepting new associations and waits for the listener to shut down. Associations
16
+ * already in progress finish independently (or hit their own idle timeout) - this does not
17
+ * interrupt them. Safe to call more than once.
18
+ */
19
+ close(): void
20
+ }
21
+
22
+ export declare class DicomVolumeHandle {
23
+ /** Rows in the source slices (image height). */
24
+ get rows(): number
25
+ /** Columns in the source slices (image width). */
26
+ get cols(): number
27
+ /** Number of slices in the built volume. */
28
+ get numSlices(): number
29
+ /**
30
+ * Bytes of voxel memory this volume holds (native memory, invisible to the JS heap), until
31
+ * `release()`.
32
+ */
33
+ get byteLength(): number
34
+ /** Whether `release()` has run. */
35
+ get released(): boolean
36
+ /**
37
+ * Frees the voxel memory now instead of whenever the garbage collector finalizes this
38
+ * handle (which can be much later: the JS heap doesn't see native memory). Calls already
39
+ * running finish first; `reformat`/`exportTexture` afterwards throw. Idempotent.
40
+ */
41
+ release(): void
42
+ /**
43
+ * The volume's own acquisition-native orientation, for seeding an "axial" reformat -
44
+ * `[rowDir(3), colDir(3)]`.
45
+ */
46
+ get nativeBasis(): Array<number>
47
+ /** The volume's own physical center, in patient/LPS mm - a reasonable default reformat origin. */
48
+ get center(): Array<number>
49
+ /** The volume's own smallest voxel dimension, in mm - a reasonable default output spacing. */
50
+ get minSpacingMm(): number
51
+ /**
52
+ * Resamples one plane through this volume and encodes it exactly like a normal 2D render
53
+ * (same `RenderedFrame` shape `renderFrame` returns), so callers can reuse their existing
54
+ * image-display code path unchanged.
55
+ */
56
+ reformat(options: ReformatPlaneOptions): Promise<unknown>
57
+ /**
58
+ * Packs this volume's own NATIVE voxel lattice - not a resampled oblique plane, see
59
+ * `exportTexture`'s own doc - as a lossless GPU-upload-ready texture payload (16-bit
60
+ * samples, row-major, optionally gzip-compressed). Unlike `reformat()`, this is a one-shot
61
+ * call per volume, not one per interaction: the render-server ships the returned `data`
62
+ * once and the client does all further rotate/scroll/window-level manipulation itself in a
63
+ * WebGL2 shader.
64
+ */
65
+ exportTexture(options?: ExportVolumeTextureOptions | undefined | null): Promise<unknown>
66
+ }
67
+
68
+ export declare class EchoScuHandle {
69
+ /** The eventual Status code (0 = success), without requesting cancellation. */
70
+ result(): Promise<number>
71
+ /**
72
+ * Requests a graceful A-RELEASE and resolves once the association has genuinely closed -
73
+ * real acknowledgement, not a fire-and-forget signal. Idempotent.
74
+ */
75
+ release(): Promise<number>
76
+ /**
77
+ * Requests an immediate A-ABORT (no wait on the peer at all) and resolves once the
78
+ * association has genuinely closed. Idempotent.
79
+ */
80
+ abort(): Promise<number>
81
+ }
82
+
83
+ export declare class FindScuHandle {
84
+ /**
85
+ * The eventual matched Identifiers (flat/hex-keyed DICOM JSON, one per match), without
86
+ * requesting cancellation.
87
+ */
88
+ result(): Promise<Array<string>>
89
+ /**
90
+ * Requests a graceful A-RELEASE and resolves once the association has genuinely closed -
91
+ * real acknowledgement, not a fire-and-forget signal. Idempotent.
92
+ */
93
+ release(): Promise<Array<string>>
94
+ /**
95
+ * Requests an immediate A-ABORT (no wait on the peer at all) and resolves once the
96
+ * association has genuinely closed. Idempotent.
97
+ */
98
+ abort(): Promise<Array<string>>
99
+ }
100
+
101
+ export declare class MoveScuHandle {
102
+ /**
103
+ * The eventual terminal `MoveScuResult`, without requesting cancellation - for a caller
104
+ * that just wants to await completion.
105
+ */
106
+ result(): Promise<MoveScuResult>
107
+ /**
108
+ * Requests a graceful A-RELEASE and resolves once the association has genuinely closed -
109
+ * real acknowledgement, not a fire-and-forget signal that might land seconds later (or
110
+ * never, if missed). Idempotent: a second call just observes the same outcome.
111
+ */
112
+ release(): Promise<MoveScuResult>
113
+ /**
114
+ * Requests an immediate A-ABORT (no wait on the peer at all) and resolves once the
115
+ * association has genuinely closed. Idempotent.
116
+ */
117
+ abort(): Promise<MoveScuResult>
118
+ }
119
+
120
+ export declare class StoreScuHandle {
121
+ /**
122
+ * The eventual per-file `{sopInstanceUid, status}` results, without requesting
123
+ * cancellation.
124
+ */
125
+ result(): Promise<Array<StoreScuResult>>
126
+ /**
127
+ * Requests a graceful A-RELEASE and resolves once the association has genuinely closed -
128
+ * real acknowledgement, not a fire-and-forget signal. Idempotent.
129
+ */
130
+ release(): Promise<Array<StoreScuResult>>
131
+ /**
132
+ * Requests an immediate A-ABORT (no wait on the peer at all) and resolves once the
133
+ * association has genuinely closed. Idempotent.
134
+ */
135
+ abort(): Promise<Array<StoreScuResult>>
136
+ }
137
+
138
+ /**
139
+ * Builds a 3D volume from a parallel stack of DICOM slice files (e.g. every image instance in
140
+ * one CT/MR/PT series) sharing consistent `ImageOrientationPatient`. Slices are spatially
141
+ * re-sorted internally by `ImagePositionPatient`, regardless of `filePaths`' own order. Returns a
142
+ * `DicomVolumeHandle` for repeated `reformat()` calls. Rejects (rather than silently
143
+ * mis-rendering) fewer than 2 files, mismatched Rows/Columns, or a non-parallel/gantry-tilt-
144
+ * inconsistent stack.
145
+ */
146
+ export declare function buildVolume(filePaths: Array<string>): Promise<unknown>
147
+
148
+ /**
149
+ * Reports whether a file looks like valid DICOM. Mirrors `dcmnorm
150
+ * --check-dicom`.
151
+ */
152
+ export declare function checkDicom(filePath: string): Promise<unknown>
153
+
154
+ /**
155
+ * Computes a pixel-value histogram for every frame of a DICOM file (or just one, via
156
+ * `options.frameIndex`). Mirrors `dcmnorm --histogram --histogram-bins ... file.dcm`.
157
+ */
158
+ export declare function computeHistogram(filePath: string, options?: HistogramOptions | undefined | null): Promise<unknown>
159
+
160
+ /**
161
+ * One file of the File-set for `writeDicomdir`: its File ID plus its header, either as DICOM
162
+ * JSON (`json`) or a file to read it from (`path`; pixel data isn't loaded).
163
+ */
164
+ export interface DicomdirEntry {
165
+ /**
166
+ * File ID components, e.g. `["DICOM", "ST000001", "SE000001", "IM000001"]`: 1-8
167
+ * components of 1-8 characters from A-Z, 0-9 and _ (PS3.10 8.2).
168
+ */
169
+ fileId: Array<string>
170
+ /**
171
+ * The referenced file's DICOM JSON (what `readJson` returns; BulkDataURI elements are
172
+ * ignored). One of `json` and `path` is required.
173
+ */
174
+ json?: string
175
+ /** 'flat' (default, `readJson`'s default) or 'standard', for `json`. */
176
+ format?: string
177
+ /** A DICOM file to read the header from instead of `json`. */
178
+ path?: string
179
+ /**
180
+ * The referenced file's transfer syntax. With `json`, defaults to the JSON's
181
+ * TransferSyntaxUID (0002,0010), else Explicit VR Little Endian; with `path`, the file's.
182
+ */
183
+ transferSyntaxUid?: string
184
+ }
185
+
186
+ export interface DicomdirRecordCount {
187
+ recordType: string
188
+ count: number
189
+ }
190
+
191
+ /**
192
+ * A value `writeDicomdir` made up (or copied from another attribute) for a Type 1 key the
193
+ * instances lacked (IHE RAD TF-2 Table 4.47.4-1).
194
+ */
195
+ export interface DicomdirSynthesized {
196
+ /** e.g. "STUDY". */
197
+ recordType: string
198
+ /**
199
+ * The Study/Series/SOP Instance UID; for PATIENT the patient's name, or "patient of
200
+ * study <UID>" when the patient has no name either.
201
+ */
202
+ entity: string
203
+ /** Attribute keyword, e.g. "StudyID". */
204
+ attribute: string
205
+ value: string
206
+ /** Keyword of the instance attribute it was copied from, if any (e.g. "SeriesDate"). */
207
+ source?: string
208
+ }
209
+
210
+ /**
211
+ * Performs a C-ECHO (DICOM Verification) against `destination` ("host:port"). Resolves with the
212
+ * response Status code (0 = success); rejects only if the association itself could not be
213
+ * established (unreachable host, no accepted presentation context, etc). `onLog`, if given, is
214
+ * called (synchronously, no return value expected) with a debug line for each notable DIMSE
215
+ * event - association open/close, the request sent, the response received.
216
+ */
217
+ export declare function echoScu(destination: string, options?: EchoScuOptions | undefined | null, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): Promise<unknown>
218
+
219
+ export interface EchoScuOptions {
220
+ callingAeTitle?: string
221
+ calledAeTitle?: string
222
+ timeoutMs?: number
223
+ }
224
+
225
+ /**
226
+ * Sets/removes DICOM attributes, optionally stripping private tags. Mirrors
227
+ * `dcmnorm --set KEY=VALUE --remove KEY --remove-private-tags`. Writes back
228
+ * to `file_path` in place unless `options.output_path` is given.
229
+ */
230
+ export declare function editTags(filePath: string, options?: EditTagsOptions | undefined | null): Promise<unknown>
231
+
232
+ export interface EditTagsOptions {
233
+ outputPath?: string
234
+ set?: Record<string, string>
235
+ remove?: Array<string>
236
+ removePrivateTags?: boolean
237
+ }
238
+
239
+ /**
240
+ * Packs several independent frames (from one or more files) as one texture-array upload - see
241
+ * `dcmnorm::dicom_io::pack_frame_stack_texture`'s own doc for the full contract (no resampling,
242
+ * no cross-layer interpolation, no physical geometry). Mirrors `exportFrameTexture`'s
243
+ * options/result shape, generalized to many sources.
244
+ */
245
+ export declare function exportFrameStackTexture(sources: Array<FrameStackSource>, options?: ExportFrameStackTextureOptions | undefined | null): Promise<unknown>
246
+
247
+ export interface ExportFrameStackTextureOptions {
248
+ /** 'gzip' (default) or 'none'. */
249
+ compression?: string
250
+ windowCenter?: number
251
+ windowWidth?: number
252
+ }
253
+
254
+ /**
255
+ * Color counterpart to `exportFrameStackTexture` - packs several independent color frames as one
256
+ * `rgb8` texture-array upload. Same options/result shape (minus window, which color never has).
257
+ */
258
+ export declare function exportFrameStackTextureRgb(sources: Array<FrameStackSource>, options?: ExportFrameStackTextureRgbOptions | undefined | null): Promise<unknown>
259
+
260
+ export interface ExportFrameStackTextureRgbOptions {
261
+ /** 'gzip' (default) or 'none'. */
262
+ compression?: string
263
+ }
264
+
265
+ /**
266
+ * Packs a single frame's raw (unwindowed) physical values as a depth-1 "1-slice volume" texture
267
+ * - lets a large diagnostic 2D image (e.g. DX/CR/mammography) reuse the exact same client GPU
268
+ * texture/shader pipeline as an MPR volume, instead of the lossy zoomed-JPEG path `renderFrame`
269
+ * produces. Mirrors `dcmnorm --render-frame ... --output-type texture file.dcm out.gputex`.
270
+ */
271
+ export declare function exportFrameTexture(filePath: string, options?: ExportFrameTextureOptions | undefined | null): Promise<unknown>
272
+
273
+ export interface ExportFrameTextureOptions {
274
+ /** Zero-based frame index for a multi-frame file. Defaults to 0. */
275
+ frameIndex?: number
276
+ targetMaxDim?: number
277
+ /** 'gzip' (default) or 'none'. */
278
+ compression?: string
279
+ windowCenter?: number
280
+ windowWidth?: number
281
+ }
282
+
283
+ /**
284
+ * Color counterpart to `exportFrameTexture` - packs a single color frame (RGB/YBR variants, or
285
+ * PALETTE COLOR) as an `rgb8` depth-1 texture instead of a quantized grayscale one. Same
286
+ * result shape (`TextureExportResult`), no window options (color is never windowed).
287
+ */
288
+ export declare function exportFrameTextureRgb(filePath: string, options?: ExportFrameTextureRgbOptions | undefined | null): Promise<unknown>
289
+
290
+ export interface ExportFrameTextureRgbOptions {
291
+ /** Zero-based frame index for a multi-frame file. Defaults to 0. */
292
+ frameIndex?: number
293
+ targetMaxDim?: number
294
+ /** 'gzip' (default) or 'none'. */
295
+ compression?: string
296
+ }
297
+
298
+ export interface ExportVolumeTextureOptions {
299
+ /**
300
+ * Caps the longest of width/height/depth at this many samples, proportionally downsampling
301
+ * (trilinear) if the native volume exceeds it. Omitted means no cap (full native
302
+ * resolution) - the caller (render-server) is expected to derive this from the client's
303
+ * reported `MAX_3D_TEXTURE_SIZE`, or from a small fixed value for a fast "progressive"
304
+ * first pass ahead of the full-resolution texture.
305
+ */
306
+ targetMaxDim?: number
307
+ /** 'gzip' (default) or 'none'. */
308
+ compression?: string
309
+ /**
310
+ * Optional default window/level to carry through to `TextureExportResult.defaultWindowCenter`
311
+ * /`defaultWindowWidth` - purely informational for the client's initial render, since the
312
+ * exported samples themselves are never windowed.
313
+ */
314
+ windowCenter?: number
315
+ windowWidth?: number
316
+ }
317
+
318
+ /**
319
+ * Performs a C-FIND (Study Root Query/Retrieve) against `destination` ("host:port"). `query`
320
+ * values: empty string is a universal-match "return key" (mirrors findscu's bare `-k TAG`),
321
+ * non-empty constrains the match (mirrors `-k TAG=value`); `QueryRetrieveLevel` defaults to
322
+ * `"STUDY"` if not given. Resolves with one flat/hex-keyed DICOM JSON string per match (parse
323
+ * JS-side, same shape as `readJson({format: "flat", keyStyle: "hex"})`). `onLog`, if given, is
324
+ * called (synchronously, no return value expected) with a debug line for each notable DIMSE
325
+ * event - association open/close, and each C-FIND-RQ/RSP (query values are not logged, only the
326
+ * tag keys queried, since the Identifier commonly carries PHI).
327
+ */
328
+ export declare function findScu(destination: string, query: Record<string, string>, options?: FindScuOptions | undefined | null, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): Promise<unknown>
329
+
330
+ export interface FindScuOptions {
331
+ callingAeTitle?: string
332
+ calledAeTitle?: string
333
+ maxPduLength?: number
334
+ timeoutMs?: number
335
+ }
336
+
337
+ /** Mirrors `dcmnorm::dicom_io::FrameHistogram` for the JS side. */
338
+ export interface FrameHistogram {
339
+ frameIndex: number
340
+ /**
341
+ * `null` for a grayscale frame. `"red" | "green" | "blue"` for one channel of an RGB/color
342
+ * frame - `computeHistogram` returns three entries per frame for those, all sharing the same
343
+ * `frameIndex`, each over that channel's own decoded 8-bit (0-255) samples.
344
+ */
345
+ channel?: string
346
+ binCount: number
347
+ rangeMin: number
348
+ rangeMax: number
349
+ binWidth: number
350
+ counts: Array<number>
351
+ pixelCount: number
352
+ minValue: number
353
+ maxValue: number
354
+ mean: number
355
+ stdDev: number
356
+ }
357
+
358
+ export interface FrameStackSource {
359
+ filePath: string
360
+ /** Zero-based frame indices to include from this file, in order. Defaults to `[0]`. */
361
+ frameIndices?: Array<number>
362
+ }
363
+
364
+ export interface HistogramOptions {
365
+ /** Number of bins per frame histogram. Defaults to 256. */
366
+ binCount?: number
367
+ /** Compute only this zero-based frame's histogram, instead of every frame in the instance. */
368
+ frameIndex?: number
369
+ /**
370
+ * Lower bound of the binned value range. Defaults to each frame's own observed minimum.
371
+ * Must be set together with `maxValue`.
372
+ */
373
+ minValue?: number
374
+ /**
375
+ * Upper bound of the binned value range. Defaults to each frame's own observed maximum.
376
+ * Must be set together with `minValue`.
377
+ */
378
+ maxValue?: number
379
+ }
380
+
381
+ /**
382
+ * Performs a C-MOVE (Study Root Query/Retrieve), asking `destination` ("host:port") to push
383
+ * `studyInstanceUid` - or one series of it / a list of its instances, per
384
+ * `options.queryRetrieveLevel` - to `moveDestinationAe` (an AE title `destination` already knows how to
385
+ * reach, not a socket address). Returns a handle immediately - the retrieve itself runs on its
386
+ * own background thread - rather than blocking until it reaches a terminal status; call
387
+ * `.result()` to await that terminal status and sub-operation counts (regardless of
388
+ * success/warning/failure, mirroring the old behavior), or `.release()`/`.abort()` to close it
389
+ * early once some other signal (e.g. the study already being confirmed fully received via a
390
+ * separate channel) makes further waiting pointless. See `MoveScuHandle`.
391
+ *
392
+ * `onLog`, if given, is called (synchronously, no return value expected) with a debug line for
393
+ * each notable DIMSE event - association open/close, and each C-MOVE-RQ/RSP (including every
394
+ * pending response, so a slow multi-instance move is visible sub-operation by sub-operation).
395
+ */
396
+ export declare function moveScu(destination: string, moveDestinationAe: string, studyInstanceUid: string, options?: MoveScuOptions | undefined | null, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): MoveScuHandle
397
+
398
+ export interface MoveScuOptions {
399
+ callingAeTitle?: string
400
+ calledAeTitle?: string
401
+ maxPduLength?: number
402
+ /** Absolute ceiling (connect through release) for the whole call - not reset by activity. */
403
+ timeoutMs?: number
404
+ /**
405
+ * Directory to watch for local write progress (e.g. this retrieve's own cache destination)
406
+ * - see `staleDataTimeoutMs`. Both must be set for the watch to run.
407
+ */
408
+ watchPath?: string
409
+ /**
410
+ * How long `watchPath` may go without a new/modified file before the connection is
411
+ * considered stale and aborted - independent of, and typically much shorter than,
412
+ * `timeoutMs`.
413
+ */
414
+ staleDataTimeoutMs?: number
415
+ /**
416
+ * `"STUDY"` (default: the whole study, same Identifier as before this option existed),
417
+ * `"SERIES"` (needs `seriesInstanceUid`) or `"IMAGE"` (needs `seriesInstanceUid` and a
418
+ * non-empty `sopInstanceUids`). An invalid combination rejects `.result()` without opening
419
+ * an association.
420
+ */
421
+ queryRetrieveLevel?: string
422
+ /** SeriesInstanceUID for a `"SERIES"`/`"IMAGE"` retrieve; ignored for `"STUDY"`. */
423
+ seriesInstanceUid?: string
424
+ /**
425
+ * SOPInstanceUIDs for an `"IMAGE"` retrieve, sent as one multi-valued UID list; ignored
426
+ * otherwise.
427
+ */
428
+ sopInstanceUids?: Array<string>
429
+ }
430
+
431
+ export interface MoveScuResult {
432
+ status: number
433
+ completed: number
434
+ failed: number
435
+ warning: number
436
+ remaining: number
437
+ cancelled: boolean
438
+ /**
439
+ * `"release"`/`"abort"` when `cancelled` is true, indicating which teardown verb actually
440
+ * produced it (see `MoveScuHandle.release`/`.abort`) - `null` for a real terminal C-MOVE-RSP.
441
+ */
442
+ cancelledVia?: string
443
+ }
444
+
445
+ /** Mirrors `dcmnorm::dicom_io::OverlaySummary` for the JS side. */
446
+ export interface OverlaySummary {
447
+ index: number
448
+ group: number
449
+ rows: number
450
+ columns: number
451
+ overlayType?: string
452
+ label?: string
453
+ }
454
+
455
+ /**
456
+ * Reads the full DICOM dataset as JSON. Mirrors plain `dcmnorm file.dcm`
457
+ * (flat/name keys, bulk data as a URI reference, by default) or
458
+ * `--format standard --keys hex --bulk-data inline`.
459
+ */
460
+ export declare function readJson(filePath: string, options?: ReadJsonOptions | undefined | null): Promise<unknown>
461
+
462
+ export interface ReadJsonOptions {
463
+ format?: string
464
+ keyStyle?: string
465
+ /**
466
+ * 'uri' (default, matches the CLI) emits PixelData/other bulk elements as a
467
+ * small "?offset=..&length=.." reference; 'inline' base64-embeds them, which
468
+ * for a typical image is orders of magnitude larger.
469
+ */
470
+ bulkData?: string
471
+ /**
472
+ * With format 'standard': omit the non-standard Keyword and VM members, leaving
473
+ * only what PS3.18 Annex F defines (the CLI's `--omit-keyword-vm`). Default false.
474
+ */
475
+ omitKeywordVm?: boolean
476
+ }
477
+
478
+ export declare function readTags(filePath: string, tags: Array<string>): Promise<unknown>
479
+
480
+ export interface ReformatPlaneOptions {
481
+ /** World-space (mm, patient/LPS) point at the CENTER of the reformatted output image. */
482
+ origin: Array<number>
483
+ /** Unit vector: direction of travel across the output image as the column index increases. */
484
+ rowDir: Array<number>
485
+ /** Unit vector: direction of travel down the output image as the row index increases. */
486
+ colDir: Array<number>
487
+ outputWidth: number
488
+ outputHeight: number
489
+ /** Physical size of one output pixel, in mm - the same in both output axes. */
490
+ spacingMm: number
491
+ windowCenter?: number
492
+ windowWidth?: number
493
+ /** 'jpeg' (default) or 'png'. */
494
+ format?: string
495
+ jpegQuality?: number
496
+ /**
497
+ * 'trilinear' (default) or 'nearest' - nearest is faster and intended for a live-drag
498
+ * preview frame, trilinear for the settled/idle frame.
499
+ */
500
+ interpolation?: string
501
+ /**
502
+ * Total slab thickness in mm, centered on `origin` along the plane's own normal. Omitted or
503
+ * 0 reformats an infinitely-thin plane (the original single-voxel-thick MPR behavior).
504
+ */
505
+ slabThicknessMm?: number
506
+ /**
507
+ * How the slab's samples combine when `slabThicknessMm > 0`: 'mip' (default, maximum
508
+ * intensity projection), 'minip' (minimum intensity projection), or 'average'.
509
+ */
510
+ slabProjection?: string
511
+ }
512
+
513
+ export interface RenderedFrame {
514
+ mimeType: string
515
+ width: number
516
+ height: number
517
+ data: Buffer
518
+ /**
519
+ * All overlay planes present on the source instance, regardless of whether one was
520
+ * rendered into `data`.
521
+ */
522
+ overlays: Array<OverlaySummary>
523
+ /** Which overlay (by `OverlaySummary.index`) was actually composited into `data`, if any. */
524
+ selectedOverlayIndex?: number
525
+ /**
526
+ * `true` when `data` is the frame's own original bytes, delivered untouched (see
527
+ * `RenderFrameOptions.passthrough`) - `false` for the ordinary decode/re-encode path,
528
+ * including whenever `passthrough` was requested but the frame didn't qualify.
529
+ */
530
+ passthrough: boolean
531
+ }
532
+
533
+ export interface RenderedMovie {
534
+ mimeType: string
535
+ data: Buffer
536
+ }
537
+
538
+ /**
539
+ * Renders a single frame of a DICOM file to JPEG or PNG. Mirrors `dcmnorm --output-width ...
540
+ * --output-height ... --window-center ... --window-width ... --render-frame ... file.dcm out.jpg`.
541
+ */
542
+ export declare function renderFrame(filePath: string, options?: RenderFrameOptions | undefined | null): Promise<unknown>
543
+
544
+ export interface RenderFrameOptions {
545
+ /** 'jpeg' (default) or 'png'. */
546
+ format?: string
547
+ outputWidth?: number
548
+ outputHeight?: number
549
+ windowCenter?: number
550
+ windowWidth?: number
551
+ frameIndex?: number
552
+ jpegQuality?: number
553
+ /**
554
+ * Whether to composite an overlay plane, when the instance has one. Defaults to `true` -
555
+ * the first available overlay renders by default.
556
+ */
557
+ showOverlays?: boolean
558
+ /**
559
+ * Which overlay to render, by its 0-based `OverlaySummary.index`. Defaults to the first
560
+ * available overlay. Ignored when `showOverlays` is `false`.
561
+ */
562
+ overlayIndex?: number
563
+ /** Fill color for rendered overlay pixels, as `"#RRGGBB"` or `"R,G,B"`. Defaults to green. */
564
+ overlayColor?: string
565
+ /**
566
+ * When `true`, attempts to serve the frame's own original JPEG Baseline bytes untouched
567
+ * (no decode/re-encode) instead of the usual render pipeline - see
568
+ * `try_extract_passthrough_jpeg_frame`'s own doc for the exact eligibility conditions
569
+ * (color, JPEG Baseline source, no overlay, one fragment per frame). Falls through
570
+ * transparently to the ordinary render when any condition isn't met - `RenderedFrame.
571
+ * passthrough` tells the caller which path was actually taken. Defaults to `false`
572
+ * (unset/omitted callers get byte-for-byte identical behavior to before this option existed).
573
+ */
574
+ passthrough?: boolean
575
+ }
576
+
577
+ /**
578
+ * Renders every frame of a multi-frame DICOM file to an MP4 (via a piped `ffmpeg` subprocess -
579
+ * requires `ffmpeg` on `PATH`). Mirrors `dcmnorm --render-fps ... --output-width ... file.dcm out.mp4`.
580
+ */
581
+ export declare function renderMovie(filePath: string, options?: RenderMovieOptions | undefined | null): Promise<unknown>
582
+
583
+ export interface RenderMovieOptions {
584
+ outputWidth?: number
585
+ outputHeight?: number
586
+ windowCenter?: number
587
+ windowWidth?: number
588
+ /** Defaults to 24 (matching the CLI's default when the DICOM file itself specifies no frame rate). */
589
+ fps?: number
590
+ }
591
+
592
+ /**
593
+ * Starts a DICOM SCP (association acceptor) on `port` (0 picks an ephemeral port - see the
594
+ * returned handle's `localPort`), answering C-ECHO, C-STORE, C-FIND, and C-MOVE. C-ECHO and
595
+ * C-STORE are handled entirely natively (C-STORE writes each received instance under
596
+ * `cachePath` as `S_<StudyInstanceUID>/<Modality>_<SOPInstanceUID>.dcm`); C-FIND, C-MOVE, and
597
+ * "association complete" (fired once per association that stored at least one instance) are
598
+ * delegated to the given `async function` callbacks:
599
+ *
600
+ * - `onFind(filterJson)` - `filterJson` has whichever of StudyInstanceUID/StudyDate/
601
+ * PatientName/PatientID keys the request's Identifier actually had values for, plus
602
+ * `AffectedSOPClassUID` (Study Root or Patient Root Query/Retrieve FIND; any other C-FIND,
603
+ * e.g. Modality Worklist, is answered 0x0122 "SOP class not supported" without calling
604
+ * `onFind`). Must resolve
605
+ * to a JSON array of matched-study objects (whichever of StudyInstanceUID/AccessionNumber/
606
+ * PatientID/PatientName/PatientBirthDate/StudyDate/StudyTime/StudyDescription/
607
+ * ModalitiesInStudy/NumberOfStudyRelatedSeries/NumberOfStudyRelatedInstances each has).
608
+ * - `onMove(studyInstanceUid, moveDestinationAe)` - must resolve to `"true"`/`"false"`
609
+ * (JSON-booleans-as-strings) indicating whether the move was successfully queued.
610
+ * - `onAssociationComplete(storedInstancesByStudyJson)` - `storedInstancesByStudyJson` maps
611
+ * each StudyInstanceUID to the on-disk paths of every instance C-STORE'd for it during that
612
+ * association. Return value is ignored.
613
+ *
614
+ * `onLog`, if given, is called (fire-and-forget, from whichever connection thread is handling
615
+ * the association at the time) with a debug-detail line per association accept/negotiation,
616
+ * each request/response, and release/abort - the SCP-side counterpart of `onLog` on
617
+ * `echoScu`/`storeScu`/`findScu`/`moveScu`.
618
+ *
619
+ * Accepts every proposed presentation context regardless of abstract syntax - this is a
620
+ * permissive "accept anything a real sender proposes" SCP, not a curated allow-list. A
621
+ * C-CANCEL-RQ during a C-FIND stops the matches and answers 0xFE00.
622
+ */
623
+ export declare function startDicomServer(port: number, cachePath: string, aeTitle: string, maxPduLength: number | undefined | null, idleTimeoutMs: number | undefined | null, onFind: JsonCallback, onMove: TwoStringCallback, onAssociationComplete: JsonCallback, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): DicomServerHandle
624
+
625
+ /**
626
+ * Same as `echoScu`, but returns immediately with a handle instead of blocking until the
627
+ * C-ECHO completes - lets a caller `abort()`/`release()` it early. See `EchoScuHandle`.
628
+ */
629
+ export declare function startEchoScu(destination: string, options?: EchoScuOptions | undefined | null, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): EchoScuHandle
630
+
631
+ /**
632
+ * Same as `findScu`, but returns immediately with a handle instead of blocking until the
633
+ * C-FIND completes - lets a caller `abort()`/`release()` it early. See `FindScuHandle`.
634
+ */
635
+ export declare function startFindScu(destination: string, query: Record<string, string>, options?: FindScuOptions | undefined | null, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): FindScuHandle
636
+
637
+ /**
638
+ * Same as `storeScu`, but returns immediately with a handle instead of blocking until every
639
+ * file has been sent - lets a caller `abort()`/`release()` it early. See `StoreScuHandle`.
640
+ */
641
+ export declare function startStoreScu(destination: string, files: Array<string>, options?: StoreScuOptions | undefined | null, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): StoreScuHandle
642
+
643
+ /**
644
+ * Sends each of `files` via C-STORE to `destination` ("host:port"). Resolves with one
645
+ * `{sopInstanceUid, status}` per file that could be read and sent - a non-zero Status is just
646
+ * data in the result (the peer rejected that instance), not a rejected Promise; this only
647
+ * rejects if the association itself could not be established, or none of `files` could be read
648
+ * as DICOM at all. `onLog`, if given, is called (synchronously, no return value expected) with a
649
+ * debug line for each notable DIMSE event - association open/close, and each C-STORE-RQ/RSP.
650
+ */
651
+ export declare function storeScu(destination: string, files: Array<string>, options?: StoreScuOptions | undefined | null, onLog?: (((err: Error | null, arg: string) => any)) | undefined | null): Promise<unknown>
652
+
653
+ export interface StoreScuOptions {
654
+ callingAeTitle?: string
655
+ calledAeTitle?: string
656
+ maxPduLength?: number
657
+ neverTranscode?: boolean
658
+ /** Absolute ceiling (connect through release) for the whole call - not reset by activity. */
659
+ timeoutMs?: number
660
+ }
661
+
662
+ export interface StoreScuResult {
663
+ sopInstanceUid: string
664
+ status: number
665
+ }
666
+
667
+ export interface TextureExportResult {
668
+ /** 'volume', 'image2d', or 'framestack'. */
669
+ contentKind: string
670
+ /**
671
+ * 'int16' or 'uint16' for a grayscale texture, 'rgb8' for a color texture (see
672
+ * `exportFrameTextureRgb`/`exportFrameStackTextureRgb`) - `data` is interleaved 8-bit-per-
673
+ * channel RGB in that case, never quantized (`lossless` is unconditionally `true`).
674
+ */
675
+ sampleFormat: string
676
+ /** 'none' or 'gzip' - matches how `data` below is actually encoded. */
677
+ compression: string
678
+ /**
679
+ * `false` means `data` is a bounded-error quantization (see `rescaleSlope`/
680
+ * `rescaleIntercept`), not an exact round-trip of the source samples.
681
+ */
682
+ lossless: boolean
683
+ width: number
684
+ height: number
685
+ /** Always 1 for `contentKind: 'image2d'`. */
686
+ depth: number
687
+ /** `texel * rescaleSlope + rescaleIntercept` recovers the physical value (e.g. HU). */
688
+ rescaleSlope: number
689
+ rescaleIntercept: number
690
+ rowSpacingMm: number
691
+ colSpacingMm: number
692
+ /** `0` for `contentKind: 'image2d'`. */
693
+ sliceSpacingMm: number
694
+ /** `[x, y, z]`, LPS mm, center of voxel (0,0,0). */
695
+ origin: Array<number>
696
+ rowDir: Array<number>
697
+ colDir: Array<number>
698
+ normalDir: Array<number>
699
+ defaultWindowCenter?: number
700
+ defaultWindowWidth?: number
701
+ /**
702
+ * Whether the client shader should display `1.0 - windowedIntensity` rather than
703
+ * `windowedIntensity` - the invert decision `dcmnorm::dicom_io::render::resolve_grayscale_invert`
704
+ * makes (PresentationLUTShape overriding PhotometricInterpretation's MONOCHROME1/2-derived
705
+ * default). Always `false` for `contentKind: 'volume'` - see `TextureMeta::invert`'s own doc.
706
+ */
707
+ invert: boolean
708
+ /**
709
+ * `framestack` only (empty otherwise): each layer's own default window and invert decision,
710
+ * index-aligned with the layers - see `TextureMeta::layer_default_windows`. Prefer these over
711
+ * the stack-wide `default_window_*`/`invert` whenever present.
712
+ */
713
+ layerWindowCenters: Array<number>
714
+ layerWindowWidths: Array<number>
715
+ layerInvert: Array<boolean>
716
+ nativeWidth: number
717
+ nativeHeight: number
718
+ nativeDepth: number
719
+ downsampled: boolean
720
+ /**
721
+ * Uncompressed byte length of `data`'s content - an exact integer, safely representable as
722
+ * `f64` at any real texture size (well under 2^53).
723
+ */
724
+ payloadBytesRaw: number
725
+ /**
726
+ * `data.length` - included on the result too (not just derivable from `data` client-side)
727
+ * so the render-server can log/cap transfer size without touching the buffer itself.
728
+ */
729
+ payloadBytesStored: number
730
+ data: Buffer
731
+ }
732
+
733
+ /**
734
+ * Transcodes a DICOM file to the given transfer syntax UID. Mirrors
735
+ * `dcmnorm --transfer-syntax UID in.dcm out.dcm`.
736
+ */
737
+ export declare function transcode(filePath: string, outputPath: string, transferSyntaxUid: string): Promise<unknown>
738
+
739
+ /**
740
+ * Writes a DICOMDIR (Media Storage Directory, Explicit VR Little Endian) for a File-set:
741
+ * PATIENT > STUDY > SERIES > one record per entry, its type from the SOP Class (IMAGE, SR
742
+ * DOCUMENT, KEY OBJECT DOC, PRESENTATION, ENCAP DOC, ...; PS3.3 F.5). Type 1 keys the instances
743
+ * lack are synthesized and reported in `synthesized`. Rejects bad File IDs / File-set IDs, a
744
+ * Patient ID shared by two patients, a study under two patients, a series in two studies,
745
+ * duplicate files or SOP Instance UIDs. Mirrors `dcmnorm dicomdir ROOT`, which scans a
746
+ * directory instead of taking entries.
747
+ */
748
+ export declare function writeDicomdir(entries: Array<DicomdirEntry>, outputPath: string, options?: WriteDicomdirOptions | undefined | null): Promise<unknown>
749
+
750
+ export interface WriteDicomdirOptions {
751
+ /** File-set ID (0004,1130): up to 16 characters from A-Z, 0-9 and _. Default empty. */
752
+ fileSetId?: string
753
+ /** SOP Instance UID of the DICOMDIR itself. Generated when not given. */
754
+ sopInstanceUid?: string
755
+ }
756
+
757
+ export interface WriteDicomdirResult {
758
+ /** Total Directory Records written. */
759
+ records: number
760
+ /** Records per Directory Record Type, in first-seen order. */
761
+ recordTypes: Array<DicomdirRecordCount>
762
+ synthesized: Array<DicomdirSynthesized>
763
+ warnings: Array<string>
764
+ }
765
+
766
+ /**
767
+ * Writes a DICOM file from JSON (flat or standard format, auto never guessed -
768
+ * pass the same `format` used to read it). Mirrors `dcmnorm dataset.json out.dcm`.
769
+ * Sequence elements are always (re)written with undefined length, so this does
770
+ * not carry forward stale defined-length byte counts from whatever encoding the
771
+ * JSON was originally read from - see dicom_io::json's DataSetSequence handling.
772
+ */
773
+ export declare function writeJson(json: string, outputPath: string, options?: WriteJsonOptions | undefined | null): Promise<unknown>
774
+
775
+ export interface WriteJsonOptions {
776
+ format?: string
777
+ /**
778
+ * Resolves "?offset=..&length=.." BulkDataURIs (readJson's default 'uri'
779
+ * bulkData mode emits these for bulk elements already in the source file)
780
+ * against this file's bytes - mirrors the CLI's `--bulk-data-source`. Not
781
+ * needed for InlineBinary or "file://" BulkDataURI elements, which are
782
+ * self-contained and resolved independently of this option.
783
+ */
784
+ bulkDataSourcePath?: string
785
+ }