dcmnorm 0.13.1 → 0.15.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.
- package/README.md +59 -2
- package/dcmnorm.d.ts +181 -0
- package/dcmnorm.js +525 -0
- package/dicom-constants.d.ts +11473 -0
- package/dicom-constants.js +6188 -0
- package/index.d.ts +113 -0
- package/index.js +66 -56
- package/package.json +13 -9
package/README.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
<img src="https://raw.githubusercontent.com/pohcee/dcmnorm/main/docs/images/dcmnorm-icon.png" alt="dcmnorm" width="96">
|
|
2
|
+
|
|
1
3
|
# dcmnorm (Node.js binding)
|
|
2
4
|
|
|
3
5
|
Native Node.js bindings for dcmnorm, built with [napi-rs](https://napi.rs). Calls
|
|
@@ -41,6 +43,61 @@ npm run build:docker # Linux release build inside node:22-bullseye-slim (glibc 2
|
|
|
41
43
|
npm test # runs test/smoke.js against the fixtures in ../../test/files
|
|
42
44
|
```
|
|
43
45
|
|
|
46
|
+
## Typed datasets
|
|
47
|
+
|
|
48
|
+
`require("dcmnorm")` (the package entry point, `dcmnorm.js`) adds a typed dataset API to the
|
|
49
|
+
calls below (#6). A source is a path, a `Buffer`/`Uint8Array`, or a readable stream (collected
|
|
50
|
+
into a Buffer first: the native reader needs the bytes).
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
const { read, toDicomJson, write, renderPixels, Tag, VR, TransferSyntax } = require("dcmnorm");
|
|
54
|
+
|
|
55
|
+
const ds = await read("in.dcm", { untilPixelData: true }); // DicomDataset, no native handles
|
|
56
|
+
ds.getString(Tag.StudyInstanceUID);
|
|
57
|
+
ds.getInt(Tag.NumberOfFrames, 1);
|
|
58
|
+
ds.getSequence(Tag.ReferencedSeriesSequence); // DicomDataset[]
|
|
59
|
+
ds.getPersonName(Tag.PatientName).familyName;
|
|
60
|
+
ds.getBulkDataRef(Tag.PixelData); // { tag, vr, offset, length }
|
|
61
|
+
|
|
62
|
+
const json = await toDicomJson("in.dcm", { // PS3.18 Annex F, PixelData never read
|
|
63
|
+
excludeTags: [Tag.PatientComments],
|
|
64
|
+
bulkDataUriBuilder: (ref) => `${base}/bulk/${ref.offset}/${ref.length}`,
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
const edited = (await read("in.dcm")).toBuilder().set(Tag.PatientName, VR.PN, "Doe^Jane").build();
|
|
68
|
+
await write(edited, "out.dcm", { transferSyntax: TransferSyntax.ExplicitVRLittleEndian });
|
|
69
|
+
|
|
70
|
+
const { width, height, channels, pixels } = await renderPixels("in.dcm", 0, { windowCenter: 40, windowWidth: 400 });
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- `read(source, { untilPixelData, loadBulkData })`: `untilPixelData` stops at the PixelData
|
|
74
|
+
header; bulk values (PixelData, binary values over 32 bytes) stay in the source as references
|
|
75
|
+
unless `loadBulkData`. Accessors: `getString`, `getStrings`, `getInt`, `getFloat`,
|
|
76
|
+
`getNumbers`, `getBytes`, `getSequence`, `getNestedDataset`, `getPersonName`,
|
|
77
|
+
`getBulkDataRef`, `vr`, `tags`, `fileMeta`, `transferSyntaxUid`, `numberOfFrames`,
|
|
78
|
+
`frameTimeMillis`, `pixelAspectRatio`; iterate for `{ tag, vr, type, value }` elements.
|
|
79
|
+
Integers are JS numbers (SV/UV beyond 2^53 lose precision).
|
|
80
|
+
- `toDicomJson(source | dataset, options)`: `includeTags`, `excludeTags`, `bulkData`
|
|
81
|
+
(`"uri"` | `"inline"`), `bulkDataUriBase`, `bulkDataUriBuilder(ref)`, `includeFileMeta`,
|
|
82
|
+
`keywordAndVM`.
|
|
83
|
+
- `toBuilder()` → `set(tag, vr, ...values)` / `set(tag, [values])` (dictionary VR), `setInt`,
|
|
84
|
+
`setDouble`, `setTags`, `setBytes`, `setSequence`, `addSequenceItem`, `editSequenceItem`,
|
|
85
|
+
`remove`, `removePrivateTags`, `build()`. `write(dataset, path | null, { transferSyntax,
|
|
86
|
+
bulkDataSource })` / `toBuffer`: File Meta Information is created; references (PixelData) are
|
|
87
|
+
read natively from the source, not passed through JS.
|
|
88
|
+
- `renderPixels(source, frame, params)`: 8-bit pixels without image encoding, `pixels` a
|
|
89
|
+
Buffer of `width * height * channels` (1 gray, 3 RGB). Params: `windowCenter`/`windowWidth`,
|
|
90
|
+
`voiLut`, `modalityLut`, `iccProfile`, `outputWidth`, `outputHeight`, `showOverlays`,
|
|
91
|
+
`overlayIndex`, `overlayColor`. The pipeline is the one described in
|
|
92
|
+
[the Java guide](../java/GUIDE.md#3-frame-rendering).
|
|
93
|
+
- `transcodeTo(source, uid, path?)`, `transferSyntaxSupport()`, `keywordOf` / `vrOf` /
|
|
94
|
+
`tagForKeyword`, `sopClassName(uid)`.
|
|
95
|
+
- Generated constants: `Tag`, `VR`, `VR_KIND`, `TransferSyntax`, `TRANSFER_SYNTAX_INFO`
|
|
96
|
+
(`lossy`, `encapsulated`, `explicitVR`, ...), `SOPClassUID`.
|
|
97
|
+
- Errors: `DcmnormError` and `InvalidDicomError`, `UnsupportedTransferSyntaxError`,
|
|
98
|
+
`DecodeError`, `EncodeError`, `RenderError`, `DimseError`, with `kind`, `code`
|
|
99
|
+
(`ERR_DCMNORM_<KIND>`), `sourceTransferSyntaxUid`, `targetTransferSyntaxUid`, `frameIndex`.
|
|
100
|
+
|
|
44
101
|
## API
|
|
45
102
|
|
|
46
103
|
- `readTags(filePath, tags: string[]): Promise<string>` — JSON (flat, hex-keyed,
|
|
@@ -91,7 +148,7 @@ npm test # runs test/smoke.js against the fixtures in ../../test/fil
|
|
|
91
148
|
— computes a pixel-value histogram per frame, over the same modality-LUT-applied grayscale
|
|
92
149
|
values `renderFrame` decodes from (so e.g. a CT frame's bins are in Hounsfield units). Mirrors
|
|
93
150
|
the CLI's `--histogram`/`--histogram-bins`/`--histogram-frame`/`--histogram-min`/`--histogram-max`
|
|
94
|
-
— see the
|
|
151
|
+
— see the [CLI docs](../../docs/cli.md#compute-a-pixel-histogram-with---histogram) for the
|
|
95
152
|
field-by-field output shape. `binCount` defaults to 256; `frameIndex` (0-based) restricts the
|
|
96
153
|
result to one frame instead of every frame in the instance (and, like `renderFrame`, reads only
|
|
97
154
|
that frame's bytes of a native multi-frame file, and decodes only that frame of a compressed
|
|
@@ -134,7 +191,7 @@ Packs a volume, a single frame, or several independent frames as a lossless, GPU
|
|
|
134
191
|
payload (16-bit samples, row-major, optionally gzip-compressed) instead of an 8-bit windowed
|
|
135
192
|
render — the client does its own window/level and oblique reslicing in a GPU shader instead of
|
|
136
193
|
round-tripping to the server per interaction. Mirrors the CLI's `--output-type texture`/`.gputex`
|
|
137
|
-
(`exportTexture`/`exportFrameTexture`) — see the
|
|
194
|
+
(`exportTexture`/`exportFrameTexture`) — see the [CLI docs](../../docs/cli.md#export-a-gpu-texture-gputex)
|
|
138
195
|
and `dcmnorm::dicom_io::texture_export`'s own module doc for the full format contract.
|
|
139
196
|
|
|
140
197
|
- `DicomVolumeHandle.exportTexture(options?: { targetMaxDim?, compression?: 'gzip'|'none', windowCenter?, windowWidth? }): Promise<TextureExportResult>`
|
package/dcmnorm.d.ts
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
// Types of the package entry point (dcmnorm.js): the native addon's API (index.d.ts), the
|
|
2
|
+
// generated DICOM constants (dicom-constants.d.ts) and the typed dataset API of #6.
|
|
3
|
+
|
|
4
|
+
export * from "./index";
|
|
5
|
+
export * from "./dicom-constants";
|
|
6
|
+
|
|
7
|
+
import type { VR, TransferSyntaxInfo } from "./dicom-constants";
|
|
8
|
+
|
|
9
|
+
/** A path, a Buffer/Uint8Array, or a readable stream / async iterable of chunks (collected first). */
|
|
10
|
+
export type DicomSource = string | URL | Uint8Array | AsyncIterable<Uint8Array | string>;
|
|
11
|
+
|
|
12
|
+
export type DicomErrorKind =
|
|
13
|
+
| "InvalidDicom"
|
|
14
|
+
| "UnsupportedTransferSyntax"
|
|
15
|
+
| "Decode"
|
|
16
|
+
| "Encode"
|
|
17
|
+
| "Render"
|
|
18
|
+
| "Dimse"
|
|
19
|
+
| "Io"
|
|
20
|
+
| "InvalidArgument"
|
|
21
|
+
| "Internal"
|
|
22
|
+
| "Other";
|
|
23
|
+
|
|
24
|
+
/** Every dataset API failure; `code` is `ERR_DCMNORM_<KIND>`. */
|
|
25
|
+
export declare class DcmnormError extends Error {
|
|
26
|
+
readonly kind: DicomErrorKind;
|
|
27
|
+
readonly code: string;
|
|
28
|
+
readonly sourceTransferSyntaxUid: string | null;
|
|
29
|
+
readonly targetTransferSyntaxUid: string | null;
|
|
30
|
+
readonly frameIndex: number | null;
|
|
31
|
+
}
|
|
32
|
+
export declare class InvalidDicomError extends DcmnormError {}
|
|
33
|
+
export declare class UnsupportedTransferSyntaxError extends DcmnormError {}
|
|
34
|
+
export declare class DecodeError extends DcmnormError {}
|
|
35
|
+
export declare class EncodeError extends DcmnormError {}
|
|
36
|
+
export declare class RenderError extends DcmnormError {}
|
|
37
|
+
export declare class DimseError extends DcmnormError {}
|
|
38
|
+
|
|
39
|
+
/** A value left in its source: absolute byte offset and length (-1: undefined). */
|
|
40
|
+
export interface BulkDataRef {
|
|
41
|
+
readonly tag: number;
|
|
42
|
+
readonly vr: VR;
|
|
43
|
+
readonly offset: number;
|
|
44
|
+
readonly length: number;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export type DicomElement =
|
|
48
|
+
| { readonly tag: number; readonly vr: VR; readonly type: "empty"; readonly value: null }
|
|
49
|
+
| { readonly tag: number; readonly vr: VR; readonly type: "strings"; readonly value: readonly string[] }
|
|
50
|
+
| { readonly tag: number; readonly vr: VR; readonly type: "ints" | "doubles" | "tags"; readonly value: readonly number[] }
|
|
51
|
+
| { readonly tag: number; readonly vr: VR; readonly type: "bytes"; readonly value: Buffer }
|
|
52
|
+
| { readonly tag: number; readonly vr: VR; readonly type: "bulkData"; readonly value: BulkDataRef }
|
|
53
|
+
| { readonly tag: number; readonly vr: VR; readonly type: "fragments"; readonly value: { offsetTable: number[]; fragments: Buffer[] } }
|
|
54
|
+
| { readonly tag: number; readonly vr: "SQ"; readonly type: "sequence"; readonly value: readonly DicomDataset[] };
|
|
55
|
+
|
|
56
|
+
export interface PersonNameGroup {
|
|
57
|
+
readonly familyName: string;
|
|
58
|
+
readonly givenName: string;
|
|
59
|
+
readonly middleName: string;
|
|
60
|
+
readonly namePrefix: string;
|
|
61
|
+
readonly nameSuffix: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export declare class PersonName {
|
|
65
|
+
constructor(value: string);
|
|
66
|
+
readonly value: string;
|
|
67
|
+
readonly alphabetic: PersonNameGroup;
|
|
68
|
+
readonly ideographic: PersonNameGroup;
|
|
69
|
+
readonly phonetic: PersonNameGroup;
|
|
70
|
+
readonly familyName: string;
|
|
71
|
+
readonly givenName: string;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** A read-only data set as plain JS values. */
|
|
75
|
+
export declare class DicomDataset implements Iterable<DicomElement> {
|
|
76
|
+
static empty(): DicomDataset;
|
|
77
|
+
readonly size: number;
|
|
78
|
+
readonly transferSyntaxUid: string | null;
|
|
79
|
+
readonly transferSyntax: TransferSyntaxInfo | null;
|
|
80
|
+
readonly fileMeta: DicomDataset;
|
|
81
|
+
readonly numberOfFrames: number;
|
|
82
|
+
/** FrameTime (ms), or null. */
|
|
83
|
+
readonly frameTimeMillis: number | null;
|
|
84
|
+
readonly frameTimeVector: number[] | null;
|
|
85
|
+
/** Vertical / horizontal pixel size. */
|
|
86
|
+
readonly pixelAspectRatio: number;
|
|
87
|
+
[Symbol.iterator](): Iterator<DicomElement>;
|
|
88
|
+
tags(): number[];
|
|
89
|
+
has(tag: number): boolean;
|
|
90
|
+
get(tag: number): DicomElement | undefined;
|
|
91
|
+
vr(tag: number): VR | null;
|
|
92
|
+
getString(tag: number, defaultValue?: string | null, index?: number): string | null;
|
|
93
|
+
getStrings(tag: number): string[] | null;
|
|
94
|
+
getNumber(tag: number, defaultValue?: number | null, index?: number): number | null;
|
|
95
|
+
getInt(tag: number, defaultValue?: number | null, index?: number): number | null;
|
|
96
|
+
getFloat(tag: number, defaultValue?: number | null, index?: number): number | null;
|
|
97
|
+
getNumbers(tag: number): number[] | null;
|
|
98
|
+
getInts(tag: number): number[] | null;
|
|
99
|
+
getFloats(tag: number): number[] | null;
|
|
100
|
+
getBytes(tag: number): Buffer | null;
|
|
101
|
+
getBulkDataRef(tag: number): BulkDataRef | null;
|
|
102
|
+
getSequence(tag: number): DicomDataset[] | null;
|
|
103
|
+
getNestedDataset(tag: number, index?: number): DicomDataset | null;
|
|
104
|
+
getPersonName(tag: number, index?: number): PersonName | null;
|
|
105
|
+
toBuilder(): DicomDatasetBuilder;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export declare class DicomDatasetBuilder {
|
|
109
|
+
set(tag: number, vr: VR, ...values: Array<string | number>): this;
|
|
110
|
+
set(tag: number, values: Array<string | number>): this;
|
|
111
|
+
setInt(tag: number, vr: VR, ...values: number[]): this;
|
|
112
|
+
setDouble(tag: number, vr: VR, ...values: number[]): this;
|
|
113
|
+
setTags(tag: number, ...tags: number[]): this;
|
|
114
|
+
setBytes(tag: number, vr: VR, bytes: Uint8Array): this;
|
|
115
|
+
setNull(tag: number, vr: VR): this;
|
|
116
|
+
setSequence(tag: number, items: DicomDataset[]): this;
|
|
117
|
+
addSequenceItem(tag: number, item: DicomDataset): this;
|
|
118
|
+
editSequenceItem(tag: number, index: number, edit: (item: DicomDatasetBuilder) => void): this;
|
|
119
|
+
removeSequenceItem(tag: number, index: number): this;
|
|
120
|
+
remove(tag: number): this;
|
|
121
|
+
removePrivateTags(): this;
|
|
122
|
+
build(): DicomDataset;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export interface ReadOptions {
|
|
126
|
+
/** Stop at the PixelData header (PixelData is then a BulkDataRef). */
|
|
127
|
+
untilPixelData?: boolean;
|
|
128
|
+
/** Read bulk values instead of leaving them in the source as references. */
|
|
129
|
+
loadBulkData?: boolean;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export interface DicomJsonOptions {
|
|
133
|
+
includeTags?: number[];
|
|
134
|
+
excludeTags?: number[];
|
|
135
|
+
bulkData?: "uri" | "inline";
|
|
136
|
+
bulkDataUriBase?: string;
|
|
137
|
+
bulkDataUriBuilder?: (ref: BulkDataRef) => string;
|
|
138
|
+
includeFileMeta?: boolean;
|
|
139
|
+
keywordAndVM?: boolean;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
export interface WriteDatasetOptions {
|
|
143
|
+
/** Transcode to this transfer syntax UID. */
|
|
144
|
+
transferSyntax?: string;
|
|
145
|
+
/** Where the data set's bulk data references are read from, instead of its own source. */
|
|
146
|
+
bulkDataSource?: string | Uint8Array;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export interface RenderParams {
|
|
150
|
+
windowCenter?: number;
|
|
151
|
+
windowWidth?: number;
|
|
152
|
+
voiLut?: boolean;
|
|
153
|
+
modalityLut?: boolean;
|
|
154
|
+
iccProfile?: boolean;
|
|
155
|
+
outputWidth?: number;
|
|
156
|
+
outputHeight?: number;
|
|
157
|
+
showOverlays?: boolean;
|
|
158
|
+
overlayIndex?: number;
|
|
159
|
+
overlayColor?: string;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
export interface RenderedPixels {
|
|
163
|
+
width: number;
|
|
164
|
+
height: number;
|
|
165
|
+
/** 1 (gray) or 3 (RGB interleaved). */
|
|
166
|
+
channels: number;
|
|
167
|
+
/** width * height * channels bytes, rows top to bottom. */
|
|
168
|
+
pixels: Buffer;
|
|
169
|
+
overlays: Array<{ index: number; group: number; rows: number; columns: number; overlayType?: string; label?: string }>;
|
|
170
|
+
selectedOverlayIndex?: number;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export declare function read(source: DicomSource, options?: ReadOptions): Promise<DicomDataset>;
|
|
174
|
+
export declare function toDicomJson(source: DicomSource | DicomDataset, options?: DicomJsonOptions): Promise<string>;
|
|
175
|
+
export declare function write(dataset: DicomDataset, outputPath: string, options?: WriteDatasetOptions): Promise<void>;
|
|
176
|
+
export declare function write(dataset: DicomDataset, outputPath: null, options?: WriteDatasetOptions): Promise<Buffer>;
|
|
177
|
+
export declare function toBuffer(dataset: DicomDataset, options?: WriteDatasetOptions): Promise<Buffer>;
|
|
178
|
+
export declare function renderPixels(source: DicomSource, frameIndex?: number, params?: RenderParams): Promise<RenderedPixels>;
|
|
179
|
+
export declare function transcodeTo(source: DicomSource, transferSyntaxUid: string, outputPath: string): Promise<void>;
|
|
180
|
+
export declare function transcodeTo(source: DicomSource, transferSyntaxUid: string, outputPath?: null): Promise<Buffer>;
|
|
181
|
+
export declare function sopClassName(uid: string): string | null;
|