@cosyte/dicom 0.0.1 → 0.0.4

package/README.md

@@ -1,13 +1,13 @@
 # @cosyte/dicom
 
-> Read a real-world, vendor-quirky DICOM Part 10 file and pull the metadata you need in one line — without having read the DICOM standard.
+> Read a real-world, vendor-quirky DICOM Part 10 file and pull the metadata you need in one line, without having read the DICOM standard.
 
 [![npm version](https://img.shields.io/npm/v/@cosyte/dicom.svg)](https://www.npmjs.com/package/@cosyte/dicom)
 [![CI](https://img.shields.io/github/actions/workflow/status/cosyte/dicom/ci.yml?branch=main&label=CI)](https://github.com/cosyte/dicom/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
 
-A developer-focused DICOM Part 10 parser and utility library for Node.js and TypeScript. **Metadata-first**: it reads the headers — patient, study, series, image, codes, UIDs — leniently and fast, exposes pixel data as raw bytes, and **never decodes pixels**. Sibling to [`@cosyte/hl7`](https://github.com/cosyte/hl7); same engineering bar.
+A developer-focused DICOM Part 10 parser and utility library for Node.js and TypeScript. **Metadata-first**: it reads the headers (patient, study, series, image, codes, UIDs) leniently and fast, exposes pixel data as raw bytes, and **never decodes pixels**. Sibling to [`@cosyte/hl7`](https://github.com/cosyte/hl7); same engineering bar.
 
 ---
 
@@ -16,7 +16,7 @@ A developer-focused DICOM Part 10 parser and utility library for Node.js and Typ
 Useful output after install + parse. No DICOM spec knowledge required.
 
 ```bash
-# pnpm (recommended) — also works with: npm install @cosyte/dicom  |  yarn add @cosyte/dicom
+# pnpm (recommended). Also works with: npm install @cosyte/dicom  |  yarn add @cosyte/dicom
 pnpm add @cosyte/dicom
 ```
 
@@ -26,25 +26,25 @@ import { parseDicom } from "@cosyte/dicom";
 
 const ds = parseDicom(await readFile("study.dcm"));
 
-ds.get("PatientName")?.value; // PN value — structured, never flattened
-ds.study.instanceUid; // "1.2.840.…" — the global study anchor
-ds.image.rescaleSlope; // number | undefined — undefined means "absent", never 1
+ds.get("PatientName")?.value; // PN value: structured, never flattened
+ds.study.instanceUid; // "1.2.840.…": the global study anchor
+ds.image.rescaleSlope; // number | undefined: undefined means "absent", never 1
 ```
 
-That's the pitch: no config, no schema upload, no spec lookup. The parser accepts vendor-quirky input by default — it tolerates a missing preamble, a wrong File Meta group length, odd-length values, and the dozen-or-so deviations real scanners emit — and records each as a stable warning code rather than failing. You reach for typed value decode, safety-critical views, profiles, or the serializer when you want them.
+That's the pitch: no config, no schema upload, no spec lookup. The parser accepts vendor-quirky input by default (it tolerates a missing preamble, a wrong File Meta group length, odd-length values, and the dozen-or-so deviations real scanners emit) and records each as a stable warning code rather than failing. You reach for typed value decode, safety-critical views, profiles, or the serializer when you want them.
 
 ---
 
 ## Features
 
-- **One-line metadata extraction** — `ds.patient`, `ds.study`, `ds.series`, `ds.image`: typed, fail-safe views over the safety-critical attributes. No `(group,element)` tags to memorise.
-- **Two access patterns** — named views, or structural `ds.get("PatientName")` / `ds.get("(0010,0010)")` by keyword or tag, plus `ds.elements()` to walk everything.
-- **Lazy typed value decode** — `element.value` decodes raw bytes into a discriminated `DicomValue` across all 34 VRs (numbers, `bigint`s, person names, dates/times, sequences, raw `binary`), honoring `(0008,0005)` Specific Character Set through nested items.
-- **Real-world tolerance, Postel's Law** — a lenient reader emits 24 stable warning codes for what it tolerated; only 4 truly-structural conditions are fatal. The serializer always writes spec-clean Part 10.
-- **Source/vendor profile system** — `defineProfile()` + 5 built-ins (`ge`, `siemens`, `philips`, `strict`, `lenient`) that only ever _tighten or annotate_ a parse, resolving vendor private tags by the file's live Private Creator string — never a wrong decode.
-- **Metadata-level de-identification** — `deidentify()` applies the PS3.15 Annex E Basic Profile + the nine metadata Options, returning a fresh dataset and a value-free audit report.
-- **Spec-clean serializer** — `serializeDicom(ds)` round-trips a dataset back to Part 10 bytes in its source transfer syntax (no transcode), with correct File Meta group length, even-length padding, byte-exact sequence passthrough, and lossless File Meta — non-modeled `(0002,xxxx)` elements are preserved and re-emitted in tag order.
-- **Strict TypeScript, dual ESM + CJS, Node ≥ 22** — `noUncheckedIndexedAccess`, no `any`, JSDoc + `@example` on every public export feeding your editor's IntelliSense. Zero runtime dependencies today.
+- **One-line metadata extraction**: `ds.patient`, `ds.study`, `ds.series`, `ds.image`: typed, fail-safe views over the safety-critical attributes. No `(group,element)` tags to memorise.
+- **Two access patterns**: named views, or structural `ds.get("PatientName")` / `ds.get("(0010,0010)")` by keyword or tag, plus `ds.elements()` to walk everything.
+- **Lazy typed value decode**: `element.value` decodes raw bytes into a discriminated `DicomValue` across all 34 VRs (numbers, `bigint`s, person names, dates/times, sequences, raw `binary`), honoring `(0008,0005)` Specific Character Set through nested items.
+- **Real-world tolerance, Postel's Law**: a lenient reader emits 24 stable warning codes for what it tolerated; only 4 truly-structural conditions are fatal. The serializer always writes spec-clean Part 10.
+- **Source/vendor profile system**: `defineProfile()` + 5 built-ins (`ge`, `siemens`, `philips`, `strict`, `lenient`) that only ever _tighten or annotate_ a parse, resolving vendor private tags by the file's live Private Creator string, never a wrong decode.
+- **Metadata-level de-identification**: `deidentify()` applies the PS3.15 Annex E Basic Profile + the nine metadata Options, returning a fresh dataset and a value-free audit report.
+- **Spec-clean serializer**: `serializeDicom(ds)` round-trips a dataset back to Part 10 bytes in its source transfer syntax (no transcode), with correct File Meta group length, even-length padding, byte-exact sequence passthrough, and lossless File Meta: non-modeled `(0002,xxxx)` elements are preserved and re-emitted in tag order.
+- **Strict TypeScript, dual ESM + CJS, Node ≥ 22**: `noUncheckedIndexedAccess`, no `any`, JSDoc + `@example` on every public export feeding your editor's IntelliSense. Zero runtime dependencies today.
 
 ---
 
@@ -52,18 +52,18 @@ That's the pitch: no config, no schema upload, no spec lookup. The parser accept
 
 A DICOM Part 10 file is a 128-byte preamble + the `DICM` magic, then a **File Meta** group (always Explicit VR Little Endian) naming the **transfer syntax**, then the **dataset**: a flat, tag-ordered stream of **data elements**.
 
-Each element is identified by a `(group,element)` **tag** (e.g. `(0010,0010)` = Patient's Name) and carries a two-letter **VR** (Value Representation — `PN`, `DA`, `US`, `SQ`, …) that says how to decode its bytes. Some elements are **sequences** (`SQ`): ordered lists of **items**, each a nested dataset. The transfer syntax decides endianness, whether VRs are written explicitly, and whether the stream is deflated.
+Each element is identified by a `(group,element)` **tag** (e.g. `(0010,0010)` = Patient's Name) and carries a two-letter **VR** (Value Representation: `PN`, `DA`, `US`, `SQ`, …) that says how to decode its bytes. Some elements are **sequences** (`SQ`): ordered lists of **items**, each a nested dataset. The transfer syntax decides endianness, whether VRs are written explicitly, and whether the stream is deflated.
 
 ```
 DICOM file
  ├── preamble (128 bytes) + "DICM"
- ├── File Meta group (0002,xxxx)   — transfer syntax UID, SOP Class/Instance UID
+ ├── File Meta group (0002,xxxx)   : transfer syntax UID, SOP Class/Instance UID
  └── dataset
       ├── (0008,0060) Modality           "CT"
       ├── (0010,0010) PatientName  PN     "Doe^Jane"
       ├── (0020,000D) StudyInstanceUID UI "1.2.840.…"
       ├── (0028,0100) BitsAllocated  US   16
-      └── (7FE0,0010) PixelData     OW    «raw bytes — not decoded»
+      └── (7FE0,0010) PixelData     OW    «raw bytes, not decoded»
 ```
 
 `@cosyte/dicom` reads all of that leniently and hands you typed accessors over it. The one thing it deliberately does **not** do is decode the pixels.
@@ -74,11 +74,11 @@ DICOM file
 
 ### Safety-critical views
 
-The four views — `patient`, `study`, `series`, `image` — pull the right field out of the right tag for the jobs that matter most, and they are **fail-safe**: a missing value is typed-absent (`undefined`), never a substituted default.
+The four views (`patient`, `study`, `series`, `image`) pull the right field out of the right tag for the jobs that matter most, and they are **fail-safe**: a missing value is typed-absent (`undefined`), never a substituted default.
 
 ```ts
 const p = ds.patient;
-p.id; // "MRN-42" — NOT globally unique on its own…
+p.id; // "MRN-42": NOT globally unique on its own…
 p.issuerOfId; // …pair with the issuer for cross-system matching
 p.name?.alphabetic.familyName; // structured PN, never flattened
 
@@ -95,7 +95,7 @@ s.accessionNumber; // ties the study to the HIS order (0008,0050)
 ds.get("Modality"); // by keyword
 ds.get("(0008,0060)"); // same element, by tag
 ds.has("PixelData"); // boolean
-ds.elements(); // readonly Element[] — walk everything
+ds.elements(); // readonly Element[]: walk everything
 ```
 
 ### Typed values
@@ -120,7 +120,7 @@ Recipes for the jobs a metadata parser is actually asked to do. Every attribute
 
 ### Index a folder of studies
 
-Pull a few fields out of each file to build a searchable index — the bread-and-butter PACS/archive job.
+Pull a few fields out of each file to build a searchable index: the bread-and-butter PACS/archive job.
 
 ```ts
 import { readFile } from "node:fs/promises";
@@ -145,18 +145,18 @@ Nothing here throws on a quirky file; absent fields come back `undefined`. Check
 
 ### Build routing keys
 
-Routing and reconciliation hang off a small set of identifiers. Surface them correctly — a Patient ID without its issuer is ambiguous across systems (PS3.3 C.7.1.1).
+Routing and reconciliation hang off a small set of identifiers. Surface them correctly: a Patient ID without its issuer is ambiguous across systems (PS3.3 C.7.1.1).
 
 ```ts
 // Hierarchy keys for filing into Study → Series → Instance:
-const studyKey = ds.study.instanceUid; // (0020,000D) — global anchor
+const studyKey = ds.study.instanceUid; // (0020,000D): global anchor
 const seriesKey = ds.series.instanceUid; // (0020,000E)
 const instanceKey = ds.image.sopInstanceUid; // (0008,0018)
 
-// Cross-system patient key — id ALONE is not unique; pair it with the issuer:
+// Cross-system patient key: id ALONE is not unique; pair it with the issuer:
 const p = ds.patient;
 const patientKey = `${p.issuerOfId ?? "?"}|${p.id ?? "?"}`;
-p.otherIds; // (0010,1002) Other Patient IDs Sequence — additional {id, issuer} pairs
+p.otherIds; // (0010,1002) Other Patient IDs Sequence: additional {id, issuer} pairs
 ```
 
 ### Read pixel-interpretation metadata safely
@@ -170,12 +170,12 @@ img.rescaleIntercept; // (0028,1052) apply as: stored*slope + intercept
 img.signed; // true/false only if (0028,0103) Pixel Representation was present; else undefined
 img.bitsStored; // (0028,0101)
 img.photometricInterpretation; // (0028,0004) never defaulted to MONOCHROME2
-img.pixelSpacing; // (0028,0030) patient-plane mm — distinct from imagerPixelSpacing
+img.pixelSpacing; // (0028,0030) patient-plane mm, distinct from imagerPixelSpacing
 ```
 
-> **Vendor note.** Philips writes private rescale tags `(2005,1409/140A/140B)` that shadow the standard `(0028,1052/1053)`; using the standard tags alone can yield non-quantitative values. This parser **preserves** the private tags so you can prefer them — reach them with `ds.get("(2005,1409)")` (optionally under `profiles.philips`).
+> **Vendor note.** Philips writes private rescale tags `(2005,1409/140A/140B)` that shadow the standard `(0028,1052/1053)`; using the standard tags alone can yield non-quantitative values. This parser **preserves** the private tags so you can prefer them. Reach them with `ds.get("(2005,1409)")` (optionally under `profiles.philips`).
 
-For Enhanced multi-frame objects, `image.frame(i)` resolves each frame's functional-group macros Per-Frame-else-Shared (PS3.3 C.7.6.16). It throws a `DicomValueError` — carrying only structural facts, never PHI — for an out-of-range frame or a required geometry macro missing from both groups.
+For Enhanced multi-frame objects, `image.frame(i)` resolves each frame's functional-group macros Per-Frame-else-Shared (PS3.3 C.7.6.16). It throws a `DicomValueError` (carrying only structural facts, never PHI) for an out-of-range frame or a required geometry macro missing from both groups.
 
 ```ts
 if (img.isEnhancedMultiFrame) {
@@ -187,15 +187,15 @@ if (img.isEnhancedMultiFrame) {
 
 ### De-identify before sharing
 
-`deidentify()` applies the PS3.15 Annex E Basic Application Level Confidentiality Profile — replacing, emptying, or removing every attribute the standard lists as identifying — and returns a fresh dataset plus a value-free report.
+`deidentify()` applies the PS3.15 Annex E Basic Application Level Confidentiality Profile (replacing, emptying, or removing every attribute the standard lists as identifying) and returns a fresh dataset plus a value-free report.
 
 ```ts
 import { parseDicom, deidentify, serializeDicom } from "@cosyte/dicom";
 
 const { dataset, report } = deidentify(parseDicom(buf));
-const safe = serializeDicom(dataset); // safe to share — input dataset never mutated
+const safe = serializeDicom(dataset); // safe to share: input dataset never mutated
 
-report.attributes.length; // count of attributes acted on (each carries tag/keyword/action — no values)
+report.attributes.length; // count of attributes acted on (each carries tag/keyword/action, no values)
 report.warnings; // e.g. DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED
 ```
 
@@ -210,6 +210,10 @@ deidentify(parseDicom(buf), {
 
 This is **metadata-level** de-identification. Pixel cleaning is out of scope: when a file carries burned-in annotation this layer cannot remove, you get a `DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED` warning rather than a false sense of safety (pixel cleaning is deferred to `@cosyte/dicom-pixel`).
 
+The action table comes from NEMA's PS3.15 2026c DocBook, the normative publication of the standard, rather than from a third-party mirror of it, so the current edition's patient attributes are removed rather than quietly kept. That includes the three rows the standard states as a repeating-group mask rather than a single tag: `(50xx,xxxx)` Curve Data, `(60xx,3000)` Overlay Data and `(60xx,4000)` Overlay Comments are matched in every overlay or curve group the standard defines, removed, and named in the report with the mask that matched them. Overlay comments in particular are a common carrier for text typed onto a study, so a clean report on a file that still held them was worse than no report.
+
+The groups a mask covers are the sixteen even ones PS3.5 bounds it to (`6000`-`601E`, `5000`-`501E`), not any four hex digits. Reading `xx` as a wildcard would strip attributes the standard never marked, which is data loss on a call you asked to be conservative. That bound is read out of PS3.5 itself, pinned by SHA-256 the same way the action table is, rather than copied into the source by hand: the current edition states the overlay range, and the curve range comes from the 2004 edition its own note delegates to, with the two required to agree where they overlap.
+
 ### Bridge to FHIR / HL7 v2
 
 A common consulting ask is joining imaging to the rest of the record. The authoritative crosswalk is the FHIR [`ImagingStudy` "Mappings for DICOM"](https://build.fhir.org/imagingstudy-mappings.html) tab. The join keys a metadata parser must surface correctly:
@@ -230,7 +234,7 @@ const imagingStudy = {
 const obr18 = ds.study.accessionNumber;
 ```
 
-> Series and SOP Instance UIDs are **not** represented in HL7 v2 — image-level identity lives only in DICOM.
+> Series and SOP Instance UIDs are **not** represented in HL7 v2. Image-level identity lives only in DICOM.
 
 ### Round-trip: read, edit, re-serialize
 
@@ -238,10 +242,10 @@ const obr18 = ds.study.accessionNumber;
 import { parseDicom, serializeDicom } from "@cosyte/dicom";
 
 const ds = parseDicom(buf);
-const out = serializeDicom(ds); // spec-clean Part 10, same transfer syntax — no transcode
+const out = serializeDicom(ds); // spec-clean Part 10, same transfer syntax, no transcode
 ```
 
-The serializer is the conservative half of Postel's Law: it rebuilds the File Meta group with a correct `(0002,0000)` length, pads values to even length, and re-emits sequences and encapsulated pixel data byte-for-byte. The File Meta group round-trips losslessly — non-modeled `(0002,xxxx)` elements (Sending/Receiving AE Title, Private Information, etc.) are preserved on parse and re-emitted in ascending tag order.
+The serializer is the conservative half of Postel's Law: it rebuilds the File Meta group with a correct `(0002,0000)` length, pads values to even length, and re-emits sequences and encapsulated pixel data byte-for-byte. The File Meta group round-trips losslessly: non-modeled `(0002,xxxx)` elements (Sending/Receiving AE Title, Private Information, etc.) are preserved on parse and re-emitted in ascending tag order.
 
 ---
 
@@ -256,13 +260,13 @@ import { parseDicom, profiles } from "@cosyte/dicom";
 const ds = parseDicom(buf, { profile: profiles.siemens });
 ```
 
-A profile bundles three things that only ever **tighten or annotate** a parse — never loosen it past the lenient default:
+A profile bundles three things that only ever **tighten or annotate** a parse, never loosen it past the lenient default:
 
-- **Private-dictionary overlay** — resolves the Implicit VR of vendor private data elements by the file's _live_ Private Creator string (e.g. `"SIEMENS CSA HEADER"`), keyed canonically as `"GGGGxxLL"` (PS3.5 §7.8.1), never a hard-coded block number. (This is why Agfa IMPAX re-assigning blocks still resolves.) An unknown creator degrades to `UN` plus a `DICOM_PRIVATE_CREATOR_UNKNOWN` warning.
-- **Escalations** — Tier-2 warning codes promoted to a thrown `DicomParseError` (a stricter posture for known-unsafe deviations).
-- **Suppressions** — benign, high-volume warning codes silenced for a known-quirky source.
+- **Private-dictionary overlay**: resolves the Implicit VR of vendor private data elements by the file's _live_ Private Creator string (e.g. `"SIEMENS CSA HEADER"`), keyed canonically as `"GGGGxxLL"` (PS3.5 §7.8.1), never a hard-coded block number. (This is why Agfa IMPAX re-assigning blocks still resolves.) An unknown creator degrades to `UN` plus a `DICOM_PRIVATE_CREATOR_UNKNOWN` warning.
+- **Escalations**: Tier-2 warning codes promoted to a thrown `DicomParseError` (a stricter posture for known-unsafe deviations).
+- **Suppressions**: benign, high-volume warning codes silenced for a known-quirky source.
 
-Five built-ins ship under the `profiles` namespace: `ge`, `siemens`, `philips` (vendor overlays, grounded in the public GDCM / dcm4che / dcm2niix dictionaries) and `strict` / `lenient` (posture presets). Build your own with `defineProfile()` — it validates input, composes via `extends`, and returns a frozen profile:
+Five built-ins ship under the `profiles` namespace: `ge`, `siemens`, `philips` (vendor overlays, grounded in the public GDCM / dcm4che / dcm2niix dictionaries) and `strict` / `lenient` (posture presets). Build your own with `defineProfile()`. It validates input, composes via `extends`, and returns a frozen profile:
 
 ```ts
 import { defineProfile, profiles } from "@cosyte/dicom";
@@ -284,7 +288,7 @@ At an RSNA-era interoperability test, ~80% of real-world patient CDs failed stri
 
 | Tier | Behavior       | When                           | Example codes            |
 | ---- | -------------- | ------------------------------ | ------------------------ |
-| 0    | Silent         | Spec-compliant input           | —                        |
+| 0    | Silent         | Spec-compliant input           | none                     |
 | 1    | Auto-handled   | Trivial deviation, no warning  | trailing-space tidy      |
 | 2    | Warning        | Recoverable deviation          | `DICOM_MISSING_PREAMBLE` |
 | 3    | Fatal (always) | Unrecoverable structural error | `NOT_DICOM_PART_10`      |
@@ -304,7 +308,7 @@ for (const w of ds.warnings) {
 
 The 24 Tier-2 codes (`DICOM_MISSING_PREAMBLE`, `DICOM_FILE_META_GROUP_LENGTH_MISMATCH`, `DICOM_UN_PARSED_AS_SQ`, `DICOM_ODD_LENGTH_VALUE_PADDED`, `DICOM_PRIVATE_CREATOR_UNKNOWN`, `DICOM_VR_MISMATCH`, `DICOM_DA_LEGACY_FORMAT`, … ) live in [`src/parser/warnings.ts`](./src/parser/warnings.ts). Narrow on `w.code === WARNING_CODES.…` for typo-free comparisons, or pass `{ onWarning }` to `parseDicom` to stream them.
 
-The 4 Tier-3 fatal codes — `NOT_DICOM_PART_10`, `INVALID_FILE_META`, `UNSUPPORTED_TRANSFER_SYNTAX`, `EMPTY_INPUT` — always throw a `DicomParseError`; they represent input the parser cannot meaningfully recover.
+The 4 Tier-3 fatal codes (`NOT_DICOM_PART_10`, `INVALID_FILE_META`, `UNSUPPORTED_TRANSFER_SYNTAX`, `EMPTY_INPUT`) always throw a `DicomParseError`; they represent input the parser cannot meaningfully recover.
 
 ---
 
@@ -330,7 +334,7 @@ try {
 
 ### `DicomValueError`
 
-Thrown only by `image.frame(i)` — `FRAME_INDEX_OUT_OF_RANGE` for an index outside `[0, numberOfFrames)`, or `MISSING_REQUIRED_FUNCTIONAL_GROUP` when an enhanced object lacks a required geometry macro in both the Per-Frame and Shared groups. Value decode (`element.value`) never throws — it warns and returns `null`/typed-absent instead.
+Thrown only by `image.frame(i)`: `FRAME_INDEX_OUT_OF_RANGE` for an index outside `[0, numberOfFrames)`, or `MISSING_REQUIRED_FUNCTIONAL_GROUP` when an enhanced object lacks a required geometry macro in both the Per-Frame and Shared groups. Value decode (`element.value`) never throws. It warns and returns `null`/typed-absent instead.
 
 ### `DicomSerializeError`
 
@@ -338,7 +342,7 @@ Thrown by `serializeDicom` for `MISSING_TRANSFER_SYNTAX` (the dataset names no t
 
 ### `ProfileDefinitionError` · `DeidentifyError`
 
-`defineProfile()` throws `ProfileDefinitionError` for a structurally invalid profile; `deidentify()` throws `DeidentifyError` (`INVALID_OPTIONS`) for an unknown Retain option or malformed UID root. Both messages carry only structural facts — option names, the UID root — never a decoded value.
+`defineProfile()` throws `ProfileDefinitionError` for a structurally invalid profile; `deidentify()` throws `DeidentifyError` (`INVALID_OPTIONS`) for an unknown Retain option or malformed UID root. Both messages carry only structural facts (option names, the UID root), never a decoded value.
 
 ---
 
@@ -360,18 +364,23 @@ Supported transfer syntaxes (structure for all; **pixels never decoded**): Impli
 
 v1 is metadata-feature-complete. Future companion packages (separate repos, demand-sequenced):
 
-- **`@cosyte/dicom-pixel`** — pixel decode/decompression, frame extraction, burned-in-annotation cleaning.
-- **`@cosyte/dicom-net`** — DIMSE network services.
-- **`@cosyte/dicomweb`** — QIDO / WADO / STOW REST clients.
+- **`@cosyte/dicom-pixel`**: pixel decode/decompression, frame extraction, burned-in-annotation cleaning.
+- **`@cosyte/dicom-net`**: DIMSE network services.
+- **`@cosyte/dicomweb`**: QIDO / WADO / STOW REST clients.
 
 ---
 
 ## Contributing
 
-Vendor-quirk fixtures (synthetic or properly de-identified), profile improvements, and dictionary corrections are all welcome — the more real-world edge cases the test suite covers, the more robust the parser gets. See [CONTRIBUTING.md](./CONTRIBUTING.md) if present, or open an issue.
+Vendor-quirk fixtures (synthetic or properly de-identified), profile improvements, and dictionary corrections are all welcome. The more real-world edge cases the test suite covers, the more robust the parser gets. See [CONTRIBUTING.md](./CONTRIBUTING.md) if present, or open an issue.
 
 ---
 
+## Trademarks
+
+GE, Siemens, and Philips are trademarks of their respective owners. cosyte is not affiliated with, endorsed by, or
+sponsored by any of them. The names identify the vendors whose private dictionaries the built-in profiles resolve. See [TRADEMARKS.md](./TRADEMARKS.md).
+
 ## License
 
 [MIT](./LICENSE) © Cosyte

package/TRADEMARKS.md

@@ -0,0 +1,32 @@
+# Trademarks
+
+`@cosyte/dicom` is an independent open-source project. cosyte is **not affiliated with, endorsed by,
+or sponsored by** any company named in this repository or its documentation.
+
+## Why these names appear
+
+DICOM private data elements carry no on-wire VR under Implicit VR Little Endian, so resolving them
+requires knowing whose private blocks they belong to. Naming the vendor is the only way to
+describe (or correctly decode) its private dictionary.
+
+Every reference is **descriptive**: it identifies whose private dictionary a profile resolves, and nothing more. Naming a system is the only way to say
+whether a library works with it.
+
+## Where the profiles come from
+
+The built-in source profiles are authored through this package's own public `defineProfile()` API,
+from public open-source dictionaries (the GDCM private dictionary and dcm2niix tag notes) and
+from vendor-published schema identifiers. Each profile documents its sources inline. They embed
+no privileged, confidential, or reverse-engineered material, and no patient data.
+
+## Names referenced
+
+| Name    | Where it appears                                                              |
+| ------- | ----------------------------------------------------------------------------- |
+| GE      | `profiles.ge`: a built-in profile name, resolving the `GEMS_*` private blocks |
+| Siemens | `profiles.siemens`: a built-in profile name                                   |
+| Philips | `profiles.philips`: a built-in profile name                                   |
+
+All product names, logos, and brands are the property of their respective owners. Use of a name here
+does not imply any affiliation with, or endorsement by, its owner. If you own one of these marks and
+would like a reference changed, please open an issue.