python-gdcm

Common errors

• ModuleNotFoundError: No module named '_gdcm.gdcmswig'

  cause A local directory named `_gdcm` exists in your Python path, shadowing the actual internal module.
  fix Rename or remove the `_gdcm` directory in your current working directory or any directory where Python searches for modules before the site-packages containing `python-gdcm`.

• ImportError: DLL load failed: The specified module could not be found.

  cause This error, particularly on Windows, indicates that necessary underlying C++ dynamic link libraries (DLLs) for GDCM are not found or are incompatible with your Python environment. This can happen with manual GDCM installations or when using older, non-wheel-based distributions.
  fix Ensure you installed `python-gdcm` via `pip install -U python-gdcm` to get pre-compiled wheels, which usually bundle necessary DLLs. Verify your Python version is compatible (`>=3.7`). If building from source, ensure all C++ dependencies (like compilers, CMake, SWIG) are correctly configured and their output is on the system PATH.

• AttributeError: module 'gdcm' has no attribute 'DataElement'

  cause This error often occurs when `pydicom` attempts to use `gdcm` as a pixel data handler, but the `gdcm` module found is not the expected library (e.g., a local directory named `gdcm` or an incomplete installation) and therefore lacks the necessary attributes.
  fix Check for any local directories named `gdcm` in your Python path and rename them. Ensure `python-gdcm` is correctly installed via `pip`. If using `pydicom`, consider its specific version requirements for `gdcm`.

Warnings

• gotcha When using `import gdcm`, ensure that your current working directory does not contain a folder named `_gdcm`. If such a folder exists, it can lead to a `ModuleNotFoundError: No module named '_gdcm.gdcmswig'` or other unexpected import errors due to Python's module resolution order conflicting with the internal structure of the `python-gdcm` package.
  Fix: Rename or remove any local `_gdcm` directory if you encounter import issues.
• breaking Previous versions of GDCM for Python (before the `python-gdcm` PyPI package became the primary distribution) often had complex installation procedures, especially on Windows, and could be sensitive to the Python version. The `python-gdcm` package on PyPI aims to provide pre-built wheels for common platforms, significantly simplifying installation. However, older manual installations might lead to `ImportError: DLL load failed` due to missing C++ runtime libraries or incorrect Python bindings.
  Fix: Always prefer `pip install python-gdcm` to leverage pre-built wheels. Ensure your Python environment meets the `>=3.7` requirement. For issues related to third-party libraries like `pydicom` using `gdcm` as a backend, verify `pydicom`'s compatibility with your `python-gdcm` version.
• gotcha Although `python-gdcm` wraps the C++ GDCM library, direct breaking changes within the Python API between `python-gdcm` versions 3.0.x and 3.2.x are not widely documented. Most compatibility concerns arise from interactions with other Python DICOM libraries like `pydicom`, which might have their own breaking changes or specific GDCM version requirements. For example, `pydicom` v3.0.0 introduced breaking changes and may interact differently with GDCM.
  Fix: When upgrading `python-gdcm` alongside other DICOM libraries, consult the release notes for all involved packages for potential interaction issues. Test thoroughly after upgrades.

Install

• pip install -U python-gdcm Install latest stable version

Imports

• gdcm
  wrong:

  import _gdcm.gdcmswig

  correct:

  import gdcm

  The `_gdcm.gdcmswig` module is an internal SWIG-generated module and should not be imported directly. The `gdcm` module is the public entry point.

Quickstart

This quickstart demonstrates how to read a DICOM image file using `gdcm.ImageReader`. It initializes a reader, sets the file name, attempts to read the file, and prints a success or error message.

import gdcm

# Assuming 'dicom_image_file.dcm' exists in the current directory
# Or provide a full path: reader.SetFileName('/path/to/your/dicom_image_file.dcm')

reader = gdcm.ImageReader()
reader.SetFileName("dicom_image_file.dcm")

if reader.Read():
    image = reader.GetImage()
    print(f"DICOM image successfully read. Dimensions: {image.GetDimension(0)}x{image.GetDimension(1)}")
    # Further processing, e.g., accessing pixel data:
    # pixel_array = image.GetBuffer()
else:
    print(f"Error: It was not possible to read 'dicom_image_file.dcm'.")