Skip to main content
Version: v0.0.4

Class: Element

One DICOM Data Element as parsed by Phase 2.

Phase 2 surface (this plan): tag, vr, vm, length, rawBytes, byteOffset, privateCreator. NO .value getter, NO decoders, NO navigation methods. Phase 3 (per D-42) extends this class with a lazy, memoized .value getter and the VR-aware decoders under src/dataset/vr/.

rawBytes retention behaviour: zero-copy Buffer.subarray view by default (pins source ArrayBuffer); pass { copyValues: true } to parseDicom for Buffer.from(slice) per element when the source needs to be released.

Example​

import { Buffer } from "node:buffer";
import { Element } from "@cosyte/dicom";
const el = new Element({
  tag: "00100010",
  vr: "PN",
  vm: 1,
  length: 8,
  rawBytes: Buffer.from("DOE^JANE"),
  byteOffset: 200,
  littleEndian: true,
});
// el.tag === "00100010"; el.rawBytes is a Buffer of 8 bytes.
// el.value.kind === "personName".

Constructors​

Constructor​

new Element(init): Element

Internal

Construct a new structural Element. Producers (parser plans 02-03 onward) build these directly from on-wire bytes; consumers receive them via Dataset after parseDicom.

Parameters​

init​

ElementInit

Returns​

Element

Properties​

byteOffset​

readonly byteOffset: number

cp246Promoted​

readonly cp246Promoted: boolean | undefined

Internal

Phase 2 hint for Phase 3's lazy SQ decoder per D-30. true when this Element was promoted from VR=UN with undefined length to VR=SQ via the CP-246 fallback. Phase 3 uses this to choose the Implicit VR LE inner decoder. Always undefined on standard SQ elements.

items​

readonly items: readonly Item[] | undefined

Parsed items for an SQ element; undefined otherwise.

length​

readonly length: number

littleEndian​

readonly littleEndian: boolean

Value byte order (per transfer syntax). See ElementInit.littleEndian.

privateCreator​

readonly privateCreator: string | undefined

rawBytes​

readonly rawBytes: Buffer

specificCharacterSet​

readonly specificCharacterSet: readonly string[] | undefined

In-effect (0008,0005) terms, or undefined for the Default Repertoire.

tag​

readonly tag: string

vm​

readonly vm: number

vr​

readonly vr: VR

Accessors​

value​

Get Signature​

get value(): DicomValue

The decoded value of this element, by VR. Decode is lazy (the structural parse stays eager; field decode runs on first access) and memoized - the documented ~30× win on large studies where most fields are never read. Fail-safe: never throws; a malformed value surfaces as typed-absent with the deviation on the returned value's warnings.

Example​
import { parseDicom } from "@cosyte/dicom";
const ds = parseDicom(buf);
const v = ds.get("00100010")?.value; // Patient's Name (PN)
if (v?.kind === "personName") console.log(v.values[0]?.alphabetic.familyName);
Returns​

DicomValue