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

Pure Elixir DICOM P10 parser and writer.

Provides functions to parse DICOM Part 10 files into structured data sets
and serialize them back. Built on Elixir's binary pattern matching for
fast, streaming-capable parsing.

## Quick Start

    # Parse a DICOM file
    {:ok, data_set} = Dicom.parse_file("/path/to/image.dcm")

    # Access patient name
    patient_name = Dicom.DataSet.get(data_set, Dicom.Tag.patient_name())

    # Write back to file
    :ok = Dicom.write_file(data_set, "/path/to/output.dcm")

## DICOM Standard Coverage

- PS3.5 — Data Structures and Encoding
- PS3.6 — Data Dictionary
- PS3.10 — Media Storage and File Format

# `parse`

```elixir
@spec parse(binary()) :: {:ok, Dicom.DataSet.t()} | {:error, term()}
```

Parses a DICOM P10 binary into a `Dicom.DataSet`.

The binary must start with the 128-byte preamble followed by the "DICM"
magic bytes, then File Meta Information and the data set.

## Examples

    {:ok, data_set} = Dicom.parse(binary)
    {:error, :invalid_preamble} = Dicom.parse(<<"not dicom">>)

# `parse_file`

```elixir
@spec parse_file(Path.t()) :: {:ok, Dicom.DataSet.t()} | {:error, term()}
```

Parses a DICOM P10 file from disk.

## Examples

    {:ok, data_set} = Dicom.parse_file("/path/to/image.dcm")
    {:error, :enoent} = Dicom.parse_file("/nonexistent.dcm")

# `stream_parse`

```elixir
@spec stream_parse(binary()) :: Enumerable.t()
```

Parses a DICOM P10 binary into a lazy stream of events.

Returns an `Enumerable` that emits `Dicom.P10.Stream.Event` values as the
binary is traversed. Use with `Enum` or `Stream` functions.

## Examples

    events = Dicom.stream_parse(binary)
    tags = events
           |> Stream.filter(&match?({:element, _}, &1))
           |> Enum.map(fn {:element, elem} -> elem.tag end)

# `stream_parse_file`

```elixir
@spec stream_parse_file(
  Path.t(),
  keyword()
) :: Enumerable.t()
```

Parses a DICOM P10 file into a lazy stream of events.

Opens the file and streams events lazily. The file handle is closed
when the stream is fully consumed or halted.

## Examples

    events = Dicom.stream_parse_file("/path/to/image.dcm")
    {:ok, data_set} = Dicom.P10.Stream.to_data_set(events)

# `write`

```elixir
@spec write(Dicom.DataSet.t()) :: {:ok, binary()} | {:error, term()}
```

Serializes a `Dicom.DataSet` to DICOM P10 binary format.

# `write_file`

```elixir
@spec write_file(Dicom.DataSet.t(), Path.t()) :: :ok | {:error, term()}
```

Writes a `Dicom.DataSet` to a DICOM P10 file on disk.

---

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