Merge pull request #56 from jcupitt/main

Update to 1.0

.editorconfig

@@ -0,0 +1,15 @@
+# http://editorconfig.org
+
+[*]
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{cpp,c,h}]
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_style = space
+indent_size = 4

.github/workflows/codespell.yml

@@ -1,14 +1,8 @@
----
 name: Codespell
 
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
+on: [push, pull_request]
 
-permissions:
-  contents: read
+permissions: {}
 
 jobs:
   codespell:

.github/workflows/run_unit_tests.yml

@@ -46,7 +46,7 @@ jobs:
 
     - name: Install build and test dependencies (Windows)
       if: startsWith(matrix.os, 'windows')
-      run: pip install meson
+      run: pip install meson ninja
 
     - name: Build and install library
       shell: bash

README.md

@@ -1,4 +1,5 @@
-[![Build Status](https://github.com/ImagingDataCommons/libdicom/actions/workflows/run_unit_tests.yml/badge.svg)](https://github.com/ImagingDataCommons/libdicom/actions)
+[![Build
+Status](https://github.com/ImagingDataCommons/libdicom/actions/workflows/run_unit_tests.yml/badge.svg)](https://github.com/ImagingDataCommons/libdicom/actions)
 
 # libdicom
 
@@ -8,19 +9,43 @@ C library and executable tools for reading DICOM files.
 
 ### Building from source
 
-```none
+```shell
 meson setup --buildtype release builddir
 meson compile -C builddir
 meson install -C builddir
 ```
-See [the installation documentation](https://libdicom.readthedocs.io/en/latest/installation.html) for build dependencies and installation options.
+See [the installation
+documentation](https://libdicom.readthedocs.io/en/latest/installation.html)
+for build dependencies and installation options.
 
 ### Printing the metadata of a DICOM file
 
-```none
+```shell
 dcm-dump data/test_files/sm_image.dcm
 ```
 
+### Fetching a frame from a file
+
+```shell
+dcm-getframe -o tile.raw data/test_files/sm_image.dcm 12
+```
+
+### From Python
+
+There's a sample Python binding here:
+
+https://github.com/ImagingDataCommons/pylibdicom
+
 ## Documentation
 
-User and developer guides as well as API documentation can be found at [libdicom.readthedocs.io](https://libdicom.readthedocs.io/en/latest/).
+User and developer guides as well as API documentation can be found at
+[libdicom.readthedocs.io](https://libdicom.readthedocs.io/en/latest/).
+
+# Thanks
+
+Development of this library was supported by [NCI Imaging Data
+Commons](https://imaging.datacommons.cancer.gov/), and has been funded in
+whole or in part with Federal funds from the National Cancer Institute,
+National Institutes of Health, under Task Order No. HHSN26110071 under
+Contract No. HHSN261201500003l.
+

doc/source/api.rst

@@ -1,4 +1,4 @@
 API documentation
 -----------------
 
-.. c:autodoc:: dicom.h
+.. c:autodoc:: dicom/dicom.h

doc/source/conf.py

@@ -14,6 +14,7 @@
 import os
 import sys
 from hawkmoth.util import readthedocs
+from hawkmoth.util import compiler
 from clang.cindex import Config as clang_config
 
 # -- Project information -----------------------------------------------------
@@ -22,7 +23,6 @@
 copyright = '2021, Markus D. Herrmann'
 author = 'Markus D. Herrmann'
 
-
 # -- General configuration ---------------------------------------------------
 
 primary_domain = 'c'
@@ -57,8 +57,11 @@
 
 # -- Hawkmoth extension ------------------------------------------------------
 
-cautodoc_root = os.path.abspath('../../include')
+hawkmoth_root = os.path.abspath('../../include')
 readthedocs.clang_setup()
+hawkmoth_clang = compiler.get_include_args()
+# we need build to get version.h
+hawkmoth_clang.append(f"-I{os.path.abspath('../../build')}")
 if sys.platform == 'darwin':
     lib_search_dirs = [
         '/usr/lib',

doc/source/contributing.rst

@@ -4,7 +4,9 @@ Contributing
 Coding style
 ++++++++++++
 
-Source code should be written following the `K&R (Kernighan & Ritchie) style <https://en.wikipedia.org/wiki/Indentation_style#K&R_style>`_ with a few modifications.
+Source code should be written following the `K&R (Kernighan & Ritchie)
+style <https://en.wikipedia.org/wiki/Indentation_style#K&R_style>`_ with
+a few modifications.
 
 * Line length: max 80 characters
 
@@ -13,68 +15,107 @@ Source code should be written following the `K&R (Kernighan & Ritchie) style <ht
 * Braces:
 
   - Functions: opening brace at next line
+
   - Control statements (mandatory): opening brace at same line
 
 * Spacing:
 
   - 2 lines between function definitions
-  - 1 line between logical blocks within functions (and between variable declarations and definitions)
+
+  - 1 line between logical blocks within functions (and between variable
+    declarations and definitions)
 
 * Comments:
 
-  - Documentation of functions and other symbols: balanced, multi-line ``/** ... */`` comments in `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ format using `field lists <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists>`_ ``:param:`` and ``:return:`` to document function parameters and return values, respectively, and ``:c:member:``, ``:c:func:``, ``:c:macro:``, ``:c:struct:``, ``:c:union:``, ``:c:enum:``, ``:c:enumerator:``, ``:c:type:``, ``:c:expr:``, ``:c:var:`` from the `Sphinx C domain <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain>`_ directive to `cross-reference other C language constructs <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-c-constructs>`_ or to insert a C expression as inline code.
+  - Documentation of functions and other symbols: balanced,
+    multi-line ``/** ... */`` comments in `reStructuredText
+    <https://docutils.sourceforge.io/rst.html>`_ format using `field lists
+    <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists>`_
+    ``:param:`` and ``:return:`` to document function parameters and return
+    values, respectively, and ``:c:member:``, ``:c:func:``, ``:c:macro:``,
+    ``:c:struct:``, ``:c:union:``, ``:c:enum:``, ``:c:enumerator:``,
+    ``:c:type:``, ``:c:expr:``, ``:c:var:`` from the `Sphinx C domain
+    <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain>`_
+    directive to `cross-reference other C language constructs
+    <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-c-constructs>`_
+    or to insert a C expression as inline code.
 
   - Inline comments in function body: single-line ``//`` C++ style comments
 
 * Naming conventions:
 
-  - Data structures (``struct`` or ``enum``) and types are named using upper camel case (e.g., ``DcmDataSet``), while functions are named using all lower case with underscores (e.g., ``dcm_dataset_create()``).
+  - Data structures (``struct`` or ``enum``) and types are named using
+    upper camel case (e.g., ``DcmDataSet``), while functions are named using
+    all lower case with underscores (e.g., ``dcm_dataset_create()``).
 
-  - Names of ``external`` functions, data structures, and types that are declared in the ``dicom.h`` header file are prefixed with ``dcm_`` or ``Dcm``. Names of ``static`` functions, types, or data structures declared in ``*.c`` files are never prefixed.
+  - Names of ``external`` functions, data structures, and types that are
+    declared in the ``dicom.h`` header file are prefixed with ``dcm_`` or
+    ``Dcm``. Names of ``static`` functions, types, or data structures declared
+    in ``*.c`` files are never prefixed.
 
 
 Interface
 +++++++++
 
-The library exposes an "object-oriented" application programming interface (API), which provides data structures and functions to store, access, and manipulate the data.
+The library exposes an "object-oriented" application programming interface
+(API), which provides data structures and functions to store, access,
+and manipulate the data.
 
 To facilitate portability, the ``dicom.h`` header file is restricted to
 
-* C99 version of the standard (C89 + Boolean type from ``stdbool.h`` + fixed-width integer types from ``stdint.h``/``inttypes.h``)
+* C99 version of the standard (C89 + Boolean type from ``stdbool.h`` +
+  fixed-width integer types from ``stdint.h``/``inttypes.h``)
+
 * Opaque data types
-* Clear, exact-width integer types (``int16_t``, ``int32_t``, ``int64_t``, ``uint16_t``, ``uint32_t``, and ``uint64_t``)
+
+* Clear, exact-width integer types (``int16_t``, ``int32_t``, ``int64_t``,
+  ``uint16_t``, ``uint32_t``, and ``uint64_t``)
+
 * Minimal use of enums
 
 
 Implementation
 ++++++++++++++
 
-The ``dicom-data.c`` (Part 5), ``dicom-dict.c`` (Part 6), and ``dicom-file.c`` (Part 10) are implemented based on the C11 version of the standard.
+The ``dicom-data.c`` (Part 5), ``dicom-dict.c`` (Part 6), and ``dicom-file.c``
+ and ``dicom-parse.c`` (Part 10) are implemented based on the C11 version
+ of the standard.
 
-The Data Set and Sequence data structures are implemented using the battletested `uthash <https://troydhanson.github.io/uthash>`_ headers.
+The Data Set and Sequence data structures are implemented using the
+battletested `uthash <https://troydhanson.github.io/uthash>`_ headers.
 
 
 Documentation
 +++++++++++++
 
-Documentation is written in `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ format and HTML documents are autogenerated using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
-API documentation is automatically extracted from the comments in the source code in the ``dicom.h`` header file via the `Hawkmoth Sphinx C Autodoc <https://hawkmoth.readthedocs.io/en/latest/index.html>`_ extension, which relies on `Clang <https://libclang.readthedocs.io/en/latest/index.html>`_ to parse C code.
+Documentation is written in `reStructuredText
+<https://docutils.sourceforge.io/rst.html>`_ format and HTML documents
+are autogenerated using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+API documentation is automatically extracted from the comments in the source
+code in the ``dicom.h`` header file via the `Hawkmoth Sphinx C Autodoc
+<https://hawkmoth.readthedocs.io/en/latest/index.html>`_ extension, which
+relies on `Clang <https://libclang.readthedocs.io/en/latest/index.html>`_
+to parse C code.
 
-Documentation files are located under the ``doc/source`` directory of the repository.
-To build the documentation, install ``libclang`` development headers and the Python ``venv`` module, then build with ``meson``:
+Documentation files are located under the ``doc/source`` directory of the
+repository.  To build the documentation, install ``libclang`` development
+headers and the Python ``venv`` module, then build with ``meson``:
 
     meson compile -C builddir html
 
-The generated documentation files will then be located under the ``builddir/html`` directory.
-The ``builddir/html/index.html`` HTML document can be rendered in the web browser.
+The generated documentation files will then be located under the
+``builddir/html`` directory.  The ``builddir/html/index.html`` HTML document
+can be rendered in the web browser.
 
 
 Testing
 +++++++
 
-Unit test cases are defined and run using `check <https://github.com/libcheck/check>`_.
+Unit test cases are defined and run using `check
+<https://github.com/libcheck/check>`_.
 
-Test files are located under ``/tests`` and can be built and run using ``meson``::
+Test files are located under ``/tests`` and can be built and run using
+``meson``::
 
     meson test -C builddir
 
@@ -87,8 +128,8 @@ For example::
 
     valgrind --leak-check=full dcm-dump data/test_files/sm_image.dcm
 
-
-Unit testing and dynamic analysis can also be performed using the provided `Dockerfile` (located in the root of the repository)::
+Unit testing and dynamic analysis can also be performed using the provided
+`Dockerfile` (located in the root of the repository)::
 
     docker build -t dcm-testing .
     docker run dcm-testing

doc/source/installation.rst

@@ -4,7 +4,8 @@ Installation
 Building
 ++++++++
 
-The library and executables can be built using `Meson <https://mesonbuild.com/>`_:
+The library and executables can be built using `Meson
+<https://mesonbuild.com/>`_:
 
 .. code:: bash
 
@@ -45,15 +46,18 @@ Build for development and debugging:
 
 .. code:: bash
 
-    CFLAGS="-DDEBUG" meson setup builddir
+    meson setup builddir --buildtype debug
     meson compile -C builddir
 
 
 Optional dependencies
 +++++++++++++++++++++
 
-This package uses `check <https://libcheck.github.io/check/>`_ for unit testing and `uthash <https://troydhanson.github.io/uthash/>`_ for data structures.
-It will automatically download and build both libraries, or can use system copies.
+This package uses `check <https://libcheck.github.io/check/>`_ for unit
+testing and `uthash <https://troydhanson.github.io/uthash/>`_ for data
+structures.  It will automatically download and build both libraries,
+or can use system copies.
+
 To install system copies:
 
 On Debian-based Linux distributions: