.. _writing_dicom_files:
.. title:: Writing DICOM Files

Writing DICOM Files
===================

.. currentmodule:: pydicom

.. rubric:: How to write DICOM files using pydicom.

Introduction
------------

Probably the most common use of pydicom is to read an existing DICOM file,
alter some items, and write it back out again. The first example in
:doc:`getting_started` shows how to do this.

If you need to create a DICOM file from scratch, there are a couple of ways
of going about this: using the "codify" script, or creating a Dataset directly
and populating it.

.. Warning::

  To be truly DICOM compliant, certain data elements will be required in the
  file meta information, and in the main dataset. Also, you should create your
  own UIDs, implementation name, and so on.


Using the Codify Script
-----------------------

In the pydicom 'util' folder, there is a script called `codify.py
<https://github.com/pydicom/pydicom/blob/master/pydicom/util/codify.py>`_.
It takes an existing DICOM file, and produces python code. The python code
uses pydicom to produce a copy of the original file again, when the code is
run.

In other words: pydicom has a tool that can automatically generate
well-designed python code for you - code that creates DICOM files. The only
requirement is that you have an existing DICOM file that looks approximately
like the one you need. You can then use the code as a model to work from. The
tool is especially useful with Sequences, which can be tricky to code
correctly.

.. Warning::

  The code produced by codify will contain all the information in the original
  file, which may include private health information or other sensitive
  information.  If the code is run, the resulting dicom file will also contain
  that information. You may want to consider using de-identified dicom files
  with codify, or handling the output files according to your requirements for
  sensitive information.

One issue to be aware of is that codify will not create code for large items
like pixel data. Instead it creates a line like:

.. code-block:: python

   ds.PixelData = # XXX Array of 524288 bytes excluded

In that case, the code will produce a syntax error when run, and you will have
to edit the code to supply a valid value.

.. note:: The --exclude-size parameter can set the maximum size of the data
   element value that is coded. Data elements bigger than that will have the
   syntax error line as shown above.

One potential disadvantage of codify, depending on your use case, is that it
does not create loops. If you have, say, 30 items in a Sequence, codify will
produce code that makes them one at a time. Code you wrote by hand would
likely create them in a loop, because most of the code needed is quite
repetitive. If you want to switch to a loop, you could use the first item's
code as a starting point, and modify as needed, deleting the code for the
other individual items.

Codify could also be called from code, rather than as a script; you can look
at the codify.py source and the ``code_file`` function for a starting point
for that.

To call codify as a script, use::

    python <path-to-pydicom-util folder>/codify.py -s savename dicom-file createdicomfile.py

The -s parameter is optional, but if present, is followed by a save filename
(the DICOM filename that would be created when the code is run). If not
specified, then a modified version of the input dicom filename is used. The
output file (createdicomfile.py in the example above) is optional.  If nothing
is specified, the code is written to standard output.

There is also a parameter ``--exclude-private`` if you don't want private data
elements to be included in the generated code.

You can also call codify with ``--help`` to see details of all the parameters.


Writing a file from Scratch
---------------------------

The codify tool, described in the previous section, is a good starting point
for pydicom code, but if you can't (or don't want to) use that tool, then you
can certainly write code from scratch to make a complete DICOM file using
pydicom.

It's not particularly difficult, but to produce a valid DICOM file requires
specific items to be created.  A basic example of that is available in the 
example file :ref:`sphx_glr_auto_examples_input_output_plot_write_dicom.py`.

Just don't forget the warnings in the Introduction section above, and be sure
to create all the required DICOM data elements.
