Package com.pixelmed.display

## Class SourceImage

- java.lang.Object
- - com.pixelmed.display.SourceImage

- Direct Known Subclasses:
    `SourceImageSubset`

      public class SourceImage
      extends java.lang.Object

  A class that encapsulates the pixel data and features and values from an image source (such as a DICOM image), usually for the purpose of displaying it.

  See Also:
    `SingleImagePanel`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static boolean` | `allowDeferredReadFromFileIfNotMemoryMapped` |
    `protected static boolean` | `allowMemoryMapping` |
    `protected static boolean` | `allowMemoryMappingFromMultiplePerFrameFiles` |
    `protected boolean` | `applyICCProfileIfPresent` |
    `protected com.pixelmed.display.SourceImage.BufferedImageSource` | `bufferedImageSource` |
    `protected java.nio.MappedByteBuffer[]` | `memoryMappedByteBuffers` |
    `protected java.nio.channels.FileChannel` | `memoryMappedFileChannel` |
    `protected java.nio.channels.FileChannel[]` | `memoryMappedFileChannels` |
    `protected java.io.FileInputStream` | `memoryMappedFileInputStream` |
    `protected java.io.FileInputStream[]` | `memoryMappedFileInputStreams` |
    `protected static int` | `memoryMapperNumberOfRetries` |
    `protected static int` | `memoryMapperRetriesBeforeSleeping` |
    `protected static int` | `memoryMapperSleepTimeBetweenRetries` |

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `SourceImage()` | Allow subclasses to have their own constructors.
    `` | `SourceImage​(AttributeList list)` | Construct an image from a single or multi-frame DICOM image from a list of DICOM attributes.
    `` | `SourceImage​(AttributeList list, boolean applyICCProfileIfPresent)` | Construct an image from a single or multi-frame DICOM image from a list of DICOM attributes.
    `` | `SourceImage​(DicomInputStream i)` | Construct an image from a single or multi-frame DICOM image from an input stream (such as from a file or the network).
    `` | `SourceImage​(DicomInputStream i, boolean applyICCProfileIfPresent)` | Construct an image from a single or multi-frame DICOM image from an input stream (such as from a file or the network).
    `` | `SourceImage​(java.io.InputStream i, int w, int h, int depth)` | Construct a single-frame image from an unsigned raw image (no header) on an input stream with the specified width, height and bit depth.
    `` | `SourceImage​(java.io.InputStream i, int w, int h, int depth, int frames)` | Construct a multi-frame image from an unsigned raw image (no header) on an input stream with the specified width, height and bit depth.
    `` | `SourceImage​(java.lang.String filename)` | Construct an image from a single or multi-frame DICOM image from a file.
    `` | `SourceImage​(java.lang.String filename, boolean applyICCProfileIfPresent)` | Construct an image from a single or multi-frame DICOM image from a file.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected static void` | `clean​(java.lang.Object object)` |
    `void` | `close()` |
    `static java.awt.image.BufferedImage` | `createBandInterleavedByteThreeComponentColorImage​(int w, int h, byte[] data, int offset, java.awt.color.ColorSpace colorSpace)` |
    `static java.awt.image.BufferedImage` | `createBandInterleavedShortThreeComponentColorImage​(int w, int h, short[] data, int offset, java.awt.color.ColorSpace colorSpace)` |
    `static java.awt.image.BufferedImage` | `createByteGrayscaleImage​(int w, int h, byte[] data, int offset)` |
    `static java.awt.image.BufferedImage` | `createDoubleGrayscaleImage​(int w, int h, double[] data, int offset)` |
    `static java.awt.image.BufferedImage` | `createFloatGrayscaleImage​(int w, int h, float[] data, int offset)` |
    `static java.awt.image.BufferedImage` | `createPixelInterleavedByteThreeComponentColorImage​(int w, int h, byte[] data, int offset, java.awt.color.ColorSpace colorSpace, boolean isChrominanceHorizontallyDownsampledBy2)` |
    `static java.awt.image.BufferedImage` | `createPixelInterleavedShortThreeComponentColorImage​(int w, int h, short[] data, int offset, java.awt.color.ColorSpace colorSpace)` |
    `static java.awt.image.BufferedImage` | `createSignedShortGrayscaleImage​(int w, int h, short[] data, int offset)` |
    `static java.awt.image.BufferedImage` | `createUnsignedShortGrayscaleImage​(int w, int h, short[] data, int offset)` |
    `protected void` | `finalize()` |
    `int` | `getBackgroundValue()` |
    `java.awt.image.BufferedImage` | `getBufferedImage()` | Make a BufferedImage for the first or only frame.
    `java.awt.image.BufferedImage` | `getBufferedImage​(boolean useICC)` | Make a BufferedImage for the first or only frame.
    `java.awt.image.BufferedImage` | `getBufferedImage​(int i)` | Make a BufferedImage for the selected frame.
    `java.awt.image.BufferedImage` | `getBufferedImage​(int i, boolean useICC)` | Make a BufferedImage for the selected frame.
    `protected java.nio.ByteBuffer[]` | `getByteBuffersFromOtherAttributeOnDisk​(OtherAttributeOnDisk oad, int nframes)` | Get memory mapped file buffers for the specified attribute.
    `protected java.nio.ByteBuffer[]` | `getByteBuffersFromOtherByteAttributeMultipleFilesOnDisk​(OtherByteAttributeMultipleFilesOnDisk oad, int nframes)` | Get memory mapped file buffers for the specified attribute.
    `java.awt.Dimension` | `getDimension()` |
    `DisplayShutter` | `getDisplayShutter()` |
    `int` | `getHeight()` |
    `int` | `getMaskValue()` |
    `double` | `getMaximum()` |
    `double` | `getMinimum()` |
    `ModalityTransform` | `getModalityTransform()` |
    `int` | `getNumberOfBufferedImages()` |
    `int` | `getNumberOfFrames()` |
    `Overlay` | `getOverlay()` |
    `int` | `getPadRangeLimit()` |
    `int` | `getPadValue()` |
    `int` | `getPaletteColorBitsPerEntry()` |
    `short[]` | `getPaletteColorBlueTable()` |
    `int` | `getPaletteColorFirstValueMapped()` |
    `short[]` | `getPaletteColorGreenTable()` |
    `int` | `getPaletteColorLargestGray()` |
    `int` | `getPaletteColorNumberOfEntries()` |
    `short[]` | `getPaletteColorRedTable()` |
    `RealWorldValueTransform` | `getRealWorldValueTransform()` |
    `protected java.nio.ShortBuffer[]` | `getShortBuffersFromOtherWordAttributeOnDisk​(OtherWordAttributeOnDisk oad, int nframes)` | Get a memory mapped file buffer for value of the specified attribute.
    `SUVTransform` | `getSUVTransform()` |
    `java.lang.String` | `getTitle()` |
    `VOITransform` | `getVOITransform()` |
    `int` | `getWidth()` |
    `boolean` | `isGrayscale()` |
    `boolean` | `isImage()` |
    `boolean` | `isInverted()` |
    `boolean` | `isPadded()` |
    `boolean` | `isSigned()` |
    `boolean` | `isYBR()` |
    `static void` | `setAllowDeferredReadFromFileIfNotMemoryMapped​(boolean allowDeferredReadFromFileIfNotMemoryMapped)` | Static method to set whether or not to reading of per-frame data from a file to be deferred when subsequently constructing SourceImage objects from attributes whose pixel data has been left on disk rather than all frames to be read and constructed in memory.
    `static void` | `setAllowMemoryMapping​(boolean allowMemoryMapping)` | Static method to set whether or not to allow memory mapping to be used at all when subsequently constructing SourceImage objects from attributes whose pixel data has been left on disk rather than read or constructed in memory.
    `static void` | `setAllowMemoryMappingFromMultiplePerFrameFiles​(boolean allowMemoryMappingFromMultiplePerFrameFiles)` | Static method to set whether or not to allow memory mapping to be used in the special case that the images on disk have their frames spread across separate files rather than one large contiguous file.
    `void` | `setClipRect​(int i, java.awt.Rectangle clipRect)` | Set the rectanguler clipping region for the selected frame.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### allowMemoryMapping

          protected static boolean allowMemoryMapping

    - #### allowMemoryMappingFromMultiplePerFrameFiles

          protected static boolean allowMemoryMappingFromMultiplePerFrameFiles

    - #### allowDeferredReadFromFileIfNotMemoryMapped

          protected static boolean allowDeferredReadFromFileIfNotMemoryMapped

    - #### applyICCProfileIfPresent

          protected boolean applyICCProfileIfPresent

    - #### bufferedImageSource

          protected com.pixelmed.display.SourceImage.BufferedImageSource bufferedImageSource

    - #### memoryMappedFileInputStream

          protected java.io.FileInputStream memoryMappedFileInputStream

    - #### memoryMappedFileChannel

          protected java.nio.channels.FileChannel memoryMappedFileChannel

    - #### memoryMappedFileInputStreams

          protected java.io.FileInputStream[] memoryMappedFileInputStreams

    - #### memoryMappedFileChannels

          protected java.nio.channels.FileChannel[] memoryMappedFileChannels

    - #### memoryMappedByteBuffers

          protected java.nio.MappedByteBuffer[] memoryMappedByteBuffers

    - #### memoryMapperNumberOfRetries

          protected static int memoryMapperNumberOfRetries

    - #### memoryMapperSleepTimeBetweenRetries

          protected static int memoryMapperSleepTimeBetweenRetries

    - #### memoryMapperRetriesBeforeSleeping

          protected static int memoryMapperRetriesBeforeSleeping

  - ### Constructor Detail

    - #### SourceImage

          protected SourceImage()

      Allow subclasses to have their own constructors.

    - #### SourceImage

          public SourceImage​(java.io.InputStream i,
                             int w,
                             int h,
                             int depth)
                      throws java.io.IOException

      Construct a single-frame image from an unsigned raw image (no header) on an input stream with the specified width, height and bit depth.

      Parameters:
        `i` - the input stream
        `w` - image width
        `h` - image height
        `depth` - bit depth
      Throws:
        `java.io.IOException`

    - #### SourceImage

          public SourceImage​(java.io.InputStream i,
                             int w,
                             int h,
                             int depth,
                             int frames)
                      throws java.io.IOException

      Construct a multi-frame image from an unsigned raw image (no header) on an input stream with the specified width, height and bit depth.

      Parameters:
        `i` - the input stream
        `w` - image width
        `h` - image height
        `depth` - bit depth
        `frames` - number of frames
      Throws:
        `java.io.IOException`

    - #### SourceImage

          public SourceImage​(java.lang.String filename,
                             boolean applyICCProfileIfPresent)
                      throws java.io.IOException,
                             DicomException

      Construct an image from a single or multi-frame DICOM image from a file.

      Parameters:
        `filename` -
        `applyICCProfileIfPresent` - whether or not to apply any ICC profile present in the attribute list
      Throws:
        `java.io.IOException`
        `DicomException`

    - #### SourceImage

          public SourceImage​(java.lang.String filename)
                      throws java.io.IOException,
                             DicomException

      Construct an image from a single or multi-frame DICOM image from a file.

      Applies any ICC Profile that is present.

      Parameters:
        `filename` -
      Throws:
        `java.io.IOException`
        `DicomException`

    - #### SourceImage

          public SourceImage​(DicomInputStream i,
                             boolean applyICCProfileIfPresent)
                      throws java.io.IOException,
                             DicomException

      Construct an image from a single or multi-frame DICOM image from an input stream (such as from a file or the network).

      Parameters:
        `i` - the input stream
        `applyICCProfileIfPresent` - whether or not to apply any ICC profile present in the attribute list
      Throws:
        `java.io.IOException`
        `DicomException`

    - #### SourceImage

          public SourceImage​(DicomInputStream i)
                      throws java.io.IOException,
                             DicomException

      Construct an image from a single or multi-frame DICOM image from an input stream (such as from a file or the network).

      Applies any ICC Profile that is present.

      Parameters:
        `i` - the input stream
      Throws:
        `java.io.IOException`
        `DicomException`

    - #### SourceImage

          public SourceImage​(AttributeList list,
                             boolean applyICCProfileIfPresent)
                      throws DicomException

      Construct an image from a single or multi-frame DICOM image from a list of DICOM attributes.

      If decompression was deferred during AttributeList read, take care not to remove the Transfer Syntax from the AttributeList until after deferred decompression.

      Parameters:
        `list` - the list of attributes that include the description and values of the pixel data
        `applyICCProfileIfPresent` - whether or not to apply any ICC profile present in the attribute list
      Throws:
        `DicomException`

    - #### SourceImage

          public SourceImage​(AttributeList list)
                      throws DicomException

      Construct an image from a single or multi-frame DICOM image from a list of DICOM attributes.

      If decompression was deferred during AttributeList read, take care not to remove the Transfer Syntax from the AttributeList until after deferred decompression.

      Applies any ICC Profile that is present.

      Parameters:
        `list` - the list of attributes that include the description and values of the pixel data
      Throws:
        `DicomException`

  - ### Method Detail

    - #### setAllowMemoryMapping

          public static void setAllowMemoryMapping​(boolean allowMemoryMapping)

      Static method to set whether or not to allow memory mapping to be used at all when subsequently constructing SourceImage objects from attributes whose pixel data has been left on disk rather than read or constructed in memory.

      Default is to allow memory mapping.

      Performance will generally be suprior with memory mapping turned on, and less heap will be used, but apparent issues with native memory allocation and revovery after a failed mapping on some platforms may require disabling it.

      Parameters:
        `allowMemoryMapping` - true or false to allow or disallow memory mapping, respectively

    - #### setAllowMemoryMappingFromMultiplePerFrameFiles

          public static void setAllowMemoryMappingFromMultiplePerFrameFiles​(boolean allowMemoryMappingFromMultiplePerFrameFiles)

      Static method to set whether or not to allow memory mapping to be used in the special case that the images on disk have their frames spread across separate files rather than one large contiguous file.

      Default is to to disable memory mapping in this case.

      Parameters:
        `allowMemoryMappingFromMultiplePerFrameFiles` - true or false to allow or disallow memory mapping of per-frame files, respectively

    - #### setAllowDeferredReadFromFileIfNotMemoryMapped

          public static void setAllowDeferredReadFromFileIfNotMemoryMapped​(boolean allowDeferredReadFromFileIfNotMemoryMapped)

      Static method to set whether or not to reading of per-frame data from a file to be deferred when subsequently constructing SourceImage objects from attributes whose pixel data has been left on disk rather than all frames to be read and constructed in memory.

      Does not apply if memory mapping is enabled and succeeds.

      Default is to to allow deferred reading.

      Reading of the pixel data for a frame (and allocation of memory for it) is deferred until `SourceImage.getBufferedImage(int)` is called.

      Parameters:
        `allowDeferredReadFromFileIfNotMemoryMapped` - true or false to allow or disallow deferred read of per-frame data from file, respectively

    - #### setClipRect

          public void setClipRect​(int i,
                                  java.awt.Rectangle clipRect)

      Set the rectanguler clipping region for the selected frame.

      Parameters:
        `i` - frame number (from 0)

    - #### createUnsignedShortGrayscaleImage

          public static java.awt.image.BufferedImage createUnsignedShortGrayscaleImage​(int w,
                                                                                       int h,
                                                                                       short[] data,
                                                                                       int offset)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createSignedShortGrayscaleImage

          public static java.awt.image.BufferedImage createSignedShortGrayscaleImage​(int w,
                                                                                     int h,
                                                                                     short[] data,
                                                                                     int offset)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createByteGrayscaleImage

          public static java.awt.image.BufferedImage createByteGrayscaleImage​(int w,
                                                                              int h,
                                                                              byte[] data,
                                                                              int offset)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createPixelInterleavedByteThreeComponentColorImage

          public static java.awt.image.BufferedImage createPixelInterleavedByteThreeComponentColorImage​(int w,
                                                                                                        int h,
                                                                                                        byte[] data,
                                                                                                        int offset,
                                                                                                        java.awt.color.ColorSpace colorSpace,
                                                                                                        boolean isChrominanceHorizontallyDownsampledBy2)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createBandInterleavedByteThreeComponentColorImage

          public static java.awt.image.BufferedImage createBandInterleavedByteThreeComponentColorImage​(int w,
                                                                                                       int h,
                                                                                                       byte[] data,
                                                                                                       int offset,
                                                                                                       java.awt.color.ColorSpace colorSpace)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createPixelInterleavedShortThreeComponentColorImage

          public static java.awt.image.BufferedImage createPixelInterleavedShortThreeComponentColorImage​(int w,
                                                                                                         int h,
                                                                                                         short[] data,
                                                                                                         int offset,
                                                                                                         java.awt.color.ColorSpace colorSpace)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createBandInterleavedShortThreeComponentColorImage

          public static java.awt.image.BufferedImage createBandInterleavedShortThreeComponentColorImage​(int w,
                                                                                                        int h,
                                                                                                        short[] data,
                                                                                                        int offset,
                                                                                                        java.awt.color.ColorSpace colorSpace)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createFloatGrayscaleImage

          public static java.awt.image.BufferedImage createFloatGrayscaleImage​(int w,
                                                                               int h,
                                                                               float[] data,
                                                                               int offset)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### createDoubleGrayscaleImage

          public static java.awt.image.BufferedImage createDoubleGrayscaleImage​(int w,
                                                                                int h,
                                                                                double[] data,
                                                                                int offset)

      Parameters:
        `w` -
        `h` -
        `data` -
        `offset` -

    - #### clean

          protected static void clean​(java.lang.Object object)
                               throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### close

          public void close()
                     throws java.lang.Throwable

      Throws:
        `java.lang.Throwable`

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Throws:
        `java.lang.Throwable`

    - #### getByteBuffersFromOtherByteAttributeMultipleFilesOnDisk

          protected java.nio.ByteBuffer[] getByteBuffersFromOtherByteAttributeMultipleFilesOnDisk​(OtherByteAttributeMultipleFilesOnDisk oad,
                                                                                                  int nframes)
                                                                                           throws DicomException,
                                                                                                  java.io.IOException,
                                                                                                  java.lang.Throwable

      Get memory mapped file buffers for the specified attribute.

      Parameters:
        `oad` - the attribute on disk to memory map
      Returns:
        an array of byte buffers, one per frame
      Throws:
        `DicomException` - if cannot memory map file
        `java.io.IOException` - of cannot open file
        `java.lang.Throwable` - if problem closing memory mapped file

    - #### getByteBuffersFromOtherAttributeOnDisk

          protected java.nio.ByteBuffer[] getByteBuffersFromOtherAttributeOnDisk​(OtherAttributeOnDisk oad,
                                                                                 int nframes)
                                                                          throws DicomException,
                                                                                 java.io.IOException,
                                                                                 java.lang.Throwable

      Get memory mapped file buffers for the specified attribute.

      Parameters:
        `oad` - the attribute on disk to memory map
      Returns:
        an array of byte buffers, one per frame
      Throws:
        `DicomException` - if cannot memory map file
        `java.io.IOException` - of cannot open file
        `java.lang.Throwable` - if problem closing memory mapped file

    - #### getShortBuffersFromOtherWordAttributeOnDisk

          protected java.nio.ShortBuffer[] getShortBuffersFromOtherWordAttributeOnDisk​(OtherWordAttributeOnDisk oad,
                                                                                       int nframes)
                                                                                throws DicomException,
                                                                                       java.io.IOException,
                                                                                       java.lang.Throwable

      Get a memory mapped file buffer for value of the specified attribute.

      Parameters:
        `oad` - the attribute on disk to memory map
        `nframes` - the number of frames
      Returns:
        an array of short buffers
      Throws:
        `DicomException` - if cannot memory map file
        `java.io.IOException` - of cannot open file
        `java.lang.Throwable` - if problem closing memory mapped file

    - #### getBufferedImage

          public java.awt.image.BufferedImage getBufferedImage()

      Make a BufferedImage for the first or only frame.

      The BufferedImage will have the bit depth and photometric interpretation of the original SourceImage.

      If it is an RGB photometric interpretation, and an ICC profile is present, it will be applied.

      Returns:
        a BufferedImage for the first or only frame

    - #### getBufferedImage

          public java.awt.image.BufferedImage getBufferedImage​(boolean useICC)

      Make a BufferedImage for the first or only frame.

      The BufferedImage will have the bit depth and photometric interpretation of the original SourceImage.

      Parameters:
        `useICC` - if true, if image has an RGB photometric interpretation, and an ICC profile is present, it will be applied
      Returns:
        a BufferedImage for the first or only frame

    - #### getBufferedImage

          public java.awt.image.BufferedImage getBufferedImage​(int i)

      Make a BufferedImage for the selected frame.

      The BufferedImage will have the bit depth and photometric interpretation of the original SourceImage.

      If it is an RGB photometric interpretation, and an ICC profile is present, it will be applied.

      Parameters:
        `i` - frame number (from 0)
      Returns:
        a BufferedImage for the selected frame

    - #### getBufferedImage

          public java.awt.image.BufferedImage getBufferedImage​(int i,
                                                               boolean useICC)

      Make a BufferedImage for the selected frame.

      The BufferedImage will have the bit depth and photometric interpretation of the original SourceImage.

      Parameters:
        `i` - frame number (from 0)
        `useICC` - if true, if image has an RGB photometric interpretation, and an ICC profile is present, it will be applied
      Returns:
        a BufferedImage for the selected frame

    - #### getNumberOfBufferedImages

          public int getNumberOfBufferedImages()

    - #### isImage

          public boolean isImage()

    - #### getWidth

          public int getWidth()

    - #### getHeight

          public int getHeight()

    - #### getDimension

          public java.awt.Dimension getDimension()

    - #### getMinimum

          public double getMinimum()

      Returns:
        the minimum pixel value, excluding any pixels in the padding value range

    - #### getMaximum

          public double getMaximum()

      Returns:
        the maximum pixel value, excluding any pixels in the padding value range

    - #### getMaskValue

          public int getMaskValue()

    - #### isSigned

          public boolean isSigned()

    - #### isInverted

          public boolean isInverted()

    - #### isPadded

          public boolean isPadded()

    - #### getPadValue

          public int getPadValue()

    - #### getPadRangeLimit

          public int getPadRangeLimit()

    - #### getBackgroundValue

          public int getBackgroundValue()

    - #### isGrayscale

          public boolean isGrayscale()

    - #### isYBR

          public boolean isYBR()

    - #### getTitle

          public java.lang.String getTitle()

    - #### getNumberOfFrames

          public int getNumberOfFrames()

    - #### getPaletteColorLargestGray

          public int getPaletteColorLargestGray()

    - #### getPaletteColorFirstValueMapped

          public int getPaletteColorFirstValueMapped()

    - #### getPaletteColorNumberOfEntries

          public int getPaletteColorNumberOfEntries()

    - #### getPaletteColorBitsPerEntry

          public int getPaletteColorBitsPerEntry()

    - #### getPaletteColorRedTable

          public short[] getPaletteColorRedTable()

    - #### getPaletteColorGreenTable

          public short[] getPaletteColorGreenTable()

    - #### getPaletteColorBlueTable

          public short[] getPaletteColorBlueTable()

    - #### getSUVTransform

          public SUVTransform getSUVTransform()

    - #### getRealWorldValueTransform

          public RealWorldValueTransform getRealWorldValueTransform()

    - #### getModalityTransform

          public ModalityTransform getModalityTransform()

    - #### getVOITransform

          public VOITransform getVOITransform()

    - #### getDisplayShutter

          public DisplayShutter getDisplayShutter()

    - #### getOverlay

          public Overlay getOverlay()