loci.formats.in

Class DicomReader

java.lang.Object

loci.formats.FormatHandler

loci.formats.FormatReader

loci.formats.SubResolutionFormatReader

loci.formats.in.DicomReader

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, IFormatHandler, IFormatReader, IMetadataConfigurable, IPyramidHandler

public class DicomReader
extends SubResolutionFormatReader

DicomReader is the file format reader for DICOM files.

Field Summary

Fields

Modifier and Type	Field and Description
private int	centerPixelValue
private java.util.List<java.lang.String>	channelNames
private java.util.List<java.lang.String>	companionFiles
private java.lang.Number	concatenationNumber
private java.lang.String	date
static java.lang.String	DICOM_MAGIC_STRING
private static java.lang.String[]	DICOM_SUFFIXES
private boolean	edf
private java.util.Map<java.lang.Integer,java.util.List<java.lang.String>>	fileList
static int	HEADER_LENGTH
private int	imagesPerFile
private java.lang.String	imageType
private java.lang.String	instanceUID
private boolean	inverted
private boolean	isDeflate
private boolean	isJP2K
private boolean	isJPEG
private boolean	isRLE
private byte[][]	lut
private int	maxPixelRange
private java.lang.String	originalDate
private java.lang.String	originalInstance
private int	originalSeries
private java.lang.String	originalSpecimen
private java.lang.String	originalTime
private int	originalX
private int	originalY
private java.lang.String	pixelSizeX
private java.lang.String	pixelSizeY
private java.lang.Double	pixelSizeZ
private java.util.List<java.lang.Double>	positionX
private java.util.List<java.lang.Double>	positionY
private java.util.List<java.lang.Double>	positionZ
private short[][]	shortLut
private java.util.List<DicomTag>	tags
private java.util.Map<java.lang.Integer,java.util.List<DicomTile>>	tilePositions
private java.lang.String	time
private java.util.Map<java.lang.Integer,java.util.List<java.lang.Double>>	zOffsets

Fields inherited from class loci.formats.SubResolutionFormatReader

core

Fields inherited from class loci.formats.FormatReader

coreIndex, datasetDescription, domains, filterMetadata, flattenedResolutions, group, hasCompanionFiles, in, indexedAsRGB, metadata, metadataStore, normalizeData, resolution, saveOriginalMetadata, series, suffixNecessary, suffixSufficient, THUMBNAIL_DIMENSION

Fields inherited from class loci.formats.FormatHandler

COMPRESSION_SUFFIXES, currentId, format, LOGGER, metadataOptions, suffixes

Fields inherited from interface loci.formats.IFormatReader

CAN_GROUP, CANNOT_GROUP, MUST_GROUP

Constructor Summary

Constructors

Constructor and Description
DicomReader() Constructs a new DICOM reader.

Method Summary

Modifier and Type	Method and Description
private void	addFileToList(java.lang.String file, boolean checkSeries) Determine if the given file belongs in the same dataset as this file.
private void	addInfo(DicomTag info)
private void	addOriginalMetadata(java.lang.String key, DicomTag info) Store the given tag's value (if present) in the original metadata hashtable using the provided key.
private void	attachCompanionFiles() DICOM datasets produced by: http://www.ct-imaging.de/index.php/en/ct-systeme-e/mikro-ct-e.html contain a bunch of extra metadata and log files.
private void	calculatePixelsOffsets(long baseOffset) Calculate offsets to all pixel data (tiles or planes) in the file, starting from the given offset.
void	close(boolean fileOnly) Closes the currently open file.
private DicomFileInfo	createFileInfo(java.lang.String file) Construct a DicomFileInfo for the given file.
int	fileGroupOption(java.lang.String id) Returns an indication of whether the files in a multi-file dataset can be handled individually.
short[][]	get16BitLookupTable() Gets the 16-bit color lookup table associated with the most recently opened image.
byte[][]	get8BitLookupTable() Gets the 8-bit color lookup table associated with the most recently opened image.
java.util.List<java.lang.String>	getChannelNames()
int	getConcatenationIndex()
java.lang.String	getImageType()
int	getOptimalTileHeight() Returns the optimal sub-image height for use with openBytes.
int	getOptimalTileWidth() Returns the optimal sub-image width for use with openBytes.
ome.units.quantity.Length	getPixelSizeX()
ome.units.quantity.Length	getPixelSizeY()
ome.units.quantity.Length	getPixelSizeZ()
java.util.List<java.lang.Double>	getPositionX()
java.util.List<java.lang.Double>	getPositionY()
java.util.List<java.lang.Double>	getPositionZ()
int	getRequiredDirectories(java.lang.String[] files) Returns the number of parent directories that are important when processing the given list of files.
java.lang.String[]	getSeriesUsedFiles(boolean noPixels) Returns an array of filenames needed to open the current series.
java.util.List<DicomTag>	getTags() Provide the complete hierarchy of DICOM tags.
private void	getTile(DicomTile tile, byte[] buf, int x, int y, int w, int h) Decompress pixel data associated with the given DicomTile.
java.util.List<DicomTile>	getTiles()
ome.xml.model.primitives.Timestamp	getTimestamp()
private long	getTimestampMicroseconds(java.lang.String v) Convert the timestamp from a TM value to microseconds.
java.util.List<java.lang.Double>	getZOffsets()
private void	handleReferencedFile(DicomTag tag, java.lang.String currentType)
protected void	initFile(java.lang.String id) Initializes the given file (parsing header information, etc.).
boolean	isExtendedDepthOfField()
boolean	isThisType(loci.common.RandomAccessInputStream stream) Checks if the given stream is a valid stream for this file format.
boolean	isThisType(java.lang.String name, boolean open) Checks if a file matches the type of this format reader.
private void	makeFileList() Build a list of files that belong with the current file.
byte[]	openBytes(int no, byte[] buf, int x, int y, int w, int h) Obtains a sub-image of the specified image plane into a pre-allocated byte array.
private int	parseIntValue(java.lang.Number v, int defaultValue)
private void	parsePixelSpacing(java.lang.String value)
private void	scanDirectory(loci.common.Location dir, boolean checkSeries) Scan the given directory for files that belong to this dataset.
private void	updateCoreMetadata(CoreMetadata ms)

Methods inherited from class loci.formats.SubResolutionFormatReader

coreIndexToSeries, flattenHashtables, getCoreIndex, getCoreMetadataList, getCurrentCore, getResolution, getResolutionCount, getSeries, getSeriesCount, seriesToCoreIndex, setCoreIndex, setResolution, setSeries

Methods inherited from class loci.formats.FormatReader

addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMeta, addGlobalMetaList, addMeta, addMetaList, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMeta, addSeriesMetaList, close, getAcquisitionMode, getAdvancedSeriesUsedFiles, getAdvancedUsedFiles, getArcType, getAvailableOptions, getBinning, getBitsPerPixel, getCompression, getContrastMethod, getCorrection, getCurrentFile, getDatasetStructureDescription, getDetectorType, getDimensionOrder, getDimensionOrder, getDomains, getEffectiveSizeC, getExperimentType, getFilamentType, getFillRule, getFilterType, getFontFamily, getFontStyle, getGlobalMeta, getGlobalMetadata, getIlluminationType, getImageCount, getImmersion, getIndex, getIndex, getLaserMedium, getLaserType, getMarker, getMedium, getMetadataStore, getMetadataStoreRoot, getMetadataValue, getMicrobeamManipulationType, getMicroscopeType, getModuloC, getModuloT, getModuloZ, getNamingConvention, getPixelType, getPixelType, getPossibleDomains, getPulse, getRGBChannelCount, getRotationTransform, getSeriesMeta, getSeriesMetadata, getSeriesMetadataValue, getSeriesUsedFiles, getSizeC, getSizeT, getSizeX, getSizeY, getSizeZ, getThumbSizeX, getThumbSizeY, getUnderlyingReaders, getUsedFiles, getUsedFiles, getZCTCoords, getZCTModuloCoords, hasCompanionFiles, hasFlattenedResolutions, isFalseColor, isGroupFiles, isIndexed, isInterleaved, isInterleaved, isLittleEndian, isMetadataComplete, isMetadataFiltered, isNormalized, isOrderCertain, isOriginalMetadataPopulated, isRGB, isSingleFile, isThisType, isThisType, isThumbnailSeries, isUsedFile, makeFilterMetadata, openBytes, openBytes, openBytes, openPlane, openThumbBytes, readPlane, readPlane, readPlane, reopenFile, setFlattenedResolutions, setGroupFiles, setId, setMetadataFiltered, setMetadataStore, setNormalized, setOriginalMetadataPopulated, updateMetadataLists

Methods inherited from class loci.formats.FormatHandler

checkSuffix, checkSuffix, getFormat, getMetadataOptions, getNativeDataType, getSuffixes, getSupportedMetadataLevels, setMetadataOptions

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface loci.formats.IFormatHandler

getFormat, getNativeDataType, getSuffixes

Methods inherited from interface loci.formats.IMetadataConfigurable

getMetadataOptions, getSupportedMetadataLevels, setMetadataOptions

Field Detail

DICOM_MAGIC_STRING

public static final java.lang.String DICOM_MAGIC_STRING

See Also:

Constant Field Values

HEADER_LENGTH

public static final int HEADER_LENGTH

See Also:

Constant Field Values

DICOM_SUFFIXES

private static final java.lang.String[] DICOM_SUFFIXES

lut

private byte[][] lut

shortLut

private short[][] shortLut

maxPixelRange

private int maxPixelRange

centerPixelValue

private int centerPixelValue

inverted

private boolean inverted

date

private java.lang.String date

time

private java.lang.String time

imageType

private java.lang.String imageType

pixelSizeX

private java.lang.String pixelSizeX

pixelSizeY

private java.lang.String pixelSizeY

pixelSizeZ

private java.lang.Double pixelSizeZ

positionX

private java.util.List<java.lang.Double> positionX

positionY

private java.util.List<java.lang.Double> positionY

positionZ

private java.util.List<java.lang.Double> positionZ

channelNames

private java.util.List<java.lang.String> channelNames

isJPEG

private boolean isJPEG

isRLE

private boolean isRLE

isJP2K

private boolean isJP2K

isDeflate

private boolean isDeflate

fileList

private java.util.Map<java.lang.Integer,java.util.List<java.lang.String>> fileList

imagesPerFile

private int imagesPerFile

instanceUID

private java.lang.String instanceUID

originalDate

private java.lang.String originalDate

originalTime

private java.lang.String originalTime

originalInstance

private java.lang.String originalInstance

originalSeries

private int originalSeries

originalX

private int originalX

originalY

private int originalY

originalSpecimen

private java.lang.String originalSpecimen

companionFiles

private java.util.List<java.lang.String> companionFiles

tilePositions

private java.util.Map<java.lang.Integer,java.util.List<DicomTile>> tilePositions

zOffsets

private java.util.Map<java.lang.Integer,java.util.List<java.lang.Double>> zOffsets

concatenationNumber

private java.lang.Number concatenationNumber

edf

private boolean edf

tags

private java.util.List<DicomTag> tags

Constructor Detail

DicomReader

public DicomReader()

Constructs a new DICOM reader.

Method Detail

isThisType

public boolean isThisType(java.lang.String name,
                          boolean open)

Description copied from class: FormatReader

Checks if a file matches the type of this format reader. Checks filename suffixes against those known for this format. If the suffix check is inconclusive and the open parameter is true, the file is opened and tested with FormatReader.isThisType(RandomAccessInputStream).

Specified by:

isThisType in interface IFormatReader

Overrides:

isThisType in class FormatReader

open - If true, and the file extension is insufficient to determine the file type, the (existing) file is opened for further analysis.

isThisType

public boolean isThisType(loci.common.RandomAccessInputStream stream)
                   throws java.io.IOException

Description copied from interface: IFormatReader

Checks if the given stream is a valid stream for this file format. The number of bytes read is format-dependent.

Specified by:

isThisType in interface IFormatReader

Overrides:

isThisType in class FormatReader

Parameters:

stream - A RandomAccessInputStream representing the file to check. The first byte in the stream is assumed to be the first byte in the file.

Returns:

true if the file represented by the stream can be read by this reader; false otherwise.

Throws:

java.io.IOException

getRequiredDirectories

public int getRequiredDirectories(java.lang.String[] files)
                           throws FormatException,
                                  java.io.IOException

Description copied from interface: IFormatReader

Returns the number of parent directories that are important when processing the given list of files. The number of directories is relative to the common parent. For example, given a list with these two files: /path/to/file/foo /path/to/file/that/is/related A return value of 0 indicates that "/path/to/file/" is irrelevant. A return value of 1 indicates that "/path/to/" is irrelevant. Return values less than 0 are invalid. All listed files are assumed to belong to datasets of the same format.

Specified by:

getRequiredDirectories in interface IFormatReader

Overrides:

getRequiredDirectories in class FormatReader

Throws:

FormatException

java.io.IOException

get8BitLookupTable

public byte[][] get8BitLookupTable()

Description copied from interface: IFormatReader

Gets the 8-bit color lookup table associated with the most recently opened image. If no image planes have been opened, or if IFormatReader.isIndexed() returns false, then this may return null. Also, if IFormatReader.getPixelType() returns anything other than FormatTools.INT8 or FormatTools.UINT8, this method will return null.

