Skip to content

Behaviour notes

pydcm aims for value-for-value correctness with the conventions Python DICOM users already expect — for anything not listed here, standard DICOM behaviour applies. The points below are pydcm's deliberate choices and current limits.

Deliberate behaviours

  1. PALETTE COLOR pixel_array auto-expands to RGB. pydcm applies the palette LUT and returns an [H, W, 3] RGB array — usually what you want. For the raw index image, use pydcm.pixels.apply_color_lut to control the index → RGB step yourself.

  2. save_as of a Big-Endian / Deflated image raises rather than silently rewriting it. Deep Big-Endian support in the native parser was judged too risky for a retired transfer syntax — pydcm refuses rather than produce a file with dropped pixels.

  3. Big-Endian pixel_array byteorder is normalized to native. The values are unchanged; only the array's reported byteorder differs (int16 rather than >i2).

  4. generate_uid() mints under pydcm's own registered root — 1.2.826.0.1.3680043.9.7155. (PYDCM_ROOT_UID), so the UIDs pydcm creates carry its own identity. UIDs are opaque unique strings, so this is transparent in practice; pass an explicit prefix= for a different root, or prefix=None for a 2.25. UUID-derived UID.

Extra detail you may notice

pydcm is a superset, so you may see more than the minimum:

  • Private-tag names resolve from a 12,608-pattern vendor dictionary, so tags that are often printed as Unknown come back named (e.g. DLP, Total Saving Dose).
  • One private sequence that is usually left opaque, pydcm parses.
  • The keyword ↔ tag ↔ VR dictionary holds 17,699 entries — a strict superset of the standard dictionaries — so attribute names resolve broadly.
  • pydcm encodes too: Dataset.compress(ts) transcodes to RLE / JPEG-2000-lossless / JPEG-LS / HTJ2K / JPEG-XL, bit-lossless and genuinely encapsulated — no plugin stack required.

RT: two things worth knowing

  • DVH.counts and DVH.cumulative are both arrays, always. pydcm computes the differential histogram and its suffix-sum together and hands you both, so neither attribute is a DVH object you have to convert. bins /bincenters are the dose axis in Gy.

  • A constraint with no answer is nan, not 0 Gy. dvh.D2cc on a 0.5 cm³ structure asks about volume that is not there. NaN says so; zero would be a dose, and a wrong one. The CLI writes the same reading as JSON null.

Known limits

  • file_meta surfaces the three mandatory group-0002 UIDs (Media Storage SOP Class / Instance, Transfer Syntax), not the optional group-0002 elements.
  • A from-scratch save_as (no source file) writes Implicit or Explicit VR Little Endian — it honours file_meta.TransferSyntaxUID / implicit_vr= and includes uncompressed PixelData — but does not produce a compressed/ encapsulated or Big-Endian file from scratch (use Dataset.compress(ts) for compression).

Reporting unexpected behaviour

If you hit a behaviour that isn't listed here and looks wrong, it probably is — the policy is value-for-value correctness except where this page says otherwise.