Latest Version -------------- 1.1 - Amazonic Bagua (Stable) 1.2 - Imperial Cusco (Stable) 1.3 - Ancient Cajamarca (Stable) Download -------- https://github.com/nanodocumet/Nanodicom Explanation ----------- There seems to be only one available PHP DICOM parser: php-dicom. However, after using it for a while (I took the lead on that project and added some new features), I felt that it needed a big overhaul. The rationale for this new toolkit is to provide the following features: - Robustness. Should not abruptly die. Exceptions are now triggered properly. - No dependencies. Self-contained at its core, period. - Performance improvements. - Memory is kept as low as possible, expect to have at least 10-30% extra of the size of the DICOM object to be read. - Speed. Dictionaries are avoided at parsing time. Only a small subset is loaded. If only certain tags are requested, the parsing will stop there. - Handling exceptions have been added. - Up to date. DICOM dictionary has been updated to 2009. Except for few cases (multiplicity and conditional VR) almost 99% of tags are present. The new way to load dictionary allows for easy extensibility to include own private dictionaries. - Documentation. Great tools should have great documentation. Users should solve most of their inquiries by reading documentation. More to come. For now, inline documentation is extensively provided. - Community-based. Using github to host the source code, hopefully others can contribute. - Extensibility. The core code should be kept intact. The toolkit allows the easy extension of the main core class. It also allows the dynamic extension to include other tools at runtime. Please be aware that this feature is still experimental. Read Additional notes at the end of the file for more information. Requirements ------------ - PHP 5.2.6+ (tested, possibly older versions) License ------- The MIT License Copyright (c) 2010-2011 Jorge "Nano" Documet Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Tested environments ------------------- 1) 32-bits Windows7 PHP 5.3.0 (cli) (built: Jun 29 2009 21:25:23) Copyright (c) 1997-2009 The PHP Group Zend Engine v2.3.0, Copyright (c) 1998-2009 Zend Technologies with Xdebug v2.1.0, Copyright (c) 2002-2010, by Derick Rethans 2) 64-bits "Linux 2.6.32-4-pve #1 SMP Mon Sep 20 11:36:51 CEST 2010 x86_64 GNU/Linux" - Debian Lenny PHP 5.2.6-1+lenny9 with Suhosin-Patch 0.9.6.2 (cli) (built: Aug 4 2010 06:06:53) Copyright (c) 1997-2008 The PHP Group Zend Engine v2.2.0, Copyright (c) 1998-2008 Zend Technologies 3) 32-bits "Linux 2.6.32-24-generic-pae #42-Ubuntu SMP Fri Aug 20 15:37:22 UTC 2010 i686 GNU/Linux" - Ubuntu 10.04 (Virtual Machine) PHP 5.3.2-1ubuntu4.2 with Suhosin-Patch (cli) (built: May 13 2010 20:01:00) Copyright (c) 1997-2009 The PHP Group Zend Engine v2.3.0, Copyright (c) 1998-2010 Zend Technologies 4) 64 bits "Linux 2.6.33.7-vs2.3.0.36.30.4 #23 SMP Tue Sep 28 05:47:35 PDT 2010 x86_64 GNU/Linux" - Debian Lenny (Virtual Machine) PHP 5.2.14 (cli) (built: Oct 4 2010 16:17:01) Copyright (c) 1997-2010 The PHP Group Zend Engine v2.2.0, Copyright (c) 1998-2010 Zend Technologies with Zend Extension Manager v1.2.2, Copyright (c) 2003-2007, by Zend Technologies with XCache v1.2.2, Copyright (c) 2005-2007, by mOo with Zend Optimizer v3.3.9, Copyright (c) 1998-2009, by Zend Technologies 5) 32 bits "Linux 2.6.32-24-generic-pae #39-Ubuntu SMP Wed Jul 28 07:39:26 UTC 2010 i686 GNU/Linux" - Ubuntu 10.04 (Virtual Machine) PHP 5.3.2-1ubuntu4.5 with Suhosin-Patch (cli) (built: Sep 17 2010 13:41:55) Copyright (c) 1997-2009 The PHP Group Zend Engine v2.3.0, Copyright (c) 1998-2010 Zend Technologies 6) 64 bits Sun Solaris Ultra-Sparc More details to come Steps to use the module ----------------------- 1) Place the nanodicom and dicom folders anywhere (but they have to be in the same parent folder) 2) Add the following statement anywhere in your code require_once PATH_TO_NANODICOM.'nanodicom.php'; 3) Load files the following way: $dicom = Nanodicom::factory(LOCATION_OF_FILE); Supported official extensions (tools) ------------------------------------- 'simple' => Simple and dummy wrapper to Core. Nothing extra 'dumper' => To dump the contents of a DICOM file. Very helpful for dumping to prompt or creating html output. xml output should be straightforward. 'anonymizer' => To anonymize DICOM files. It keeps track of repeated values among files for consistency. New v1.1!: Searches and replaces inside Sequences. Great for DICOMDIR New v1.2!: Allows passing an array to replace values if found. Great when loading anonymized values from DB or other sources. 'pixeler' => New v1.2!: Reads pixel data from images and returns image objects. Uncompressed images only for now. New v1.2!: Reads RLE, jpeg 8-bit lossy and uncompressed data. New v1.2!: Reads Monochrome1 and Monochrome2 or Paletter color. New v1.2!: Reads Planar Configuration of 0 (Color-by-pixel RGBRGB...) and 1 (Color-by-plane RRRR...GGGG...BBBB...) 'getter' => New from v1.3: Parses the file but forces the loading of the dictionaries. Miscelaneous ------------ - Coding conventions from Kohana: http://kohanaframework.org/guide/about.conventions - DICOM standard: ftp://medical.nema.org/medical/dicom/2009/ - DICOM Dictionary up to 2009 version (self-extracted) ftp://medical.nema.org/medical/dicom/2009/09_06pu3.pdf - Special thanks to the hundreds of people that uploaded their DICOM files to the php-DICOM test page. I have used that repository to test this new toolkit extensively. - DICOM sample files have been obtained from python package "pydicom" (thanks Darcy) http://code.google.com/p/pydicom/ http://code.google.com/p/pydicom/source/browse/source/dicom/testfiles/README.txt - Inspiration for nanodcm command line helper https://github.com/goyote/kohana-installer Supported (Tested) Transfer Syntaxes --------------------------- - For reading (actually, just for parsing, no pixel data is read) NONE 1.2.840.10008.1.2 Implicit VR Little Endian: Default Transfer Syntax for DICOM 1.2.840.10008.1.2.1 Explicit VR Little Endian 1.2.840.10008.1.2.1.99 Deflated Explicit VR Little Endian 1.2.840.10008.1.2.2 Explicit VR Big Endian 1.2.840.10008.1.2.4.50 JPEG Baseline (Process 1): Default Transfer Syntax for Lossy JPEG 8 Bit Image Compression 1.2.840.10008.1.2.4.51 JPEG Extended (Process 2 & 4): Default Transfer Syntax for Lossy JPEG 12 Bit Image Compression (Process 4 only) 1.2.840.10008.1.2.4.57 JPEG Lossless, Non-Hierarchical (Process 14) 1.2.840.10008.1.2.4.70 JPEG Lossless, Non-Hierarchical, First-Order Prediction (Process 14 [Selection Value 1]): Default Transfer Syntax for Lossless JPEG Image Compression 1.2.840.10008.1.2.4.90 JPEG 2000 Image Compression (Lossless Only) 1.2.840.10008.1.2.4.91 JPEG 2000 Image Compression 1.2.840.10008.1.2.5 RLE Lossless 1.2.840.10008.1.2.5.1.1 UNKNOWN - For writing (please see Additional Notes) 1.2.840.10008.1.2 Implicit VR Little Endian: Default Transfer Syntax for DICOM 1.2.840.10008.1.2.1 Explicit VR Little Endian 1.2.840.10008.1.2.1.99 Deflated Explicit VR Little Endian 1.2.840.10008.1.2.2 Explicit VR Big Endian Roadmap (as of November 17th, 2011) ------- Version 1.4 1) Improve Pixeler performance Version 2.0 1) DICOM Network tools (low priority) Examples -------- 1) Most basic example. Fast! $dicom = Nanodicom::factory($filename); // Only a small subset of the dictionary entries were loaded echo $dicom->parse()->profiler_diff('parse')."\n"; 2) Load only given tags. It will stop once all given tags are found. Fastest! $dicom = Nanodicom::factory($filename, 'simple'); $dicom->parse(array(array(0x0010, 0x0010))); // Only a small subset of the dictionary entries were loaded echo $dicom->profiler_diff('parse')."\n"; echo 'Patient name if exists: '.$dicom->value(0x0010, 0x0010)."\n"; // Patient Name if exists // This will return nothing because dictionaries were not loaded echo 'Patient name should be empty here: '.$dicom->PatientName."\n"; 3) Load only given tags by name. Stops once all tags are found. Not so fast. $dicom = Nanodicom::factory($filename, 'simple'); $dicom->parse(array('PatientName')); echo $dicom->profiler_diff('parse')."\n"; echo 'Patient name if exists: '.$dicom->value(0x0010, 0x0010)."\n"; // Patient Name if exists // Or echo 'Patient name if exists: '.$dicom->PatientName."\n"; // Patient Name if exists 4) Load only given tags. Dump it and print certain tags. Load 'dumper' directly. $dicom = Nanodicom::factory($filename, 'dumper'); $dicom->parse(array(array(0x0010, 0x0010))); echo $dicom->dump(); echo $dicom->profiler_diff('parse')."\n"; // Patient Name if exists echo 'Something should show if element exists.'.$dicom->value(0x0010, 0x0010)."\n"; // This will return the value because 'dumper' was used and loaded the dictionaries echo 'This should be empty, no dictionaries loaded.'.$dicom->PatientName."\n"; 5) Load simple and print certain value $dicom = Nanodicom::factory($filename); $dicom->parse(); echo $dicom->profiler_diff('parse')."\n"; echo 'Patient Name: '.$dicom->value(0x0010, 0x0010)."\n"; // Patient Name if exists 6) Load simple and extend it to 'dumper' $dicom = Nanodicom::factory($filename); echo $dicom->parse()->extend('dumper')->dump(); echo $dicom->profiler_diff('parse').' '.$dicom->profiler_diff('dump')."\n"; 7) Load simple and extend it to 'dumper'. No need to parse, dump() does it. Parsing is done only once. $dicom = Nanodicom::factory($filename); echo $dicom->extend('dumper')->dump(); echo $dicom->profiler_diff('parse').' '.$dicom->profiler_diff('dump')."\n"; 8) Load 'dumper' directly. Dump output is in html format. $dicom = Nanodicom::factory($filename, 'dumper'); echo $dicom->parse()->dump('html'); echo $dicom->profiler_diff('parse').' '.$dicom->profiler_diff('dump')."\n"; 9) Load 'anonymizer' directly. $dicom = Nanodicom::factory($filename, 'anonymizer'); file_put_contents($filename.'.ex9', $dicom->anonymize()); 10) Extend 'anonymizer'. No need to call parse(), anonymize() will do it. $dicom = Nanodicom::factory($filename); file_put_contents($filename.'.ex10', $dicom->extend('anonymizer')->anonymize()); 11) Double extension (and probably you can go on and on) $dicom = Nanodicom::factory($filename); echo $dicom->extend('dumper')->dump(); file_put_contents($filename.'.ex11', $dicom->extend('anonymizer')->anonymize()); 12) Save file as Explicit VR Little Endian. Read Additional notes below! $dicom = Nanodicom::factory($filename); echo $dicom->parse()->profiler_diff('parse')."\n"; // Setting values takes care of even length // If set to '1.2.840.10008.1.2.1.99' it will use deflate $dicom->value(0x0002, 0x0010, $dicom::EXPLICIT_VR_LITTLE_ENDIAN); echo $dicom->write_file($filename.'.ex12')->profiler_diff('write')."\n"; 13) Pass file contents instead of filename. $contents = file_get_contents(FILE); $dicom = Nanodicom::factory($contents, 'dumper', 'blob'); echo $dicom->dump(); 14) Check if file has preamble and DICM. $dicom = Nanodicom::factory($filename); echo 'Is DICOM? '.$dicom->is_dicom()."\n"; 15) Anonymize and save file as Explicit VR Little Endian. Read Additional notes below! $dicom = Nanodicom::factory($filename); echo $dicom->parse()->profiler_diff('parse')."\n"; // Setting values takes care of even length // If set to '1.2.840.10008.1.2.1.99' it will use deflate $dicom->value(0x0002, 0x0010, $dicom::EXPLICIT_VR_LITTLE_ENDIAN); file_put_contents($filename.'.ex15', $dicom->extend('anonymizer')->anonymize()); 16) Provide your own dumper formatting $formatting = array( 'dataset_begin' => '', 'dataset_end' => "\n", 'item_begin' => '', 'item_end' => '', 'spacer' => ' ', 'text_begin' => '', 'text_end' => '', 'columns' => array( 'off' => array('%04X', ' '), 'g' => array('%04X', ':'), 'e' => array('%04X', ' '), 'name' => array('%-30.30s', ' '), 'vr' => array('%2s', ' '), 'len' => array('%-3d', ' '), 'val' => array('[%s]', ''), ), ); $dicom = Nanodicom::factory($filename, 'dumper'); echo $dicom->dump($formatting); 17) Anonymize on the fly and dump the contents, don't save to a file $dicom = Nanodicom::factory($filename, 'anonymizer'); $dicom1 = Nanodicom::factory($dicom->anonymize(), 'dumper', 'blob'); echo $dicom1->dump(); unset($dicom); unset($dicom1); 18) Pass your own list of elements to anonymizer // Own tag elements for anonymizing $tags = array( array(0x0008, 0x0020, '{date|Ymd}'), // Study Date array(0x0008, 0x0021, '{date|Ymd}'), // Series Date array(0x0008, 0x0090, 'physician{random}'), // Referring Physician array(0x0010, 0x0010, 'patient{consecutive}'), // Patient Name array(0x0010, 0x0020, 'id{consecutive}'), // Patient ID array(0x0010, 0x0030, '{date|Ymd}'), // Patient Date of Birth ); $dicom = Nanodicom::factory($filename, 'anonymizer'); $dicom1 = Nanodicom::factory($dicom->anonymize($tags), 'dumper', 'blob'); echo $dicom1->dump(); unset($dicom); unset($dicom1); 19) Pass your own list of mappings to anonymizer. Patient Name should be replace to 'Mapped' if 'Anonymized' is found. Case sensitive // Own tag elements for anonymizing $tags = array( array(0x0008, 0x0020, '{date|Ymd}'), // Study Date array(0x0008, 0x0021, '{date|Ymd}'), // Series Date array(0x0008, 0x0090, 'physician{random}'), // Referring Physician array(0x0010, 0x0010, 'patient{consecutive}'), // Patient Name array(0x0010, 0x0020, 'id{consecutive}'), // Patient ID array(0x0010, 0x0030, '{date|Ymd}'), // Patient Date of Birth ); $replacements = array( array(0x0010, 0x0010, 'anonymized', 'Mapped'), ); $dicom = Nanodicom::factory($filename, 'anonymizer'); $dicom1 = Nanodicom::factory($dicom->anonymize($tags, $replacements), 'dumper', 'blob'); echo $dicom1->dump(); file_put_contents($filename.'.ex19', $dicom1->write()); unset($dicom); unset($dicom1); 20) Gets the images from the dicom object if they exist. This example is for gd $dicom = Nanodicom::factory($filename, 'pixeler'); if ( ! file_exists($filename.'.0.jpg')) { $images = $dicom->get_images(); // If using another library, for example, imagemagick, the following should be done: // $images = $dicom->set_driver('imagick')->get_images(); if ($images !== FALSE) { foreach ($images as $index => $image) { // Defaults to jpg $test->write_image($image, $dir.$file.'.'.$index); // To write another format, pass the format in second parameter. // This will write a png image instead // $test->write_image($image, $dir.$file.'.'.$index, 'png'); } } else { echo "There are no DICOM images or transfer syntax not supported yet.\n"; } $images = NULL; } else { echo "Image already exists\n"; } unset($dicom); 21) Prints summary report $dicom = Nanodicom::factory($filename); echo $dicom->summary(); unset($dicom); 22) Proper way of handling exceptions try { // All other examples should be placed here $dicom = Nanodicom::factory('simple', $filename); echo $dicom->parse()->profiler_diff('parse')."\n"; } catch (Nanodicom_Exception $e) { echo 'File failed. '.$e->getMessage()."\n"; } Tests --------------- Basic tests have been added. They are run using phpunit (you need to have phpunit installed) To run (at the base directory of nanodicom) $ phpunit NanodicomCoreTest.php PHPUnit 3.4.5 by Sebastian Bergmann. ............ Time: 2 seconds, Memory: 7.00Mb OK (12 tests, 12 assertions) Additional notes --------------- 1) Attention! No pixel data conversion is provided yet to change transfer syntaxes at will. Even though the toolkit DOES change the transfer syntax and the related encoding is verified (Implicit vs Explicit and Big vs Little Endian), encapsulated pixel data IS NOT CONVERTED! Thus, encapsulated Dicom files with a not encapsulated Transfer Syntax can lead to problems. 2) Extended tools get a copy of the current Nanodicom object at the moment of extension. Whatever happens in the extended tool is not kept in sync with the main (initially loaded) tool. This could lead to unexpected results. Thus, please treat the 'extend' feature still as experimental. Loading the right tool from the beginning (ie dumper or anonymizer) and performing any operations directly there is recommended. 3) In order to have the nanodcm tool running, you need to change the mode to 755. Run `chmod 0755 nanodcm` to achieve that.