# `Dicom.Json`
[🔗](https://github.com/Balneario-de-Cofrentes/dicom/blob/v0.5.1/lib/dicom/json.ex#L1)

DICOM JSON Model (PS3.18 Annex F.2).

Encodes and decodes DICOM DataSets to/from the DICOM JSON model
used by DICOMweb (STOW-RS, WADO-RS, QIDO-RS).

Produces/consumes plain Elixir maps — any JSON library (Jason, Poison)
can serialize the result to a JSON string.

## Examples

    # Encode a DataSet to a DICOM JSON map
    map = Dicom.Json.to_map(data_set)
    json_string = Jason.encode!(map)

    # Decode a DICOM JSON map back to a DataSet
    {:ok, data_set} = Dicom.Json.from_map(map)

    # Resolve BulkDataURI references during decode
    {:ok, data_set} =
      Dicom.Json.from_map(map,
        bulk_data_resolver: fn _tag, _vr, uri ->
          File.read(uri)
        end
      )

Reference: DICOM PS3.18 Annex F.2.

# `from_map`

```elixir
@spec from_map(
  map(),
  keyword()
) :: {:ok, Dicom.DataSet.t()} | {:error, term()}
```

Decodes a DICOM JSON map into a `Dicom.DataSet`.

## Options

- `bulk_data_resolver` — `fn tag, vr, uri -> {:ok, binary} | {:error, reason} end`
  used to resolve `BulkDataURI` entries during decode. Without a resolver,
  `BulkDataURI` returns an error instead of being stored as element bytes.
- `transfer_syntax_uid` — transfer syntax context used to interpret compressed
  Pixel Data JSON payloads. When omitted, `from_map/2` also checks file meta
  `(0002,0010)` after decoding.

For compressed transfer syntaxes, Pixel Data JSON binary payloads must contain
a valid encapsulated DICOM Value Field. They are normalized to
`{:encapsulated, fragments}` during decode instead of being left as raw bytes.
Returns `{:ok, data_set}` or `{:error, reason}`.

# `to_map`

```elixir
@spec to_map(
  Dicom.DataSet.t(),
  keyword()
) :: map()
```

Converts a `Dicom.DataSet` to a DICOM JSON map.

## Options

- `include_file_meta` — include group 0002 elements (default: `false`)
- `bulk_data_uri` — `fn tag, vr -> url | nil end` to emit BulkDataURI
  instead of InlineBinary for binary VRs. For encapsulated pixel data, the
  URI or inline payload represents the full DICOM Value Field, including the
  Basic Offset Table item, fragment items, and sequence delimiter.

---

*Consult [api-reference.md](api-reference.md) for complete listing*