@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">>)

@spec parse_data_set(binary(), String.t()) ::
  {:ok, Dicom.DataSet.t()} | {:error, term()}

Parses a raw DICOM data set binary using the given transfer syntax UID.

Unlike parse/1, this expects only the encoded data set payload used by DIMSE services, not a full Part 10 file with preamble and file meta.

@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")

@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)

@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)

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

Serializes a Dicom.DataSet to DICOM P10 binary format.

@spec write_data_set(Dicom.DataSet.t(), String.t()) ::
  {:ok, binary()} | {:error, term()}

Serializes a Dicom.DataSet as a raw DICOM data set using the given transfer syntax UID.

Unlike write/1, this writes only the encoded data set payload used by DIMSE services, without Part 10 preamble or file meta information.

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

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