loci.formats.out

Class DicomWriter

java.lang.Object

loci.formats.FormatHandler

loci.formats.FormatWriter

loci.formats.out.DicomWriter

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, ICompressedTileWriter, IFormatHandler, IFormatWriter, IMetadataConfigurable, IPyramidHandler, IExtraMetadataWriter

public class DicomWriter
extends FormatWriter
implements IExtraMetadataWriter

DicomWriter is the file format writer for DICOM files. This is designed for whole slide images, and may not produce schema-compliant files for other modalities.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	DicomWriter.PlaneOffset
(package private) class	DicomWriter.UIDCreator Helper class for creating UIDs.

Field Summary

Fields

Modifier and Type	Field and Description
private int	baseTileHeight
private int	baseTileWidth
private boolean	bigTiff
private long[]	compressionMethodPointer
private java.lang.Integer	currentPlane
private long	fileMetaLengthPointer
private IFD[][]	ifds
private java.lang.String	implementationUID
private java.lang.String	instanceUIDValue
private long[]	nextIFDPointer
private long[]	pixelDataLengthPointer
private int[]	pixelDataSize
private DicomWriter.PlaneOffset[][]	planeOffsets
private static java.lang.String	SOP_CLASS_UID_VALUE
private java.util.ArrayList<ITagProvider>	tagProviders
static java.lang.String	TIFF_KEY Option for turning off TIFF metadata.
private TiffSaver	tiffSaver
private long[]	tileCountPointer
private int[]	tileHeight
private long[]	tileHeightPointer
private int[]	tileWidth
private long[]	tileWidthPointer
private long[]	transferSyntaxPointer
static java.lang.String	UID_DEFAULT_ROOT
static java.lang.String	UID_ROOT_KEY Option for setting the organization root for UIDs.
private DicomWriter.UIDCreator	uids
private java.lang.Boolean	validPixelCount

Fields inherited from class loci.formats.FormatWriter

cm, compression, compressionTypes, fps, initialized, interleaved, metadataRetrieve, options, out, resolution, resolutionData, sequential, series, validBits

Fields inherited from class loci.formats.FormatHandler

COMPRESSION_SUFFIXES, currentId, format, LOGGER, metadataOptions, suffixes

Constructor Summary

Constructors

Constructor and Description
DicomWriter()

Method Summary

Modifier and Type	Method and Description
boolean	canDoStacks() Reports whether the writer can save multiple images to a single file.
private void	checkPixelCount(boolean warn)
private void	checkPrecompressedSupport() Check if pre-compressed tiles are supported with the current options.
void	close()
private ome.units.quantity.Length	fixUnits(ome.units.quantity.Length size) Check if the unit for the given Length is "pixel" or "referenceframe".
Codec	getCodec()
private java.lang.String	getCompressionMethod()
private java.lang.String	getFilename(int pyramid, int res)
private java.lang.String	getImageType(java.lang.String pyramidName, int res, boolean hasPyramid, int resolutionCount)
private int	getIndex(int pyramid, int res)
private TiffRational	getPhysicalSize(ome.units.quantity.Length size)
int[]	getPixelTypes(java.lang.String codec) Gets the supported pixel types for the given codec.
private int	getStoredLength(DicomTag tag)
private TiffCompression	getTIFFCompression()
int	getTileSizeX() Retrieves the current tile width Defaults to 0 if not supported
int	getTileSizeY() Retrieves the current tile height Defaults to 0 if not supported
private java.lang.String	getTransferSyntax()
java.lang.String	getUIDRoot()
private int[]	getZCTCoords(int no)
private boolean	isReallySequential()
private DicomTag	lookupTag(java.util.List<DicomTag> tags, DicomTag compare)
private DicomTag	makeItem()
private DicomTag	makeItemDelimitation()
private short[]	makeShortArray(int v)
private void	openFile(int pyramid, int res)
private java.lang.String	padString(java.lang.String value) Pad the given string so that the length is a multiple of 2.
private java.lang.String	padString(java.lang.String value, java.lang.String append)
private java.lang.String	padString(java.lang.String value, java.lang.String append, int length)
private void	padTagValues(DicomTag t)
private java.lang.String	padUID(java.lang.String value) Pad the given string so that the length is a multiple of 2.
void	saveBytes(int no, byte[] buf, int x, int y, int w, int h) Saves the given image tile to the current series in the current file.
void	saveCompressedBytes(int no, byte[] buf, int x, int y, int w, int h) Save a compressed tile to the current output file.
void	setBigTiff(boolean bigTiff) Sets whether or not BigTIFF files should be written.
void	setExtraMetadata(java.lang.String tagSource) Provide additional metadata that should be written as part of this dataset.
void	setId(java.lang.String id) Initializes a writer from the input file name.
void	setResolution(int r) Set the resolution level.
void	setSeries(int s) Sets the current series.
int	setTileSizeX(int tileSize) Will attempt to set the tile width to the desired value and return the actual value which will be used
int	setTileSizeY(int tileSize) Will attempt to set the tile height to the desired value and return the actual value which will be used
protected org.perf4j.slf4j.Slf4JStopWatch	stopWatch()
boolean	writeDualPersonality() Checks the writer's associated MetadataOptions to see if dual personality writing has been explicitly enabled or disabled.
private void	writeHeader() Write the preamble, prefix, and file meta elements.
private void	writeIFDs(int resIndex)
private void	writeTag(DicomTag tag)
private void	writeTag(DicomTag tag, loci.common.RandomAccessOutputStream output)

