dcmnorm 0.14.0 → 0.16.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/index.d.ts CHANGED
@@ -20,9 +20,12 @@ export declare class DicomServerHandle {
20
20
  }
21
21
 
22
22
  export declare class DicomVolumeHandle {
23
- /** Rows in the source slices (image height). */
23
+ /**
24
+ * Rows of the volume's slice grid (image height). The source images' Rows, except for a
25
+ * desheared (gantry-tilted) stack, whose grid covers every slice's footprint.
26
+ */
24
27
  get rows(): number
25
- /** Columns in the source slices (image width). */
28
+ /** Columns of the volume's slice grid (image width); see `rows`. */
26
29
  get cols(): number
27
30
  /** Number of slices in the built volume. */
28
31
  get numSlices(): number
@@ -48,6 +51,31 @@ export declare class DicomVolumeHandle {
48
51
  get center(): Array<number>
49
52
  /** The volume's own smallest voxel dimension, in mm - a reasonable default output spacing. */
50
53
  get minSpacingMm(): number
54
+ /** `Modality` of the source images (`CT`, `MR`, `PT`, ...), or `null`. */
55
+ get modality(): string | null
56
+ /** `FrameOfReferenceUID` of the source images, or `null`. */
57
+ get frameOfReferenceUid(): string | null
58
+ /** `SeriesInstanceUID` of the source images, or `null`. */
59
+ get seriesInstanceUid(): string | null
60
+ /** `StudyInstanceUID` of the source images, or `null`. */
61
+ get studyInstanceUid(): string | null
62
+ /**
63
+ * Gantry tilt of the acquisition, degrees: the angle between the slice-to-slice position
64
+ * step and the slice normal. `0` for an ordinary stack.
65
+ */
66
+ get gantryTiltDeg(): number
67
+ /** Whether the stack was sheared (gantry tilt) and resampled onto an orthogonal grid. */
68
+ get desheared(): boolean
69
+ /**
70
+ * Whether the slice gaps are irregular (a missing slice, variable pitch). Reformats
71
+ * interpolate by real position either way; `exportTexture` resamples to a uniform lattice.
72
+ */
73
+ get irregularSpacing(): boolean
74
+ /**
75
+ * Row-major 4x4 matrix from voxel index `(col, row, slice, 1)` to patient LPS mm (slice
76
+ * axis at the nominal uniform spacing).
77
+ */
78
+ get voxelToPatient(): Array<number>
51
79
  /**
52
80
  * Resamples one plane through this volume and encodes it exactly like a normal 2D render
53
81
  * (same `RenderedFrame` shape `renderFrame` returns), so callers can reuse their existing
@@ -117,6 +145,16 @@ export declare class MoveScuHandle {
117
145
  abort(): Promise<MoveScuResult>
118
146
  }
119
147
 
148
+ /**
149
+ * Cancels a running `registerVolumes`: pass it as the 4th argument and call `cancel()`; the
150
+ * registration rejects with "registration cancelled" at its next metric evaluation.
151
+ */
152
+ export declare class RegistrationCancelToken {
153
+ constructor()
154
+ cancel(): void
155
+ get cancelled(): boolean
156
+ }
157
+
120
158
  export declare class StoreScuHandle {
121
159
  /**
122
160
  * The eventual per-file `{sopInstanceUid, status}` results, without requesting
@@ -137,11 +175,13 @@ export declare class StoreScuHandle {
137
175
 
138
176
  /**
139
177
  * 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.
178
+ * one CT/MR/PT series) sharing consistent `ImageOrientationPatient`, or from Enhanced
179
+ * multi-frame objects (one Enhanced CT/MR/PET file is enough; per-frame positions and rescale
180
+ * are honoured). Slices are spatially re-sorted internally by `ImagePositionPatient`,
181
+ * regardless of `filePaths`' own order; a gantry-tilted stack is desheared onto an orthogonal
182
+ * grid. Returns a `DicomVolumeHandle` for repeated `reformat()` calls. Rejects (rather than
183
+ * silently mis-rendering) fewer than 2 slices, mismatched Rows/Columns, or a non-parallel
184
+ * stack.
145
185
  */
146
186
  export declare function buildVolume(filePaths: Array<string>): Promise<unknown>
147
187
 
@@ -157,6 +197,33 @@ export declare function checkDicom(filePath: string): Promise<unknown>
157
197
  */
158
198
  export declare function computeHistogram(filePath: string, options?: HistogramOptions | undefined | null): Promise<unknown>
159
199
 
200
+ /**
201
+ * Internal (see `dcmnorm.js` `toDicomJson`): DICOM JSON of an encoded data set, bulk data from
202
+ * its source path/bytes in inline mode.
203
+ */
204
+ export declare function datasetDocumentToJson(document: Buffer, sourcePath: string | undefined | null, sourceBytes: Buffer | undefined | null, options: NativeJsonOptions): Promise<unknown>
205
+
206
+ /** Internal (see `dcmnorm.js` `read`): the data set of a path or bytes, in the binary form. */
207
+ export declare function datasetRead(path: string | undefined | null, bytes: Buffer | undefined | null, untilPixelData: boolean, loadBulkData: boolean): Promise<unknown>
208
+
209
+ /** Internal (see `dcmnorm.js` `renderPixels`): one frame's 8-bit display pixels. */
210
+ export declare function datasetRenderPixels(path: string | undefined | null, bytes: Buffer | undefined | null, frameIndex: number, params: NativeRenderParams): Promise<unknown>
211
+
212
+ /** Internal (see `dcmnorm.js` `toDicomJson`): DICOM JSON of a source. */
213
+ export declare function datasetSourceToJson(path: string | undefined | null, bytes: Buffer | undefined | null, options: NativeJsonOptions): Promise<unknown>
214
+
215
+ /**
216
+ * Internal (see `dcmnorm.js` `transcode`): transcode a source to `outputPath`, or resolve to
217
+ * the bytes.
218
+ */
219
+ export declare function datasetTranscode(path: string | undefined | null, bytes: Buffer | undefined | null, outputPath: string | undefined | null, transferSyntaxUid: string): Promise<unknown>
220
+
221
+ /**
222
+ * Internal (see `dcmnorm.js` `write`): write an encoded data set to `outputPath`, or (no path)
223
+ * resolve to the file's bytes.
224
+ */
225
+ export declare function datasetWrite(document: Buffer, sourcePath?: string | undefined | null, sourceBytes?: Buffer | undefined | null, outputPath?: string | undefined | null, transferSyntaxUid?: string | undefined | null): Promise<unknown>
226
+
160
227
  /**
161
228
  * One file of the File-set for `writeDicomdir`: its File ID plus its header, either as DICOM
162
229
  * JSON (`json`) or a file to read it from (`path`; pixel data isn't loaded).
@@ -236,6 +303,25 @@ export interface EditTagsOptions {
236
303
  removePrivateTags?: boolean
237
304
  }
238
305
 
306
+ /**
307
+ * A fast moving -> fixed translation: the S-I shift from cross-correlating per-height profiles
308
+ * (body area; plus lung and bone area for CT-CT, integrated intensity for MR-MR / PT-PT), the
309
+ * in-plane shift from body-mask centroids over the matched overlap. Works for any acquisition
310
+ * orientation. Tens of milliseconds for a typical CT.
311
+ */
312
+ export declare function estimateTranslation(fixed: DicomVolumeHandle, moving: DicomVolumeHandle, options?: EstimateTranslationOptions | undefined | null): Promise<unknown>
313
+
314
+ export interface EstimateTranslationOptions {
315
+ /** Overrides the fixed volume's Modality ('CT', 'MR', 'PT', ...). */
316
+ fixedModality?: string
317
+ /** Overrides the moving volume's Modality. */
318
+ movingModality?: string
319
+ /** Smallest S-I overlap of the two scans a z shift may imply, mm (default 60). */
320
+ minOverlapMm?: number
321
+ /** Largest |z shift| considered, mm (default: anything with enough overlap). */
322
+ maxShiftMm?: number
323
+ }
324
+
239
325
  /**
240
326
  * Packs several independent frames (from one or more files) as one texture-array upload - see
241
327
  * `dcmnorm::dicom_io::pack_frame_stack_texture`'s own doc for the full contract (no resampling,
@@ -378,6 +464,9 @@ export interface HistogramOptions {
378
464
  maxValue?: number
379
465
  }
380
466
 
467
+ /** The standard keyword of a tag (`0x0020000D` -> `"StudyInstanceUID"`), or null. */
468
+ export declare function keywordOf(tag: number): string | null
469
+
381
470
  /**
382
471
  * Performs a C-MOVE (Study Root Query/Retrieve), asking `destination` ("host:port") to push
383
472
  * `studyInstanceUid` - or one series of it / a list of its instances, per
@@ -442,6 +531,69 @@ export interface MoveScuResult {
442
531
  cancelledVia?: string
443
532
  }
444
533
 
534
+ export interface NativeError {
535
+ kind: string
536
+ message: string
537
+ sourceTransferSyntaxUid?: string
538
+ targetTransferSyntaxUid?: string
539
+ frameIndex?: number
540
+ }
541
+
542
+ /** Options of `toDicomJson`, as `dcmnorm.js` passes them. */
543
+ export interface NativeJsonOptions {
544
+ includeTags?: Array<number>
545
+ excludeTags?: Array<number>
546
+ bulkData?: string
547
+ bulkDataUriBase?: string
548
+ includeFileMeta?: boolean
549
+ keywordAndVm?: boolean
550
+ /**
551
+ * Write each BulkDataURI as the placeholder `dcmnorm-bulk:<TAG>:<VR>:<offset>:<length>`,
552
+ * for the JS layer to replace with its `bulkDataUriBuilder`'s result (a JS callback can't
553
+ * run on the thread pool).
554
+ */
555
+ placeholderUris?: boolean
556
+ }
557
+
558
+ export interface NativeOverlay {
559
+ index: number
560
+ group: number
561
+ rows: number
562
+ columns: number
563
+ overlayType?: string
564
+ label?: string
565
+ }
566
+
567
+ export interface NativeRendered {
568
+ width: number
569
+ height: number
570
+ channels: number
571
+ pixels: Buffer
572
+ overlays: Array<NativeOverlay>
573
+ selectedOverlayIndex?: number
574
+ }
575
+
576
+ export interface NativeRenderParams {
577
+ windowCenter?: number
578
+ windowWidth?: number
579
+ voiLut?: boolean
580
+ modalityLut?: boolean
581
+ iccProfile?: boolean
582
+ outputWidth?: number
583
+ outputHeight?: number
584
+ showOverlays?: boolean
585
+ overlayIndex?: number
586
+ overlayColor?: string
587
+ }
588
+
589
+ /** What a `dataset*` call resolves to: `error`, or one of the payloads. */
590
+ export interface NativeResult {
591
+ error?: NativeError
592
+ data?: Buffer
593
+ text?: string
594
+ rendered?: NativeRendered
595
+ }
596
+
445
597
  /** Mirrors `dcmnorm::dicom_io::OverlaySummary` for the JS side. */
446
598
  export interface OverlaySummary {
447
599
  index: number
@@ -475,6 +627,16 @@ export interface ReadJsonOptions {
475
627
  omitKeywordVm?: boolean
476
628
  }
477
629
 
630
+ /**
631
+ * Reads a DICOM Spatial Registration object (1.2.840.10008.5.1.4.1.1.66.1; for a Deformable
632
+ * one, .66.3, only its pre/post-deformation matrices) and resolves with its JSON form as a
633
+ * string: the REG's own (registered) Frame of Reference, one entry per Registration Sequence
634
+ * item with its Frame of Reference, the composed item -> REG matrix (row-major), its type and
635
+ * referenced images, the Common Instance Reference series, and `warnings` (IOD problems).
636
+ * Rejects anything that is not a registration object.
637
+ */
638
+ export declare function readSpatialRegistration(filePath: string): Promise<unknown>
639
+
478
640
  export declare function readTags(filePath: string, tags: Array<string>): Promise<unknown>
479
641
 
480
642
  export interface ReformatPlaneOptions {
@@ -510,6 +672,96 @@ export interface ReformatPlaneOptions {
510
672
  slabProjection?: string
511
673
  }
512
674
 
675
+ /**
676
+ * Rigid (6-DOF) registration of `moving` onto `fixed`, any CT / MR / PT pairing: a multi-
677
+ * resolution pyramid, modality-aware body masks (CT table removed), NCC for the same modality
678
+ * and Mattes mutual information across modalities, Powell's optimizer. Deterministic, bounded
679
+ * by `maxMemoryBytes` and `timeLimitMs`, cancellable through `cancel`. Resolves with the
680
+ * moving -> fixed patient matrix, the metric, a quality score and timing; rejects when the
681
+ * volumes have no body or do not overlap, on invalid options, or when cancelled.
682
+ */
683
+ export declare function registerVolumes(fixed: DicomVolumeHandle, moving: DicomVolumeHandle, options?: RegisterVolumesOptions | undefined | null, cancel?: RegistrationCancelToken | undefined | null): Promise<unknown>
684
+
685
+ export interface RegisterVolumesOptions {
686
+ /**
687
+ * 'auto' (default: 'ncc' for the same modality, 'mattes-mi' across modalities), 'ncc' or
688
+ * 'mattes-mi'.
689
+ */
690
+ metric?: string
691
+ fixedModality?: string
692
+ movingModality?: string
693
+ /** Starting moving -> fixed transform (16 numbers, row-major), e.g. the viewer's translation. */
694
+ initialMatrix?: Array<number>
695
+ /**
696
+ * Without `initialMatrix`: 'translation' (default; estimateTranslation, then the mask
697
+ * centroids when it is not confident), 'centroid' or 'none'.
698
+ */
699
+ initialize?: string
700
+ /** Working-grid spacing per pyramid level, coarse to fine, mm (default [8, 4, 2]). */
701
+ levelsMm?: Array<number>
702
+ /** Optimizer iterations per level (default 40). */
703
+ maxIterations?: number
704
+ /**
705
+ * Wall-clock limit, ms (default 30000). On expiry the best result so far is returned with
706
+ * `stopReason: 'time-limit'`.
707
+ */
708
+ timeLimitMs?: number
709
+ /** 'auto' (default: modality-aware body mask, CT table removed) or 'none'. */
710
+ mask?: string
711
+ /** Optional box in FIXED patient coordinates the fixed mask is limited to (min corner). */
712
+ roiMinMm?: Array<number>
713
+ /** Max corner of `roiMinMm`'s box. */
714
+ roiMaxMm?: Array<number>
715
+ /** Mutual-information histogram bins (default 32). */
716
+ histogramBins?: number
717
+ /** Metric sample points per level (default 100000). */
718
+ maxSamples?: number
719
+ /** Working-memory cap in bytes (default 268435456); a level that would exceed it is coarsened. */
720
+ maxMemoryBytes?: number
721
+ }
722
+
723
+ export interface RegistrationLevel {
724
+ spacingMm: number
725
+ iterations: number
726
+ metricEvaluations: number
727
+ metricValue: number
728
+ }
729
+
730
+ export interface RegistrationResult {
731
+ /** Moving -> fixed patient, row-major 4x4. */
732
+ matrix: Array<number>
733
+ /** Euler angles of the matrix's rotation, degrees (`R = Rz * Ry * Rx`). */
734
+ rotationDeg: Array<number>
735
+ /** The matrix's translation column, mm. */
736
+ translationMm: Array<number>
737
+ /** Centre of rotation the optimizer used (fixed body centroid), fixed patient mm. */
738
+ centerMm: Array<number>
739
+ /** 'ncc' or 'mattes-mi'. */
740
+ metric: string
741
+ /** NCC correlation (-1..1), or mutual information (nats). */
742
+ metricValue: number
743
+ initialMetricValue: number
744
+ /** NCC correlation, or MI's entropy correlation coefficient (0..1). */
745
+ normalizedMetric: number
746
+ /** Fraction of the fixed body samples that land inside the moving volume. */
747
+ overlapFraction: number
748
+ /** 0..1 heuristic; show it, and never apply a 'poor' result silently. */
749
+ quality: number
750
+ /** 'good' (>= 0.7), 'fair' (>= 0.4) or 'poor'. */
751
+ qualityLabel: string
752
+ iterations: number
753
+ metricEvaluations: number
754
+ levels: Array<RegistrationLevel>
755
+ /** 'matrix', 'translation', 'centroid' or 'none'. */
756
+ initialization: string
757
+ converged: boolean
758
+ /** 'converged', 'max-iterations' or 'time-limit'. */
759
+ stopReason: string
760
+ timingMs: number
761
+ /** Peak bytes of working images and samples held. */
762
+ workingBytes: number
763
+ }
764
+
513
765
  export interface RenderedFrame {
514
766
  mimeType: string
515
767
  width: number
@@ -664,6 +916,9 @@ export interface StoreScuResult {
664
916
  status: number
665
917
  }
666
918
 
919
+ /** The tag of a standard keyword or tag expression, or null. */
920
+ export declare function tagForKeyword(keyword: string): number | null
921
+
667
922
  export interface TextureExportResult {
668
923
  /** 'volume', 'image2d', or 'framestack'. */
669
924
  contentKind: string
@@ -736,6 +991,40 @@ export interface TextureExportResult {
736
991
  */
737
992
  export declare function transcode(filePath: string, outputPath: string, transferSyntaxUid: string): Promise<unknown>
738
993
 
994
+ /** What this build can read, write, decode and encode, per transfer syntax UID. */
995
+ export declare function transferSyntaxSupport(): Array<TransferSyntaxSupportInfo>
996
+
997
+ export interface TransferSyntaxSupportInfo {
998
+ uid: string
999
+ name: string
1000
+ encapsulated: boolean
1001
+ canReadDataset: boolean
1002
+ canWriteDataset: boolean
1003
+ canDecode: boolean
1004
+ canEncode: boolean
1005
+ canTranscodeTo: boolean
1006
+ }
1007
+
1008
+ export interface TranslationEstimate {
1009
+ /** Moving -> fixed patient (a pure translation), row-major 4x4. */
1010
+ matrix: Array<number>
1011
+ translationMm: Array<number>
1012
+ /**
1013
+ * 0..1: the correlation peak's height and its margin over the next peak 20+ mm away.
1014
+ * Below ~0.3, fall back to capture-on-link.
1015
+ */
1016
+ confidence: number
1017
+ peakCorrelation: number
1018
+ secondPeakCorrelation: number
1019
+ overlapMm: number
1020
+ /** The profiles correlated: 'body', 'lung', 'bone' (CT-CT), 'intensity' (MR-MR, PT-PT). */
1021
+ profiles: Array<string>
1022
+ timingMs: number
1023
+ }
1024
+
1025
+ /** The dictionary VR of a tag, or null. */
1026
+ export declare function vrOf(tag: number): string | null
1027
+
739
1028
  /**
740
1029
  * Writes a DICOMDIR (Media Storage Directory, Explicit VR Little Endian) for a File-set:
741
1030
  * PATIENT > STUDY > SERIES > one record per entry, its type from the SOP Class (IMAGE, SR
@@ -783,3 +1072,36 @@ export interface WriteJsonOptions {
783
1072
  */
784
1073
  bulkDataSourcePath?: string
785
1074
  }
1075
+
1076
+ /**
1077
+ * Builds a DICOM Spatial Registration instance from `specJson` (a JSON string) and writes it to
1078
+ * `outputPath`, or returns its bytes as `data` when `outputPath` is omitted. The REG goes in the
1079
+ * FIXED study and Frame of Reference: item 1 maps the fixed frame with the identity, item 2 the
1080
+ * moving frame with `matrix` (moving -> fixed, row-major, what registerVolumes returns).
1081
+ *
1082
+ * spec: `{ matrix: number[16], matrixType?: 'RIGID' (default) | 'RIGID_SCALE' | 'AFFINE',
1083
+ * registrationType?: 'auto' | 'manual' | 'identity', fixed: { frameOfReferenceUid,
1084
+ * studyInstanceUid, seriesInstanceUid, instances?: [{ sopClassUid, sopInstanceUid }] }, moving:
1085
+ * { ...same }, copyPatientStudyFrom?: path to one fixed-study DICOM file, patient?: {
1086
+ * patientName, patientId, patientBirthDate, patientSex }, study?: { studyDate, studyTime,
1087
+ * accessionNumber, referringPhysicianName, studyId, studyDescription }, sopInstanceUid?,
1088
+ * seriesInstanceUid?, seriesNumber?, seriesDescription?, instanceNumber?, contentLabel?,
1089
+ * contentDescription?, contentCreatorName?, manufacturer?, comment? }`. Rejects a spec that would
1090
+ * not produce a conformant object (missing UIDs, a non-rigid RIGID matrix, fixed and moving in
1091
+ * one Frame of Reference, ...).
1092
+ */
1093
+ export declare function writeSpatialRegistration(specJson: string, outputPath?: string | undefined | null): Promise<unknown>
1094
+
1095
+ export interface WrittenSpatialRegistration {
1096
+ /** The written object in readSpatialRegistration's JSON form (a string). */
1097
+ json: string
1098
+ /**
1099
+ * The written object as standard PS3.18 DICOM JSON (hex tag keys, `{vr, Value}`), a
1100
+ * string, ready for `writeJson`.
1101
+ */
1102
+ dataset: string
1103
+ sopInstanceUid: string
1104
+ seriesInstanceUid: string
1105
+ /** The Part 10 file's bytes, when no `outputPath` was given. */
1106
+ data?: Buffer
1107
+ }