NAME
PDL::IO::Dcm - Reads dicom files, sorts them and stores the result into piddles with headers
VERSION
Version 0.9
SYNOPSIS
This is inteded to read and sort dicom images created by medical imaging devices.
Either use something like the following from within your module/application
# loads all dicom files in this directory
# $id is a code reference returning e.g. the Series Number
my $dcms=load_dcm_dir($dir,$id);
die "no data!" unless (keys %$dcms);
print "Read data; ProtIDs: ",join ', ',keys %$dcms,"\n";
# sort all individual dicoms into a hash of piddles.
my $data=parse_dcms($dcms);or use the read_dcm.pl script to convert dicom files in a directory to serealised piddles (PDL::IO::Sereal) or NIFTI files with separate text headers (PDL::IO::Nifti).
This software is tailored to Siemens MRI data based on the author's needs. For general usage, the read_dcm function should and probably will be moved to vendor/modality specific plugin modules in future releases.
Some notes on Dicom fields and how they are stored/treated
The image data field is stored as the piddle, the other dicom elements are stored in the header under the raw_dicom key.
The Siemens protocol ASCCONV part is stored in the ascconv key.
Key 0029,1010 is the Siemens specific field that contains the ICE miniheaders with dimension information - and position in matrix 0029,1020 is deleted from the header, it is big, containing the whole protocol. The important part is parsed into ascconv.
Keys are parsed into a hash under the dicom key using the DicomPack module(s) to unpack.
The header fields IceDims and IcePos are used for sorting datasets. The field Dimensions lists the sorted names of dimensions.
Piddles are created for each lProtID or Series Number value.
SUBROUTINES/METHODS
is_equal ($dcm1,$dcm2,$pattern)
This is used to check if two dicoms can be stacked based on matrix size, orientation and pixel spacing.
If $pattern matches /d/, only dims are checked
load_dcm_dir ( $dir,\%options)
reads all dicom files in a dicrectory and returns a hash of piddles containing sorted N-D data sets.
Fields in the options hash include:
- id:
-
Uses a code reference to access the field by which to split. See read_dcm.pl for details. Currently, the ascconv field lProtID or dicom Series Number are used as keys.
- sp:
-
Split slice groups, otherwise they are stacked together if xy-dims match, even transposed.
parse_dcms
Parses and sorts a hash of hashes of dicoms (such as returned by load_dcm_dir) based on lProtID and the ICE_Dims field in 0029_1010. Returns a hash of piddles (lProtID).
unpack_field
unpacks dicom fields and walks subfield structures recursively.
sort_series
Groups dicom files based on their series number. If data within the series don't fit, the outcome depends on the split option. If set, it will always produce several piddles, appending a, b, c, etc.; if not, transposition is tried, ignoring Pixel Spacing and Image Rotation. Only if this fails, data is split.
read_dcm ($file, \%options)
reads a dicom file and creates a piddle-with-header structure.
printStruct
This is used to generate human readable and parsable text from the headers.
TODO
write tests!
Generalise to other modalities. This will be done based on request or as needed.
LICENSE AND COPYRIGHT
Copyright 2016 Albrecht Ingo Schmid.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.