Methods inherited from class loci.formats.FormatWriter

changeOutputFile, checkParams, createOutputStream, getCodecOptions, getColorModel, getCompression, getCompressionTypes, getFramesPerSecond, getMetadataRetrieve, getPixelTypes, getPlaneCount, getPlaneCount, getResolution, getResolutionCount, getResolutions, getSamplesPerPixel, getSamplesPerPixel, getSeries, getSizeX, getSizeY, hasResolutions, isFullPlane, isInterleaved, isSupportedType, saveBytes, saveBytes, savePlane, savePlane, savePlane, seekToPlaneOffset, setCodecOptions, setColorModel, setCompression, setFramesPerSecond, setInterleaved, setMetadataRetrieve, setResolutions, setValidBitsPerPixel, setWriteSequentially

Methods inherited from class loci.formats.FormatHandler

checkSuffix, checkSuffix, getFormat, getMetadataOptions, getNativeDataType, getSuffixes, getSupportedMetadataLevels, isThisType, 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, isThisType

Methods inherited from interface loci.formats.IMetadataConfigurable

getMetadataOptions, getSupportedMetadataLevels, setMetadataOptions

Field Detail

UID_ROOT_KEY

public static final java.lang.String UID_ROOT_KEY

Option for setting the organization root for UIDs.

See Also:

Constant Field Values

UID_DEFAULT_ROOT

public static final java.lang.String UID_DEFAULT_ROOT

See Also:

Constant Field Values

TIFF_KEY

public static final java.lang.String TIFF_KEY

Option for turning off TIFF metadata.

See Also:

Constant Field Values

SOP_CLASS_UID_VALUE

private static final java.lang.String SOP_CLASS_UID_VALUE

See Also:

Constant Field Values

pixelDataLengthPointer

private long[] pixelDataLengthPointer

pixelDataSize

private int[] pixelDataSize

transferSyntaxPointer

private long[] transferSyntaxPointer

compressionMethodPointer

private long[] compressionMethodPointer

nextIFDPointer

private long[] nextIFDPointer

ifds

private IFD[][] ifds

fileMetaLengthPointer

private long fileMetaLengthPointer

baseTileWidth

private int baseTileWidth

baseTileHeight

private int baseTileHeight

tileWidth

private int[] tileWidth

tileHeight

private int[] tileHeight

tileWidthPointer

private long[] tileWidthPointer

tileHeightPointer

private long[] tileHeightPointer

tileCountPointer

private long[] tileCountPointer

planeOffsets

private DicomWriter.PlaneOffset[][] planeOffsets

currentPlane

private java.lang.Integer currentPlane

uids

private DicomWriter.UIDCreator uids

instanceUIDValue

private java.lang.String instanceUIDValue

implementationUID

private java.lang.String implementationUID

tagProviders

private java.util.ArrayList<ITagProvider> tagProviders

bigTiff

private boolean bigTiff

tiffSaver

private TiffSaver tiffSaver

validPixelCount

private java.lang.Boolean validPixelCount

Constructor Detail

DicomWriter

public DicomWriter()

Method Detail

setExtraMetadata

public void setExtraMetadata(java.lang.String tagSource)

Description copied from interface: IExtraMetadataWriter

Provide additional metadata that should be written as part of this dataset. Primarily intended for DicomWriter. Calling this method is optional. Multiple calls are allowed, e.g. if tags come from multiple external sources. If multiple calls to this method are made then the order matters, with earlier calls implying higher priority when resolving duplicate or conflicting tags. All calls to this method must occur before setId is called.

