PHPackages                             rbraunm/class\_dicom - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. rbraunm/class\_dicom

ActiveLibrary[Utility & Helpers](/categories/utility)

rbraunm/class\_dicom
====================

PHP library for DICOM tag handling, image conversion, compression, and networking via DCMTK

v1.1.0(1mo ago)2449MITPHPPHP >=8.0

Since Sep 2Pushed 1mo agoCompare

[ Source](https://github.com/rbraunm/class_dicom.php)[ Packagist](https://packagist.org/packages/rbraunm/class_dicom)[ RSS](/packages/rbraunm-class-dicom/feed)WikiDiscussions main Synced 4w ago

READMEChangelog (2)DependenciesVersions (5)Used By (0)

class\_dicom.php
================

[](#class_dicomphp)

A PHP library for working with DICOM medical images. Handles tag reading and writing, JPEG conversion, compression, and DICOM networking (C-ECHO, C-STORE send and receive) by wrapping the [DCMTK](https://dicom.offis.de/dcmtk.php.en) command-line toolkit.

Originally created by Dean Vaughan ([deanvaughan.org](http://www.deanvaughan.org/projects/class_dicom_php/)).

Requirements
------------

[](#requirements)

- PHP 8.0 or later (CLI or web)
- [DCMTK](https://dicom.offis.de/dcmtk.php.en) command-line utilities installed and accessible

By default the library looks for DCMTK binaries in `/usr/local/bin`. If your installation is elsewhere, edit the `TOOLKIT_DIR` constant at the top of `class_dicom.php`.

On Debian/Ubuntu:

```
apt install php-cli dcmtk
```

Installation
------------

[](#installation)

### Composer

[](#composer)

```
composer require rbraunm/class_dicom
```

### Manual

[](#manual)

Copy `class_dicom.php` into your project and require it directly:

```
require_once('class_dicom.php');
```

Usage
-----

[](#usage)

### Reading DICOM tags

[](#reading-dicom-tags)

```
$d = new dicom_tag('/path/to/image.dcm');
$patient_name = $d->get_tag('0010', '0010');
$modality     = $d->get_tag('0008', '0060');

// All loaded tags are available in $d->tags as an associative array
// keyed by "group,element" (e.g. "0010,0010")
```

The constructor calls `load_tags()` automatically if the file exists and passes the `is_dcm()` check. Tags can also be loaded manually:

```
$d = new dicom_tag;
$d->file = '/path/to/image.dcm';
$d->load_tags();
```

### Writing DICOM tags

[](#writing-dicom-tags)

```
$d = new dicom_tag('/path/to/image.dcm');
$d->write_tags([
    '0010,0010' => 'DOE^JOHN',
    '0008,0080' => 'General Hospital',
]);
```

This modifies the file in place using `dcmodify`.

### Converting DICOM to JPEG

[](#converting-dicom-to-jpeg)

```
$c = new dicom_convert('/path/to/image.dcm');

// Full-size JPEG
$c->jpg_quality = 90;  // 0-100, default 100
$jpg_path = $c->dcm_to_jpg();

// Thumbnail
$c->tn_size = 200;  // width in pixels, default 125
$tn_path = $c->dcm_to_tn();
```

### Compression and decompression

[](#compression-and-decompression)

```
$c = new dicom_convert('/path/to/image.dcm');

// Decompress to a new file (or omit the argument to overwrite)
$c->uncompress('/path/to/output.dcm');

// JPEG lossless compress
$c->compress('/path/to/compressed.dcm');
```

### Converting JPEG to DICOM

[](#converting-jpeg-to-dicom)

> **Known issue:** `jpg_to_dcm()` treats any output from `xml2dcm` as a fatal error. The bundled XML template (`examples/jpg_to_dcm.xml`) produces a SOPInstanceUID mismatch warning on current DCMTK versions, which causes the function to return early without embedding pixel data. The resulting file is a valid DICOM header but contains no image. This will be fixed in v2.0.0.

The intended usage (once fixed) follows the pattern in `examples/jpg_to_dcm.php`:

```
$c = new dicom_convert;
$c->jpg_file  = '/path/to/photo.jpg';
$c->template  = '/path/to/jpg_to_dcm.xml';  // see examples/jpg_to_dcm.xml
$c->temp_dir  = '/tmp/dcm_temp';

$dcm_path = $c->jpg_to_dcm([
    '0008,0012' => date('Ymd'),
    '0008,0013' => date('Gis'),
    '0008,0050' => 'ACCESSION123',
    '0008,0080' => 'General Hospital',
    '0008,0090' => 'Dr. Smith',
    '0008,1030' => 'Study Description',
    '0008,103e' => 'Series Description',
    '0010,0010' => 'DOE^JOHN',
    '0010,0020' => 'PATIENT001',
    '0010,0030' => '19700101',
    '0010,0040' => 'M',
    '0010,21b0' => 'Patient History',
    '0010,4000' => 'Patient Comments',
    '0018,0015' => 'Head',
    '0020,000d' => '1.3.51.0.7.2822962297.26312.19209.44846.7354.10266.42',
    '0020,000e' => '1.3.51.5156.4083.' . date('Ymd') . '.42',
    '0020,0011' => '1',
    '0020,0012' => '1',
    '0020,0013' => '1',
]);
```

The tag keys must match the `(group,element)` placeholders in the XML template. See `examples/jpg_to_dcm.php` for the full tag mapping.

### Multiframe DICOM to video

[](#multiframe-dicom-to-video)

```
$c = new dicom_convert('/path/to/multiframe.dcm');
$video_path = $c->multiframe_to_video('mp4', 24, '/tmp/video_temp');
```

Requires `ffmpeg` on the system.

### DICOM networking

[](#dicom-networking)

```
$n = new dicom_net;

// C-ECHO (DICOM ping)
$result = $n->echoscu('192.168.1.100', 104, 'MY_AE', 'REMOTE_AE');
// Returns 0 on success, error output string on failure

// C-STORE send (single file)
$n->file = '/path/to/image.dcm';
$n->send_dcm('192.168.1.100', 104, 'MY_AE', 'REMOTE_AE');

// C-STORE send (batch — all files in the same directory)
$n->file = '/path/to/image.dcm';
$n->send_dcm('192.168.1.100', 104, 'MY_AE', 'REMOTE_AE', 1);

// C-STORE receive (blocking — starts a DICOM listener)
$n->store_server(
    11112,                              // port
    '/var/dicom/incoming',              // storage directory
    '/path/to/handler_script.php',      // called after each file received
    '/path/to/store_server_config.cfg', // storescp config
);
```

See `examples/store_server.php`, `examples/store_server_handler.php`, and `examples/store_server_config.cfg` for a working receive setup.

### Utility functions

[](#utility-functions)

```
// Check if a file is valid DICOM
if (is_dcm('/path/to/file')) {
    // it's DICOM
}
```

Testing
-------

[](#testing)

The test suite uses PHP + DCMTK for the code under test and Python for independent validation. This ensures DICOM files produced by the library are verified by a completely separate implementation, not just read back by the same tools that wrote them.

### Test dependencies

[](#test-dependencies)

```
# System packages
apt install php-cli dcmtk

# Python packages
pip install pydicom pynetdicom Pillow numpy
```

### Running tests

[](#running-tests)

```
python3 tests/test_class_dicom.py
```

The test runner exercises every public method against real DICOM files:

- Tag reads are cross-validated against pydicom
- Tag writes are confirmed by both PHP re-read and pydicom
- JPEG conversions are validated with Pillow (magic bytes, full decode, dimension matching)
- Compress/uncompress cycles verify transfer syntax changes, demographic preservation, and pixel data integrity
- Network operations run against a pynetdicom SCP that confirms C-ECHO events server-side and validates C-STORE round-trips down to pixel-level array equality

API reference
-------------

[](#api-reference)

### Classes

[](#classes)

ClassPurpose`dicom_tag`Read and write DICOM tags via dcmdump/dcmodify`dicom_convert`Image format conversion, compression, thumbnails`dicom_net`DICOM networking: C-ECHO, C-STORE SCU/SCP### Standalone functions

[](#standalone-functions)

FunctionPurpose`is_dcm($file)`Returns 1 if the file is valid DICOM, 0 otherwise`Execute($command)`Shell execution wrapper (captures stdout + stderr)Examples
--------

[](#examples)

The `examples/` directory contains working scripts for common operations:

FileDescription`get_tags.php`Read and display tags from a DICOM file`get_tags_webbased.php`Same, formatted for browser output`write_tags.php`Modify tags in a DICOM file`dcm_to_jpg.php`Convert DICOM to JPEG`jpg_to_dcm.php`Convert JPEG to DICOM with custom tags`jpg_to_dcm.xml`XML template for JPEG-to-DICOM conversion`compress.php`JPEG lossless compress a DICOM file`uncompress.php`Decompress a DICOM file`send_dcm.php`Send a DICOM file to a remote host`send_directory.php`Send all files in a directory`store_server.php`Start a DICOM receive server`store_server_handler.php`Handler script called after each received file`store_server_config.cfg`Configuration for the receive serverLicense
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 89% of packages

Maintenance93

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 73.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~267 days

Total

2

Last Release

33d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/5680061?v=4)[Randy Braunm](/maintainers/rbraunm)[@rbraunm](https://github.com/rbraunm)

---

Top Contributors

[![vedicveko](https://avatars.githubusercontent.com/u/544487?v=4)](https://github.com/vedicveko "vedicveko (19 commits)")[![rbraunm](https://avatars.githubusercontent.com/u/5680061?v=4)](https://github.com/rbraunm "rbraunm (4 commits)")[![claude-asf28fjas[bot]](https://avatars.githubusercontent.com/u/5680061?v=4)](https://github.com/claude-asf28fjas[bot] "claude-asf28fjas[bot] (2 commits)")[![turbo124](https://avatars.githubusercontent.com/u/5827962?v=4)](https://github.com/turbo124 "turbo124 (1 commits)")

---

Tags

dicompacsdcmtkmedical-imagingdicom-networking

### Embed Badge

![Health badge](/badges/rbraunm-class-dicom/health.svg)

```
[![Health](https://phpackages.com/badges/rbraunm-class-dicom/health.svg)](https://phpackages.com/packages/rbraunm-class-dicom)
```

###  Alternatives

[mikemccabe/json-patch-php

Produce and apply json-patch objects

1125.0M7](/packages/mikemccabe-json-patch-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)