@ubercode/dcmtk 0.1.4 → 0.3.0

package/dist/dicom.d.cts

@@ -1,3 +1,368 @@
-export { C as ChangeSet, b as DicomDataset, c as DicomFile, d as DicomFileOptions, f as DictionaryEntry, g as SOPClassName, h as SOP_CLASSES, i as TagSegment, V as VR, j as VRCategoryName, k as VRMetadata, l as VRValue, m as VR_CATEGORY, n as VR_CATEGORY_NAME, o as VR_META, w as getVRCategory, x as isBinaryVR, y as isNumericVR, z as isStringVR, E as lookupTag, F as lookupTagByKeyword, G as lookupTagByName, H as segmentsToModifyPath, I as segmentsToString, J as sopClassNameFromUID, K as tagPathToSegments } from './index-DX4C3zbo.cjs';
-export { x as xmlToJson } from './dcmodify-CTXBWKU9.cjs';
-import './types-zHhxS7d2.cjs';
+import { D as DicomTag, a as DicomTagPath } from './DicomInstance-DNHPkkzl.cjs';
+export { C as ChangeSet, b as DicomDataset, d as DicomInstance } from './DicomInstance-DNHPkkzl.cjs';
+export { x as xmlToJson } from './dcmodify-Gds9u5Vj.cjs';
+import './types-Cgumy1N4.cjs';
+
+/**
+ * DICOM Value Representation (VR) definitions, categories, and metadata.
+ *
+ * Provides a complete catalogue of all 34 standard DICOM VRs with their
+ * constraints (max length, padding, fixed-length) and category classification.
+ *
+ * @module dicom/vr
+ */
+/**
+ * All 34 standard DICOM Value Representation codes.
+ *
+ * @see DICOM PS3.5 Section 6.2
+ */
+declare const VR: {
+    /** Application Entity — 16 bytes max, leading/trailing spaces significant */
+    readonly AE: "AE";
+    /** Age String — 4 bytes fixed, e.g. "032Y" */
+    readonly AS: "AS";
+    /** Attribute Tag — 4 bytes fixed */
+    readonly AT: "AT";
+    /** Code String — 16 bytes max */
+    readonly CS: "CS";
+    /** Date — 8 bytes fixed, YYYYMMDD */
+    readonly DA: "DA";
+    /** Decimal String — 16 bytes max per value */
+    readonly DS: "DS";
+    /** Date Time — 26 bytes max */
+    readonly DT: "DT";
+    /** Floating Point Double — 8 bytes fixed */
+    readonly FD: "FD";
+    /** Floating Point Single — 4 bytes fixed */
+    readonly FL: "FL";
+    /** Integer String — 12 bytes max */
+    readonly IS: "IS";
+    /** Long String — 64 chars max */
+    readonly LO: "LO";
+    /** Long Text — 10240 chars max */
+    readonly LT: "LT";
+    /** Other Byte — no max */
+    readonly OB: "OB";
+    /** Other Double — no max */
+    readonly OD: "OD";
+    /** Other Float — no max */
+    readonly OF: "OF";
+    /** Other Long — no max */
+    readonly OL: "OL";
+    /** Other 64-bit Very Long — no max */
+    readonly OV: "OV";
+    /** Other Word — no max */
+    readonly OW: "OW";
+    /** Person Name — 64 chars max per component group */
+    readonly PN: "PN";
+    /** Short String — 16 chars max */
+    readonly SH: "SH";
+    /** Signed Long — 4 bytes fixed */
+    readonly SL: "SL";
+    /** Sequence of Items — no max */
+    readonly SQ: "SQ";
+    /** Signed Short — 2 bytes fixed */
+    readonly SS: "SS";
+    /** Short Text — 1024 chars max */
+    readonly ST: "ST";
+    /** Signed 64-bit Very Long — 8 bytes fixed */
+    readonly SV: "SV";
+    /** Time — 14 bytes max */
+    readonly TM: "TM";
+    /** Unlimited Characters — no max */
+    readonly UC: "UC";
+    /** Unique Identifier (UID) — 64 bytes max */
+    readonly UI: "UI";
+    /** Unsigned Long — 4 bytes fixed */
+    readonly UL: "UL";
+    /** Unknown — no max */
+    readonly UN: "UN";
+    /** Universal Resource Identifier/Locator — no max */
+    readonly UR: "UR";
+    /** Unsigned Short — 2 bytes fixed */
+    readonly US: "US";
+    /** Unlimited Text — no max */
+    readonly UT: "UT";
+    /** Unsigned 64-bit Very Long — 8 bytes fixed */
+    readonly UV: "UV";
+};
+/** A valid DICOM Value Representation code. */
+type VRValue = (typeof VR)[keyof typeof VR];
+/** Names for the five VR categories. */
+declare const VR_CATEGORY_NAME: {
+    readonly STRING: "STRING";
+    readonly NUMERIC: "NUMERIC";
+    readonly BINARY: "BINARY";
+    readonly SEQUENCE: "SEQUENCE";
+    readonly TAG: "TAG";
+};
+/** A VR category name. */
+type VRCategoryName = (typeof VR_CATEGORY_NAME)[keyof typeof VR_CATEGORY_NAME];
+/**
+ * VR codes grouped by category.
+ *
+ * - STRING: text-based VRs that hold character data
+ * - NUMERIC: VRs that hold numeric data (integer or float)
+ * - BINARY: VRs that hold raw binary/byte data
+ * - SEQUENCE: the SQ VR for nested datasets
+ * - TAG: the AT VR for attribute tag references
+ */
+declare const VR_CATEGORY: {
+    readonly STRING: readonly ["AE", "AS", "CS", "DA", "DS", "DT", "IS", "LO", "LT", "PN", "SH", "ST", "TM", "UC", "UI", "UR", "UT"];
+    readonly NUMERIC: readonly ["FD", "FL", "SL", "SS", "SV", "UL", "US", "UV"];
+    readonly BINARY: readonly ["OB", "OD", "OF", "OL", "OV", "OW", "UN"];
+    readonly SEQUENCE: readonly ["SQ"];
+    readonly TAG: readonly ["AT"];
+};
+/** Metadata describing the constraints of a single VR. */
+interface VRMetadata {
+    /** Maximum value length in bytes/chars, or null if unlimited. */
+    readonly maxLength: number | null;
+    /** Character used for padding to even length, or null if no padding. */
+    readonly paddingChar: ' ' | '\0' | null;
+    /** Whether this VR has a fixed (non-variable) length. */
+    readonly fixed: boolean;
+    /** The category this VR belongs to. */
+    readonly category: VRCategoryName;
+}
+/**
+ * Complete metadata for all 34 standard DICOM VRs.
+ *
+ * @see DICOM PS3.5 Table 6.2-1
+ */
+declare const VR_META: Readonly<Record<VRValue, VRMetadata>>;
+/**
+ * Type guard: checks whether a string is a valid DICOM VR code.
+ *
+ * @param vr - The string to check
+ * @returns True if `vr` is one of the 34 standard VR codes
+ */
+declare function isStringVR(vr: string): vr is VRValue;
+/**
+ * Checks whether a VR code represents a numeric value representation.
+ *
+ * @param vr - The VR code to check
+ * @returns True if the VR is FD, FL, SL, SS, SV, UL, US, or UV
+ */
+declare function isNumericVR(vr: string): boolean;
+/**
+ * Checks whether a VR code represents a binary value representation.
+ *
+ * @param vr - The VR code to check
+ * @returns True if the VR is OB, OD, OF, OL, OV, OW, or UN
+ */
+declare function isBinaryVR(vr: string): boolean;
+/**
+ * Returns the category name for a given VR code.
+ *
+ * @param vr - A valid VR code
+ * @returns The category name (STRING, NUMERIC, BINARY, SEQUENCE, or TAG)
+ */
+declare function getVRCategory(vr: VRValue): VRCategoryName;
+
+/**
+ * DICOM tag dictionary with O(1) lookup by tag and lazy reverse lookup by name.
+ *
+ * Uses the shipped `src/data/dictionary.json` generated from `_configs/dicom.dic.json`.
+ *
+ * @module dicom/dictionary
+ */
+
+/** A single entry from the DICOM data dictionary. */
+interface DictionaryEntry {
+    /** The Value Representation code (e.g. "PN", "LO", "US"). */
+    readonly vr: VRValue;
+    /** The standard keyword name (e.g. "PatientName"). */
+    readonly name: string;
+    /** Value multiplicity as [min, max], where max is null if unbounded. */
+    readonly vm: readonly [number, number | null];
+    /** Whether this tag is retired in the current DICOM standard. */
+    readonly retired: boolean;
+}
+/**
+ * Looks up a DICOM tag in the data dictionary.
+ *
+ * Accepts tags in either branded `DicomTag` format `"(0010,0010)"` or
+ * raw 8-char hex format `"00100010"`.
+ *
+ * @param tag - A DicomTag or 8-char hex string
+ * @returns The dictionary entry, or undefined if the tag is not in the dictionary
+ */
+declare function lookupTag(tag: DicomTag | string): DictionaryEntry | undefined;
+/**
+ * Looks up a DICOM tag by its standard keyword name.
+ *
+ * @param name - The standard keyword (e.g. "PatientName", "Modality")
+ * @returns An object with the 8-char hex tag and dictionary entry, or undefined
+ */
+declare function lookupTagByName(name: string): {
+    readonly tag: string;
+    readonly entry: DictionaryEntry;
+} | undefined;
+/**
+ * Looks up a DICOM tag by its standard keyword, returning just the branded DicomTag.
+ *
+ * @param keyword - The standard keyword (e.g. "PatientName")
+ * @returns The DicomTag in `(XXXX,XXXX)` format, or undefined if not found
+ */
+declare function lookupTagByKeyword(keyword: string): DicomTag | undefined;
+
+/**
+ * Curated list of common DICOM SOP Class UIDs.
+ *
+ * This is not exhaustive — DICOM defines hundreds of SOP classes.
+ * This file covers the ~70 most commonly encountered SOP classes
+ * in clinical and research imaging workflows.
+ *
+ * @see DICOM PS3.4 Annex B — SOP Class definitions
+ * @module data/sopClasses
+ */
+/**
+ * Common DICOM SOP Class UIDs.
+ *
+ * Keys are PascalCase names matching the DICOM standard keyword.
+ * Values are the dotted-numeric UID strings.
+ */
+declare const SOP_CLASSES: {
+    readonly Verification: "1.2.840.10008.1.1";
+    readonly ComputedRadiographyImageStorage: "1.2.840.10008.5.1.4.1.1.1";
+    readonly DigitalXRayImageStorageForPresentation: "1.2.840.10008.5.1.4.1.1.1.1";
+    readonly DigitalXRayImageStorageForProcessing: "1.2.840.10008.5.1.4.1.1.1.1.1";
+    readonly DigitalMammographyXRayImageStorageForPresentation: "1.2.840.10008.5.1.4.1.1.1.2";
+    readonly DigitalMammographyXRayImageStorageForProcessing: "1.2.840.10008.5.1.4.1.1.1.2.1";
+    readonly CTImageStorage: "1.2.840.10008.5.1.4.1.1.2";
+    readonly EnhancedCTImageStorage: "1.2.840.10008.5.1.4.1.1.2.1";
+    readonly UltrasoundMultiFrameImageStorage: "1.2.840.10008.5.1.4.1.1.3.1";
+    readonly MRImageStorage: "1.2.840.10008.5.1.4.1.1.4";
+    readonly EnhancedMRImageStorage: "1.2.840.10008.5.1.4.1.1.4.1";
+    readonly MRSpectroscopyStorage: "1.2.840.10008.5.1.4.1.1.4.2";
+    readonly EnhancedMRColorImageStorage: "1.2.840.10008.5.1.4.1.1.4.3";
+    readonly UltrasoundImageStorage: "1.2.840.10008.5.1.4.1.1.6.1";
+    readonly EnhancedUSVolumeStorage: "1.2.840.10008.5.1.4.1.1.6.2";
+    readonly SecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7";
+    readonly MultiFrameSingleBitSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.1";
+    readonly MultiFrameGrayscaleByteSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.2";
+    readonly MultiFrameGrayscaleWordSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.3";
+    readonly MultiFrameTrueColorSecondaryCaptureImageStorage: "1.2.840.10008.5.1.4.1.1.7.4";
+    readonly XRayAngiographicImageStorage: "1.2.840.10008.5.1.4.1.1.12.1";
+    readonly EnhancedXAImageStorage: "1.2.840.10008.5.1.4.1.1.12.1.1";
+    readonly XRayRadiofluoroscopicImageStorage: "1.2.840.10008.5.1.4.1.1.12.2";
+    readonly EnhancedXRFImageStorage: "1.2.840.10008.5.1.4.1.1.12.2.1";
+    readonly NuclearMedicineImageStorage: "1.2.840.10008.5.1.4.1.1.20";
+    readonly VLEndoscopicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.1";
+    readonly VLMicroscopicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.2";
+    readonly VLSlideCoordinatesMicroscopicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.3";
+    readonly VLPhotographicImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.4";
+    readonly OphthalmicPhotography8BitImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.5.1";
+    readonly OphthalmicPhotography16BitImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.5.2";
+    readonly VLWholeSlideMicroscopyImageStorage: "1.2.840.10008.5.1.4.1.1.77.1.6";
+    readonly PositronEmissionTomographyImageStorage: "1.2.840.10008.5.1.4.1.1.128";
+    readonly EnhancedPETImageStorage: "1.2.840.10008.5.1.4.1.1.130";
+    readonly RTImageStorage: "1.2.840.10008.5.1.4.1.1.481.1";
+    readonly RTDoseStorage: "1.2.840.10008.5.1.4.1.1.481.2";
+    readonly RTStructureSetStorage: "1.2.840.10008.5.1.4.1.1.481.3";
+    readonly RTBeamsTreatmentRecordStorage: "1.2.840.10008.5.1.4.1.1.481.4";
+    readonly RTPlanStorage: "1.2.840.10008.5.1.4.1.1.481.5";
+    readonly RTBrachyTreatmentRecordStorage: "1.2.840.10008.5.1.4.1.1.481.6";
+    readonly RTTreatmentSummaryRecordStorage: "1.2.840.10008.5.1.4.1.1.481.7";
+    readonly RTIonPlanStorage: "1.2.840.10008.5.1.4.1.1.481.8";
+    readonly RTIonBeamsTreatmentRecordStorage: "1.2.840.10008.5.1.4.1.1.481.9";
+    readonly BasicTextSRStorage: "1.2.840.10008.5.1.4.1.1.88.11";
+    readonly EnhancedSRStorage: "1.2.840.10008.5.1.4.1.1.88.22";
+    readonly ComprehensiveSRStorage: "1.2.840.10008.5.1.4.1.1.88.33";
+    readonly Comprehensive3DSRStorage: "1.2.840.10008.5.1.4.1.1.88.34";
+    readonly KeyObjectSelectionDocumentStorage: "1.2.840.10008.5.1.4.1.1.88.59";
+    readonly GrayscaleSoftcopyPresentationStateStorage: "1.2.840.10008.5.1.4.1.1.11.1";
+    readonly ColorSoftcopyPresentationStateStorage: "1.2.840.10008.5.1.4.1.1.11.2";
+    readonly EncapsulatedPDFStorage: "1.2.840.10008.5.1.4.1.1.104.1";
+    readonly EncapsulatedCDAStorage: "1.2.840.10008.5.1.4.1.1.104.2";
+    readonly RawDataStorage: "1.2.840.10008.5.1.4.1.1.66";
+    readonly SpatialRegistrationStorage: "1.2.840.10008.5.1.4.1.1.66.1";
+    readonly SpatialFiducialsStorage: "1.2.840.10008.5.1.4.1.1.66.2";
+    readonly DeformableSpatialRegistrationStorage: "1.2.840.10008.5.1.4.1.1.66.3";
+    readonly SegmentationStorage: "1.2.840.10008.5.1.4.1.1.66.4";
+    readonly SurfaceSegmentationStorage: "1.2.840.10008.5.1.4.1.1.66.5";
+    readonly TwelveLeadECGWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.1.1";
+    readonly GeneralECGWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.1.2";
+    readonly AmbulatoryECGWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.1.3";
+    readonly HemodynamicWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.2.1";
+    readonly BasicVoiceAudioWaveformStorage: "1.2.840.10008.5.1.4.1.1.9.4.1";
+    readonly PatientRootQueryRetrieveInformationModelFind: "1.2.840.10008.5.1.4.1.2.1.1";
+    readonly PatientRootQueryRetrieveInformationModelMove: "1.2.840.10008.5.1.4.1.2.1.2";
+    readonly PatientRootQueryRetrieveInformationModelGet: "1.2.840.10008.5.1.4.1.2.1.3";
+    readonly StudyRootQueryRetrieveInformationModelFind: "1.2.840.10008.5.1.4.1.2.2.1";
+    readonly StudyRootQueryRetrieveInformationModelMove: "1.2.840.10008.5.1.4.1.2.2.2";
+    readonly StudyRootQueryRetrieveInformationModelGet: "1.2.840.10008.5.1.4.1.2.2.3";
+    readonly ModalityWorklistInformationModelFind: "1.2.840.10008.5.1.4.31";
+    readonly StorageCommitmentPushModel: "1.2.840.10008.1.20.1";
+};
+/** A SOP class name key from the curated list. */
+type SOPClassName = keyof typeof SOP_CLASSES;
+/**
+ * Looks up the SOP class name for a given UID string.
+ *
+ * @param uid - A DICOM SOP Class UID string
+ * @returns The SOP class name, or undefined if not in the curated list
+ */
+declare function sopClassNameFromUID(uid: string): SOPClassName | undefined;
+
+/**
+ * DICOM tag path parser and serializer.
+ *
+ * Provides iterative (no recursion) parsing of DICOM tag paths like
+ * `(0040,A730)[0].(0040,A160)` into structured segments, and conversion
+ * back to dcmodify-compatible strings.
+ *
+ * Supports wildcard indices `[*]` for use with DicomDataset.findValues.
+ *
+ * @module dicom/tagPath
+ */
+
+/** A single segment of a parsed DICOM tag path. */
+interface TagSegment {
+    /** The DICOM tag for this segment. */
+    readonly tag: DicomTag;
+    /** The array index for sequence items, or undefined for non-sequence tags. */
+    readonly index?: number | undefined;
+    /** Whether this segment uses a wildcard index `[*]`. */
+    readonly isWildcard?: boolean | undefined;
+}
+/**
+ * Parses a DICOM tag path into an array of segments.
+ *
+ * Uses iterative parsing with bounded loop (Rule 8.2: no recursion).
+ *
+ * @param path - A branded DicomTagPath string
+ * @returns An array of TagSegment objects
+ * @throws Error if the path is malformed or exceeds MAX_TRAVERSAL_DEPTH
+ *
+ * @example
+ * ```ts
+ * tagPathToSegments('(0040,A730)[0].(0040,A160)' as DicomTagPath)
+ * // => [
+ * //   { tag: '(0040,A730)' as DicomTag, index: 0 },
+ * //   { tag: '(0040,A160)' as DicomTag }
+ * // ]
+ * ```
+ */
+declare function tagPathToSegments(path: DicomTagPath): ReadonlyArray<TagSegment>;
+/**
+ * Converts tag segments back to a dcmodify-compatible path string.
+ *
+ * Format: `(0040,A730)[0].(0040,A160)`
+ *
+ * @param segments - An array of TagSegment objects
+ * @returns A dcmodify-compatible path string
+ */
+declare function segmentsToModifyPath(segments: ReadonlyArray<TagSegment>): string;
+/**
+ * Converts tag segments to a canonical display string.
+ *
+ * Same format as dcmodify path: `(0040,A730)[0].(0040,A160)`
+ *
+ * @param segments - An array of TagSegment objects
+ * @returns A human-readable path string
+ */
+declare function segmentsToString(segments: ReadonlyArray<TagSegment>): string;
+
+export { type DictionaryEntry, type SOPClassName, SOP_CLASSES, type TagSegment, VR, type VRCategoryName, type VRMetadata, type VRValue, VR_CATEGORY, VR_CATEGORY_NAME, VR_META, getVRCategory, isBinaryVR, isNumericVR, isStringVR, lookupTag, lookupTagByKeyword, lookupTagByName, segmentsToModifyPath, segmentsToString, sopClassNameFromUID, tagPathToSegments };