Specified by:

setExtraMetadata in interface IExtraMetadataWriter

setBigTiff

public void setBigTiff(boolean bigTiff)

Sets whether or not BigTIFF files should be written. This flag is not reset when close() is called.

writeDualPersonality

public boolean writeDualPersonality()

Checks the writer's associated MetadataOptions to see if dual personality writing has been explicitly enabled or disabled. If the option is not set, the default is to return true, enabling dual personality writing.

setSeries

public void setSeries(int s)
               throws FormatException

Description copied from interface: IFormatWriter

Sets the current series.

Specified by:

setSeries in interface IFormatWriter

Overrides:

setSeries in class FormatWriter

Parameters:

s - the series index, starting from 0.

Throws:

FormatException - if the specified series is invalid.

setResolution

public void setResolution(int r)

Description copied from interface: IPyramidHandler

Set the resolution level.

Specified by:

setResolution in interface IPyramidHandler

Overrides:

setResolution in class FormatWriter

See Also:

IPyramidHandler.getResolutionCount()

getCodec

public Codec getCodec()

Specified by:

getCodec in interface ICompressedTileWriter

Returns:

the codec that can be used to compress tiles

saveCompressedBytes

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

Description copied from interface: ICompressedTileWriter

Save a compressed tile to the current output file. The compression type of the tile should match the compression type set in the writer.

Specified by:

saveCompressedBytes in interface ICompressedTileWriter

Parameters:

no - plane index

buf - compressed tile bytes

x - pixel X coordinate of the upper-left corner of the tile

y - pixel Y coordinate of the upper-left corner of the tile

w - width in pixels of the compressed tile

h - height in pixels of the compressed tile

Throws:

FormatException

java.io.IOException

saveBytes

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

Description copied from interface: IFormatWriter

Saves the given image tile to the current series in the current file.

Specified by:

saveBytes in interface IFormatWriter

Parameters:

no - the plane index within the series.

buf - the byte array that represents the image tile.

x - the X coordinate of the upper-left corner of the image tile.

y - the Y coordinate of the upper-left corner of the image tile.

w - the width (in pixels) of the image tile.

h - the height (in pixels) of the image tile.

Throws:

FormatException - if one of the parameters is invalid.

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

See Also:

IFormatWriter.saveBytes(int, byte[], int, int, int, int)

canDoStacks

public boolean canDoStacks()

Description copied from interface: IFormatWriter

Reports whether the writer can save multiple images to a single file.

Specified by:

canDoStacks in interface IFormatWriter

Overrides:

canDoStacks in class FormatWriter

getPixelTypes

public int[] getPixelTypes(java.lang.String codec)

Description copied from interface: IFormatWriter

Gets the supported pixel types for the given codec.

Specified by:

getPixelTypes in interface IFormatWriter

Overrides:

getPixelTypes in class FormatWriter

setId

public void setId(java.lang.String id)
           throws FormatException,
                  java.io.IOException

Description copied from class: FormatWriter

Initializes a writer from the input file name. Initializes a RandomAccessOutputStream for the output file and initializes the metadata for all the series using FormatWriter.setSeries(int).

Specified by:

setId in interface IFormatHandler

Overrides:

setId in class FormatWriter

Parameters:

id - a String specifying the path to the file

Throws:

FormatException

java.io.IOException

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class FormatWriter

Throws:

java.io.IOException

setTileSizeX

public int setTileSizeX(int tileSize)
                 throws FormatException

Description copied from interface: IFormatWriter

Will attempt to set the tile width to the desired value and return the actual value which will be used

Specified by:

setTileSizeX in interface IFormatWriter

Overrides:

setTileSizeX in class FormatWriter

Parameters:

tileSize - The tile width you wish to use. Setting to 0 will disable tiling

Returns:

The tile width which will actually be used, this may differ from the value requested. If the requested value is not supported the writer will return and use the closest appropriate value.

Throws:

FormatException - Tile size must be greater than or equal to 0 and less than the image width

getTileSizeX

public int getTileSizeX()

Description copied from interface: IFormatWriter

Retrieves the current tile width Defaults to 0 if not supported

Specified by:

getTileSizeX in interface IFormatWriter

Overrides:

getTileSizeX in class FormatWriter

Returns:

The current tile width being used

setTileSizeY

