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

    All Methods Static Methods Instance Methods Concrete Methods
    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".
    `static java.lang.String` | `formatFixedWidth(double v, int width)` Format the given double as a string with no more than `width` characters.
    `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 static java.lang.String` | `getScientificNotationPattern(int intDigits, int signBytes, int width)`
    `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`

    - #### getScientificNotationPattern

          private static java.lang.String getScientificNotationPattern(int intDigits,
                                                                       int signBytes,
                                                                       int width)

    - #### formatFixedWidth

          public static java.lang.String formatFixedWidth(double v,
                                                          int width)

      Format the given double as a string with no more than `width` characters.

    - #### stopWatch

          protected org.perf4j.slf4j.Slf4JStopWatch stopWatch()

Copyright © 2026 Open Microscopy Environment