Specified by:

get8BitLookupTable in interface IFormatReader

Overrides:

get8BitLookupTable in class FormatReader

get16BitLookupTable

public short[][] get16BitLookupTable()

Description copied from interface: IFormatReader

Gets the 16-bit color lookup table associated with the most recently opened image. If no image planes have been opened, or if IFormatReader.isIndexed() returns false, then this may return null. Also, if IFormatReader.getPixelType() returns anything other than FormatTools.INT16 or FormatTools.UINT16, this method will return null.

Specified by:

get16BitLookupTable in interface IFormatReader

Overrides:

get16BitLookupTable in class FormatReader

getSeriesUsedFiles

public java.lang.String[] getSeriesUsedFiles(boolean noPixels)

Description copied from interface: IFormatReader

Returns an array of filenames needed to open the current series. If the 'noPixels' flag is set, then only files that do not contain pixel data will be returned. The first element in the array is expected to be the path passed to IFormatHandler.setId(String), if appropriate based upon 'noPixels'. The remaining elements are expected to be in a consistent order; if a directory listing is necessary to build the list then it should be sorted first.

Specified by:

getSeriesUsedFiles in interface IFormatReader

Overrides:

getSeriesUsedFiles in class FormatReader

fileGroupOption

public int fileGroupOption(java.lang.String id)
                    throws FormatException,
                           java.io.IOException

Description copied from interface: IFormatReader

Returns an indication of whether the files in a multi-file dataset can be handled individually. This method is only useful for formats and datasets which contain multiple files.

Specified by:

fileGroupOption in interface IFormatReader

Overrides:

fileGroupOption in class FormatReader

Parameters:

id - a file in the multi-file dataset

Returns:

an int indicating that we cannot, must, or might group the files. A return value of FormatTools.MUST_GROUP indicates that the files cannot be handled separately; the reader will always detect and read all files in the dataset. FormatTools.CAN_GROUP indicates that the files may be handled separately, but file grouping must then be disabled via IFormatReader.setGroupFiles(boolean). FormatTools.CANNOT_GROUP indicates that the files must be handled separately; the reader will not attempt to read all files in the dataset (this is rare).

Throws:

FormatException

java.io.IOException

See Also:

FormatTools.MUST_GROUP, FormatTools.CAN_GROUP, FormatTools.CANNOT_GROUP

getOptimalTileWidth

public int getOptimalTileWidth()

Description copied from interface: IFormatReader

Returns the optimal sub-image width for use with openBytes.

Specified by:

getOptimalTileWidth in interface IFormatReader

Overrides:

getOptimalTileWidth in class FormatReader

getOptimalTileHeight

public int getOptimalTileHeight()

Description copied from interface: IFormatReader

Returns the optimal sub-image height for use with openBytes.

Specified by:

getOptimalTileHeight in interface IFormatReader

Overrides:

getOptimalTileHeight in class FormatReader

openBytes

public byte[] openBytes(int no,
                        byte[] buf,
                        int x,
                        int y,
                        int w,
                        int h)
                 throws FormatException,
                        java.io.IOException

Description copied from interface: IFormatReader

Obtains a sub-image of the specified image plane into a pre-allocated byte array.

Specified by:

openBytes in interface IFormatReader

Specified by:

openBytes in class FormatReader

Parameters:

no - the plane index within the current series.

buf - a pre-allocated buffer.

x - X coordinate of the upper-left corner of the sub-image

y - Y coordinate of the upper-left corner of the sub-image

w - width of the sub-image

h - height of the sub-image

Returns:

the pre-allocated buffer buf for convenience.

Throws:

FormatException - if there was a problem parsing the metadata of the file.

java.io.IOException - if there was a problem reading the file.

See Also:

IFormatReader.openBytes(int, byte[], int, int, int, int)

close

public void close(boolean fileOnly)
           throws java.io.IOException

Description copied from interface: IFormatReader

Closes the currently open file. If the flag is set, this is all that happens; if unset, it is equivalent to calling Closeable.close().

Specified by:

close in interface IFormatReader

Overrides:

close in class SubResolutionFormatReader

Throws:

java.io.IOException

initFile

protected void initFile(java.lang.String id)
                 throws FormatException,
                        java.io.IOException

Description copied from class: SubResolutionFormatReader

Initializes the given file (parsing header information, etc.). Most subclasses should override this method to perform initialization operations such as parsing metadata.