public int setTileSizeY(int tileSize)
                 throws FormatException

Description copied from interface: IFormatWriter

Will attempt to set the tile height to the desired value and return the actual value which will be used

Specified by:

setTileSizeY in interface IFormatWriter

Overrides:

setTileSizeY in class FormatWriter

Parameters:

tileSize - The tile height you wish to use. Setting to 0 will disable tiling

Returns:

The tile height which will actually be used, this may differ from the value requested. If the requested value is not supported the writer will return and use the closest appropriate value.

Throws:

FormatException - Tile size must be greater than or equal to 0 and less than the image height

getTileSizeY

public int getTileSizeY()

Description copied from interface: IFormatWriter

Retrieves the current tile height Defaults to 0 if not supported

Specified by:

getTileSizeY in interface IFormatWriter

Overrides:

getTileSizeY in class FormatWriter

Returns:

The current tile height being used

getUIDRoot

public java.lang.String getUIDRoot()

getStoredLength

private int getStoredLength(DicomTag tag)

writeTag

private void writeTag(DicomTag tag)
               throws java.io.IOException

Throws:

java.io.IOException

writeTag

private void writeTag(DicomTag tag,
                      loci.common.RandomAccessOutputStream output)
               throws java.io.IOException

Throws:

java.io.IOException

padString

private java.lang.String padString(java.lang.String value)

Pad the given string so that the length is a multiple of 2. If the input is null, an empty string is returned. Otherwise, a space is appended if necessary. This should not be used for UID values.

Parameters:

value - original string

Returns:

padded string whose length is a multiple of 2

padUID

private java.lang.String padUID(java.lang.String value)

Pad the given string so that the length is a multiple of 2. If the input is null, an empty string is returned. Otherwise, a null character is appended if necessary. This should not be used for non-UID values.

Parameters:

value - original string

Returns:

padded string whose length is a multiple of 2

padString

private java.lang.String padString(java.lang.String value,
                                   java.lang.String append)

padString

private java.lang.String padString(java.lang.String value,
                                   java.lang.String append,
                                   int length)

getTransferSyntax

private java.lang.String getTransferSyntax()

Returns:

transfer syntax UID corresponding to the current compression type

getCompressionMethod

private java.lang.String getCompressionMethod()

Returns:

compression method corresponding to the current compression type

openFile

private void openFile(int pyramid,
                      int res)
               throws java.io.IOException

Throws:

java.io.IOException

writeHeader

private void writeHeader()
                  throws java.io.IOException

Write the preamble, prefix, and file meta elements. See http://dicom.nema.org/medical/dicom/current/output/html/part10.html#sect_7.1

Throws:

java.io.IOException

getFilename

private java.lang.String getFilename(int pyramid,
                                     int res)

getIndex

private int getIndex(int pyramid,
                     int res)

getZCTCoords

private int[] getZCTCoords(int no)

isReallySequential

private boolean isReallySequential()

getImageType

private java.lang.String getImageType(java.lang.String pyramidName,
                                      int res,
                                      boolean hasPyramid,
                                      int resolutionCount)

writeIFDs

private void writeIFDs(int resIndex)
                throws java.io.IOException

Throws:

java.io.IOException

getTIFFCompression

private TiffCompression getTIFFCompression()

makeItem

private DicomTag makeItem()

Returns:

item tag with an undefined length

makeItemDelimitation

private DicomTag makeItemDelimitation()

Returns:

item delimitation tag with 0 length

lookupTag

private DicomTag lookupTag(java.util.List<DicomTag> tags,
                           DicomTag compare)

padTagValues

private void padTagValues(DicomTag t)

makeShortArray

private short[] makeShortArray(int v)

fixUnits

private ome.units.quantity.Length fixUnits(ome.units.quantity.Length size)

Check if the unit for the given Length is "pixel" or "referenceframe". These two units cannot be assigned to proper physical units (e.g. mm), so need to be handled specially.

getPhysicalSize

private TiffRational getPhysicalSize(ome.units.quantity.Length size)

checkPrecompressedSupport

private void checkPrecompressedSupport()

Check if pre-compressed tiles are supported with the current options. TODO: maybe this should be a higher-level API method?

Throws:

java.lang.UnsupportedOperationException - if pre-compressed tiles are not supported

checkPixelCount

private void checkPixelCount(boolean warn)
                      throws FormatException

Throws:

FormatException

stopWatch

protected org.perf4j.slf4j.Slf4JStopWatch stopWatch()