Package com.pixelmed.display

## Class ConsumerFormatImageMaker

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

-     public class ConsumerFormatImageMaker
      extends java.lang.Object

  A class of static methods to make consumer format images from DICOM images.

  The formats supported depend on what JIIO codecs are available in the JRE and or provided through JIIO; see http://download.java.net/media/jai-imageio/javadoc/1.1/

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ALL_ANNOTATIONS` |
    `static java.lang.String` | `COLOR_ANNOTATIONS` |
    `static java.lang.String` | `ICON_ANNOTATIONS` |
    `static java.lang.String` | `NO_ANNOTATIONS` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ConsumerFormatImageMaker()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String[]` | `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat)` | Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int firstFrame, int lastFrame, int imageQuality, java.lang.String annotation)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int firstFrame, int lastFrame, int imageQuality, java.lang.String annotation, int debugLevel)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int firstFrame, int lastFrame, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, double superimposedToleranceDistance, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int firstFrame, int lastFrame, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, double superimposedToleranceDistance, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int debugLevel)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int firstFrame, int lastFrame, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int firstFrame, int lastFrame, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int debugLevel)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int imageQuality, java.lang.String annotation)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int imageQuality, java.lang.String annotation, int debugLevel)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, double superimposedToleranceDistance, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, double superimposedToleranceDistance, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int debugLevel)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]`

    `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, double windowCenter, double windowWidth, int imageWidth, int imageHeight, int imageQuality, java.lang.String annotation, java.util.Vector<SuperimposedImage> superimposedImages, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int debugLevel)`

    Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

    `static java.lang.String[]` | `convertFileToEightBitImage​(java.lang.String dicomFileName, java.lang.String outputFileName, java.lang.String outputFormat, int debugLevel)` | Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.
    `static void` | `main​(java.lang.String[] arg)` | Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.
    `static java.awt.image.BufferedImage` | `makeEightBitFrame​(SourceImage sImg, int f)` | Create a single frame 8-bit per channel image (windowed if grayscale) from the specified frame.
    `static java.awt.image.BufferedImage` | `makeEightBitFrame​(SourceImage sImg, int f, int debugLevel)` | Create a single frame 8-bit per channel image (windowed if grayscale) from the specified frame.
    `static java.awt.image.BufferedImage` | `makeEightBitImage​(AttributeList list)` | Create a single frame 8-bit per channel image (windowed if grayscale) from the first, or only, frame.
    `static java.awt.image.BufferedImage` | `makeEightBitImage​(AttributeList list, int debugLevel)` | Create a single frame 8-bit per channel image (windowed if grayscale) from the first, or only, frame.
    `static java.awt.image.BufferedImage[]` | `makeEightBitImages​(AttributeList list)` | Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.
    `static java.awt.image.BufferedImage[]` | `makeEightBitImages​(AttributeList list, int debugLevel)` | Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

    `static java.awt.image.BufferedImage[]`

    `makeEightBitImages​(AttributeList list, GeometryOfVolume imageGeometry, java.util.Vector<SuperimposedImage> superimposedImages, double superimposedToleranceDistance, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int firstFrame, int lastFrame)`

    Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

    `static java.awt.image.BufferedImage[]`

    `makeEightBitImages​(AttributeList list, GeometryOfVolume imageGeometry, java.util.Vector<SuperimposedImage> superimposedImages, double superimposedToleranceDistance, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int firstFrame, int lastFrame, int debugLevel)`

    Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

    `static java.awt.image.BufferedImage[]` | `makeEightBitImages​(AttributeList list, GeometryOfVolume imageGeometry, java.util.Vector<SuperimposedImage> superimposedImages, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int firstFrame, int lastFrame)` | Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

    `static java.awt.image.BufferedImage[]`

    `makeEightBitImages​(AttributeList list, GeometryOfVolume imageGeometry, java.util.Vector<SuperimposedImage> superimposedImages, java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes, int firstFrame, int lastFrame, int debugLevel)`

    Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

    `static void` | `replaceWindowWidthAndCenterInAttributeList​(AttributeList list, Attribute aWindowWidth, Attribute aWindowCenter)` |
    `static void` | `replaceWindowWidthAndCenterInFunctionalGroupSequences​(AttributeList list, int nFrames, Attribute aWindowWidth, Attribute aWindowCenter)` |

    `static void`

    `writeEightBitImageForFrame​(java.awt.image.BufferedImage renderedImage, java.util.Iterator<TextAnnotationPositioned> annotations, java.lang.String outputFileName, java.lang.String outputFormat, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int imageQuality, boolean useColorForAnnotations)`

    Write a single frame 8-bit per channel BufferedImage.

    `static void`

    `writeEightBitImageForFrame​(java.awt.image.BufferedImage renderedImage, java.util.Iterator<TextAnnotationPositioned> annotations, java.lang.String outputFileName, java.lang.String outputFormat, int imageWidth, int imageHeight, int regionX, int regionY, int regionWidth, int regionHeight, int imageQuality, boolean useColorForAnnotations, int debugLevel)`

    Write a single frame 8-bit per channel BufferedImage.

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

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

- - ### Field Detail

    - #### ALL_ANNOTATIONS

          public static final java.lang.String ALL_ANNOTATIONS

      See Also:
        Constant Field Values

    - #### ICON_ANNOTATIONS

          public static final java.lang.String ICON_ANNOTATIONS

      See Also:
        Constant Field Values

    - #### COLOR_ANNOTATIONS

          public static final java.lang.String COLOR_ANNOTATIONS

      See Also:
        Constant Field Values

    - #### NO_ANNOTATIONS

          public static final java.lang.String NO_ANNOTATIONS

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ConsumerFormatImageMaker

          public ConsumerFormatImageMaker()

  - ### Method Detail

    - #### makeEightBitFrame

          public static final java.awt.image.BufferedImage makeEightBitFrame​(SourceImage sImg,
                                                                             int f,
                                                                             int debugLevel)

      Create a single frame 8-bit per channel image (windowed if grayscale) from the specified frame.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `sImg` - the image
        `f` - the frame, numbered from 0 (not 1)
        `debugLevel` - ignored
      Returns:
        an 8 bit BufferedImage of the most favourable type for the platform

    - #### makeEightBitFrame

          public static final java.awt.image.BufferedImage makeEightBitFrame​(SourceImage sImg,
                                                                             int f)

      Create a single frame 8-bit per channel image (windowed if grayscale) from the specified frame.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `sImg` - the image
        `f` - the frame, numbered from 0 (not 1)
      Returns:
        an 8 bit BufferedImage of the most favourable type for the platform

    - #### makeEightBitImage

          public static final java.awt.image.BufferedImage makeEightBitImage​(AttributeList list,
                                                                             int debugLevel)
                                                                      throws DicomException

      Create a single frame 8-bit per channel image (windowed if grayscale) from the first, or only, frame.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `list` - the DICOM attributes
        `debugLevel` - ignored
      Returns:
        an 8 bit BufferedImage
      Throws:
        `DicomException` - if attribute is not an image

    - #### makeEightBitImage

          public static final java.awt.image.BufferedImage makeEightBitImage​(AttributeList list)
                                                                      throws DicomException

      Create a single frame 8-bit per channel image (windowed if grayscale) from the first, or only, frame.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `list` - the DICOM attributes
      Returns:
        an 8 bit BufferedImage
      Throws:
        `DicomException` - if attribute is not an image

    - #### makeEightBitImages

          public static final java.awt.image.BufferedImage[] makeEightBitImages​(AttributeList list,
                                                                                int debugLevel)
                                                                         throws DicomException

      Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `list` - the DICOM attributes
        `debugLevel` - ignored
      Returns:
        an array of 8 bit BufferedImages
      Throws:
        `DicomException` - if attribute is not an image

    - #### makeEightBitImages

          public static final java.awt.image.BufferedImage[] makeEightBitImages​(AttributeList list)
                                                                         throws DicomException

      Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `list` - the DICOM attributes
      Returns:
        an array of 8 bit BufferedImages
      Throws:
        `DicomException` - if attribute is not an image

    - #### makeEightBitImages

          public static final java.awt.image.BufferedImage[] makeEightBitImages​(AttributeList list,
                                                                                GeometryOfVolume imageGeometry,
                                                                                java.util.Vector<SuperimposedImage> superimposedImages,
                                                                                java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                                int firstFrame,
                                                                                int lastFrame,
                                                                                int debugLevel)
                                                                         throws DicomException

      Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

      Parameters:
        `list` - the DICOM attributes
        `imageGeometry` - the geometry already extracted from the list, or null if need to extract it (only needed if have superimposedImages)
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `debugLevel` - ignored
      Returns:
        an array of 8 bit BufferedImages
      Throws:
        `DicomException` - if attribute is not an image

    - #### makeEightBitImages

          public static final java.awt.image.BufferedImage[] makeEightBitImages​(AttributeList list,
                                                                                GeometryOfVolume imageGeometry,
                                                                                java.util.Vector<SuperimposedImage> superimposedImages,
                                                                                java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                                int firstFrame,
                                                                                int lastFrame)
                                                                         throws DicomException

      Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `list` - the DICOM attributes
        `imageGeometry` - the geometry already extracted from the list, or null if need to extract it (only needed if have superimposedImages)
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
      Returns:
        an array of 8 bit BufferedImages
      Throws:
        `DicomException` - if attribute is not an image

    - #### makeEightBitImages

          public static final java.awt.image.BufferedImage[] makeEightBitImages​(AttributeList list,
                                                                                GeometryOfVolume imageGeometry,
                                                                                java.util.Vector<SuperimposedImage> superimposedImages,
                                                                                double superimposedToleranceDistance,
                                                                                java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                                int firstFrame,
                                                                                int lastFrame,
                                                                                int debugLevel)
                                                                         throws DicomException

      Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `list` - the DICOM attributes
        `imageGeometry` - the geometry already extracted from the list, or null if need to extract it (only needed if have superimposedImages)
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `superimposedToleranceDistance` - difference in distance along normal to orientation for underlying and superimposed frames to be close enough to superimpose, in mm
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `debugLevel` - ignored
      Returns:
        an array of 8 bit BufferedImages
      Throws:
        `DicomException` - if attribute is not an image

    - #### makeEightBitImages

          public static final java.awt.image.BufferedImage[] makeEightBitImages​(AttributeList list,
                                                                                GeometryOfVolume imageGeometry,
                                                                                java.util.Vector<SuperimposedImage> superimposedImages,
                                                                                double superimposedToleranceDistance,
                                                                                java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                                int firstFrame,
                                                                                int lastFrame)
                                                                         throws DicomException

      Create an array of single frame 8-bit per channel image (windowed if grayscale) from the from the only or all frames.

      Uses the window center and width in the attribute list.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `list` - the DICOM attributes
        `imageGeometry` - the geometry already extracted from the list, or null if need to extract it (only needed if have superimposedImages)
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `superimposedToleranceDistance` - difference in distance along normal to orientation for underlying and superimposed frames to be close enough to superimpose, in mm
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
      Returns:
        an array of 8 bit BufferedImages
      Throws:
        `DicomException` - if attribute is not an image

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      int debugLevel)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      Uses the window center and width in the file.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `debugLevel` - ignored
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      Uses the window center and width in the file.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### replaceWindowWidthAndCenterInAttributeList

          public static void replaceWindowWidthAndCenterInAttributeList​(AttributeList list,
                                                                        Attribute aWindowWidth,
                                                                        Attribute aWindowCenter)

    - #### replaceWindowWidthAndCenterInFunctionalGroupSequences

          public static void replaceWindowWidthAndCenterInFunctionalGroupSequences​(AttributeList list,
                                                                                   int nFrames,
                                                                                   Attribute aWindowWidth,
                                                                                   Attribute aWindowCenter)

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      int debugLevel)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `debugLevel` - ignored
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int imageQuality,
                                                                      java.lang.String annotation)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int regionX,
                                                                      int regionY,
                                                                      int regionWidth,
                                                                      int regionHeight,
                                                                      int firstFrame,
                                                                      int lastFrame,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      int debugLevel)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `debugLevel` - ignored
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int regionX,
                                                                      int regionY,
                                                                      int regionWidth,
                                                                      int regionHeight,
                                                                      int firstFrame,
                                                                      int lastFrame,
                                                                      int imageQuality,
                                                                      java.lang.String annotation)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      The aspect ratio of the sub-region width and height, if any, should be the same as that of any explicitly specified image width and height, to avoid distortion.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      double superimposedToleranceDistance,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                      int debugLevel)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `superimposedToleranceDistance` - difference in distance along normal to orientation for underlying and superimposed frames to be close enough to superimpose, in mm
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
        `debugLevel` - ignored
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      double superimposedToleranceDistance,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `superimposedToleranceDistance` - difference in distance along normal to orientation for underlying and superimposed frames to be close enough to superimpose, in mm
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                      int debugLevel)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
        `debugLevel` - ignored
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int regionX,
                                                                      int regionY,
                                                                      int regionWidth,
                                                                      int regionHeight,
                                                                      int firstFrame,
                                                                      int lastFrame,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                      int debugLevel)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
        `debugLevel` - ignored
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int regionX,
                                                                      int regionY,
                                                                      int regionWidth,
                                                                      int regionHeight,
                                                                      int firstFrame,
                                                                      int lastFrame,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      The aspect ratio of the sub-region width and height, if any, should be the same as that of any explicitly specified image width and height, to avoid distortion.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int regionX,
                                                                      int regionY,
                                                                      int regionWidth,
                                                                      int regionHeight,
                                                                      int firstFrame,
                                                                      int lastFrame,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      double superimposedToleranceDistance,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes,
                                                                      int debugLevel)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `superimposedToleranceDistance` - difference in distance along normal to orientation for underlying and superimposed frames to be close enough to superimpose, in mm
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
        `debugLevel` - ignored
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### convertFileToEightBitImage

          public static java.lang.String[] convertFileToEightBitImage​(java.lang.String dicomFileName,
                                                                      java.lang.String outputFileName,
                                                                      java.lang.String outputFormat,
                                                                      double windowCenter,
                                                                      double windowWidth,
                                                                      int imageWidth,
                                                                      int imageHeight,
                                                                      int regionX,
                                                                      int regionY,
                                                                      int regionWidth,
                                                                      int regionHeight,
                                                                      int firstFrame,
                                                                      int lastFrame,
                                                                      int imageQuality,
                                                                      java.lang.String annotation,
                                                                      java.util.Vector<SuperimposedImage> superimposedImages,
                                                                      double superimposedToleranceDistance,
                                                                      java.util.Vector<java.awt.Shape>[] arrayOfPerFrameDrawingShapes)
                                                               throws DicomException,
                                                                      java.io.IOException

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      The aspect ratio of the sub-region width and height, if any, should be the same as that of any explicitly specified image width and height, to avoid distortion.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `dicomFileName` - the input file name
        `outputFileName` - the output file name (or basis of names for multiple frames)
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `windowCenter` - the window center to use
        `windowWidth` - the window width to use, or 0 if to use the width and center in the DICOM file
        `imageWidth` - the width (number of columns) to make, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to make, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `firstFrame` - the first frame to include, numbered from 0 (not 1)
        `lastFrame` - the last frame to include, numbered from 0 (not 1), or -1 if all frames
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `annotation` - the type of annotation to apply (choice is "all"; anything else means no annotation), or null if absent
        `superimposedImages` - images to to be displayed superimposed on the appropriate frames, or null if none
        `superimposedToleranceDistance` - difference in distance along normal to orientation for underlying and superimposed frames to be close enough to superimpose, in mm
        `arrayOfPerFrameDrawingShapes` - per-frame shapes to be displayed on the respective frame, or null if none
      Returns:
        a String[] of the output filenames ordered by the frame order of the input image
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### writeEightBitImageForFrame

          public static void writeEightBitImageForFrame​(java.awt.image.BufferedImage renderedImage,
                                                        java.util.Iterator<TextAnnotationPositioned> annotations,
                                                        java.lang.String outputFileName,
                                                        java.lang.String outputFormat,
                                                        int imageWidth,
                                                        int imageHeight,
                                                        int regionX,
                                                        int regionY,
                                                        int regionWidth,
                                                        int regionHeight,
                                                        int imageQuality,
                                                        boolean useColorForAnnotations,
                                                        int debugLevel)
                                                 throws DicomException,
                                                        java.io.IOException

      Write a single frame 8-bit per channel BufferedImage.

      Parameters:
        `renderedImage` - the 8 bit image (already windowed if grayscale)
        `annotations` - an Iterator of annotations to apply, or null if none
        `outputFileName` - the output file name
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `imageWidth` - the width (number of columns) to write, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to weite, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `useColorForAnnotations` - use color for annotations (i.e., produce color output image even if input is grayscale)
        `debugLevel` - ignored
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### writeEightBitImageForFrame

          public static void writeEightBitImageForFrame​(java.awt.image.BufferedImage renderedImage,
                                                        java.util.Iterator<TextAnnotationPositioned> annotations,
                                                        java.lang.String outputFileName,
                                                        java.lang.String outputFormat,
                                                        int imageWidth,
                                                        int imageHeight,
                                                        int regionX,
                                                        int regionY,
                                                        int regionWidth,
                                                        int regionHeight,
                                                        int imageQuality,
                                                        boolean useColorForAnnotations)
                                                 throws DicomException,
                                                        java.io.IOException

      Write a single frame 8-bit per channel BufferedImage.

      The aspect ratio of the sub-region width and height, if any, should be the same as that of any explicitly specified image width and height, to avoid distortion.

      Parameters:
        `renderedImage` - the 8 bit image (already windowed if grayscale)
        `annotations` - an Iterator of annotations to apply, or null if none
        `outputFileName` - the output file name
        `outputFormat` - the output file format name that a JIIO SPI will recognize (e.g. "jpeg")
        `imageWidth` - the width (number of columns) to write, or <= 0 if default (the width in the DICOM file, or scaled by height with pixel aspect ratio preserved)
        `imageHeight` - the height (number of rows) to weite, or <= 0 if default (the height in the DICOM file, or scaled by width with pixel aspect ratio preserved)
        `regionX` - the x (along row) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionY` - the y (down column) integer offset (from 0 being the TLHC pixel) of the sub-region to write
        `regionWidth` - the width (number of columns) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `regionHeight` - the height (number of rows) to write, or <= 0 if no sub-region selected (i.e., write the whole image)
        `imageQuality` - the image quality from 1 to 100 (best), or -1 if absent
        `useColorForAnnotations` - use color for annotations (i.e., produce color output image even if input is grayscale)
      Throws:
        `DicomException`
        `java.io.IOException`

    - #### main

          public static void main​(java.lang.String[] arg)

      Read a DICOM image input file, and create single frame 8-bit per channel images (windowed if grayscale) from the only or all frames.

      If the input file has multiple frames, the output file name will be postfixed with the frame number before the format extension, e.g., "output.jpg" will become "output_001.jpg", etc.

      The aspect ratio of the sub-region width and height, if any, should be the same as that of any explicitly specified image width and height, to avoid distortion.

      Performs any necessary color space transformation (e.g., from YBR to RGB) to make the result displayable.

      Parameters:
        `arg` - two required parameters, the input file name, output file name (or basis of names for multiple frames), optionally the format (defaults to jpeg), then optionally the window center and width, then optionally the desired width and height (or 0 if to use the width and center in the DICOM file and more arguments), then optionally the image quality from 0 to 100 (or -1 to use default), then optionally whether or not to include annotation (choice is "all" or "icon" +/- "color", e.g., "all_color"; anything else means no annotation; default is "all_color") then optionally the sub region x, y, width and height then optionally the first and last frame (-1 if all frames)