Overrides:

initFile in class SubResolutionFormatReader

Throws:

FormatException - if a parsing error occurs processing the file.

java.io.IOException - if an I/O error occurs processing the file

addInfo

private void addInfo(DicomTag info)
              throws java.io.IOException

Throws:

java.io.IOException

addOriginalMetadata

private void addOriginalMetadata(java.lang.String key,
                                 DicomTag info)

Store the given tag's value (if present) in the original metadata hashtable using the provided key. Any children of the tag will be added to the table as well. Note that the "Per-Frame Functional Groups Sequence" and "Referenced Image Navigation Sequence" and any children will be omitted, as will any values that are byte or short arrays (e.g. lookup tables). This is necessary to prevent memory exhaustion. Applications that need to traverse the complete hierarchy of DICOM tags should use getTags() to access tags directly and not rely upon the original metadata table.

makeFileList

private void makeFileList()
                   throws FormatException,
                          java.io.IOException

Build a list of files that belong with the current file.

Throws:

FormatException

java.io.IOException

scanDirectory

private void scanDirectory(loci.common.Location dir,
                           boolean checkSeries)
                    throws FormatException,
                           java.io.IOException

Scan the given directory for files that belong to this dataset.

Throws:

FormatException

java.io.IOException

addFileToList

private void addFileToList(java.lang.String file,
                           boolean checkSeries)
                    throws FormatException,
                           java.io.IOException

Determine if the given file belongs in the same dataset as this file.

Throws:

FormatException

java.io.IOException

parseIntValue

private int parseIntValue(java.lang.Number v,
                          int defaultValue)

getTimestampMicroseconds

private long getTimestampMicroseconds(java.lang.String v)

Convert the timestamp from a TM value to microseconds. The timestamp format defined in the standard is HHMMSS.FFFFFF but HH:MM:SS.FFFFFF is supported as well since some files incorrectly use that format.

attachCompanionFiles

private void attachCompanionFiles()
                           throws java.io.IOException

DICOM datasets produced by: http://www.ct-imaging.de/index.php/en/ct-systeme-e/mikro-ct-e.html contain a bunch of extra metadata and log files. We do not parse these extra files, but do locate and attach them to the DICOM file(s).

Throws:

java.io.IOException

getTile

private void getTile(DicomTile tile,
                     byte[] buf,
                     int x,
                     int y,
                     int w,
                     int h)
              throws FormatException,
                     java.io.IOException

Decompress pixel data associated with the given DicomTile.

Throws:

FormatException

java.io.IOException

parsePixelSpacing

private void parsePixelSpacing(java.lang.String value)

handleReferencedFile

private void handleReferencedFile(DicomTag tag,
                                  java.lang.String currentType)

calculatePixelsOffsets

private void calculatePixelsOffsets(long baseOffset)
                             throws FormatException,
                                    java.io.IOException

Calculate offsets to all pixel data (tiles or planes) in the file, starting from the given offset.

Throws:

FormatException

java.io.IOException

createFileInfo

private DicomFileInfo createFileInfo(java.lang.String file)
                              throws FormatException,
                                     java.io.IOException

Construct a DicomFileInfo for the given file. If the file is the currently initialized file, don't parse it again.

Throws:

FormatException

java.io.IOException

updateCoreMetadata

private void updateCoreMetadata(CoreMetadata ms)

getImageType

public java.lang.String getImageType()

getTiles

public java.util.List<DicomTile> getTiles()

getZOffsets

public java.util.List<java.lang.Double> getZOffsets()

getConcatenationIndex

public int getConcatenationIndex()

getPixelSizeX

public ome.units.quantity.Length getPixelSizeX()

getPixelSizeY

public ome.units.quantity.Length getPixelSizeY()

getPixelSizeZ

public ome.units.quantity.Length getPixelSizeZ()

getPositionX

public java.util.List<java.lang.Double> getPositionX()

getPositionY

public java.util.List<java.lang.Double> getPositionY()

getPositionZ

public java.util.List<java.lang.Double> getPositionZ()

getChannelNames

public java.util.List<java.lang.String> getChannelNames()

isExtendedDepthOfField

public boolean isExtendedDepthOfField()

getTimestamp

public ome.xml.model.primitives.Timestamp getTimestamp()

getTags

public java.util.List<DicomTag> getTags()

Provide the complete hierarchy of DICOM tags. Applications that need to query or display the complete tag structure should use this method to retrieve tags instead of relying upon original metadata.