USAGE: upacksdcmdir -src srcdir : directory with the DICOM files -targ targdir : top directory into which the files will be unpacked -run runno subdir format name : spec unpacking rules on cmdline -cfg file : spec unpacking rules in file -seqcfg seqcfgfile : spec unpacking rules based on sequence -fsfast : unpack to fsfast directory structure -generic : unpack to generic directory structure -scanonly file : only scan the directory and put result in file -nspmzeropad N : set frame number zero padding width for SPM -unpackerr : try to unpack runs with errors -help : print out information about how to run this program DESCRIPTION This program will unpack the data from a directory containing Siemens DICOM files. Unpacking can entail copying DICOM files into directories sorted by series/run or converting them into a different format (also sorted by series/run). It is assumed that the source directory contains the files from one and only one scanning session. Supported formats are DICOM, COR, bshort, MINC, analyze, and SPM-analyze. Note: this program does not convert properly to MINC yet. ARGUMENTS: -src srcdir This is the directory where the DICOM files reside. This can be a subdirectory on a CD-ROM. Note that there is often a file called 'dicomdir.' This should not be confused with the directory where the puts DICOM files are located. -targ trgdir This is the parent directory into which the files will be unpacked. It does not need to exist before running this script. The sorting of the files into directories under the parent is determined by the unpacking rules (see below). -run RunNumber Subdir Format Name Specifies unpacking rules from the command-line. -cfgfile file Specifies unpacking rules using the given file. -seqcfg file Specifies unpacking rules based on the acquisition pulse sequence/protocol name (DICOM tag 0x18, 0x1030). This may be more convenient than run-based. See SPECIFYING UNPACKING RULES below. Note: the protocol name listed in the seqcfgfile cannot have white spaces (see BUGS below). -fsfast Sort into FS-FAST directory structure. -generic Sort generically. -nspmzeropad N Set the zero-padding of the frame number for spm-analyze files. Default is 3. SPM files will have names of the following format NameXXX.img, where XXX is the zero-padded frame number. -scanonly file This instructs the script to only scan the directory to determine the contents. A summary of the contents are stored in file. This can be useful for specifying the unpacking rules and for checking the error status of each run. It is not necessary to specify unpacking rules (though source and target directories are still necessary). -unpackerr Try to unpack a run even if the error flag is set. This may be possible if the run was simply truncated. SPECIFYING UNPACKING RULES: To unpack a series/run of data, one needs to specify three things: 1. The subdirectory the data will go into 2. The name assigned to the data file(s) 3. The format This is done by specifying a configuration and sorting method. The sorting method can be either generic or fsfast. The configuration can be either run-based or pulse sequence-based. The final path of a data file can be determined from the following table: Generic, Run-based: targdir/subdir/name.ext Generic, Seq-based: targdir/subdir/nameXXX.ext FSFAST, Run-based: targdir/subdir/XXX/name.ext FSFAST, Seq-based: targdir/subdir/XXX/name.ext where XXX is the three digit, zero-padded run number. ext is the format-based extension. The run-based configuration can be specified either on the command line (-run option) or from a file (-cfg option). In either case, the configuration is consists of four pieces of information: run number, subdir, format, and name. The run number is the integer number of the run (or Series) to be unpacked. Only the runs specified will be unpacked. The pulse sequence-based configuration can only be specified from a file. Each row in the file must contain the following four pieces of information: protocol/sequence name, subdirectory, format, name. The protocol name is that stored in DICOM tag 0x18 0x1030. If a protocol in the source directory does not match one in the configuration file, the unpacking process aborts. If generic sorting is used, then the three digit run number is inserted between the name and extension. This method is convenient when unpacking many different sessions where the sequences are all the same but the run on which each was collected may change. A configuration file with sequences commonly used around the MGH/NMR center can be found in $FREESURFER_HOME/numaris4-protocols.unpackcfg. Legal formats are: DICOM - just copies DICOM files COR - MGH-NMR COR file format bshort - MGH-NMR bshort file format MINC - MNI Medical Imaging NetCDF format NOTE: does not convert properly to MINC yet SPM - SPM (Analyze 3D) format ANALYZE - Full Analyze 4D format MGH - Local MGH format Case is ignored. For DICOM and COR formats, the Name is ignored (though there must be a placeholder there). For bshort, the Name becomes the stem. For FS-FAST applications, it is strongly suggested that the Name for bshorts be set to 'f' (no quotes). When SPM format is chosen, the actual file name will be NameXXX.img, where XXX is the three- digit, zero-padded frame number (starting with 1). The width of the zero- padding can be set with -nspmzeropad option. For ANALYZE, Name.img and Name.hdr will be created. The unpacking configuration can be specified either on the command-line (with the -run flag) or in a file (with the -cfg flag), but not both. If using the command-line option, multiple runs can be can be specified with multiple -run flags. If using a configuration file, specify all runs inside the file. The configuration file has a row for each run. Each run has four columns separated by 'white' space (ie, spaces or tabs). The information in each row is the same as that specified with -run. SCANNING A DICOM DIRECTORY When the -scanonly option is used, unpacksmincdir will scan the source directory for all the Siemens DICOM files. It will also sort them into Run/Series and make sure that each Run is complete. The summary will be put into file specified as the argument to -scanonly. This can be useful for determining the unpacking rules. The output of scanonly looks something like below: 1 localizer ok 512 512 3 1 6142643 2 SagMPRAGE8Min ok 256 192 160 1 6142657 3 SagMPRAGE4Min ok 256 256 60 1 6142077 4 SagMPRAGE8Min ok 256 192 160 1 6140088 5 T1ep2dHighRes ok 256 256 21 1 6139499 6 T2TSEAxialHiRes ok 512 448 21 1 6136953 7 ep2d_mosaic_mgh ok 64 64 21 172 6137247 8 ep2d_mosaic_mgh ok 64 64 21 172 6136826 9 ep2d_mosaic_mgh err 64 64 21 2 6133576 10 ep2d_mosaic_mgh ok 64 64 21 196 6133604 11 ep2d_mosaic_mgh ok 64 64 21 196 6130701 12 T2TSEAxialHiRes ok 512 512 21 1 6128022 The columns have the following interpretation: run/series number, protocol, error status, number of columns, number of rows, number of slices, number of frames, and DICOM file. The error status is either 'err' or 'ok'. The status is set to 'err' if the run appears to be incomplete for some reason (probably aborted). The DICOM file is the first file found in the series (mainly good for debugging). EXAMPLES Consider a session consisting of the data collected above sitting in a directory called /space/dicomdir 1. Copy the localizer DICOM files to /space/mydata/scout unpacksdcmdir -src /space/dicomdir -targ /space/mydata -generic -run 1 scout DICOM blah Note: 'blah' is ignored because the format is DICOM. 2. Convert the t1epi and the second functional to bshort using FS-FAST sorting unpacksdcmdir -src /space/dicomdir -targ /space/mydata -fsfast -run 5 t1epi bshort f -run 8 bold bshort f This will create /space/mydata/t1epi/005 and /space/mydata/bold/008, each with bshort volumes. 3. Convert the MP-RAGES to COR, and the t2 conventional and all the functionals (except run 9) to bshort using FS-FAST sorting and a configuration file. Create a configuration file (eg, mycfgfile) with the contents 2 3danat COR blah 3 3danat COR blah 4 3danat COR blah 6 t2conv bshort f 7 bold bshort f 8 bold bshort f 10 bold bshort f 11 bold bshort f unpacksdcmdir -src /space/dicomdir -targ /space/mydata -fsfast -cfg mycfgfile This will create 3danat/002, 3danat/003, 3danat/004 (each with COR volumes), t2conv/006, bold/007, bold/008, bold/010, bold/011 (each as bshort volumes with stem f). 4. Convert the MP-RAGES to MINC using generic sorting Create a configuration file (eg, mycfgfile) with the contents 2 Sag8Min MINC MPRAGE1.mnc 3 Sag4Min MINC MPRAGE1.mnc 4 Sag8Min MINC MPRAGE2.mnc unpacksdcmdir -src /space/dicomdir -targ /space/mydata -generic -cfg mycfgfile This will create /space/mydata/Sag8Min/MPAGE1.mnc and MPAGE2.mnc, and /space/mydata/Sag4Min/MPAGE1.mnc. Note that the files that go in Sag8Min must have different names or else one will overwrite the other. 5. Convert the functionals to spm-analyze format using generic sorting. Set the frame number zero padding width to 4. Create a configuration file (eg, mycfgfile) with the contents 7 bold SPM f-ep2d-07- 8 bold SPM f-ep2d-08- 10 bold SPM f-ep2d-10- 11 bold SPM f-ep2d-11- unpacksdcmdir -src /space/dicomdir -targ /space/mydata -generic -cfg mycfgfile -nspmzeropad 4 This will create directory /space/mydata/bold/ in which there will be four volumes. The first volume will have 172 files, each corresponding to a frame. The files in the series will be f-ep2d-07-0001.img, f-ep2d-07-0002.img, ... f-ep2d-07-0172.img, etc. 6. Convert the first anatomical and first functional to Analyze 4D format using generic sorting. Create a configuration file (eg, mycfgfile) with the contents 2 Sag8Min MINC MPRAGE1 7 bold ANALYZE f-ep2d-07 unpacksdcmdir -src /space/dicomdir -targ /space/mydata -generic -cfg mycfgfile This will create directory /space/mydata/bold/ in which there will be eight files: MPRAGE1.img, MPRAGE1.hdr, MPRAGE1.mat, f-ep2d-07.img, f-ep2d-07.hdr, and f-ep2d-07.mat. OTHER OUTPUT A file called unpack.log is created in the target directory. This is useful for debugging and generally keeping track of where the data came from and how it was unpacked. A file called dicomdir.sumfile is created in the target directory. Each file from the DICOM directory is listed in file along with various parameters associated with each file. In each output directory there will be a file called Name-infodump.dat. This is a dump of information for one of the files in the series. BUGS This is not guaranteed to work on all Siemens DICOM files. The DICOM files must adhere to certain rules. It is incumbent upon the pulse sequence programmer to assure that the output files conform to this standard. For more information, send email to: analysis-bugs@nmr.mgh.harvard.edu. Fails on supermosiacs. Does not compute the TR properly if there is a temporal gap between volumes. MINC volumes are incorrectly oriented. The protocol names in the DICOM files (tag 18,1030) may have white spaces in them. If this is the case, the white spaces are stripped before the protocol name is compared to the protocol names found in the sequence configuration file. Therefore, when creating the sequence configuration file, make sure to strip all the white spaces from the protocol names. BUG REPORTING Send bugs/suggestions to analysis-bugs@nmr.mgh.harvard.edu. For bug reports, include the command-line used, the unpack.log file, and the dicomdir.sumfile. AUTHOR Douglas N. Greve, Ph.D., MGH-NMR Center VERSION $Id: unpacksdcmdir,v 1.9 2003/04/14 23:14:18 greve Exp $